Migrera agentisk hämtningskod till den senaste versionen

Om din agentiska hämtningskod riktar sig mot en tidigare API-version förklarar den här artikeln när och hur du migrerar till en nyare version. Den beskriver även både bakåtkompatibla och icke-bakåtkompatibla ändringar för alla API-versioner som stöder agentbaserad hämtning.

Migreringsinstruktioner är avsedda att hjälpa dig att köra en befintlig lösning på en nyare API-version. Anvisningarna i den här artikeln hjälper dig att hantera ändringar som bryter kompatibilitet på API-nivå så att din app fungerar som tidigare. Om du vill ha hjälp med att lägga till nya funktioner börjar du med Vad är nytt i Azure AI-sökning.

När du ska migrera

De flesta versioner som stöder agentbaserad hämtning medförde icke-bakåtkompatibla ändringar. Du kan fortsätta att köra äldre kod oförändrad genom att behålla API-versionsvärdet, men för att kunna dra nytta av felkorrigeringar, förbättringar och nyare funktioner måste du uppdatera koden.

Om koden är avsedd för en förhandsversion rekommenderar vi att du migrerar till den senaste stabila versionen endast om ditt användningsfall stöds fullt ut av 2026-04-01. Om du förlitar dig på svarssyntes, resonemang som kräver mer än minimal ansträngning, eller meddelanden med flera turer, granskar du störande och icke-störande ändringar innan du bestämmer dig för att migrera. Dessa funktioner finns kvar i förhandsversionen.

Innan du migrerar

• Om du vill förstå omfånget för ändringar kan du granska icke-bakåtkompatibla och icke-bakåtkompatibla ändringar för varje version.

• Den migreringsväg som stöds är inkrementell. Om koden har som mål 2025-05-01-previewmigrerar du först till 2025-08-01-previewoch fortsätter sedan genom varje efterföljande version tills du når målversionen.

• För en migrering sida vid sida skapar du unikt namngivna objekt som implementerar beteendet för den tidigare versionen. Den här metoden bevarar befintliga objekt medan du utvecklar och testar ersättningar. Om ett objekt stöder uppdatering på plats anropar de versionsspecifika stegen det alternativet.

• För varje objekt som du migrerar börjar du med att hämta den aktuella definitionen från söktjänsten så att du kan granska befintliga egenskaper innan du anger den nya.

• Ta bara bort äldre versioner efter att migreringen har testats och distribuerats fullständigt.

Så här migrerar du

Det här avsnittet beskriver migreringssteg för följande API-versioner:

• Förhandsversion 2026-08-01
• 2026-05-01-förhandsvisning
• 2026-04-01
• Förhandsversion 2025-11-01
• 2025-08-01-preview

Förhandsversion 2026-08-01

Om du migrerar från 2026-05-01-preview kan du flytta direkt till 2026-08-01-preview. Den här migreringen kräver uppdateringar av Work IQ-kunskapskällor, sidindelning av listor, svarsbearbetning, MCP-serververktygen och berörda genererade klientanrop.

1. Migrera arbets-IQ-kunskapskällor
2. Uppdatera sidindelning för listor
3. Uppdatera hämtningssvarsbearbetning
4. Uppdatera kod och klienter

Migrera kunskapskällor för Work IQ

Så här migrerar du en Arbets-IQ-kunskapskälla till den nya autentiseringskonfigurationen:

1. Exportera dess aktuella definition.

2. Uppdatera den befintliga kunskapskällan med hjälp av Kunskapskällor – Skapa eller uppdatera eller skapa en ersättning med ett unikt namn för en migrering sida vid sida.

3. Använd API-versionen 2026-08-01-preview och konfigurera workIQParameters.entraAppAuthentication. Egenskaperna applicationId och federatedCredentialId krävs. Egenskapen tenantId är valfri och är standard för söktjänstens klientorganisation.

4. Om du har skapat en ersättning uppdaterar du varje kunskapsbas som refererar till den tidigare kunskapskällan för att använda ersättningsnamnet.

