Ügynöki lekérési kód áttelepítése a legújabb verzióra

Ha az ügynöki lekérési kód egy korábbi API-verziót céloz meg, ez a cikk bemutatja, hogy mikor és hogyan migrálhat egy újabb verzióra. Emellett az ügynöki lekérést támogató összes API-verzió kompatibilitástörő és nem törhető módosításait is ismerteti.

A migrálási utasítások célja, hogy segítsenek egy meglévő megoldás futtatásában egy újabb API-verzión. A cikkben található utasítások segítenek kezelni az API-szinten bekövetkező kompatibilitástörő változásokat, hogy az alkalmazás a korábbiakhoz hasonlóan fusson. Ha segítségre van szüksége az új funkciók hozzáadásához, kezdje a Az Azure AI Keresés újdonságaival.

Mikor kell migrálni?

Az ügynöki lekérést támogató legtöbb verzió kompatibilitástörő változásokat vezetett be. Az API verzióértékének megőrzésével továbbra is változatlanul futtathatja a régebbi kódot, de a hibajavítások, a fejlesztések és az újabb funkciók előnyeinek kihasználásához frissítenie kell a kódot.

Ha a kód egy előzetes verziót céloz meg, javasoljuk, hogy csak akkor migráljon a legújabb stabil verzióra, ha a használati esetet teljes mértékben támogatja.2026-04-01 Ha válaszszintézisre, jelentős érvelési erőfeszítésre vagy több fordulós beszélgetésekre támaszkodik, a migrálás előtt tekintse át a megtörő és nem megtörő változtatásokat. Ezek a képességek előzetes verzióban maradnak.

Az áttelepítés előtt

• A változtatások körének megértéséhez tekintse át az egyes verziók kompatibilitástörő és nem kompatibilitástörő módosításait.

• A támogatott áttelepítési útvonal növekményes. Ha a kód célverziója a(z) 2025-05-01-preview, először migráljon a(z) 2025-08-01-preview verzióra, majd haladjon végig az összes következő verzión, amíg el nem éri a célverziót.

• Az egymás melletti migráláshoz hozzon létre egyedileg elnevezett objektumokat, amelyek megvalósítják az előző verzió viselkedését. Ez a módszer megőrzi a meglévő objektumokat a csere fejlesztése és tesztelése során. Ha egy objektum támogatja a helyben történő frissítést, a verzióspecifikus lépések ezt a beállítást hívják fel.

• Az egyes migrált objektumok esetében először az aktuális definíciót kell lekérte a keresési szolgáltatásból, hogy a meglévő tulajdonságokat áttekinthesse az új objektum megadása előtt.

• A régebbi verziókat csak a migrálás teljes tesztelése és üzembe helyezése után törölje.

Migrálás

Ez a szakasz a következő API-verziók áttelepítési lépéseit ismerteti:

• 2026-08-01-preview
• 2026-05-01-előzetes
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

Ha a 2026-05-01-preview verziójú előzetes kiadásról migrál, közvetlenül áttérhet a 2026-08-01-preview verzióra. Ehhez a migráláshoz frissíteni kell a Work IQ-tudásforrásokat, a listák lapozását, a válaszfeldolgozást, az MCP-kiszolgáló eszközeit és az érintett generált ügyfélhívásokat.

1. A Work IQ tudásbázisának migrálása
2. Listalapozás frissítése
3. A lekérési válasz feldolgozásának frissítése
4. Kód és ügyfelek frissítése

A Work IQ tudásbázisának migrálása

A Work IQ-tudásbázis tudásbázisának áttelepítése az új hitelesítési konfigurációba:

1. Exportálja a jelenlegi definícióját.

2. Frissítse a meglévő tudásbázist a Tudásbázisok – Létrehozás vagy frissítés használatával, vagy hozzon létre egy egyedi névvel rendelkező cserét az egymás melletti migráláshoz.

3. Használja az 2026-08-01-preview API-verziót, és konfigurálja workIQParameters.entraAppAuthentication. A(z) applicationId és federatedCredentialId tulajdonság megadása kötelező. A tenantId tulajdonság nem kötelező, és alapértelmezés szerint a keresési szolgáltatás bérlője.

