Migrowanie kodu wyszukiwania agentowego do najnowszej wersji

Jeśli kod wyszukiwania agentowego korzysta ze starszej wersji interfejsu API, w tym artykule wyjaśniono, kiedy i jak przeprowadzić migrację do nowszej wersji. Zawiera również opis zmian powodujących niezgodność i zmian niepowodujących niezgodności dla wszystkich wersji interfejsu API, które obsługują agentowe pobieranie danych.

Instrukcje dotyczące migracji mają pomóc w uruchomieniu istniejącego rozwiązania w nowszej wersji interfejsu API. Instrukcje zawarte w tym artykule ułatwiają rozwiązywanie zmian powodujących niezgodność na poziomie interfejsu API, dzięki czemu aplikacja działa tak jak poprzednio. Aby uzyskać pomoc dotyczącą dodawania nowych funkcjonalności, zacznij od Co nowego w Wyszukiwanie AI platformy Azure.

Kiedy przeprowadzić migrację

Większość wersji obsługujących wyszukiwanie agentowe wprowadziła niekompatybilne zmiany. Możesz nadal uruchamiać starszy kod bez zmian, zachowując wartość wersji interfejsu API, ale aby korzystać z poprawek błędów, ulepszeń i nowszych funkcji, musisz zaktualizować kod.

Jeśli kod jest przeznaczony dla wersji zapoznawczej, zalecamy migrację do najnowszej stabilnej wersji tylko wtedy, gdy przypadek użycia jest w pełni obsługiwany przez 2026-04-01program . Jeśli korzystasz z syntezy odpowiedzi, niewielkiego wysiłku rozumowania lub wielozwrotowych komunikatów, przed podjęciem decyzji o migracji przejrzyj zmiany powodujące niezgodność i zmiany niepowodujące niezgodności. Te możliwości pozostają w wersji zapoznawczej.

Przed migracją

• Aby zrozumieć zakres zmian, przejrzyj zmiany powodujące niezgodność i zmiany niepowodujące niezgodności dla każdej wersji.

• Obsługiwana ścieżka migracji jest przyrostowa. Jeśli Twój kod jest przeznaczony dla 2025-05-01-preview, najpierw przeprowadź migrację do 2025-08-01-preview, a następnie przechodź przez każdą kolejną wersję, aż dojdziesz do wersji docelowej.

• W przypadku migracji równoległej utwórz unikatowo nazwane obiekty, które implementują zachowania poprzedniej wersji. To podejście zachowuje istniejące obiekty podczas opracowywania i testowania zamian. Jeśli obiekt obsługuje aktualizację w miejscu, kroki zależne od wersji wskazują tę opcję.

• Dla każdego migrowanych obiektów rozpocznij od pobrania bieżącej definicji z usługi wyszukiwania, aby można było przejrzeć istniejące właściwości przed określeniem nowego.

• Usuń starsze wersje dopiero po pełnym przetestowaniu i wdrożeniu migracji.

Jak przeprowadzić migrację

W tej sekcji opisano kroki migracji dla następujących wersji interfejsu API:

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

2026-08-01-preview

Jeśli migrujesz z 2026-05-01-preview, możesz przejść bezpośrednio na 2026-08-01-preview. Ta migracja wymaga aktualizacji źródeł wiedzy Work IQ, stronicowania list, przetwarzania odpowiedzi, narzędzi serwera MCP oraz wywołań w wygenerowanym kliencie, których dotyczą te zmiany.

1. Migracja źródeł wiedzy Work IQ
2. Zaktualizuj stronicowanie listy
3. Aktualizacja przetwarzania odpowiedzi pobierania
4. Aktualizowanie kodu i klientów

Migracja źródeł wiedzy Work IQ

Aby zmigrować źródło wiedzy Work IQ do nowej konfiguracji uwierzytelniania:

1. Wyeksportuj bieżącą definicję.

2. Zaktualizuj istniejące źródło wiedzy za pomocą Knowledge Sources - Create Or Update, lub utwórz zamiennik z unikatową nazwą na potrzeby migracji równoległej.