5. Uppdatera hämtningsförfrågningar så att användarintyget skickas i rubriken x-ms-query-work-iq-source-authorization.

Konfiguration och exempel finns i Skapa en arbets-IQ-kunskapskälla (förhandsversion).

Uppdatera listsidindelning

Så här ersätter du offset-baserad sidindelning med markör-baserad sidindelning:

1. Ta bort $top, $skip och $count från begäranden om lista över kunskapskällor. Ange pageSize mellan 1 och 3 000 för att ange sidstorleken. Om du utelämnar det väljer tjänsten sidstorleken.

2. Om du vill filtrera efter namn anger du search och searchType. Det enda värde som stöds searchType är prefix, vilket också är standardvärdet. Följande begäran returnerar upp till 100 kunskapskällor vars namn börjar med contoso.

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

   Referens:Kunskapskällor – lista

3. Om svaret innehåller @odata.nextLinkskickar du url:en exakt som returnerad. Parsa eller ändra inte dess fortsättningstillstånd.

Uppdatera bearbetningen av hämtningssvar

Så här bearbetar du den nya arbets-IQ-referensen och modellbaserade aktivitetsformer:

1. Ta bort beroenden för attributions, WorkIQAttributionoch seeMoreWebUrl. Läs metadata för känslighetsetiketter från searchSensitivityLabelInfo på Work IQ-referensen.

2. I aktivitetsposter för frågeplanering, svarssyntes och webbsammanfattning läser du modelName och deploymentId från det kapslade model-objektet. Det kapslade objektet och båda egenskaperna är valfria.

Följande fragment visar ändringar i svarsformen.

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

I 2026-08-01-previewanvänder samma fragment följande form:

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

Uppdatera kod och klienter för förhandsversionen av 2026-08-01

Slutför migreringen:

1. På varje MCP-serverobjekt tools ersätter du inclusionMode med resultsProcessing. Mappa reranked till rerank och always till none. Värdet rerank är standardvärdet. Värdet none kringgår omrankningen och bevarar verktygets underliggande resultatordning. Konfiguration finns i Konfigurera verktyg för en MCP-serverkunskapskälla.

2. Om du använder en Azure SDKs installerar du ett paket som stöder 2026-08-01-previewoch granskar positionslistans anrop för ändringar i parameterordning. REST-anropare påverkas inte eftersom HTTP-parametrar är nyckelade efter namn. I C# föredrar du namngivna argument, till exempel GetKnowledgeSourcesAsync(search: ..., pageSize: ...). I Python skickar du listalternativ som nyckelordsargument.

3. Testa Work IQ-autentisering och referenser, markörbaserad paginering, deserialisering av aktivitetsposter, ordning för MCP-serverresultat och anrop från genererade klienter innan du uppdaterar produktionsmiljön.

4. Om du har skapat nya Arbets-IQ-kunskapskällor tar du bort de tidigare källorna först efter att migreringen har klarat alla tester, ditt uppdaterade program distribueras och ingen kunskapsbas refererar till de tidigare namnen.

2026-05-01-förhandsvisning

Om du migrerar från 2026-04-01 eller 2025-11-01-preview kan du flytta direkt till 2026-05-01-preview. Begäranden, svar och bevarade objekt från dessa versioner förblir kompatibla. Skillnaderna är additiva funktioner och SDK-namn på språk.

1. Uppdatera API-versionen till 2026-05-01-preview på REST-begäranden. SDK-klienter använder paketets standard-API-version, så du behöver inte skicka ett explicit serviceVersion argument. Uppgradera i stället till SDK-paketet 2026-05-01-preview .

2. Om du använder Python eller JavaScript SDK uppdaterar du hämtningsklienten till KnowledgeBaseRetrievalClient och anropar retrieve(...) i stället för den äldre retrieveKnowledge(...). Fullständig SDK-formmappning finns i Uppdatera kod och klienter för förhandsversionen av 2026-05-01.

