Migrace kódu pro agentické načítání na nejnovější verzi

Pokud váš kód agentic retrieval používá starší verzi rozhraní API, tento článek vysvětluje, kdy a jak migrovat na novější verzi. Popisuje také úpravy vedoucí k nekompatibilitě a úpravy nezpůsobující nekompatibilitu pro všechny verze rozhraní API, které podporují agentní načítání.

Pokyny k migraci vám pomůžou spustit existující řešení v novější verzi rozhraní API. Pokyny v tomto článku vám pomůžou řešit zásadní změny na úrovni rozhraní API tak, aby vaše aplikace běžela jako předtím. Pokud potřebujete pomoc s přidáním nové funkce, začněte s Co je nového v Azure AI Vyhledávač.

Kdy migrovat

Většina verzí, které podporují agentní načítání, zavedly nekompatibilní změny. Starší kód můžete dál spouštět beze změny tím, že si zachováte hodnotu verze rozhraní API, ale pokud chcete využívat opravy chyb, vylepšení a novější funkce, musíte kód aktualizovat.

Pokud váš kód cílí na verzi Preview, doporučujeme migrovat na nejnovější stabilní verzi pouze v případě, že váš případ použití plně podporuje 2026-04-01. Pokud spoléháte na syntézu odpovědí, neminimální úsilí o odůvodnění nebo vícenásobné zprávy, zkontrolujte zásadní a nezásadní změny před tím, než se rozhodnete migrovat. Tyto funkce zůstanou ve verzi Preview.

Před migrací

• Pokud chcete porozumět rozsahu změn, projděte si kritické a nezlomné změny pro každou verzi.

• Podporovaná cesta migrace je přírůstková. Pokud je váš kód určen pro 2025-05-01-preview, nejprve migrujte na 2025-08-01-preview, poté pokračujte přes každou další verzi, dokud nedosáhnete cílové verze.

• Pro souběžnou migraci vytvořte jedinečně pojmenované objekty, které implementují chování předchozí verze. Tento přístup zachovává existující objekty při vývoji a testování nahrazení. Pokud objekt podporuje aktualizaci na místě, kroky pro konkrétní verzi na tuto možnost upozorňují.

• Pro každý objekt, který migrujete, začněte získáním aktuální definice z vyhledávací služby, abyste mohli před zadáním nové zkontrolovat existující vlastnosti.

• Odstraňte starší verze softwaru až po úplném otestování a nasazení migrace.

Postup migrace

Tato část popisuje kroky migrace pro následující verze rozhraní API:

• 2026-08-01-preview
• 2026-05-01-preview
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

Pokud migrujete z verze 2026-05-01-preview, můžete přejít přímo na 2026-08-01-preview. Tato migrace vyžaduje aktualizace zdrojů informací Work IQ, stránkování seznamů, zpracování odpovědí, nástrojů serveru MCP a ovlivněných volání generovaného klienta.

1. Migrujte zdroje znalostí Work IQ
2. Aktualizovat stránkování seznamu
3. Aktualizace zpracování odpovědí na načtení
4. Aktualizace kódu a klientů

Migrovat zdroje znalostí Work IQ

Chcete-li migrovat zdroj znalostí Work IQ na novou konfiguraci ověřování:

1. Exportujte aktuální definici.

2. Aktualizujte existující zdroj znalostí pomocí Knowledge Sources - Create Or Update nebo vytvořte náhradní zdroj s jedinečným názvem pro paralelní migraci.

3. 2026-08-01-preview Použijte verzi rozhraní API a nakonfigurujte workIQParameters.entraAppAuthentication. Vlastnosti applicationId a federatedCredentialId jsou povinné. Vlastnost tenantId je volitelná a její výchozí hodnotou je tenant vyhledávací služby.

4. Pokud jste vytvořili nahrazení, aktualizujte každou znalostní bázi, která odkazuje na předchozí zdroj znalostí, aby používala náhradní název.

5. Aktualizace žádostí o načtení pro předání uživatelského kontrolního výrazu x-ms-query-work-iq-source-authorization v hlavičce

Informace o nastavení a příkladech najdete v tématu Vytvoření zdroje znalostí IQ v práci (Preview).

Aktualizovat stránkování seznamu

Chcete-li nahradit stránkování založené na offsetu stránkováním založeným na kurzoru:

1. Odeberte $top, $skip a $count z požadavků na seznam zdrojů znalostí. Nastavte pageSize velikost stránky od 1 do 3 000. Pokud ji vynecháte, služba zvolí velikost stránky.

2. Filtrování podle názvu, nastavení search a searchType. Jediná podporovaná searchType hodnota je prefix, což je také výchozí. Následující požadavek vrátí až 100 zdrojů znalostí, jejichž názvy začínají contoso.

   GET {{search-endpoint}}/knowledgesources?api-version=2026-08-01-preview&pageSize=100&search=contoso&searchType=prefix
   Authorization: Bearer {{search-access-token}}
   

   Referenční informace:Zdroje znalostí – seznam