3. Użyj wersji interfejsu 2026-08-01-preview API i skonfiguruj element workIQParameters.entraAppAuthentication. Właściwości applicationId i federatedCredentialId są wymagane. Właściwość tenantId jest opcjonalna i domyślna dla dzierżawy usługi wyszukiwania.

4. Jeśli utworzono zamianę, zaktualizuj każdą bazę wiedzy, która odwołuje się do poprzedniego źródła wiedzy, aby użyć nazwy zastępczej.

5. Zaktualizuj żądania pobierania, aby przekazać asercję użytkownika w nagłówku x-ms-query-work-iq-source-authorization.

Aby zapoznać się z konfiguracją i przykładami, zobacz Tworzenie źródła wiedzy IQ pracy (wersja zapoznawcza).

Aktualizowanie stronicowania listy

Aby zastąpić stronicowanie oparte na offsecie stronicowaniem opartym na kursorze:

1. Usuń $top, $skip i $count z żądań listy źródeł wiedzy. Ustaw pageSize od 1 do 3000, aby kontrolować rozmiar strony. Jeśli go pominięto, usługa wybierze rozmiar strony.

2. Aby filtrować według nazwy, ustaw search i searchType. Jedyną obsługiwaną searchType wartością jest prefix, która jest również wartością domyślną. Następujące żądanie zwraca do 100 źródeł wiedzy, których nazwy zaczynają się od contoso.

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

   Dokumentacja:Źródła wiedzy — lista

3. Jeśli odpowiedź zawiera @odata.nextLink, wyślij ten adres URL dokładnie tak, jak został zwrócony. Nie analizuj ani nie modyfikuj stanu kontynuacji.

Aktualizacja przetwarzania odpowiedzi pobierania

Aby przetworzyć nowe kształty dokumentacji IQ pracy i działania oparte na modelu:

1. Usuń zależności od attributions, WorkIQAttributioni seeMoreWebUrl. Odczytaj metadane etykiety wrażliwości z searchSensitivityLabelInfo w dokumentacji referencyjnej Work IQ.

2. W rekordach aktywności planowania zapytań, syntezy odpowiedzi i podsumowywania treści z internetu odczytuj modelName i deploymentId z zagnieżdżonego obiektu model. Zarówno zagnieżdżony obiekt, jak i obie właściwości są opcjonalne.

W poniższych fragmentach przedstawiono zmiany kształtu odpowiedzi.

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

W 2026-08-01-previewprogramie te same fragmenty używają następującego kształtu:

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

Zaktualizować kod i klienty do wersji 2026-08-01-preview

Aby ukończyć migrację:

1. W każdym elemencie serwera tools MCP zastąp element resultsProcessing elementem inclusionMode. Mapuj reranked na rerank i always na none. Wartość rerank jest wartością domyślną. Wartość none pomija ponowne rankingowanie i zachowuje bazową kolejność wyników narzędzia. Aby uzyskać informacje na temat konfiguracji, zobacz Konfigurowanie narzędzi dla źródła wiedzy serwera MCP.

2. Jeśli używasz Azure SDK, zainstaluj pakiet obsługujący program 2026-08-01-previewi przejrzyj wywołania listy pozycyjnej pod kątem zmian w kolejności parametrów. Nie wpływa to na klientów REST, ponieważ parametry HTTP są identyfikowane na podstawie nazwy. W języku C# preferuj nazwane argumenty, takie jak GetKnowledgeSourcesAsync(search: ..., pageSize: ...). W Python przekaż opcje listy jako argumenty słów kluczowych.

3. Przetestuj uwierzytelnianie i odwołania Work IQ, stronicowanie za pomocą kursora, deserializację rekordów aktywności, kolejność wyników serwera MCP oraz wywołania wygenerowanego klienta, zanim zaktualizujesz środowisko produkcyjne.

4. Jeśli utworzono zastępcze źródła wiedzy Work IQ, usuń wcześniejsze źródła dopiero wtedy, gdy migracja pomyślnie przejdzie wszystkie testy, zaktualizowana aplikacja zostanie wdrożona i żadna baza wiedzy nie będzie odwoływać się do wcześniejszych nazw.

