Миграция агентского кода извлечения на последнюю версию

Если ваш код agentic retrieval ориентирован на более раннюю версию API, в этой статье объясняется, когда и как перейти на более новую версию. В нем также описываются критические и неразрывные изменения для всех версий API, поддерживающих извлечение агентов.

Инструкции по миграции предназначены для запуска существующего решения в более новой версии API. Инструкции в этой статье помогут устранить критические изменения на уровне API, чтобы приложение выполнялось как раньше. Для получения справки по добавлению новых функций начните с Что нового в Поиск с использованием ИИ Azure.

Когда мигрировать

Большинство версий, поддерживающих агентный поиск, содержали несовместимые изменения. Вы можете продолжать запускать старый код без изменений, сохраняя значение версии API, но чтобы воспользоваться исправлениями ошибок, улучшениями и более новыми функциями, необходимо обновить код.

Если код предназначен для предварительной версии, рекомендуется перейти на последнюю стабильную версию, только если вариант использования полностью поддерживается 2026-04-01. Если вы полагаетесь на синтез ответов, не минимальные усилия по анализу или многоэтапные сообщения, просмотрите критические и неразрывные изменения перед решением о миграции. Эти возможности остаются в предварительной версии.

Перед переносом

• Чтобы понять область изменений, просмотрите критические и неразрывные изменения для каждой версии.

• Поддерживаемый путь миграции является добавочным. Если ваш код ориентирован на 2025-05-01-preview, сначала выполните миграцию на 2025-08-01-preview, затем последовательно переходите на каждую следующую версию, пока не достигнете целевой версии.

• Для параллельной миграции создайте уникальные именованные объекты, реализующие поведение предыдущей версии. Этот подход сохраняет существующие объекты при разработке и тестировании замен. Если объект поддерживает обновление на месте, шаги для конкретной версии вызывают этот параметр.

• Для каждого перенесенного объекта начните с получения текущего определения из службы поиска, чтобы просмотреть существующие свойства перед указанием нового.

• Удалите старые версии только после полного тестирования и развертывания миграции.

Миграция

В этом разделе рассматриваются действия по миграции для следующих версий API:

• 2026-08-01-preview
• 2026-05-01-превью
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

При миграции с 2026-05-01-preview можно перейти непосредственно в 2026-08-01-preview. Эта миграция требует обновления источников знаний Work IQ, постраничного вывода списков, обработки ответов, инструментов сервера MCP и затронутых вызовов сгенерированного клиента.

1. Перенос источников знаний Work IQ
2. Обновление разбиения по страницам списка
3. Обновление обработки ответов при получении
4. Обновление кода и клиентов

Перенести источники знаний Work IQ

Чтобы перенести источник знаний Work IQ в новую конфигурацию проверки подлинности:

1. Экспортируйте текущее определение.

2. Обновите существующий источник знаний с помощью Knowledge Sources - Create Or Update или создайте замену с уникальным именем для параллельной миграции.

3. Используйте версию API 2026-08-01-preview и настройте workIQParameters.entraAppAuthentication. Свойства applicationId и federatedCredentialId являются обязательными. Свойство tenantId является необязательным и по умолчанию используется для клиента службы поиска.

4. При создании замены обновите каждую базу знаний, которая ссылается на предыдущий источник знаний, чтобы использовать имя замены.

5. Обновите запросы на получение, чтобы передать утверждение пользователя в заголовке x-ms-query-work-iq-source-authorization .

Сведения о настройке и примерах см. в разделе "Создание источника знаний для рабочих IQ" (предварительная версия).

Обновить разбиение списка на страницы

Чтобы заменить пагинацию на основе смещения на пагинацию на основе курсора:

1. Удалите $skip, $count и $top из запросов к списку источников знаний. Задайте pageSize от 1 до 3000, чтобы управлять размером страницы. Если вы опустите его, служба выбирает размер страницы.

2. Чтобы отфильтровать по имени, задайте search и searchType. Единственным поддерживаемым searchType значением является prefix, которое также является значением по умолчанию. Следующий запрос возвращает до 100 источников знаний, имена которых начинаются с contoso.

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

   Справочник:Источники знаний — список

3. Если ответ содержит @odata.nextLink, отправьте этот URL-адрес точно в том виде, в котором он был возвращён. Не анализируйте или не изменяйте его состояние продолжения.