4. Ha létrehozott egy helyettesítőt, frissítsen minden olyan tudásbázist, amely a korábbi tudásforrásra hivatkozik, hogy a helyettesítő nevét használja.

5. Frissítse a lekérési kérelmeket, hogy a felhasználó helyességi érvényesítést adjon át a x-ms-query-work-iq-source-authorization fejlécben.

A beállításhoz és példákhoz lásd: Create a Work IQ knowledge source (előzetes verzió).

Listalapozás frissítése

Az eltolásalapú lapozás kurzoralapú lapozásra való lecserélése:

1. Távolítsa el a $skip, $count és $top elemeket a tudásforráslista-kérelmekből. Állítsa be pageSize 1 és 3000 között az oldalméret szabályozásához. Ha kihagyja, a szolgáltatás kiválasztja az oldalméretet.

2. A név szerinti szűréshez állítsa be search és searchType. Az egyetlen támogatott searchType érték a(z) prefix, amely egyben az alapértelmezett érték is. A következő kérés legfeljebb 100 olyan tudásbázist ad vissza, amelyek neve a következővel contosokezdődik: .

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

   Referencia:Tudásbázisok – Lista

3. Ha a válasz tartalmaz @odata.nextLink, küldje el pontosan a visszaadott URL-címet. Ne elemezd vagy módosítsd a folytatási állapotot.

A lekérési válasz feldolgozásának frissítése

Az új Munkahelyi IQ-referencia és a modell által támogatott tevékenységalakzatok feldolgozása:

1. Távolítsa el az attributions, WorkIQAttribution és seeMoreWebUrl elemekre vonatkozó függőségeket. Olvassa be a bizalmassági címke metaadatait a searchSensitivityLabelInfo Work IQ-referenciából.

2. A lekérdezéstervezési, válaszszintézis- és webesösszegzés-tevékenységrekordokban olvassa be a modelName és deploymentId elemeket a beágyazott model objektumból. A beágyazott objektum és mindkét tulajdonság nem kötelező.

Az alábbi töredékek a válaszalakzat változásait mutatják.

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

Ebben 2026-08-01-previewaz esetben ugyanezek a töredékek a következő alakzatot használják:

{
  "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>"
      }
    }
  ]
}

A kód és az ügyfélalkalmazások frissítése a 2026-08-01-preview verzióhoz

A migrálás befejezéséhez:

1. Minden MCP-kiszolgáló tools elemnél cserélje le a(z) inclusionMode elemet erre: resultsProcessing. Rendelje hozzá a(z) reranked elemet a(z) rerank elemhez, és a(z) always elemet a(z) none elemhez. Az rerank érték az alapértelmezett érték. A(z) none érték megkerüli az újrarangsorolást, és megőrzi az eszköz eredeti eredménysorrendjét. A beállításhoz tekintse meg az MCP-kiszolgálói tudásbázis eszközeinek konfigurálása című témakört.

2. Ha Azure SDK-t használ, telepítsen egy 2026-08-01-preview támogatását biztosító csomagot, és tekintse át a pozicionális argumentumokat használó hívásokat a paramétersorrend változásai szempontjából. A REST-hívókat ez nem érinti, mert a HTTP-paramétereket a nevük alapján azonosítják. A C#-ban előnyben részesítse a névvel ellátott argumentumokat, például GetKnowledgeSourcesAsync(search: ..., pageSize: ...). A Python adja meg a listabeállításokat kulcsszóargumentumként.

3. Az éles környezet frissítése előtt tesztelje a Work IQ-hitelesítést és -referenciákat, a kurzoralapú lapozást, a tevékenységrekordok deszerializálását, az MCP-kiszolgáló eredményeinek rendezését és a generált klienshívásokat.

4. Ha helyettesítő Munkahelyi IQ-tudásforrásokat hozott létre, törölje a korábbi forrásokat csak azután, hogy az áttelepítés minden teszten megfelelt, a frissített alkalmazás üzembe lett helyezve, és a tudásbázis nem hivatkozik a korábbi nevekre.