Zapowiedź 1 05.2026

Jeśli migrujesz z wersji 2026-04-01 lub 2025-11-01-preview, możesz przejść bezpośrednio do 2026-05-01-preview. Żądania, odpowiedzi i utrwalone obiekty z tych wersji pozostają zgodne. Różnice dotyczą dodatkowych funkcji i zmian nazw w językowym zestawie SDK.

1. Zaktualizuj wersję interfejsu API do 2026-05-01-preview w przypadku żądań REST. Klienci zestawu SDK używają domyślnej wersji interfejsu API pakietu, więc nie trzeba przekazywać jawnego serviceVersion argumentu. Zamiast tego uaktualnij do pakietu SDK 2026-05-01-preview.

2. Jeśli używasz pakietu SDK Python lub JavaScript, zaktualizuj klienta retrieve do KnowledgeBaseRetrievalClient i wywołaj retrieve(...) zamiast dotychczasowego retrieveKnowledge(...). Aby uzyskać pełne mapowanie kształtów zestawu SDK, zobacz Aktualizowanie kodu i klientów dla wersji 2026-05-01-preview.

3. (Opcjonalnie) Włącz nowe funkcje 2026-05-01-preview, takie jak pobieranie z uwzględnieniem świeżości, limity liczby dokumentów dla poszczególnych źródeł i wyniku końcowego, trwale zapisane domyślne ustawienia pobierania, obsługę mechanizmu CORS w bazie wiedzy oraz metadane etykiet poufności w usłudze Purview w odpowiedziach operacji pobierania. Żadne z tych funkcji nie jest wymagane, aby zachować działanie istniejącego rozwiązania.

Zaktualizuj kod i biblioteki klienckie dla wersji 2026-05-01-preview

Zestawy 2026-05-01-preview SDK wprowadzają zmiany kształtu kodu w obsługiwanych językach:

Po zaktualizowaniu struktur klienta uruchom pełny przepływ, który tworzy indeks, przesyła dokumenty, tworzy źródło wiedzy, tworzy bazę wiedzy, wysyła żądanie pobrania i usuwa zasoby, aby potwierdzić migrację od początku do końca.

01.04.2026

Jeśli migrujesz z wersji 2025-11-01-preview, możesz migrować bezpośrednio do 2026-04-01. Indeks i zawartość pozostają niezmienione. Wystarczy zaktualizować schemat bazy wiedzy i kształt żądania pobierania.

1. Migrowanie źródeł wiedzy
2. Migrowanie bazy wiedzy
3. Aktualizowanie żądania pobierania
4. Aktualizowanie zgody na rozliczenia
5. Aktualizowanie kodu i klientów

Migrowanie źródeł wiedzy

W 2026-04-01 typy źródeł wiedzy searchIndex, azureBlob, indexedOneLake i web są ogólnie dostępne. Inne typy źródeł wiedzy pozostają w wersji zapoznawczej.

1. Użyj Knowledge Sources - Get (REST API), aby uzyskać bieżącą definicję.

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

2. W odpowiedzi zidentyfikuj, co należy kontynuować, i co należy usunąć:

   • W przypadku searchIndex oraz web przenieś wszystkie wartości właściwości.

   • W przypadku azureBlob i indexedOneLake, przejmij wszystkie wartości właściwości, ale pomiń ingestionPermissionOptions z ingestionParameters. Ta właściwość nie jest obsługiwana w programie 2026-04-01.

3. Użyj źródeł wiedzy — utwórz lub zaktualizuj (interfejs API REST), aby utworzyć nowe źródło wiedzy o unikatowej nazwie, 2026-04-01 wersji interfejsu API i wartości właściwości z poprzedniego kroku.

   Poniższy przykład przedstawia searchIndex źródło wiedzy. Użyj podobnego wzorca dla źródeł wiedzy azureBlob, indexedOneLake i web.

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

Migrowanie bazy wiedzy

Baza 2026-04-01 wiedzy ma prostszy schemat niż 2025-11-01-preview wersja: utrzymuje knowledgeSources i odrzuca ustawienia generowania odpowiedzi. Przed utworzeniem nowego obiektu przejrzyj bieżącą definicję.