3. (Valfritt) Anta de nya 2026-05-01-preview funktionerna, till exempel färskhetsmedveten hämtning, dokumenttak per källa och slutresultat, bevarade hämtningsstandarder, kunskapsbasen CORS och Purview-metadata för känslighetsetiketter i hämtningssvar. Ingen av dessa funktioner krävs för att en befintlig lösning ska fungera.

Uppdatera kod och klienter för förhandsversionen av 2026-05-01

2026-05-01-preview SDK:erna introducerar kodformsändringar på de språk som stöds:

När du har uppdaterat klientformerna kör du det fullständiga flödet som skapar indexet, laddar upp dokument, skapar en kunskapskälla, skapar en kunskapsbas, utfärdar en hämtningsbegäran och rensar resurser för att bekräfta migreringens slutpunkt till slutpunkt.

2026-04-01

Om du migrerar från 2025-11-01-preview kan du migrera direkt till 2026-04-01. Ditt index och innehåll förblir oförändrade. Du behöver bara uppdatera kunskapsbasschemat och formen för att hämta begäran.

1. Migrera kunskapskällor
2. Migrera kunskapsbasen
3. Uppdatera hämtningsbegäran
4. Uppdatera faktureringsmedgivande
5. Uppdatera kod och klienter

Migrera kunskapskällor

I 2026-04-01är typerna searchIndex, azureBlob, indexedOneLakeoch web kunskapskällor allmänt tillgängliga. Andra typer av kunskapskällor finns kvar i förhandsversionen.

1. Använd Kunskapskällor – Hämta (REST API) för att hämta den aktuella definitionen.

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

2. I svaret identifierar du vad du ska gå vidare med och vad du ska ta bort:

   • För searchIndex och web ska du överföra alla egenskapsvärden.

   • För azureBlob och indexedOneLakekan du överföra alla egenskapsvärden, men utelämna ingestionPermissionOptions från ingestionParameters. Den här egenskapen stöds inte i 2026-04-01.

3. Använd Kunskapskällor – Skapa eller uppdatera (REST API) för att skapa en ny kunskapskälla med ett unikt namn, 2026-04-01 API-versionen och egenskapsvärdena från föregående steg.

   I följande exempel visas en searchIndex kunskapskälla. Använd ett liknande mönster för azureBlob, indexedOneLakeoch web kunskapskällor.

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

Migrera kunskapsbasen

Kunskapsbasen 2026-04-01 har ett enklare schema än 2025-11-01-preview versionen: den behåller knowledgeSources och släpper svarsgenereringsinställningar. Granska den aktuella definitionen innan du skapar ett nytt objekt.

1. Använd Kunskapsbaser – Hämta (REST API) för att hämta den aktuella definitionen.

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

2. I svaret identifierar du vad du ska gå vidare med och vad du ska ta bort:

   • Anteckna referenserna knowledgeSources . För dessa vidare till den nya kunskapsbasen.

   • Om det finns tar du bort outputMode, answerInstructionsoch retrievalInstructions. De här egenskaperna stöds inte i 2026-04-01.

   • Om kunskapsbasen använder en web kunskapskälla behåller du models. Webbhämtning kräver modellbaserad sammanfattning. För alla andra typer av kunskapskällor tar du bort models.

3. Använd Kunskapsbaser – Skapa eller uppdatera (REST API) för att skapa en ny kunskapsbas med ett unikt namn, 2026-04-01 API-versionen och endast de egenskaper som stöds.

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

Uppdatera hämtningsbegäran

Hämtningsbegäran 2026-04-01 har en annan form än förhandsversionen:

• Använd intents i stället för messages.

• Använd maxOutputSizeInTokens i stället för maxOutputSize.

• Om det finns tar du bort retrievalReasoningEffort och alwaysQuerySource. Dessa parametrar stöds inte i 2026-04-01.

• För uppföljningsfrågor skickar du en ny hämtningsbegäran med en ny semantisk avsikt. 2026-04-01 sparar inte någon löpande logg över meddelanden.