2026-05-01-előzetes

Ha a 2026-04-01 vagy a 2025-11-01-preview verzióról migrál, közvetlenül a 2026-05-01-preview verzióra válthat. Az ezekből a verziókból származó kérések, válaszok és megőrzött objektumok továbbra is kompatibilisek maradnak. A különbségek az additív funkciók és a nyelvi SDK-átnevezések.

1. Frissítse a REST-kérelmekben használt API-verziót erre: 2026-05-01-preview. Az SDK-ügyfelek a csomag alapértelmezett API-verzióját használják, így nem kell explicit serviceVersion argumentumot átadniuk. Ehelyett frissítsen az 2026-05-01-preview SDK-csomagra.

2. Ha a Python vagy a JavaScript SDK-t használja, frissítse a retrieve klienst erre: KnowledgeBaseRetrievalClient, és a régi retrieve(...) helyett hívja meg ezt: retrieveKnowledge(...). A teljes SDK-alakzatleképezést lásd: Kód és ügyfelek frissítése 2026-05-01 előzetes verzióhoz.

3. (Nem kötelező) Fogadja el az új 2026-05-01-preview funkciókat, például a frissesség-tudatos lekérést, a forrásonkénti és a végső eredményű dokumentumkorlátokat, a tartós lekérési alapértelmezett értékeket, a tudásbázis CORS-t és a Purview bizalmassági címkével ellátott metaadatokat a válaszok lekéréséhez. A meglévő megoldás működéséhez egyik funkció sem szükséges.

Frissítse a kódot és az ügyfélprogramokat a 2026-05-01-preview verzióhoz

Az 2026-05-01-preview SDK-k kódalakzat-módosításokat vezetnek be a támogatott nyelvek között:

Az ügyfélalakzatok frissítése után futtassa a teljes folyamatot, amely létrehozza az indexet, feltölti a dokumentumokat, létrehoz egy tudásbázist, lekér egy kérést, és megtisztítja az erőforrásokat az áttelepítés befejezésének megerősítéséhez.

2026-04-01

Ha a(z) 2025-11-01-preview verzióról migrál, közvetlenül a(z) 2026-04-01 verzióra migrálhat. Az index és a tartalom változatlan marad. Csak a tudásbázissémát és a lekérési kérelem alakzatát kell frissítenie.

1. Tudásbázisok migrálása
2. A tudásbázis migrálása
3. A lekérési kérelem frissítése
4. Számlázási hozzájárulás frissítése
5. Kód és ügyfelek frissítése

Tudásbázisok migrálása

Ebben 2026-04-01az esetben a searchIndex, azureBlob, indexedOneLakeés web a tudásforrás-típusok általánosan elérhetők. Más tudásbázistípusok továbbra is előzetes verzióban maradnak.

1. A Tudásbázisok – Get (REST API) használatával szerezze be az aktuális definíciót.

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

2. A válaszban határozza meg, hogy mit kell továbbvinni, és mit kell eltávolítani:

   • A searchIndex és web esetén vigye át az összes tulajdonságértéket.

   • A azureBlob és indexedOneLake esetében vigyen át minden tulajdonságértéket, de hagyja ki ingestionPermissionOptions-t ingestionParameters-ból. Ez a tulajdonság nem támogatott a 2026-04-01.

3. A Tudásbázisok – Létrehozás vagy frissítés (REST API) használatával hozzon létre egy új, egyedi nevet, API-verziót 2026-04-01 és az előző lépésben szereplő tulajdonságértékeket tartalmazó tudásbázist.

   Az alábbi példa egy tudásbázist searchIndex mutat be. Hasonló mintát használjon a azureBlob, indexedOneLake és web tudásforrásokhoz.

   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" }
       ]
     }
   }
   

A tudásbázis migrálása

A 2026-04-01 tudásbázis a verziónál egyszerűbb sémával rendelkezik: megtartja knowledgeSources és elveti a 2025-11-01-preview válaszgenerálási beállításokat. Új objektum létrehozása előtt tekintse át az aktuális definíciót.