3. Pokud odpověď obsahuje @odata.nextLink, odešlete tuto adresu URL přesně tak, jak je vrácena. Neparsujte ani neupravujte jeho stav pokračování.

Aktualizace zpracování odpovědi při načtení

Chcete-li zpracovat nový odkaz Work IQ a tvary aktivit podporované modelem:

1. Odstraňte závislosti na attributions, WorkIQAttribution a seeMoreWebUrl. Přečtěte si metadata popisků citlivosti z searchSensitivityLabelInfo odkazu Work IQ.

2. V záznamech aktivit plánování dotazů, syntézy odpovědí a shrnutí webu čtěte modelName a deploymentId z vnořeného objektu model. Vnořený objekt a obě vlastnosti jsou volitelné.

Následující fragmenty ukazují změny obrazce odpovědi.

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "attributions": [
        {
          "seeMoreWebUrl": "<attribution-url>"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "modelName": "<model-name>"
    }
  ]
}

V 2026-08-01-preview používají stejné fragmenty následující tvar:

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "searchSensitivityLabelInfo": {
        "displayName": "<label-name>",
        "sensitivityLabelId": "<label-id>"
      }
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "model": {
        "modelName": "<model-name>",
        "deploymentId": "<deployment-id>"
      }
    }
  ]
}

Aktualizace kódu a klientů pro verzi 2026-08-01-preview

Dokončení migrace:

1. Na každé položce serveru MCP nahraďte inclusionMode za resultsProcessing. Namapujte reranked na rerank a always na none. Hodnota rerank je výchozí. Hodnota none obchází řazení a zachovává základní pořadí výsledků nástroje. Informace o nastavení najdete v tématu Konfigurace nástrojů pro zdroj znalostí serveru MCP.

2. Pokud používáte Azure SDK, nainstalujte balíček, který podporuje 2026-08-01-preview, a zkontrolujte volání pozičního seznamu pro změny pořadí parametrů. Volající REST nejsou ovlivněni, protože parametry HTTP jsou klíčovány podle názvu. V jazyce C# upřednostněte pojmenované argumenty, například GetKnowledgeSourcesAsync(search: ..., pageSize: ...). V Python předejte možnosti seznamu jako argumenty klíčových slov.

3. Před aktualizací produkčního prostředí otestujte ověřování a odkazy Work IQ, stránkování pomocí kurzoru, deserializaci záznamů aktivit, řazení výsledků serveru MCP a volání generovaného klienta.

4. Pokud jste vytvořili náhradní zdroje znalostí Work IQ, odstraňte dřívější zdroje až poté, co migrace úspěšně projde všemi testy, vaše aktualizovaná aplikace bude nasazena a žádná znalostní báze nebude odkazovat na dřívější názvy.

2026-05-01-preview

Pokud migrujete z verze 2026-04-01 nebo 2025-11-01-preview, můžete přejít přímo na 2026-05-01-preview. Požadavky, odpovědi a trvalé objekty z těchto verzí zůstanou kompatibilní. Rozdíly spočívají v dalších funkcích a přejmenování jazykových sad SDK.

1. Aktualizujte verzi API na 2026-05-01-preview v REST požadavcích. Klienti sady SDK používají výchozí verzi rozhraní API balíčku, takže nemusíte předávat explicitní serviceVersion argument. Místo toho upgradujte na 2026-05-01-preview balíček sady SDK.

2. Pokud používáte sadu SDK pro Python nebo JavaScript, aktualizujte klienta retrieve na KnowledgeBaseRetrievalClient a místo zastaralého retrieve(...) volejte retrieveKnowledge(...). Úplné mapování tvarů v sadě SDK najdete v článku Aktualizace kódu a klientů pro verzi 2026-05-01-preview.

3. (Volitelné) Začněte používat nové 2026-05-01-preview funkce, jako jsou načítání se zohledněním aktuálnosti, limity počtu dokumentů pro jednotlivé zdroje i pro konečný výsledek, trvale uložené výchozí hodnoty načítání, CORS znalostní báze a metadata popisků citlivosti Purview v odpovědích na načítání. Žádná z těchto funkcí není nutná k tomu, aby stávající řešení fungovalo.

Aktualizace kódu a klientů pro verzi 2026-05-01-preview

Sady 2026-05-01-preview SDK zavádí změny tvaru kódu v podporovaných jazycích:

Po aktualizaci typů klienta spusťte celý proces, který vytvoří index, nahraje dokumenty, vytvoří zdroj znalostí, vytvoří znalostní bázi, odešle požadavek na načtení a odstraní vytvořené prostředky, abyste ověřili migraci v celém rozsahu.

2026-04-01