1. Użyj Baz Wiedzy - Pobierz (interfejs API REST), aby uzyskać bieżącą definicję.

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

2. W odpowiedzi zidentyfikuj, co należy kontynuować, i co należy usunąć:

   • Zwróć uwagę na knowledgeSources odwołania. Kontynuuj te czynności w nowej bazie wiedzy.

   • Jeśli są obecne, usuń outputMode, answerInstructions i retrievalInstructions. Te właściwości nie są obsługiwane w programie 2026-04-01.

   • Jeśli baza wiedzy korzysta ze web źródła wiedzy, zachowaj wartość models. Pobieranie w sieci Web wymaga podsumowania opartego na modelu. W przypadku wszystkich innych typów źródeł wiedzy usuń element models.

3. Użyj baz wiedzy — utwórz lub zaktualizuj (interfejs API REST), aby utworzyć nową bazę wiedzy o unikatowej nazwie, wersji interfejsu 2026-04-01 API i tylko obsługiwanych właściwościach.

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

Aktualizowanie żądania pobierania

Żądanie pobierania 2026-04-01 ma inny kształt niż wersja zapoznawcza:

• Użyj intents zamiast messages.

• Użyj maxOutputSizeInTokens zamiast maxOutputSize.

• Jeśli są obecne, usuń retrievalReasoningEffort i alwaysQuerySource. Te parametry nie są obsługiwane w programie 2026-04-01.

• W przypadku dodatkowych pytań wyślij nowe żądanie odczytu z nową intencją. 2026-04-01 nie prowadzi bieżącego transkryptu wiadomości.

Aby przetestować odpowiedź z bazy wiedzy przy użyciu zapytania, użyj wersji 2026-04-01Knowledge Retrieval - Retrieve (interfejsu API REST).

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
}

Jeśli odpowiedź zawiera 200 OK kod HTTP, baza wiedzy pomyślnie pobrała zawartość ze źródła wiedzy.

Aktualizowanie zgody na rozliczenia

Począwszy od wersji interfejsu API 2026-04-01, zgoda na rozliczanie agentowego wyszukiwania jest kontrolowana przez osobną właściwość knowledgeRetrieval, niezależną od semanticSearch, która ma teraz zastosowanie wyłącznie do rozliczeń rankera semantycznego. knowledgeRetrieval jest właściwością płaszczyzny zarządzania, więc można ją ustawić za pomocą interfejsu API REST usługi Search Management, a nie interfejsu API REST usługi wyszukiwania.

Użyj najnowszej wersji zapoznawczej Usługi — Utwórz lub Zaktualizuj (interfejs API REST), aby skonfigurować knowledgeRetrieval na swojej usłudze wyszukiwania.

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

Aby uzyskać prawidłowe wartości i szczegóły rozliczania, zobacz Włączanie lub wyłączanie rozliczania pobierania agencyjnego.

Aktualizowanie kodu i klientów dla wersji 2026-04-01

Aby ukończyć migrację:

1. Zaktualizuj wywołania klienta, aby używały wersji interfejsu API 2026-04-01.

2. Zaktualizuj wszystkie zakodowane na stałe nazwy bazy wiedzy lub źródła wiedzy w kodzie, aby odwoływać się do nowych obiektów utworzonych podczas migracji.

3. Jeśli przeprowadzono migrację azureBlob lub indexedOneLake źródła wiedzy, zaktualizuj dowolny kod lub skrypty odwołujące się do skojarzonego indeksu, indeksatora, źródła danych lub zestawu umiejętności według nazwy, aby wskazać nowe obiekty.

4. Zaktualizuj kod, który przetwarza odzyskane odpowiedzi. Odpowiedzi zwracają treść bazową z elementami activity i references, a nie odpowiedzi syntetyzowane.

5. Usuń obiekty podglądu dopiero po pełnym zweryfikowaniu i wdrożeniu nowych obiektów.

2025-11-01-preview

W przypadku migracji z wersji 2025-08-01-preview nazwa "agenta wiedzy" zostanie zmieniona na "baza wiedzy", a wiele właściwości zostanie przeniesionych do różnych obiektów i poziomów w ramach definicji obiektu.