1. A Tudásbázisok – Get (REST API) használatával szerezze be az aktuális definíciót.

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

2. A válaszban határozza meg, hogy mit kell továbbvinni, és mit kell eltávolítani:

   • Jegyezze fel a knowledgeSources hivatkozásokat. Ezeket továbbvinni az új tudásbázisba.

   • Ha jelen van, távolítsa el az outputMode, answerInstructions és retrievalInstructions. Ezek a tulajdonságok nem támogatottak a 2026-04-01.

   • Ha a tudásbázis egy web tudásforrást használ, tartsa meg models. A webes lekéréshez modellalapú összegzés szükséges. Minden más tudásforrástípus esetén távolítsa el a models szöveget.

3. A Tudásbázisok – Létrehozás vagy frissítés (REST API) használatával hozzon létre egy új tudásbázist egyedi névvel, az 2026-04-01 API-verzióval és csak a támogatott tulajdonságokkal.

   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}}" }
     ]
   }
   

A lekérési kérelem frissítése

A 2026-04-01 lekérési kérelemnek más alakja van, mint az előzetes verziónak:

• Használja intents ahelyett, hogy messages.

• Használja maxOutputSizeInTokens ahelyett, hogy maxOutputSize.

• Ha van ilyen, távolítsa el retrievalReasoningEffort és alwaysQuerySource. Ezek a paraméterek nem támogatottak a 2026-04-01.

• További kérdések esetén küldjön egy új lekéréses kérelmet egy új szemantikai szándékkal. 2026-04-01 nem tart fenn futó üzenetek átiratát.

A tudásbázis kimenetének lekérdezéssel való teszteléséhez használja a 2026-04-01Knowledge Retrieveal – Retrieve (REST API) verziót.

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
}

Ha a válasz http-kóddal 200 OK rendelkezik, a tudásbázis sikeresen lekérte a tartalmat a tudásbázisból.

Számlázási hozzájárulás frissítése

A 2026-04-01 API-verziótól kezdve az ágensalapú lekérés számlázási beleegyezését egy dedikált knowledgeRetrieval tulajdonság szabályozza, amely elkülönül a semanticSearch tulajdonságtól, és ez utóbbi mostantól csak a szemantikai rangsoroló számlázására vonatkozik. knowledgeRetrieval egy felügyeletisík-tulajdonság, ezért a Search Management REST API-val kell beállítania, nem pedig a Keresési szolgáltatás REST API-jával.

Használja a Szolgáltatások – Létrehozás vagy frissítés (REST API) legújabb előzetes verzióját a keresési szolgáltatás beállításához knowledgeRetrieval .

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"
  }
}

Az érvényes értékekről és a számlázási adatokról az ügynöki lekéréses számlázás engedélyezése vagy letiltása című témakörben olvashat.

Kód és ügyfelek frissítése 2026-04-01-hez

A migrálás befejezéséhez:

1. Frissítse az ügyfélhívásokat az 2026-04-01 API-verzió használatára.

2. A kódban lévő beégetett tudásbázis vagy tudásforrás neveket frissítse, hogy azok a migrálás során létrehozott új objektumokra hivatkozzanak.

3. Ha migrált azureBlob vagy indexedOneLake tudásbázist használt, frissítse a társított indexre, indexelőre, adatforrásra vagy képességkészletre hivatkozó kódot vagy szkripteket név szerint, hogy az új objektumokra mutasson.

4. A válaszok lekérését feldolgozó kód frissítése. A válaszok kinyerő földelési tartalmat activity adnak vissza, és referencesnem szintetizált válaszokat.

5. Csak az új objektumok teljes ellenőrzése és üzembe helyezése után törölje az előzetes verziójú objektumokat.

2025-11-01-preview

Ha a 2025-08-01-es előzetes verzióról migrál, a "tudásügynök" neve "tudásbázis" lesz, és több tulajdonság kerül áthelyezésre egy objektumdefiníció különböző objektumaiba és szintjeibe.