Обновить обработку ответа на запрос получения

Чтобы обработать новый справочник Work IQ и схемы действий, поддерживаемые моделью:

1. Удаление зависимостей от attributions, WorkIQAttributionи seeMoreWebUrl. Считайте метаданные метки конфиденциальности из searchSensitivityLabelInfo в ссылке на Work IQ.

2. В записях действий по планированию запросов, синтезу ответов и веб-суммаризации считывайте modelName и deploymentId из вложенного объекта model. Вложенный объект и оба свойства являются необязательными.

Следующие фрагменты показывают изменения в структуре ответа.

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

В 2026-08-01-preview те же фрагменты имеют следующую форму:

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

Обновление кода и клиентов для версии 2026-08-01-preview

Чтобы завершить миграцию, выполните приведенные действия.

1. В каждом элементе сервера tools MCP замените inclusionMode на resultsProcessing. Сопоставьте reranked с rerank и always с none. Значение rerank является значением по умолчанию. Значение none обходит повторное ранжирование и сохраняет исходный порядок результатов инструмента. Сведения о настройке см. в разделе "Настройка средств для источника знаний сервера MCP".

2. Если вы используете Azure SDK, установите пакет, который поддерживает2026-08-01-preview, и просмотрите вызовы позиционного списка для изменений порядка параметров. Это не влияет на клиентов REST, поскольку параметры HTTP идентифицируются по имени. В C#предпочитайте именованные аргументы, например GetKnowledgeSourcesAsync(search: ..., pageSize: ...). В Python передайте параметры списка в качестве аргументов ключевых слов.

3. Проверьте аутентификацию Work IQ и ссылки, курсорную пагинацию, десериализацию записей активности, порядок результатов сервера MCP и вызовы сгенерированного клиента перед обновлением продакшена.

4. Если вы создали новые источники знаний Work IQ взамен прежних, удаляйте старые источники только после того, как миграция успешно пройдет все тесты, обновленное приложение будет развернуто и ни одна база знаний не будет ссылаться на прежние названия.

2026-05-01-превью

При миграции с 2026-04-01 или 2025-11-01-preview вы можете перейти непосредственно в 2026-05-01-preview. Запросы, ответы и сохраненные объекты из этих версий остаются совместимыми. Различия являются аддитивными функциями и переименованиями языкового пакета SDK.

1. Обновите версию API до 2026-05-01-preview в REST-запросах. Клиенты SDK используют версию API по умолчанию пакета, поэтому не нужно передавать явный serviceVersion аргумент. Вместо этого обновите пакет 2026-05-01-preview SDK.

2. Если вы используете пакет SDK Python или JavaScript, обновите клиент извлечения до KnowledgeBaseRetrievalClient и вызовите retrieve(...) вместо устаревшей версии retrieveKnowledge(...). Полное сопоставление фигур пакета SDK см. в разделе "Обновление кода и клиентов для версии 2026-05-01-preview".

3. (Необязательно) Внедрите новые 2026-05-01-preview функции, такие как извлечение с учетом актуальности, ограничения на количество документов для каждого источника и в итоговых результатах, сохраняемые значения по умолчанию для retrieve, поддержка CORS для базы знаний и метаданные меток конфиденциальности Purview в ответах retrieve. Ни одна из этих функций не требуется для обеспечения работы существующего решения.

Обновление кода и клиентов для версии 2026-05-01-preview

Пакеты 2026-05-01-preview SDK вводят изменения в форме кода на поддерживаемых языках:

После обновления структур клиента запустите полный процесс, который создает индекс, загружает документы, создает источник знаний, создает базу знаний, отправляет запрос на извлечение и очищает ресурсы, чтобы подтвердить сквозную миграцию.

01.04.2026

Если вы выполняете миграцию с 2025-11-01-preview, вы можете перейти непосредственно в 2026-04-01. Индекс и содержимое остаются неизменными. Вам нужно только обновить схему базы знаний и структуру запроса на извлечение.

1. Перенос источников знаний
2. Перенос базы знаний
3. Обновление запроса на получение
4. Обновление согласия на выставление счетов
5. Обновление кода и клиентов

Перенос источников знаний