Om du vill testa dina kunskapsbasutdata med en fråga använder du 2026-04-01 versionen av 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
}

Om svaret har en 200 OK HTTP-kod har kunskapsbasen hämtat innehåll från kunskapskällan.

Uppdatera faktureringsmedgivande

Från och med API-versionen 2026-04-01 styrs faktureringsmedgivande för agentbaserad hämtning av den dedikerade egenskapen knowledgeRetrieval, som är separat från semanticSearch, vilket nu endast gäller fakturering för semantisk rankning. knowledgeRetrieval är en egenskap för hanteringsplanet, så du anger den via REST-API:et för sökhantering, inte REST-API:et för söktjänsten.

Använd den senaste förhandsversionen av Services – Create Or Update (REST API) för att ställa in knowledgeRetrieval till din söktjänst.

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

Giltiga värden och faktureringsinformation finns i Aktivera eller inaktivera agentbaserad hämtningsfakturering.

Uppdatera kod och klienter för 2026-04-01

Slutför migreringen:

1. Uppdatera klientanrop för att använda API-versionen 2026-04-01 .

2. Uppdatera eventuella hårdkodade kunskapsbas- eller kunskapskällans namn i koden för att referera till de nya objekt som skapades under migreringen.

3. Om du har migrerat kunskapskällor azureBlob eller indexedOneLake, uppdatera all kod eller alla skript som refererar till det associerade indexet, indexeraren, datakällan eller kunskapsuppsättningen efter namn för att peka på de nya objekten.

4. Uppdatera kod som bearbetar hämtningssvar. Svar returnerar extraktiv grundinnehåll med activity och references, inte syntetiserade svar.

5. Ta bara bort förhandsgranskningsobjekt när de nya objekten har verifierats och distribuerats.

Förhandsversion 2025-11-01

Om du migrerar från 2025-08-01-preview byter "kunskapsagent" namn till "kunskapsbas" och flera egenskaper flyttas till olika objekt och nivåer inom en objektdefinition.

1. Uppdatera searchIndex-kunskapskällor
2. Uppdatera azureBlob-kunskapskällor
3. Ersätt kunskapsagenten med kunskapsbasen
4. Uppdatera hämtningsbegäran och skicka en fråga för att testa dina uppdateringar
5. Uppdatera klientkod

Uppdatera en searchIndex-kunskapskälla

Den här proceduren skapar en ny 2025-11-01-previewsearchIndex kunskapskälla på samma funktionsnivå som den tidigare 2025-08-01 versionen. Det underliggande indexet kräver inga uppdateringar.

1. Lista alla kunskapskällor efter namn för att hitta din kunskapskälla.

   ### 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. Hämta den aktuella definitionen för att granska befintliga egenskaper.

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

   Svaret bör likna följande exempel.

   {
        "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. Formulera en begäran om att skapa kunskapskälla som grund för migreringen.

   Börja med 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"
     }
   }
   

   Gör följande uppdateringar för en 2025-11-01-preview migrering:

   • Ge kunskapskällan ett nytt namn.

   • Ändra API-versionen till 2025-11-01-preview.

   • Byt sourceDataSelect namn på till sourceDataFields och ändra strängen till en matris med namn/värde-par för varje hämtningsbart fält som du vill fråga efter. Det här är fälten som ska returneras i sökresultaten, ungefär som en select sats i en klassisk fråga.

4. Granska dina uppdateringar och skicka sedan begäran om att skapa objektet.

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

Nu har du en migrerad kunskapskälla searchIndex som är bakåtkompatibel med den tidigare versionen med rätt egenskapsspecifikationer för 2025-11-01-preview.

Svaret innehåller den fullständiga definitionen av det nya objektet. Mer information om nya egenskaper som är tillgängliga för den här kunskapskällan, som du nu kan göra via uppdateringar, finns i Skapa en kunskapskälla för sökindex.

Uppdatera en azureBlob-kunskapskälla