1. SearchIndex-tudásbázisok frissítése
2. AzureBlob-tudásbázisok frissítése
3. Tudásügynök cseréje tudásbázisra
4. Frissítse a lekérési kérelmet, és küldjön egy lekérdezést a frissítések teszteléséhez
5. Ügyfélkód frissítése

SearchIndex-tudásbázis frissítése

Ez az eljárás az előző 2025-08-01 verzióval azonos működési szinten hoz létre egy új 2025-11-01-previewsearchIndex tudásbázist. Maga a mögöttes index nem igényel frissítéseket.

1. A tudásbázis megkereséséhez név szerint listázhatja az összes tudásbázist.

   ### 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. Kérje le a jelenlegi definíciót a meglévő tulajdonságok áttekintéséhez.

   ### 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
   

   A válasznak az alábbi példához hasonlónak kell lennie.

   {
        "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. Hozzon létre egy Tudásbázis-kérést a migrálás alapjaként.

   Kezdje a 08-01-preview JSON-val.

   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"
     }
   }
   

   Végezze el a következő frissítéseket a migráláshoz 2025-11-01-preview :

   • Adjon új nevet a tudásbázisnak.

   • Módosítsa az API-verziót a következőre 2025-11-01-preview: .

   • Nevezze sourceDataSelect át sourceDataFields és módosítsa a sztringet egy tömbre, amely név-érték párokat tartalmaz minden lekérdezni kívánt beolvasható mezőhöz. Ezek azok a mezők, amelyeket vissza kell adni a keresési eredményekben, hasonlóan a select klasszikus lekérdezések záradékához.

4. Tekintse át a frissítéseket, majd küldje el a kérést az objektum létrehozásához.

   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" }
           ]
       }
   }
   

Most már rendelkezik egy olyan migrált searchIndex tudásbázissal, amely visszafelé kompatibilis az előző verzióval a megfelelő tulajdonságspecifikációk használatával.2025-11-01-preview

A válasz tartalmazza az új objektum teljes definícióját. Az ehhez a tudásbázistípushoz elérhető új tulajdonságokról, amelyeket most már a frissítéseken keresztül is elvégezhet, tekintse meg a keresési index tudásbázisának létrehozását ismertető témakört.

AzureBlob-tudásbázis frissítése

Ez az eljárás az előző 2025-08-01 verzióval azonos működési szinten hoz létre egy új 2025-11-01-previewazureBlob tudásbázist. Létrehoz egy új generált objektumkészletet: adatforrást, képességkészletet, indexelőt, indexet.

1. A tudásbázis megkereséséhez név szerint listázhatja az összes tudásbázist.

   ### 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. Kérje le a jelenlegi definíciót a meglévő tulajdonságok áttekintéséhez.

   ### 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
   

   Ha a munkafolyamat modellel rendelkezik, a válasznak az alábbi példához hasonlónak kell lennie. Figyelje meg, hogy a válasz tartalmazza a létrehozott objektumok nevét. Ezek az objektumok teljesen függetlenek a tudásbázistól, és akkor is működőképesek maradnak, ha frissíti vagy törli a tudásbázisukat.

    {
      "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. Hozzon létre egy Tudásbázis-kérést a migrálás alapjaként.

   Kezdje a 08-01-preview JSON-val.

   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
     }
   }
   

   Végezze el a következő frissítéseket a migráláshoz 2025-11-01-preview :

   • Adjon új nevet a tudásbázisnak.

   • Módosítsa az API-verziót a következőre 2025-11-01-preview: .

   • Adja hozzá ingestionParameters tárolóként a következő gyermektulajdonságokhoz: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. Tekintse át a frissítéseket, majd küldje el a kérést az objektum létrehozásához. A rendszer új létrehozott objektumokat hoz létre az indexelő folyamathoz.

   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"
           }
       }
   }
   

Most már rendelkezik egy olyan migrált azureBlob tudásbázissal, amely visszafelé kompatibilis az előző verzióval a megfelelő tulajdonságspecifikációk használatával.2025-11-01-preview