В 2026-04-01 типы источников знаний searchIndex, azureBlob, indexedOneLake и web стали общедоступными. Другие типы источников знаний остаются в предварительной версии.

1. Используйте источники знаний — получение (REST API) для получения текущего определения.

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

2. В ответе определите, что следует перенести и что удалить:

   • Для searchIndex и web перенесите все значения свойств.

   • Для azureBlob и indexedOneLake, перенесите все значения свойств, но исключите ingestionPermissionOptions из ingestionParameters. Это свойство не поддерживается в 2026-04-01.

3. Используйте источники знаний— создание или обновление (REST API) для создания нового источника знаний с уникальным именем, 2026-04-01 версией API и значениями свойств на предыдущем шаге.

   В следующем примере показан источник знаний searchIndex . Используйте аналогичный шаблон для azureBlob, indexedOneLake, и 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" }
       ]
     }
   }
   

Перенос базы знаний

База 2026-04-01 знаний имеет простую схему, чем 2025-11-01-preview версия: она сохраняет knowledgeSources и удаляет параметры создания ответов. Просмотрите текущее определение перед созданием нового объекта.

1. Используйте базы знаний — получение (REST API) для получения текущего определения.

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

2. В ответе определите, что следует перенести и что удалить:

   • Обратите внимание на ссылки knowledgeSources. Перенесите их в новую базу знаний.

   • При наличии удалите outputMode, answerInstructions и retrievalInstructions. Эти свойства не поддерживаются в 2026-04-01.

   • Если в базе знаний используется источник знаний web , сохраните models. Для извлечения данных из Интернета требуется резюмирование на основе модели. Для всех других типов источников знаний удалите models.

3. Используйте базы знаний — создание или обновление (REST API) для создания новой базы знаний с уникальным именем, 2026-04-01 версией API и только поддерживаемыми свойствами.

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

Обновите запрос на извлечение

Запрос 2026-04-01 на получение имеет другую фигуру, отличную от предварительной версии:

• Используйте intents вместо messages.

• Используйте maxOutputSizeInTokens вместо maxOutputSize.

• При наличии, удалите retrievalReasoningEffort и alwaysQuerySource. Эти параметры не поддерживаются в 2026-04-01.

• Для дальнейших вопросов отправьте новый запрос на получение с новым семантическим намерением. 2026-04-01 не поддерживает расшифровку запущенных сообщений.

Чтобы проверить результат базы знаний с помощью запроса, используйте версию 2026-04-01Knowledge 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
}

Если ответ содержит 200 OK HTTP-код, база знаний успешно извлекла содержимое из источника знаний.

Обновление согласия на выставление счетов

Начиная с версии API 2026-04-01, согласие на выставление счетов за agentic retrieval управляется отдельным свойством knowledgeRetrieval, которое не зависит от semanticSearch, а semanticSearch теперь применяется только к биллингу семантического ранжировщика. knowledgeRetrieval — это свойство плоскости управления, поэтому его можно задать с помощью REST API управления поиском, а не REST API службы поиска.

Используйте последнюю предварительную версию служб — создание или обновление (REST API) для установки 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"
  }
}

Допустимые значения и сведения о выставлении счетов см. в разделе "Включение или отключение выставления счетов агента".

Обновление кода и клиентов для 2026-04-01

Чтобы завершить миграцию, выполните приведенные действия.

1. Обновите вызовы клиента, чтобы использовать версию 2026-04-01 API.

2. Обновите все жесткие имена базы знаний или источников знаний в коде, чтобы ссылаться на новые объекты, созданные во время миграции.

3. При перенесении azureBlob или indexedOneLake источников знаний обновите любой код или скрипты, ссылающиеся на связанный индекс, индексатор, источник данных или набор навыков по имени, чтобы ссылаться на новые объекты.

4. Обновите код, который обрабатывает получение ответов. Ответы возвращают извлекаемое опорное содержимое с activity и references, не являются синтезированными ответами.

5. Удалите объекты предварительного просмотра только после полной проверки и развертывания новых объектов.

2025-11-01-preview

Если вы выполняете миграцию с 2025-08-01-preview, "агент знаний" переименован в "базу знаний", а несколько свойств были перемещены в разные объекты и уровни в определении объекта.