Pokud migrujete z verze 2025-11-01-preview, můžete migrovat přímo do 2026-04-01. Index a obsah zůstávají beze změny. Stačí aktualizovat schéma znalostní báze a tvar žádosti o načtení.

1. Migrace zdrojů znalostí
2. Migrace znalostní báze
3. Aktualizace žádosti o načtení
4. Aktualizace souhlasu s fakturací
5. Aktualizace kódu a klientů

Migrace zdrojů znalostí

V 2026-04-01 jsou typy zdrojů znalostí searchIndex, azureBlob, indexedOneLake a web obecně dostupné. Ostatní typy zdrojů znalostí zůstávají ve verzi Preview.

1. K získání aktuální definice použijte zdroje znalostí – Získání (REST API).

   GET {{search-endpoint}}/knowledge-sources/{{knowledge-source-name}}?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. V odpovědi určete, co se má přenést a co odebrat:

   • Pro searchIndex a web přeneste všechny hodnoty vlastností.

   • Pro azureBlob a indexedOneLake přenes všechny hodnoty vlastností, ale vynech ingestionPermissionOptions z ingestionParameters. Tato vlastnost není podporována v 2026-04-01souboru .

3. Pomocí zdrojů znalostí – Vytvoření nebo aktualizace (REST API) vytvořte nový zdroj znalostí s jedinečným názvem, 2026-04-01 verzí rozhraní API a hodnotami vlastností z předchozího kroku.

   Následující příklad ukazuje searchIndex zdroj znalostí. Použijte podobný vzor pro zdroje azureBlob, indexedOneLake, a web znalostí.

   PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
     "name": "{{new-knowledge-source-name}}",
     "description": "Knowledge source backed by a search index.",
     "kind": "searchIndex",
     "searchIndexParameters": {
       "searchIndexName": "{{index-name}}",
       "sourceDataFields": [
         { "name": "id" },
         { "name": "page_chunk" },
         { "name": "page_number" }
       ]
     }
   }
   

Migrace znalostní báze

Znalostní 2026-04-01 báze má jednodušší schéma než 2025-11-01-preview verze: udržuje knowledgeSources a zahodí nastavení generování odpovědí. Před vytvořením nového objektu zkontrolujte aktuální definici.

1. K získání aktuální definice použijte znalostní báze – Get (REST API).

   GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. V odpovědi určete, co se má přenést a co odebrat:

   • Všimněte si knowledgeSources odkazů. Přeneste je do nové znalostní báze.

   • Pokud je přítomen, odeberte outputMode, answerInstructions, a retrievalInstructions. Tyto vlastnosti nejsou podporovány v 2026-04-01.

   • Pokud vaše znalostní báze používá web zdroj znalostí, ponechte si models. Načítání webu vyžaduje souhrny založené na modelu. Pro všechny ostatní typy zdrojů znalostí odeberte models.

3. Pomocí znalostních bází – Vytvoření nebo aktualizace (REST API) vytvořte novou znalostní bázi s jedinečným názvem, 2026-04-01 verzí rozhraní API a pouze podporovanými vlastnostmi.

   PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
     "name": "{{new-knowledge-base-name}}",
     "description": "Minimal knowledge base for search index retrieval.",
     "knowledgeSources": [
       { "name": "{{new-knowledge-source-name}}" }
     ]
   }
   

Aktualizace žádosti o načtení

Požadavek 2026-04-01 na načtení má jiný tvar než verze Preview:

• Používejte intents místo messages.

• Používejte maxOutputSizeInTokens místo maxOutputSize.

• Pokud jsou přítomny, odeberte retrievalReasoningEffort a alwaysQuerySource. Tyto parametry nejsou podporovány v 2026-04-01souboru .

• V případě následných otázek odešlete novou žádost o vyhledání s novým zaměřením. 2026-04-01 neuchovává průběžný přepis zpráv.

Pro otestování výstupu znalostní báze pomocí dotazu použijte verzi 2026-04-01 rozhraní Knowledge Retrieval - Retrieve (REST API).

POST {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}/retrieve?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{query-text}}"
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "{{new-knowledge-source-name}}",
      "kind": "searchIndex",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.5
    }
  ],
  "maxRuntimeInSeconds": 30,
  "maxOutputSizeInTokens": 6000
}

Pokud odpověď obsahuje 200 OK kód HTTP, vaše znalostní báze úspěšně načetla obsah ze zdroje znalostí.

Aktualizace souhlasu s fakturací

Počínaje verzí rozhraní API 2026-04-01 je souhlas s účtováním za agentické načítání řízen vyhrazenou vlastností knowledgeRetrieval, která je oddělená od semanticSearch, jež se nyní vztahuje pouze na účtování za sémantický ranker. knowledgeRetrieval je vlastnost roviny správy, takže ji nastavíte prostřednictvím rozhraní REST API pro správu vyhledávání, nikoli rozhraní REST API vyhledávací služby.