Den här proceduren skapar en ny 2025-11-01-previewazureBlob kunskapskälla på samma funktionsnivå som den tidigare 2025-08-01 versionen. Den skapar en ny uppsättning genererade objekt: datakälla, kompetensuppsättning, indexerare, index.

1. Lista alla kunskapskällor efter namn för att hitta din kunskapskälla.

   ### 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. Hämta den aktuella definitionen för att granska befintliga egenskaper.

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

   Om arbetsflödet innehåller en modell bör svaret likna följande exempel. Observera att ett svar innehåller namnen på de genererade objekten. Dessa objekt är helt oberoende av kunskapskällan och fungerar även om du uppdaterar eller tar bort deras kunskapskälla.

    {
      "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. Formulera en begäran om att skapa kunskapskälla som grund för migreringen.

   Börja med 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
     }
   }
   

   Gör följande uppdateringar för en 2025-11-01-preview migrering:

   • Ge kunskapskällan ett nytt namn.

   • Ändra API-versionen till 2025-11-01-preview.

   • Lägg till ingestionParameters som en container för följande underordnade egenskaper: "embeddingModel", "chatCompletionModel", "ingestionSchedule", . "contentExtractionMode"

4. Granska dina uppdateringar och skicka sedan begäran om att skapa objektet. Nya genererade objekt skapas för indexerarens pipeline.

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

Nu har du en migrerad kunskapskälla azureBlob som är bakåtkompatibel med den tidigare versionen med rätt egenskapsspecifikationer för 2025-11-01-preview.

Svaret innehåller den fullständiga definitionen av det nya objektet. Mer information om nya egenskaper som är tillgängliga för den här kunskapskällan, som du nu kan göra via uppdateringar, finns i Skapa en blob-kunskapskälla.

Ersätt kunskapsagenten med kunskapsbasen

1. Kunskapsbaser kräver en kunskapskälla. Se till att du har en kunskapskälla som är riktad mot 2025-11-01-preview innan du börjar.

2. Hämta den aktuella definitionen för att granska befintliga egenskaper.

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

   Svaret bör likna följande exempel.

   {
     "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. Formulera en begäran om att skapa kunskapsbas som grund för migreringen.

   Börja med 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"
       }
   }
   

   Gör följande uppdateringar för en 2025-11-01-preview migrering:

   • Ersätt slutpunkten: /knowledgebases/{{knowledge-base-name}}. Ge kunskapsbasen ett unikt namn.

   • Ändra API-versionen till 2025-11-01-preview.

   • Ta bort requestLimits. Egenskaperna maxRuntimeInSeconds och maxOutputSize anges nu direkt i hämtningsbegäran.

   • Uppdatera knowledgeSources:

     • Ta bort maxSubQueries och ersätt den med retrievalReasoningEffort (se Ange hämtningsskäl (förhandsversion)).

   • Flytta alwaysQuerySource, includeReferenceSourceData, includeReferencesoch rerankerThreshold till avsnittet i knowledgeSourceParams en hämtningsåtgärd.

   • Inga ändringar för models.

   • Uppdatera outputConfiguration:

     • Ersätt outputConfiguration med outputMode.

     • Ta bort attemptFastPath. Den finns inte längre. Motsvarande beteende uppnås genom att retrievalReasoningEffort ställs in på miniminivå (se Ange resonemangsinsatsen för hämtning (förhandsversion)).

     • Om modalitet är inställt på answerSynthesis, ska du se till att ansträngningen för hämtningsresonemanget är låg (standard) eller medel.

   • Lägg till ingestionParameters som ett krav för att skapa en 2025-11-01-preview azureBlob-kunskapskälla.

4. Granska dina uppdateringar och skicka sedan begäran om att skapa objektet. Nya genererade objekt skapas för indexerarens pipeline.

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

Nu har du en kunskapsbas i stället för en kunskapsagent och objektet är bakåtkompatibelt med den tidigare versionen.