1. Aktualizowanie źródeł wiedzy searchIndex
2. Aktualizowanie źródeł wiedzy azureBlob
3. Zastępowanie agenta wiedzy bazą wiedzy
4. Aktualizowanie żądania pobierania i wysyłanie zapytania w celu przetestowania aktualizacji
5. Aktualizowanie kodu klienta

Aktualizowanie źródła wiedzy searchIndex

Ta procedura tworzy nowe 2025-11-01-previewsearchIndex źródło wiedzy na tym samym poziomie funkcjonalności co poprzednia 2025-08-01 wersja. Sam indeks bazowy nie wymaga aktualizacji.

1. Wyświetl listę wszystkich źródeł wiedzy według nazwy, aby znaleźć źródło wiedzy.

   ### 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. Pobierz bieżącą definicję, aby przejrzeć istniejące właściwości.

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

   Odpowiedź powinna być podobna do poniższego przykładu.

   {
        "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. Sformułuj żądanie utwórz źródło wiedzy jako podstawę migracji.

   Zacznij od kodu JSON 08-01-preview.

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

   Wprowadź następujące aktualizacje na potrzeby migracji 2025-11-01-preview:

   • Nadaj źródło wiedzy nową nazwę.

   • Zmień wersję interfejsu API na 2025-11-01-preview.

   • Zmień nazwę sourceDataSelect na sourceDataFields i zmień ciąg na tablicę z parami nazwa-wartość dla każdego pola, które chcesz przeszukiwać. Są to pola, które mają być zwracane w wynikach wyszukiwania, podobnie jak klauzula select w zapytaniu klasycznym.

4. Przejrzyj aktualizacje, a następnie wyślij żądanie, aby utworzyć obiekt.

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

Masz teraz źródło wiedzy searchIndex po migracji, które jest wstecznie zgodne z poprzednią wersją i używa prawidłowych specyfikacji właściwości dla elementu 2025-11-01-preview.

Odpowiedź zawiera pełną definicję nowego obiektu. Aby uzyskać więcej informacji o nowych właściwościach dostępnych dla tego typu źródła wiedzy, które można teraz wykonać za pomocą aktualizacji, zobacz How to create a search index knowledge source (Jak utworzyć źródło wiedzy indeksu wyszukiwania).

Aktualizowanie źródła wiedzy azureBlob

Ta procedura tworzy nowe 2025-11-01-previewazureBlob źródło wiedzy na tym samym poziomie funkcjonalności co poprzednia 2025-08-01 wersja. Tworzy nowy zestaw wygenerowanych obiektów: źródło danych, zestaw funkcji, indeksator, indeks.

1. Wyświetl listę wszystkich źródeł wiedzy według nazwy, aby znaleźć źródło wiedzy.

   ### 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. Pobierz bieżącą definicję, aby przejrzeć istniejące właściwości.

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

   Jeśli przepływ pracy zawiera model, odpowiedź powinna być podobna do poniższego przykładu. Zwróć uwagę, że odpowiedź zawiera nazwy wygenerowanych obiektów. Te obiekty są w pełni niezależne od źródła wiedzy i pozostają operacyjne, nawet jeśli zaktualizujesz lub usuniesz źródło wiedzy.

    {
      "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. Sformułuj żądanie utwórz źródło wiedzy jako podstawę migracji.

   Zacznij od kodu JSON 08-01-preview.

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

   Wprowadź następujące aktualizacje na potrzeby migracji 2025-11-01-preview:

   • Nadaj źródło wiedzy nową nazwę.

   • Zmień wersję interfejsu API na 2025-11-01-preview.

   • Dodaj ingestionParameters jako kontener dla następujących właściwości podrzędnych: "embeddingModel", , "chatCompletionModel""ingestionSchedule", "contentExtractionMode".

4. Przejrzyj aktualizacje, a następnie wyślij żądanie, aby utworzyć obiekt. Dla potoku indeksatora są tworzone nowo wygenerowane obiekty.

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

Masz teraz źródło wiedzy azureBlob po migracji, które jest wstecznie zgodne z poprzednią wersją i używa prawidłowych specyfikacji właściwości dla elementu 2025-11-01-preview.

Odpowiedź zawiera pełną definicję nowego obiektu. Aby uzyskać więcej informacji o nowych właściwościach dostępnych dla tego typu źródła wiedzy, które można teraz wykonać za pomocą aktualizacji, zobacz Tworzenie źródła wiedzy obiektu blob.

Zastępowanie agenta wiedzy bazą wiedzy

1. Bazy wiedzy wymagają źródła wiedzy. Przed rozpoczęciem upewnij się, że masz źródło wiedzy ukierunkowane na 2025-11-01-preview.

2. Pobierz bieżącą definicję, aby przejrzeć istniejące właściwości.

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

   Odpowiedź powinna być podobna do poniższego przykładu.

   {
     "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. Sformułuj żądanie utwórz bazę wiedzy jako podstawę migracji.

   Zacznij od kodu JSON 08-01-preview.

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

   Wprowadź następujące aktualizacje na potrzeby migracji 2025-11-01-preview:

   • Zastąp punkt końcowy: /knowledgebases/{{knowledge-base-name}}. Nadaj bazie wiedzy unikatową nazwę.

   • Zmień wersję interfejsu API na 2025-11-01-preview.

   • Usuń requestLimits element. Właściwości maxRuntimeInSeconds i maxOutputSize są teraz określane bezpośrednio w żądaniu pobierania.

   • Aktualizacja knowledgeSources:

     • Usuń maxSubQueries i zastąp go elementem retrievalReasoningEffort (zobacz Ustawianie nakładu pracy na rozumowanie podczas pobierania (wersja zapoznawcza)).

   • Przenieś alwaysQuerySourceelement , includeReferenceSourceData, includeReferencesi rerankerThreshold do knowledgeSourceParams sekcji akcji pobierania.

   • Brak zmian dla elementu models.

   • Aktualizacja outputConfiguration:

     • Zastąp outputConfiguration ciągiem outputMode.

     • Usuń attemptFastPath element. Już nie istnieje. Równoważne działanie uzyskuje się przez ustawienie retrievalReasoningEffort na wartość minimalną (zobacz Ustawianie wysiłku wnioskowania podczas pobierania (wersja zapoznawcza)).

     • Jeśli dla modalności ustawiono answerSynthesis wartość, upewnij się, że wysiłek na rzecz uzasadnienia pobierania jest ustawiony na niski (domyślny) lub średni.

   • Dodaj ingestionParameters jako wymaganie dotyczące tworzenia 2025-11-01-preview źródła wiedzy azureBlob.

4. Przejrzyj aktualizacje, a następnie wyślij żądanie, aby utworzyć obiekt. Dla potoku indeksatora są tworzone nowo wygenerowane obiekty.

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

Masz teraz bazę wiedzy zamiast agenta wiedzy, a obiekt jest wstecznie kompatybilny z poprzednią wersją.

Odpowiedź zawiera pełną definicję nowego obiektu. Aby uzyskać więcej informacji na temat nowych właściwości dostępnych dla bazy wiedzy, które można teraz wykonać za pośrednictwem aktualizacji, zobacz Jak utworzyć bazę wiedzy.

Aktualizowanie i testowanie pobierania aktualizacji 2025-11-01-preview

Żądanie pobierania zmodyfikowano dla elementu 2025-11-01-preview, aby obsługiwało więcej formatów, w tym prostszy wariant żądania, który minimalizuje przetwarzanie przez LLM. Aby uzyskać więcej informacji na temat pobierania w tej wersji zapoznawczej, zobacz Pobieranie danych przy użyciu bazy wiedzy. W tej sekcji wyjaśniono, jak zaktualizować kod.

1. Zmień punkt końcowy /agents/retrieve na /knowledgebases/retrieve.

2. Zmień wersję interfejsu API na 2025-11-01-preview.

3. Nie trzeba wprowadzać żadnych zmian w messages, jeśli używasz wysiłku wnioskowania przy pobieraniu low lub medium. Zastąp intents elementem minimal, jeśli używasz rozumowania (zobacz messages).

4. Zmodyfikuj, knowledgeSourceParams aby uwzględnić wszystkie właściwości usunięte z agenta: rerankerThreshold, , alwaysQuerySourceincludeReferenceSourceData, includeReferences.

5. Dodaj retrievalReasoningEffort ustawioną na minimum, jeśli używałeś attemptFastPath. Jeśli używałeś maxSubQueries, już nie istnieje. Użyj ustawienia retrievalReasoningEffort, aby określić przetwarzanie podzapytań (zobacz: Ustaw poziom wysiłku związanego z rozumowaniem podczas pobierania (wersja zapoznawcza)).

Aby przetestować wyniki bazy wiedzy za pomocą zapytania, użyj 2025-11-01-previewKnowledge 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
}

Jeśli odpowiedź zawiera 200 OK kod HTTP, baza wiedzy pomyślnie pobrała zawartość ze źródła wiedzy.

Aktualizacja kodu i klienty dla wersji 2025-11-01-preview

Aby ukończyć migrację, wykonaj następujące kroki oczyszczania:

1. Tylko w przypadku źródeł wiedzy typu blob zaktualizuj klientów, aby korzystali z nowego indeksu. Jeśli masz kod lub skrypt, który uruchamia indeksator lub odwołuje się do źródła danych, indeksu lub zestawu umiejętności, upewnij się, że zaktualizowano odwołania do nowych obiektów.

2. Zastąp wszystkie odwołania agenta w plikach konfiguracji, kodzie, skryptach i testach przy użyciu knowledgeBases.

3. Zaktualizuj wywołania klienta, tak aby korzystały z 2025-11-01-preview.

4. Wyczyść lub wygeneruj ponownie buforowane definicje, które zostały utworzone przy użyciu starych kształtów.

2025-08-01-preview

Jeśli agent wiedzy został utworzony przy użyciu wersji 2025-05-01-preview, definicja agenta zawiera tablicę śródliniową targetIndexes i właściwość opcjonalną defaultMaxDocsForReranker .

Począwszy od wersji interfejsu API 2025-08-01-preview, źródła wiedzy wielokrotnego użytku zastępują targetIndexes, a defaultMaxDocsForReranker nie jest już obsługiwane. Te zmiany łamiące kompatybilność wymagają:

1. Pobieranie bieżącej targetIndexes konfiguracji
2. Tworzenie równoważnego źródła wiedzy
3. Zaktualizuj agenta, aby używał knowledgeSources zamiast targetIndexes
4. Wysyłanie zapytania w celu przetestowania pobierania
5. Usuń kod używający targetIndexes i zaktualizuj klientów

Pobieranie bieżącej konfiguracji

Aby pobrać definicję agenta, użyj elementu 2025-05-01-previewKnowledge Agents — Get (interfejs API REST).

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

Odpowiedź powinna być podobna do poniższego przykładu. indexNameSkopiuj wartości , defaultRerankerThresholdi defaultIncludeReferenceSourceData do użycia w kolejnych krokach. defaultMaxDocsForReranker jest przestarzała, więc można zignorować jego wartość.

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

Tworzenie źródła wiedzy

Aby utworzyć searchIndex źródło wiedzy, użyj opcji 2025-08-01-previewŹródła wiedzy — tworzenie (interfejs API REST). Ustaw wartość searchIndexName na skopiowaną wcześniej.

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

W poprzednim przykładzie utworzono źródło wiedzy reprezentujące jeden indeks, ale można wskazać wiele indeksów lub obiekt blob platformy Azure jako cel. Aby uzyskać więcej informacji, zobacz Tworzenie źródła wiedzy.

Aktualizuj agenta

Aby zastąpić targetIndexes elementem knowledgeSources w definicji agenta, użyj w 2025-08-01-preview. Ustaw rerankerThreshold i includeReferenceSourceData na wcześniej skopiowane wartości.

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

Poprzedni przykład aktualizuje definicję, aby odwoływać się do jednego źródła wiedzy, ale można kierować do wielu źródeł wiedzy. Możesz również użyć innych właściwości, aby kontrolować zachowanie pobierania, takie jak alwaysQuerySource. Aby uzyskać więcej informacji, zobacz Tworzenie agenta wiedzy.

Testowanie pobierania aktualizacji 2025-08-01-preview

Aby przetestować wynik działania agenta przy użyciu zapytania, użyj opcji 2025-08-01-preview w Pobieranie wiedzy — pobieranie (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"
                    }
                ]
            }
        ]
    }