Použijte nejnovější verzi ukázky Služby – Vytvořit nebo aktualizovat (REST API) k nastavení knowledgeRetrieval na vaší vyhledávací službě.

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{management-access-token}}

{
  "properties": {
    "knowledgeRetrieval": "standard"
  }
}

Platné hodnoty a podrobnosti o fakturaci najdete v tématu Povolení nebo zakázání fakturace pro agentické načítání.

Aktualizace kódu a klientů pro 1. 4. 2026

Dokončení migrace:

1. Aktualizujte volání klienta tak, aby používala 2026-04-01 verzi rozhraní API.

2. Aktualizujte všechny pevně zakódované názvy znalostní báze nebo zdroje znalostí v kódu tak, aby odkazovaly na nové objekty vytvořené během migrace.

3. Pokud jste migrovali zdroje znalostí azureBlob nebo indexedOneLake, aktualizujte kód nebo skripty, které odkazují na přidružený index, indexer, zdroj dat nebo sadu dovedností podle názvu, aby směřovaly na nové objekty.

4. Aktualizujte kód, který zpracovává načítané odpovědi. Odpovědi vracejí extrahovaný obsah pro založení s activity a references, nikoli syntetizované odpovědi.

5. Odstraňte objekty náhledu až po úplném ověření a nasazení nových objektů.

2025-11-01-preview

Pokud migrujete z verze 2025-08-01-preview, "agent znalostí" je přejmenován na "znalostní bázi" a několik vlastností je přemístěno do různých objektů a úrovní v rámci definice objektu.

1. Aktualizace zdrojů znalostí searchIndex
2. Aktualizace zdrojů znalostí AzureBlob
3. Nahraďte agenta znalostí za znalostní bázi
4. Aktualizace požadavku na načtení a odeslání dotazu pro otestování aktualizací
5. Aktualizace kódu klienta

Aktualizace zdroje znalostí searchIndex

Tento postup vytvoří nový 2025-11-01-previewsearchIndex zdroj znalostí na stejné funkční úrovni jako předchozí 2025-08-01 verze. Samotný základní index nevyžaduje žádné aktualizace.

1. Seznam všech zdrojů znalostí podle názvu a vyhledání zdroje znalostí

   ### List all knowledge sources by name
   GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. Získejte aktuální definici pro kontrolu existujících vlastností.

   ### Get a specific knowledge source
   GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

   Odpověď by měla být podobná následujícímu příkladu.

   {
        "name": "search-index-ks",
        "kind": "searchIndex",
        "description": "This knowledge source pulls from a search index created using the 2025-08-01-preview.",
        "encryptionKey": null,
        "searchIndexParameters": {
        "searchIndexName": "earth-at-night-idx",
        "sourceDataSelect": "id, page_chunk, page_number"
        },
        "azureBlobParameters": null
   }
   

3. Vytvořte žádost o vytvoření zdroje znalostí jako základ pro migraci.

   Začněte s 08-01-preview JSON.

   POST {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "search-index-ks",
       "kind": "searchIndex",
       "description": "A sample search index knowledge source",
       "encryptionKey": null,
       "searchIndexParameters": {
           "searchIndexName": "my-search-index",
           "sourceDataSelect": "id, page_chunk, page_number"
     }
   }
   

   Proveďte následující aktualizace pro migraci 2025-11-01-preview:

   • Dejte zdroji znalostí nový název.

   • Změňte verzi rozhraní API na 2025-11-01-preview.

   • Přejmenujte sourceDataSelect na sourceDataFields a změňte řetězec na pole s páry název-hodnota pro každé pole, které chcete načíst dotazem. Jedná se o pole, která se mají vrátit do výsledků hledání, podobně jako select klauzule v klasickém dotazu.

4. Zkontrolujte aktualizace a pak odešlete žádost o vytvoření objektu.

   PUT {{search-endpoint}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "search-index-ks-11-01",
       "kind": "searchIndex",
       "description": "knowledge source migrated to 2025-11-01-preview",
       "encryptionKey": null,
       "searchIndexParameters": {
           "searchIndexName": "my-search-index",
           "sourceDataFields": [
               { "name": "id" }, { "name": "page_chunk" }, { "name": "page_number" }
           ]
       }
   }
   

Nyní máte migrovaný searchIndex zdroj znalostí, který je zpětně kompatibilní s předchozí verzí a využívá správné specifikace vlastností pro 2025-11-01-preview.

Odpověď obsahuje úplnou definici nového objektu. Další informace o nových vlastnostech dostupných pro tento typ zdroje znalostí, které teď můžete provádět prostřednictvím aktualizací, najdete v tématu Vytvoření zdroje znalostí indexu vyhledávání.

Aktualizace zdroje znalostí AzureBlob