1. Обновление источников знаний searchIndex
2. Обновление источников знаний azureBlob
3. Замена агента знаний базой знаний
4. Обновление запроса на получение и отправка запроса для тестирования обновлений
5. Обновление клиентского кода

Обновление источника знаний searchIndex

Эта процедура создает новый 2025-11-01-previewsearchIndex источник знаний на том же функциональном уровне, что и предыдущая 2025-08-01 версия. Сам базовый индекс не требует обновлений.

1. Перечислите все источники знаний по имени, чтобы найти источник знаний.

   ### 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. Получите текущее определение для просмотра существующих свойств.

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

   Ответ должен быть похож на следующий пример.

   {
        "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. Сформулируйте запрос на создание источника знаний в качестве основы для миграции.

   Начните с 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"
     }
   }
   

   Выполните следующие обновления для миграции 2025-11-01-preview :

   • Присвойте источнику знаний новое имя.

   • Измените версию 2025-11-01-previewAPI на .

   • sourceDataSelect Переименуйте sourceDataFields и измените строку на массив с парами "имя-значение" для каждого извлекаемого поля, которое требуется запросить. Это поля, возвращаемые в результатах поиска, аналогичные select предложению в классическом запросе.

4. Просмотрите обновления и отправьте запрос на создание объекта.

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

Теперь у вас есть мигрированный источник знаний searchIndex, который обратно совместим с предыдущей версией и использует правильные спецификации свойств для 2025-11-01-preview.

Ответ включает полное определение нового объекта. Дополнительные сведения о новых свойствах, доступных этому типу источника знаний, которые теперь можно сделать с помощью обновлений, см. в статье "Создание источника знаний индекса поиска".

Обновите источник знаний для azureBlob

Эта процедура создает новый 2025-11-01-previewazureBlob источник знаний на том же функциональном уровне, что и предыдущая 2025-08-01 версия. Он создает новый набор созданных объектов: источник данных, набор умений, индексатор, индекс.

1. Перечислите все источники знаний по имени, чтобы найти источник знаний.

   ### 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. Получите текущее определение для просмотра существующих свойств.

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

   Если рабочий процесс содержит модель, ответ должен быть похож на следующий пример. Обратите внимание, что ответ содержит имена созданных объектов. Эти объекты полностью не зависят от источника знаний и остаются операционными, даже если вы обновляете или удаляете их источник знаний.

    {
      "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. Сформулируйте запрос на создание источника знаний в качестве основы для миграции.

   Начните с 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
     }
   }
   

   Выполните следующие обновления для миграции 2025-11-01-preview :

   • Присвойте источнику знаний новое имя.

   • Измените версию 2025-11-01-previewAPI на .

   • Добавьте ingestionParameters в контейнер для следующих дочерних свойств: "embeddingModel", "chatCompletionModel", "ingestionSchedule". "contentExtractionMode"

4. Просмотрите обновления и отправьте запрос на создание объекта. Для конвейера индексатора создаются новые объекты.

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

Теперь у вас есть мигрированный источник знаний azureBlob, который обратно совместим с предыдущей версией и использует правильные спецификации свойств для 2025-11-01-preview.

Ответ включает полное определение нового объекта. Дополнительные сведения о новых свойствах, доступных этому типу источника знаний, которые теперь можно сделать с помощью обновлений, см. в статье "Создание источника знаний BLOB-объектов".

Замена агента знаний базой знаний

1. Для баз знаний требуется источник знаний. Прежде чем начать, убедитесь, что у вас есть источник знаний, ориентированный на 2025-11-01-preview.