A válasz tartalmazza az új objektum teljes definícióját. Az ehhez a tudásbázistípushoz elérhető új tulajdonságokról, amelyeket most már a frissítéseken keresztül is elvégezhet, olvassa el a Blob-tudásbázis létrehozása című témakört.

Tudásügynök cseréje tudásbázisra

1. A tudásbázisokhoz tudásbázis szükséges. Mielőtt elkezdené, győződjön meg arról, hogy rendelkezik egy olyan tudásforrással, amely a 2025-11-01-preview elemre irányul.

2. Kérje le a jelenlegi definíciót a meglévő tulajdonságok áttekintéséhez.

   ### 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
   

   A válasznak az alábbi példához hasonlónak kell lennie.

   {
     "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. Hozzon létre egy Tudásbázis-kérést a migrálás alapjaként.

   Kezdje a 08-01-preview JSON-val.

   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"
       }
   }
   

   Végezze el a következő frissítéseket a migráláshoz 2025-11-01-preview :

   • Cserélje le a végpontot: /knowledgebases/{{knowledge-base-name}}. Adjon egyedi nevet a tudásbázisnak.

   • Módosítsa az API-verziót a következőre 2025-11-01-preview: .

   • Törlés requestLimits. A maxRuntimeInSeconds és maxOutputSize tulajdonságok most már közvetlenül a lekérési kérelemben vannak megadva.

   • Frissítés knowledgeSources:

     • Törölje a(z) maxSubQueries elemet, és cserélje le erre: retrievalReasoningEffort (lásd: A visszakeresési érvelési erőfeszítés beállítása (előzetes)).

   • Áthelyezze alwaysQuerySource, includeReferenceSourceData, includeReferences és rerankerThreshold a knowledgeSourceParams, a lekérési művelet szakaszába.

   • Nincs változás a models.

   • Frissítés outputConfiguration:

     • Csere erre outputConfiguration : outputMode.

     • Törlés attemptFastPath. Már nem létezik. Az egyenértékű viselkedés a retrievalReasoningEffort minimálisra állításával valósítható meg (lásd: A lekérési érvelési ráfordítás beállítása (előzetes verzió)).

     • Ha a modalitás answerSynthesis, győződjön meg arról, hogy a visszakeresési érvelési erőfeszítést alacsonyra (alapértelmezett) vagy közepesre állítja.

   • Vegye fel a(z) ingestionParameters elemet követelményként a(z) 2025-11-01-preview azureBlob tudásforrás létrehozásához.

4. Tekintse át a frissítéseket, majd küldje el a kérést az objektum létrehozásához. A rendszer új létrehozott objektumokat hoz létre az indexelő folyamathoz.

    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."
    }
   

Most már rendelkezik tudásbázissal a tudásügynök helyett, és az objektum visszamenőlegesen kompatibilis az előző verzióval.

A válasz tartalmazza az új objektum teljes definícióját. A tudásbázisok számára elérhető új tulajdonságokról további információt a Tudásbázis létrehozása című témakörben talál, amely most már a frissítéseken keresztül is elvégezhető.

A 2025-11-01-preview frissítések lekérésének frissítése és tesztelése

A 2025-11-01-preview lekérési kérését úgy módosították, hogy többféle formát támogasson, beleértve egy egyszerűbb kérést is, amely minimalizálja az LLM-feldolgozást. Az előzetes verzióban történő lekéréssel kapcsolatos további információkért lásd: Adatok lekérése tudásbázis használatával. Ez a szakasz a kód frissítését ismerteti.

1. Módosítsa a /agents/retrieve végpontot /knowledgebases/retrieve-re.

2. Módosítsa az API-verziót a következőre 2025-11-01-preview: .

3. A(z) messages módosítása nem szükséges, ha low vagy medium lekérési érvelési szintet használ. Cserélje le a(z) messages elemet erre: intents, ha minimal érvelést használ (lásd: A visszakeresési érvelés ráfordításának beállítása (előzetes verzió)).

4. Módosítsa úgy a knowledgeSourceParams-át, hogy az tartalmazza az ügynökből eltávolított tulajdonságokat: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