Tento postup vytvoří nový 2025-11-01-previewazureBlob zdroj znalostí na stejné funkční úrovni jako předchozí 2025-08-01 verze. Vytvoří novou sadu vygenerovaných objektů: zdroj dat, sada schopností, indexer, index.

1. Seznam všech zdrojů znalostí podle názvu a vyhledání zdroje znalostí

   ### List all knowledge sources by name
   GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. Získejte aktuální definici pro kontrolu existujících vlastností.

   ### Get a specific knowledge source
   GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

   Pokud váš pracovní postup obsahuje model, měla by odpověď vypadat podobně jako v následujícím příkladu. Všimněte si, že odpověď obsahuje názvy vygenerovaných objektů. Tyto objekty jsou plně nezávislé na zdroji znalostí a zůstávají funkční i v případě, že aktualizujete nebo odstraníte jejich zdroj znalostí.

    {
      "name": "azure-blob-ks",
      "kind": "azureBlob",
      "description": "A sample azure blob knowledge source.",
      "encryptionKey": null,
      "searchIndexParameters": null,
      "azureBlobParameters": {
        "connectionString": "<redacted>",
        "containerName": "blobcontainer",
        "folderPath": null,
        "disableImageVerbalization": false,
        "identity": null,
        "embeddingModel": {
          "name": "embedding-model",
          "kind": "azureOpenAI",
          "azureOpenAIParameters": {
            "resourceUri": "<redacted>",
            "deploymentId": "text-embedding-3-large",
            "apiKey": "<redacted>",
            "modelName": "text-embedding-3-large",
            "authIdentity": null
          },
          "customWebApiParameters": null,
          "aiServicesVisionParameters": null,
          "amlParameters": null
        },
        "chatCompletionModel": {
          "kind": "azureOpenAI",
          "azureOpenAIParameters": {
            "resourceUri": "<redacted>",
            "deploymentId": "gpt-4o-mini",
            "apiKey": "<redacted>",
            "modelName": "gpt-4o-mini",
            "authIdentity": null
          }
    },
        "ingestionSchedule": null,
        "createdResources": {
          "datasource": "azure-blob-ks-datasource",
          "indexer": "azure-blob-ks-indexer",
          "skillset": "azure-blob-ks-skillset",
          "index": "azure-blob-ks-index"
        }
      }
    }
   

3. Vytvořte žádost o vytvoření zdroje znalostí jako základ pro migraci.

   Začněte s 08-01-preview JSON.

   POST {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "azure-blob-ks",
       "kind": "azureBlob",
       "description": "A sample azure blob knowledge source.",
       "encryptionKey": null,
       "azureBlobParameters": {
           "connectionString": "<redacted>",
           "containerName": "blobcontainer",
           "folderPath": null,
           "disableImageVerbalization": false,
           "identity": null,
           "embeddingModel": {
               "name": "embedding-model",
               "kind": "azureOpenAI",
               "azureOpenAIParameters": {
               "resourceUri": "<redacted>",
               "deploymentId": "text-embedding-3-large",
               "apiKey": "<redacted>",
               "modelName": "text-embedding-3-large",
               "authIdentity": null
               },
               "customWebApiParameters": null,
               "aiServicesVisionParameters": null,
               "amlParameters": null
           },
           "chatCompletionModel": null,
           "ingestionSchedule": null
     }
   }
   

   Proveďte následující aktualizace pro migraci 2025-11-01-preview:

   • Dejte zdroji znalostí nový název.

   • Změňte verzi rozhraní API na 2025-11-01-preview.

   • Přidejte ingestionParameters jako kontejner pro následující podřízené vlastnosti: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. Zkontrolujte aktualizace a pak odešlete žádost o vytvoření objektu. Pro indexovací kanál jsou vytvořeny nové generované objekty.

   PUT {{search-endpoint}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "azure-blob-ks",
       "kind": "azureBlob",
       "description": "A sample azure blob knowledge source",
       "encryptionKey": null,
       "azureBlobParameters": {
           "connectionString": "{{blob-connection-string}}",
           "containerName": "blobcontainer",
           "folderPath": null,
           "ingestionParameters": {
               "embeddingModel": {
                   "kind": "azureOpenAI",
                   "azureOpenAIParameters": {
                       "deploymentId": "text-embedding-3-large",
                       "modelName": "text-embedding-3-large",
                       "resourceUri": "{{aoai-endpoint}}",
                       "apiKey": "{{aoai-key}}"
                   }
               },
               "chatCompletionModel": null,
               "disableImageVerbalization": false,
               "ingestionSchedule": null,
               "contentExtractionMode": "minimal"
           }
       }
   }
   

Nyní máte migrovaný azureBlob zdroj znalostí, který je zpětně kompatibilní s předchozí verzí a využívá správné specifikace vlastností pro 2025-11-01-preview.