2. Получите текущее определение для просмотра существующих свойств.

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

   Ответ должен быть похож на следующий пример.

   {
     "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. Сформулируйте запрос Создание базы знаний в качестве основы для миграции.

   Начните с 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"
       }
   }
   

   Выполните следующие обновления для миграции 2025-11-01-preview :

   • Замените конечную точку: /knowledgebases/{{knowledge-base-name}}. Присвойте базе знаний уникальное имя.

   • Измените версию 2025-11-01-previewAPI на .

   • Удалите requestLimits. Свойства maxOutputSize и maxRuntimeInSeconds теперь указываются непосредственно в самом запросе на извлечение.

   • Обновление knowledgeSources:

     • Удалите maxSubQueries и замените его на retrievalReasoningEffort (см. Настройка усилия логического вывода для извлечения (предварительная версия)).

   • Переместите alwaysQuerySource, includeReferenceSourceData, includeReferences, и rerankerThreshold в раздел knowledgeSourceParams операции извлечения.

   • Никаких изменений для models.

   • Обновление outputConfiguration:

     • Замените outputConfiguration на outputMode.

     • Удалите attemptFastPath. Она больше не существует. Аналогичное поведение реализуется путём установки retrievalReasoningEffort на минимальное значение (см. раздел Настройка усилия логического вывода при извлечении (предварительная версия)).

     • Если для модальности задано значение answerSynthesis, убедитесь, что усиление для обоснования извлечения установлено на низкий (по умолчанию) или средний.

   • Добавьте ingestionParameters в список требований для создания источника знаний 2025-11-01-preview azureBlob.

4. Просмотрите обновления и отправьте запрос на создание объекта. Для конвейера индексатора создаются новые объекты.

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

Теперь у вас есть база знаний вместо агента знаний, а объект обратно совместим с предыдущей версией.

Ответ включает полное определение нового объекта. Дополнительные сведения о новых свойствах, доступных базе знаний, которую теперь можно выполнить с помощью обновлений, см. в статье "Создание базы знаний".

Обновление и проверка получения обновлений 2025-11-01-preview

Запрос на извлечение изменён для 2025-11-01-preview, чтобы поддерживать больше форм, включая более простой вариант запроса, который сводит к минимуму обработку со стороны LLM. Дополнительные сведения о получении данных в этой предварительной версии см. в статье Получение данных с помощью базы знаний. В этом разделе объясняется, как обновить код.

1. Измените конечную точку с /agents/retrieve на /knowledgebases/retrieve.

2. Измените версию 2025-11-01-previewAPI на .

3. Не требуется вносить изменения в messages, если вы используете low или medium для уровня усилий рассуждения при извлечении. Замените intents на minimal, если используете рассуждения messages (см. Настройка усилия рассуждений при извлечении (предварительная версия)).

4. Измените knowledgeSourceParams, чтобы включить свойства, которые были удалены из агента: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

5. Добавьте значение retrievalReasoningEffort для minimum, если вы использовали attemptFastPath. Если вы использовали maxSubQueries, он больше не существует. Используйте параметр retrievalReasoningEffort, чтобы задать обработку подзапросов (см. раздел Задайте интенсивность рассуждений при извлечении данных (предварительная версия)).

Чтобы проверить ответ базы знаний с помощью запроса, используйте 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
}

Если ответ содержит 200 OK HTTP-код, база знаний успешно извлекла содержимое из источника знаний.

Обновление кода и клиентских приложений для 2025-11-01-предварительной версии

Чтобы завершить миграцию, выполните следующие действия по очистке:

1. Только для источников знаний типа blob обновите клиентские приложения для использования нового индекса. Если у вас есть код или скрипт, который запускает индексатор или ссылается на источник данных, индекс или набор навыков, убедитесь, что вы обновляете ссылки на новые объекты.

2. Замените все ссылки knowledgeBases на агенты в файлах конфигурации, коде, скриптах и тестах.

3. Обновите вызовы клиента так, чтобы они использовали 2025-11-01-preview.

4. Очистка или повторное создание кэшированных определений, созданных с помощью старых фигур.

2025-08-01-предварительный просмотр

Если вы создали агент знаний с помощью предварительной версии 2025-05-01-preview, определение агента включает встроенный targetIndexes массив и необязательное defaultMaxDocsForReranker свойство.

Начиная с версии API 2025-08-01-preview повторно используемые источники знаний заменяют targetIndexes, а defaultMaxDocsForReranker больше не поддерживается. Эти разрушающие изменения требуют от вас следующее:

1. Получите текущую targetIndexes конфигурацию
2. Создание эквивалентного источника знаний
3. Обновите агент, чтобы использовать knowledgeSources вместо targetIndexes
4. Отправка запроса для проверки извлечения
5. Удалите код, использующий targetIndexes и обновите клиентов

Получение текущей конфигурации

Чтобы получить определение агента, используйте 2025-05-01-previewметод 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}}