5. Adja hozzá a retrievalReasoningEffort készletet minimum, ha a attemptFastPath-t használta. Ha használta maxSubQueries, az már nem létezik. Az retrievalReasoningEffort beállítással adhatja meg az allekérdezések feldolgozását (lásd: A visszakeresési következtetési erőfeszítés beállítása (előzetes verzió)).

A tudásbázis kimenetének lekérdezéssel való teszteléséhez használja a 2025-11-01-previewKnowledge Retrieveal – Retrieve (REST API) lehetőséget.

### 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
}

Ha a válasz http-kóddal 200 OK rendelkezik, a tudásbázis sikeresen lekérte a tartalmat a tudásbázisból.

Kód és ügyfelek frissítése a 2025-11-01-preview verzióhoz

A migrálás befejezéséhez kövesse az alábbi tisztítási lépéseket:

1. Csak blobalapú tudásbázisok esetén frissítse az ügyfeleket az új index használatára. Ha rendelkezik olyan kóddal vagy szkripttel, amely indexelőt futtat, vagy adatforrásra, indexre vagy képességkészletre hivatkozik, győződjön meg arról, hogy frissíti az új objektumokra mutató hivatkozásokat.

2. Cserélje le az összes ügynökhivatkozást knowledgeBases-re a konfigurációs fájlokban, kódban, szkriptekben és tesztekben.

3. Frissítse a klienshívásokat a(z) 2025-11-01-preview használatára.

4. A régi alakzatokkal létrehozott gyorsítótáras definíciók törlése vagy újragenerálása.

2025-08-01-előzetes

Ha a 2025-05-01 előzetes verzióval létrehozott egy tudásügynököt, az ügynök definíciója tartalmaz egy beágyazott targetIndexes tömböt és egy opcionális defaultMaxDocsForReranker tulajdonságot.

A 2025-08-01-preview API-verziótól kezdődően az újrafelhasználható tudásforrások váltják fel a targetIndexes elemet, és a defaultMaxDocsForReranker már nem támogatott. A kompatibilitástörő változásokhoz a következőkre van szükség:

1. Az aktuális targetIndexes konfiguráció lekérése
2. Egyenértékű tudásbázis létrehozása
3. Frissítse az ügynököt, hogy a knowledgeSources-t használja a targetIndexes helyett
4. Lekérdezés küldése a lekérés teszteléséhez
5. A targetIndexes használó kód eltávolítása és az ügyfelek frissítése

Az aktuális konfiguráció lekérése

Az ügynök definíciójának lekéréséhez használja a 2025-05-01-previewTudásügynökök – Get (REST API) lehetőséget.

@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}}

A válasznak az alábbi példához hasonlónak kell lennie. Másolja ki a indexName, defaultRerankerThresholdés defaultIncludeReferenceSourceData az értékeket a közelgő lépésekben való használatra. defaultMaxDocsForReranker elavult, így figyelmen kívül hagyhatja az értékét.

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

Tudásbázis létrehozása

Tudásforrás létrehozásához használja a searchIndex2025-08-01-previewTudásforrások – Létrehozás (REST API) műveletét. Állítsa be searchIndexName a korábban másolt értéket.

@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"
        }
    }

Az előző példa egy olyan tudásbázist hoz létre, amely egy indexet jelöl, de több indexet vagy Azure blobot is megcélzhat. További információ: Tudásbázis létrehozása.

Az ügynök frissítése

Ha az ügynök definíciójában a(z) targetIndexes elemet a(z) knowledgeSources elemre szeretné lecserélni, használja a(z) 2025-08-01-preview mezőt a Tudásügynökök – Létrehozás vagy frissítés (REST API) műveletben. Állítsa be a korábban másolt értékeket rerankerThreshold és includeReferenceSourceData számára.

### 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
            }
        ]
    }

Az előző példa frissíti a definíciót, hogy egy tudásbázisra hivatkozzon, de több tudásbázist is megcélzhat. Más tulajdonságokat is használhat a beolvasási viselkedés szabályozásához, például alwaysQuerySource. További információ: Tudásügynök létrehozása.