Odpověď obsahuje úplnou definici nového objektu. Další informace o nových vlastnostech dostupných pro tento typ zdroje znalostí, které teď můžete provádět prostřednictvím aktualizací, najdete v tématu Vytvoření zdroje znalostí objektů blob.

Nahrazení znalostního agenta znalostní bází

1. Znalostní báze vyžadují zdroj znalostí. Než začnete, ujistěte se, že máte zdroj znalostí zaměřený na 2025-11-01-preview.

2. Získejte aktuální definici pro kontrolu existujících vlastností.

   ### Get a knowledge agent by name
   GET {{search-endpoint}}/agents/earth-at-night?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

   Odpověď by měla být podobná následujícímu příkladu.

   {
     "name": "earth-at-night",
     "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
     "retrievalInstructions": null,
     "requestLimits": null,
     "encryptionKey": null,
     "knowledgeSources": [
       {
         "name": "earth-at-night",
         "alwaysQuerySource": null,
         "includeReferences": null,
         "includeReferenceSourceData": null,
         "maxSubQueries": null,
         "rerankerThreshold": 2.5
       }
     ],
     "models": [
       {
         "kind": "azureOpenAI",
         "azureOpenAIParameters": {
           "resourceUri": "<redacted>",
           "deploymentId": "gpt-5-mini",
           "apiKey": "<redacted>",
           "modelName": "gpt-5-mini",
           "authIdentity": null
         }
       }
     ],
     "outputConfiguration": {
       "modality": "answerSynthesis",
       "answerInstructions": null,
       "attemptFastPath": false,
       "includeActivity": null
     }
   }
   

3. Formulujte žádost o vytvoření znalostní báze jako základ pro migraci.

   Začněte s 08-01-preview JSON.

   PUT {{search-endpoint}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "earth-at-night",
       "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
       "retrievalInstructions": null,
       "encryptionKey": null,
       "knowledgeSources": [
           {
             "name": "earth-at-night",
             "alwaysQuerySource": null,
             "includeReferences": null,
             "includeReferenceSourceData": null,
             "maxSubQueries": null,
             "rerankerThreshold": 2.5
           }
       ],
       "models": [
           {
               "kind": "azureOpenAI",
               "azureOpenAIParameters": {
                   "resourceUri": "<redacted>",
                   "apiKey": "<redacted>",
                   "deploymentId": "gpt-5-mini",
                   "modelName": "gpt-5-mini"
               }
           }
       ],
       "outputConfiguration": {
           "modality": "answerSynthesis"
       }
   }
   

   Proveďte následující aktualizace pro migraci 2025-11-01-preview:

   • Nahraďte koncový bod: /knowledgebases/{{knowledge-base-name}}. Dejte znalostní bázi jedinečný název.

   • Změňte verzi rozhraní API na 2025-11-01-preview.

   • Odstranit requestLimits. Vlastnosti maxRuntimeInSeconds a maxOutputSize jsou nyní uvedeny přímo v požadavku na načtení.

   • Aktualizace knowledgeSources:

     • Odstraňte a nahraďte jej prvkem retrievalReasoningEffort (viz maxSubQueries).

   • Přesuňte alwaysQuerySource, includeReferenceSourceData, includeReferences a rerankerThreshold do sekce knowledgeSourceParams akce načtení.

   • Žádné změny pro models.

   • Aktualizace outputConfiguration:

     • Nahradit outputConfiguration za outputMode.

     • Odstranit attemptFastPath. Už neexistuje. Ekvivalentní chování je implementováno pomocí nastavení retrievalReasoningEffort na minimální hodnotu (viz Nastavení úsilí při uvažování pro načítání (Preview)).

     • Pokud je modalita nastavena na answerSynthesis hodnotu, ujistěte se, že jste nastavili úsilí při získávání dat na nízkou (výchozí) nebo střední úroveň.

   • Přidejte ingestionParameters jako požadavek na vytvoření 2025-11-01-preview zdroje znalostí AzureBlob.