Svaret innehåller den fullständiga definitionen av det nya objektet. Mer information om nya egenskaper som är tillgängliga för en kunskapsbas, som du nu kan göra via uppdateringar, finns i Skapa en kunskapsbas.

Uppdatera och testa hämtningen för 2025-11-01-förhandsversionsuppdateringar

Hämtningsbegäran ändras i 2025-11-01-preview för att stödja fler format, inklusive en enklare begäran som minimerar bearbetning av LLM. Mer information om hämtning i den här förhandsversionen finns i Hämta data med hjälp av en kunskapsbas. I det här avsnittet beskrivs hur du uppdaterar koden.

1. /agents/retrieve Ändra slutpunkten till /knowledgebases/retrieve.

2. Ändra API-versionen till 2025-11-01-preview.

3. Inga ändringar av messages krävs om du använder resonemangsnivån för hämtning low eller medium. Ersätt messages med intents om du använder minimal resonemang (se Ange hämtningsskäl (förhandsversion)).

4. Ändra knowledgeSourceParams om du vill inkludera eventuella egenskaper som har tagits bort från agenten: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, . includeReferences

5. Lägg till retrievalReasoningEffort i minimum om du använder attemptFastPath. Om du använder maxSubQueriesfinns den inte längre. Använd inställningen retrievalReasoningEffort för att ange bearbetning av underfrågor (se Ange hämtningsskäl (förhandsversion)).

Om du vill testa kunskapsbasens 2025-11-01-preview utdata med en fråga använder du kunskapshämtning – hämta (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
}

Om svaret har en 200 OK HTTP-kod har kunskapsbasen hämtat innehåll från kunskapskällan.

Uppdatera kod och klienter för förhandsversionen av 2025-11-01

Slutför migreringen genom att följa dessa rensningssteg:

1. Endast för blob-kunskapskällor uppdaterar du klienterna så att de använder det nya indexet. Om du har kod eller skript som kör en indexerare eller refererar till en datakälla, ett index eller en kompetensuppsättning kontrollerar du att du uppdaterar referenserna till de nya objekten.

2. Ersätt alla agentreferenser med knowledgeBases i konfigurationsfiler, kod, skript och tester.

3. Uppdatera klientanrop så att de använder 2025-11-01-preview.

4. Rensa eller återskapa cachelagrade definitioner som har skapats med hjälp av de gamla formerna.

2025-08-01-preview

Om du har skapat en kunskapsagent med 2025-05-01-preview innehåller agentens definition en infogad targetIndexes matris och en valfri defaultMaxDocsForReranker egenskap.

Från och med API-versionen 2025-08-01-preview ersätter targetIndexesåteranvändbara kunskapskällor , och defaultMaxDocsForReranker stöds inte längre. Dessa icke-kompatibla ändringar kräver att du:

1. Hämta den aktuella targetIndexes konfigurationen
2. Skapa en motsvarande kunskapskälla
3. Uppdatera agenten som ska användas knowledgeSources i stället för targetIndexes
4. Skicka en fråga för att testa hämtningen
5. Ta bort kod som använder targetIndexes och uppdaterar klienter

Hämta den aktuella konfigurationen

Om du vill hämta definitionen för agenten använder du 2025-05-01-preview för 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}}

Svaret bör likna följande exempel. indexNameKopiera värdena , defaultRerankerThresholdoch defaultIncludeReferenceSourceData för användning i de kommande stegen. defaultMaxDocsForReranker är inaktuell, så du kan ignorera dess värde.

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

Skapa en kunskapskälla

Om du vill skapa en searchIndex kunskapskälla använder du 2025-08-01-previewkunskapskällor – Skapa (REST API). Ange searchIndexName till det värde som du kopierade tidigare.

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

I föregående exempel skapas en kunskapskälla som representerar ett index, men du kan rikta in dig på flera index eller en Azure blob. Mer information finns i Skapa en kunskapskälla.

Uppdatera agenten