A 2025-08-01-preview frissítések lekérésének tesztelése

Ha egy lekérdezéssel szeretné tesztelni az ügynök kimenetét, használja a 2025-08-01-previewTudáslekérés – Lekérés (REST API) lehetőséget.

### 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"
                    }
                ]
            }
        ]
    }

Ha a válasz http-kóddal 200 OK rendelkezik, az ügynök sikeresen lekérte a tartalmat a tudásbázisból.

Kód és kliensek frissítése a 2025-08-01 előzetes verzióhoz

A migrálás befejezéséhez kövesse az alábbi tisztítási lépéseket:

• Cserélje le az összes targetIndexes hivatkozást knowledgeSources hivatkozásra a konfigurációs fájlokban, a kódban, a szkriptekben és a tesztekben.
• Frissítse a klienshívásokat a(z) 2025-08-01-preview használatára.
• Törölje vagy hozza létre újra a régi formával létrehozott gyorsítótárazott ügynökdefiníciókat.

Verzióspecifikus módosítások

Ez a szakasz a következő API-verziók kompatibilitástörő és nem törhető módosításait ismerteti:

• 2026-08-01-preview
• 2026-05-01-előzetes
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

A 2026-08-01-preview verzió a 2026-05-01-es előzetes verzióra épül, és kompatibilitástörő változásokat tartalmaz a Work IQ-tudásbázist használó alkalmazásokhoz, az eltolásalapú listák lapozásához, a modell által támogatott tevékenységrekordokhoz, az MCP-kiszolgáló eredményének feldolgozásához vagy a pozícióalapú ügyfélhívásokhoz.

Az ehhez a verzióhoz tartozó REST API-referenciadokumentáció áttekintéséhez válassza ki az 2026-08-01-preview API-verziószűrőt a lap tetején.

2026-05-01-előzetes

2026-05-01-preview a tudásbázis-, tudásforrás- és lekérési funkciókat adja hozzá a 2025-11-01-preview verzióhoz a korábban megőrzött tulajdonságok eltávolítása nélkül. A korábbi előzetes verziókban létrehozott meglévő tudásbázisok és tudásbázisok továbbra is működnek. Ez a verzió többnyire új funkciókat tesz elérhetővé, és visszaállít néhány csak előzetes verziós korlátot.

Az ehhez a verzióhoz tartozó REST API-referenciadokumentáció áttekintéséhez válassza ki az 2026-05-01-preview API-verziószűrőt a lap tetején.

2026-04-01

2026-04-01 az ügynöki lekérés első stabil API-verziója. Minimális, kinyerő lekérési szerződést hoz létre, és eltávolítja az előzetes verziójú, üzenetalapú lekérdezéstervezési és válaszszintézisi képességeket.

Az ehhez a verzióhoz tartozó REST API-referenciadokumentáció áttekintéséhez válassza ki az 2026-04-01 API-verziószűrőt a lap tetején.

2025-11-01-preview

Az ehhez a verzióhoz tartozó REST API-referenciadokumentáció áttekintéséhez válassza ki az 2025-11-01-preview API-verziószűrőt a lap tetején.

2025-08-01-előzetes

Az ehhez a verzióhoz tartozó REST API-referenciadokumentáció áttekintéséhez válassza ki az 2025-08-01-preview API-verziószűrőt a lap tetején.

2025-05-01-preview

Ez az API-verzió bevezeti az ágensalapú visszakeresést és a tudásügynököket. Minden ügynökdefinícióhoz egy targetIndexes tömbre van szükség, amely egyetlen indexet és opcionális tulajdonságokat, például defaultRerankerThreshold és defaultIncludeReferenceSourceData.

Az ehhez a verzióhoz tartozó REST API-referenciadokumentáció áttekintéséhez válassza ki az 2025-05-01-preview API-verziószűrőt a lap tetején.

Kapcsolódó tartalom

• Ügynöki lekérdezés az Azure AI Keresés-ben
• Tudásbázis létrehozása
• Tudásbázis lekérdezése