4. Zkontrolujte aktualizace a pak odešlete žádost o vytvoření objektu. Pro indexovací kanál jsou vytvořeny nové generované objekty.

    PUT {{search-endpoint}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
    Authorization: Bearer {{search-access-token}}
    Content-Type: application/json
   
    {
      "name": "earth-at-night-11-01",
      "description": "A sample knowledge base at the same functional level as the previous knowledge agent.",
      "retrievalInstructions": null,
      "encryptionKey": null,
      "knowledgeSources": [
        {
            "name": "earth-at-night-ks"
        }
      ],
      "models": [
        {
          "kind": "azureOpenAI",
          "azureOpenAIParameters": {
              "resourceUri": "<redacted>",
              "apiKey": "<redacted>",
              "deploymentId": "gpt-5-mini",
              "modelName": "gpt-5-mini"
            }
        }
      ],
      "retrievalReasoningEffort": null,
      "outputMode": "answerSynthesis",
      "answerInstructions": "Provide a concise and accurate answer based on the retrieved information."
    }
   

Teď máte znalostní bázi místo agenta znalostí a objekt je zpětně kompatibilní s předchozí verzí.

Odpověď obsahuje úplnou definici nového objektu. Další informace o nových vlastnostech dostupných pro znalostní bázi, kterou teď můžete provádět prostřednictvím aktualizací, najdete v tématu Vytvoření znalostní báze.

Aktualizujte a otestujte načítání aktualizací 2025-11-01-preview

Požadavek na načtení se pro 2025-11-01-preview upravuje tak, aby podporoval více variant, včetně jednodušší varianty požadavku, která minimalizuje zpracování pomocí LLM. Další informace o načítání v této verzi Preview najdete v tématu Načtení dat pomocí znalostní báze. Tato část vysvětluje, jak aktualizovat kód.

1. /agents/retrieve Změňte koncový bod na /knowledgebases/retrieve.

2. Změňte verzi rozhraní API na 2025-11-01-preview.

3. Žádné změny v low nejsou nutné, pokud používáte úroveň úsilí při uvažování pro retrieval medium nebo messages. Nahraďte messages položkou minimal, pokud používáte uvažování (viz intents).

4. Upravit knowledgeSourceParams tak, aby zahrnovaly všechny vlastnosti, které byly odebrány z agenta: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

5. Pokud jste používali retrievalReasoningEffort, přidejte minimum nastavený na attemptFastPath. Pokud jste používali maxSubQueries, už neexistuje. Pomocí nastavení retrievalReasoningEffort můžete určit zpracování poddotazů (viz Nastavení míry uvažování při načítání (Preview)).

Chcete-li otestovat výstup vaší znalostní báze pomocí dotazu, použijte 2025-11-01-preview z Knowledge Retrieval – Retrieve (REST API).

### Send a query to the knowledge base
POST {{search-endpoint}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What are some light sources on the ocean at night" }
            ]
        }
    ],
    "includeActivity": true,
    "retrievalReasoningEffort": { "kind": "medium" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

Pokud odpověď obsahuje 200 OK kód HTTP, vaše znalostní báze úspěšně načetla obsah ze zdroje znalostí.

Aktualizace kódu a klientů pro verzi 2025-11-01-preview

Migraci dokončíte pomocí těchto kroků čištění:

1. Pouze u zdrojů znalostí typu blob aktualizujte klienty tak, aby používali nový index. Pokud máte kód nebo skript, který spouští indexer nebo odkazuje na zdroj dat, index nebo sadu dovedností, nezapomeňte aktualizovat odkazy na nové objekty.

2. Nahraďte všechny odkazy na agenty knowledgeBases v konfiguračních souborech, kódu, skriptech a testech.

3. Aktualizujte volání klienta tak, aby používalo 2025-11-01-preview.

4. Vymažte nebo znovu vygenerujte definice uložené v mezipaměti vytvořené pomocí starých obrazců.

2025-08-01-preview

Pokud jste vytvořili agenta znalostí pomocí 2025-05-01-preview, definice vašeho agenta obsahuje in-line targetIndexes pole a volitelnou defaultMaxDocsForReranker vlastnost.

Počínaje verzí rozhraní API 2025-08-01-preview nahrazují opakovaně použitelné zdroje znalostí targetIndexes a defaultMaxDocsForReranker již není podporováno. Tyto zásadní změny vyžadují, abyste:

1. Získání aktuální targetIndexes konfigurace
2. Vytvoření ekvivalentního zdroje znalostí
3. Aktualizujte agenta tak, aby místo toho používal knowledgeSourcestargetIndexes
4. Odeslání dotazu k otestování načtení
5. Odebrání kódu, který používá targetIndexes a aktualizuje klienty

Získání aktuální konfigurace

Pokud chcete načíst definici agenta, použijte 2025-05-01-preview rozhraní Knowledge Agents – Get (REST API).

@search-endpoint = <search-endpoint>
@agent-name = <agent-name>
@search-access-token = <search-access-token>

### Get agent definition
GET {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    Authorization: Bearer {{search-access-token}}

Odpověď by měla být podobná následujícímu příkladu. Zkopírujte hodnoty indexName, defaultRerankerThreshold a defaultIncludeReferenceSourceData pro použití v nadcházejících krocích. defaultMaxDocsForReranker je zastaralý, takže můžete jeho hodnotu ignorovat.

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "my-knowledge-agent",
  "description": "My description of the agent",
  "targetIndexes": [
    {
      "indexName": "my-index",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ]
}

Vytvoření zdroje znalostí

Chcete-li vytvořit searchIndex zdroj znalostí, použijte 2025-08-01-preview z Zdroje znalostí – vytvoření (REST API). Nastavte searchIndexName na hodnotu, kterou jste předtím zkopírovali.

@source-name = <source-name>

### Create a knowledge source
PUT {{search-endpoint}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index"
        }
    }

Předchozí příklad vytváří zdroj znalostí, který představuje jeden index, ale můžete ho zaměřit na více indexů nebo na objekt blob v Azure. Další informace najdete v tématu Vytvoření zdroje znalostí.

Aktualizace agenta

Chcete-li v definici svého agenta nahradit targetIndexes za knowledgeSources, použijte 2025-08-01-preview z Agenti znalostí – Vytvořit nebo aktualizovat (REST API). Nastavte rerankerThreshold a includeReferenceSourceData na hodnoty, které jste předtím zkopírovali.

### Replace targetIndexes with knowledgeSources
POST {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{agent-name}}",
        "knowledgeSources": [
            {
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5,
                "includeReferenceSourceData": true
            }
        ]
    }