Jeśli odpowiedź zawiera 200 OK kod HTTP, agent pomyślnie pobrał zawartość ze źródła wiedzy.

Aktualizowanie kodu i klientów dla wersji 2025-08-01-preview

Aby ukończyć migrację, wykonaj następujące kroki oczyszczania:

• Zamień wszystkie odwołania do targetIndexes na knowledgeSources w plikach konfiguracyjnych, kodzie, skryptach i testach.
• Zaktualizuj wywołania klienta, tak aby korzystały z 2025-08-01-preview.
• Wyczyść lub wygeneruj ponownie buforowane definicje agentów, które zostały utworzone przy użyciu starego kształtu.

Zmiany specyficzne dla wersji

W tej sekcji opisano zmiany powodujące niezgodność i niezgodność dla następujących wersji interfejsu 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

Wersja 2026-08-01-preview bazuje na wersji 2026-05-01-preview i zawiera niekompatybilne zmiany dla aplikacji korzystających ze źródeł wiedzy Work IQ, stronicowania listy opartego na przesunięciu, rekordów działań obsługiwanych przez model, przetwarzania wyników serwera MCP lub wywołań wygenerowanego klienta z argumentami pozycyjnymi.

Aby zapoznać się z dokumentacją referencyjną interfejsu API REST dla tej wersji, wybierz 2026-08-01-preview filtr wersji interfejsu API w górnej części strony.