Om du vill ersätta 2025-08-01-preview med i agentens definition använder du knowledgeSources i targetIndexes. Ange rerankerThreshold och includeReferenceSourceData till de värden som du kopierade tidigare.

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

I föregående exempel uppdateras definitionen så att den refererar till en kunskapskälla, men du kan rikta in dig på flera kunskapskällor. Du kan också använda andra egenskaper för att styra hämtningsbeteendet, till exempel alwaysQuerySource. Mer information finns i Skapa en kunskapsagent.

Testa hämtningen för förhandsversionsuppdateringar för 2025-08-01

Om du vill testa agentens utdata med en fråga använder du 2025-08-01-previewkunskapshämtning – hämta (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"
                    }
                ]
            }
        ]
    }

Om svaret har en 200 OK HTTP-kod har agenten hämtat innehåll från kunskapskällan.

Uppdatera kod och klienter för förhandsversionen av 2025-08-01

Slutför migreringen genom att följa dessa rensningssteg:

• Ersätt alla targetIndexes referenser med knowledgeSources i konfigurationsfiler, kod, skript och tester.
• Uppdatera klientanrop så att de använder 2025-08-01-preview.
• Rensa eller återskapa cachelagrade agentdefinitioner som skapades med den gamla formen.

Versionsspecifika ändringar

Det här avsnittet behandlar bakåtkompatibla och icke-bakåtkompatibla ändringar för följande API-versioner:

• Förhandsversion 2026-08-01
• 2026-05-01-förhandsvisning
• 2026-04-01
• Förhandsversion 2025-11-01
• 2025-08-01-preview
• 2025-05-01-preview

Förhandsversion 2026-08-01

Versionen 2026-08-01-preview bygger på 2026-05-01-preview och innehåller brytande ändringar för applikationer som använder Work IQ-kunskapskällor, offsetbaserad listpaginering, modellbaserade aktivitetsposter, bearbetning av MCP-serverresultat eller positionsbaserade anrop till genererade klienter.

Om du vill granska REST API-referensdokumentationen för den här versionen väljer du 2026-08-01-preview API-versionsfiltret överst på sidan.

2026-05-01-förhandsvisning

2026-05-01-preview lägger till kunskapsbas, kunskapskälla och hämta funktioner ovanpå 2025-11-01-preview utan att ta bort tidigare bevarade egenskaper. Befintliga kunskapsbaser och kunskapskällor som du skapade i tidigare förhandsversioner fortsätter att fungera. Den här versionen exponerar mestadels nya funktioner och återställer några begränsningar endast för förhandsversioner.

Om du vill granska REST API-referensdokumentationen för den här versionen väljer du 2026-05-01-preview API-versionsfiltret överst på sidan.

2026-04-01

2026-04-01 är den första stabila API-versionen för agentisk hämtning. Det etablerar ett minimalt extraktivt hämtningskontrakt och tar bort meddelandebaserad frågeplanering och svarssyntesfunktioner i förhandsversionen.

Om du vill granska REST API-referensdokumentationen för den här versionen väljer du 2026-04-01 API-versionsfiltret överst på sidan.

Förhandsversion 2025-11-01

Om du vill granska REST API-referensdokumentationen för den här versionen väljer du 2025-11-01-preview API-versionsfiltret överst på sidan.

2025-08-01-preview

Om du vill granska REST API-referensdokumentationen för den här versionen väljer du 2025-08-01-preview API-versionsfiltret överst på sidan.

2025-05-01-preview

Den här API-versionen introducerar agentiska hämtnings- och kunskapsagenter. Varje agentdefinition kräver en targetIndexes matris som anger ett enda index och valfria egenskaper, till exempel defaultRerankerThreshold och defaultIncludeReferenceSourceData.

Om du vill granska REST API-referensdokumentationen för den här versionen väljer du 2025-05-01-preview API-versionsfiltret överst på sidan.

Relaterat innehåll

• Agentic-hämtning i Azure AI-sökning
• Skapa en kunskapsbas
• Fråga en kunskapsbas