Předchozí příklad aktualizuje definici tak, aby odkazovala na jeden zdroj znalostí, ale můžete odkazovat na více zdrojů znalostí. Můžete také použít jiné vlastnosti k řízení chování načítání, například alwaysQuerySource. Další informace najdete v tématu Vytvoření agenta znalostí.

Otestujte načítání aktualizací pro verzi 2025-08-01-Preview

Chcete-li otestovat výstup agenta pomocí dotazu, použijte 2025-08-01-preview z Knowledge Retrieval - Retrieve (REST API).

### Send a query to the agent
POST {{search-endpoint}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<query-text>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

Pokud má 200 OK odpověď kód HTTP, váš agent úspěšně načetl obsah ze zdroje znalostí.

Aktualizace kódu a klientů pro verzi 2025-08-01-preview

Migraci dokončíte pomocí těchto kroků čištění:

• Nahraďte všechny targetIndexes odkazy v konfiguračních knowledgeSources souborech, kódu, skriptech a testech.
• Aktualizujte volání klienta tak, aby používalo 2025-08-01-preview.
• Vymažte nebo znovu vygenerujte definice agenta uložené v mezipaměti vytvořené pomocí starého obrazce.

Změny specifické pro verzi

Tato část se zabývá zásadními a nezásadními změnami v následujících verzích rozhraní API:

• 2026-08-01-preview
• 2026-05-01-preview
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

Verze 2026-08-01-preview vychází z verze 2026-05-01-preview a obsahuje zásadní změny pro aplikace, které používají zdroje znalostí Iq, stránkování seznamů založené na posunu, záznamy aktivit založené na modelu, zpracování výsledků serveru MCP nebo poziční generovaná volání klienta.

Pokud chcete zkontrolovat referenční dokumentaci k rozhraní REST API pro tuto verzi, vyberte 2026-08-01-preview filtr verze rozhraní API v horní části stránky.

2026-05-01-preview

2026-05-01-preview přidává znalostní bázi, zdroj znalostí a funkce načítání nad verzí 2025-11-01-preview bez odebrání dříve uložených vlastností. Stávající znalostní báze a zdroje znalostí, které jste vytvořili v dřívějších verzích Preview, nadále fungují. Tato verze především zpřístupňuje nové funkce a ruší několik omezení, která platila pouze ve verzi Preview.

Pokud chcete zkontrolovat referenční dokumentaci k rozhraní REST API pro tuto verzi, vyberte 2026-05-01-preview filtr verze rozhraní API v horní části stránky.

2026-04-01

2026-04-01 je první stabilní verze API pro agentní vyhledávání. Vytvoří minimální, extraktivní smlouvu o načítání a odebere možnosti plánování dotazů založených na zprávách z doby náhledu a možnosti syntézy odpovědí.

Pokud chcete zkontrolovat referenční dokumentaci k rozhraní REST API pro tuto verzi, vyberte 2026-04-01 filtr verze rozhraní API v horní části stránky.

2025-11-01-preview

Pokud chcete zkontrolovat referenční dokumentaci k rozhraní REST API pro tuto verzi, vyberte 2025-11-01-preview filtr verze rozhraní API v horní části stránky.

2025-08-01-preview

Pokud chcete zkontrolovat referenční dokumentaci k rozhraní REST API pro tuto verzi, vyberte 2025-08-01-preview filtr verze rozhraní API v horní části stránky.

2025-05-01-preview

Tato verze rozhraní API zavádí agentní vyhledávání a znalostní agenty. Každá definice agenta vyžaduje targetIndexes pole, které určuje jeden index a volitelné vlastnosti, například defaultRerankerThreshold a defaultIncludeReferenceSourceData.

Pokud chcete zkontrolovat referenční dokumentaci k rozhraní REST API pro tuto verzi, vyberte 2025-05-01-preview filtr verze rozhraní API v horní části stránky.

Související obsah

• Agentic vyhledávání v Azure AI Vyhledávač
• Vytvoření znalostní báze
• Dotazování znalostní báze