Zapowiedź 1 05.2026

2026-05-01-preview dodaje bazę wiedzy, źródło wiedzy i funkcje pobierania do wersji 2025-11-01-preview bez usuwania wcześniej utrwalonych właściwości. Istniejące bazy wiedzy i źródła wiedzy utworzone we wcześniejszych wersjach zapoznawczych nadal działają. Ta wersja głównie udostępnia nowe funkcje i znosi kilka ograniczeń obowiązujących wyłącznie w wersji zapoznawczej.

Aby zapoznać się z dokumentacją referencyjną interfejsu API REST dla tej wersji, wybierz 2026-05-01-preview filtr wersji interfejsu API w górnej części strony.

01.04.2026

2026-04-01 jest pierwszą stabilną wersją interfejsu API dla agentowego wyszukiwania. Ustanawia minimalny kontrakt ekstrakcyjnego pobierania i usuwa możliwości planowania zapytań oraz syntezy odpowiedzi, które istniały w okresie wersji wstępnej.

Aby zapoznać się z dokumentacją referencyjną interfejsu API REST dla tej wersji, wybierz 2026-04-01 filtr wersji interfejsu API w górnej części strony.

2025-11-01-preview

Aby zapoznać się z dokumentacją referencyjną interfejsu API REST dla tej wersji, wybierz 2025-11-01-preview filtr wersji interfejsu API w górnej części strony.

2025-08-01-preview

Aby zapoznać się z dokumentacją referencyjną interfejsu API REST dla tej wersji, wybierz 2025-08-01-preview filtr wersji interfejsu API w górnej części strony.

2025-05-01-podgląd

Ta wersja API wprowadza wyszukiwanie agentowe i agenty wiedzy. Każda definicja agenta wymaga targetIndexes tablicy, która określa pojedynczy indeks i opcjonalne właściwości, takie jak defaultRerankerThreshold i defaultIncludeReferenceSourceData.

Aby zapoznać się z dokumentacją referencyjną interfejsu API REST dla tej wersji, wybierz 2025-05-01-preview filtr wersji interfejsu API w górnej części strony.

Powiązana zawartość

• Pobieranie przy użyciu agentów w Wyszukiwanie AI platformy Azure
• Tworzenie bazy wiedzy
• Wykonywanie zapytań względem bazy wiedzy