Ответ должен быть похож на следующий пример. Скопируйте значения indexName, defaultRerankerThreshold, и defaultIncludeReferenceSourceData для использования в следующих шагах. defaultMaxDocsForReranker не рекомендуется, поэтому его значение можно игнорировать.

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

Создание источника знаний

Чтобы создать searchIndex источник знаний, используйте метод 2025-08-01-preview из Источники знаний — создание (REST API). Установите для searchIndexName ранее скопированное значение.

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

В предыдущем примере создается источник знаний, представляющий один индекс, но можно использовать несколько индексов или большой двоичный объект Azure. Дополнительные сведения см. в разделе "Создание источника знаний".

Обновление агента

Чтобы заменить targetIndexes на knowledgeSources в определении вашего агента, используйте 2025-08-01-preview из Агенты знаний — создание или обновление (REST API). Задайте rerankerThreshold и includeReferenceSourceData значения, скопированные ранее.

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

В предыдущем примере определение обновляется для ссылки на один источник знаний, но вы можете использовать несколько источников знаний. Вы также можете использовать другие свойства для управления поведением извлечения, например alwaysQuerySource. Дополнительные сведения см. в разделе "Создание агента знаний".

Проверка получения обновлений 2025-08-01-preview

Чтобы проверить ответ агента с помощью запроса, используйте 2025-08-01-preview из Получение знаний — извлечение (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"
                    }
                ]
            }
        ]
    }

Если в ответе 200 OK есть HTTP-код, агент успешно получил содержимое из источника знаний.

Обновление кода и клиентов для версии 2025-08-01-preview

Чтобы завершить миграцию, выполните следующие действия по очистке:

• Замените все ссылки targetIndexes на knowledgeSources в файлах конфигурации, коде, скриптах и тестах.
• Обновите вызовы клиента так, чтобы они использовали 2025-08-01-preview.
• Очистка или повторное создание определений кэшированных агентов, созданных с помощью старого шаблона.

Изменения, связанные с версией

В этом разделе рассматриваются критические и неразрывные изменения для следующих версий API:

• 2026-08-01-preview
• 2026-05-01-превью
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

Версия 2026-08-01-preview основана на версии 2026-05-01-preview и включает критические изменения для приложений, использующих источники знаний Work IQ, разбиение на страницы списка на основе смещения, записи действий, поддерживаемые моделью, обработку результатов сервера MCP или вызовы позиционного клиента.

Чтобы просмотреть справочную документацию по REST API для этой версии, выберите 2026-08-01-preview фильтр версий API в верхней части страницы.

2026-05-01-превью

2026-05-01-preview добавляет базу знаний, источник знаний и извлекает функции поверх 2025-11-01-preview без удаления ранее сохраненных свойств. Существующие базы знаний и источники знаний, созданные в предыдущих предварительных версиях, продолжают работать. Эта версия в основном предоставляет новые функциональные возможности и отменяет несколько ограничений, доступных только для предварительной версии.

Чтобы просмотреть справочную документацию по REST API для этой версии, выберите 2026-05-01-preview фильтр версий API в верхней части страницы.

01.04.2026

2026-04-01 — это первая стабильная версия API для агентного поиска. Он устанавливает минимальный контракт на извлечение данных и удаляет возможности планирования запросов и синтеза ответов эпохи предпросмотра.

Чтобы просмотреть справочную документацию по REST API для этой версии, выберите 2026-04-01 фильтр версий API в верхней части страницы.

2025-11-01-preview

Чтобы просмотреть справочную документацию по REST API для этой версии, выберите 2025-11-01-preview фильтр версий API в верхней части страницы.

2025-08-01-предварительный просмотр

Чтобы просмотреть справочную документацию по REST API для этой версии, выберите 2025-08-01-preview фильтр версий API в верхней части страницы.

2025-05-01-предварительная версия

В этой версии API представлены агентические агенты извлечения и агенты знаний. Для каждого определения агента требуется массив, указывающий targetIndexes один индекс и необязательные свойства, например defaultRerankerThreshold и defaultIncludeReferenceSourceData.

Чтобы просмотреть справочную документацию по REST API для этой версии, выберите 2025-05-01-preview фильтр версий API в верхней части страницы.

Связанное содержимое

• Агентическое извлечение в Поиск с использованием ИИ Azure
• Создание базы знаний
• Запрос базы знаний