你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将代理检索代码迁移到最新版本

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

如果代理检索代码面向早期 API 版本，本文介绍何时以及如何迁移到较新版本。它还描述了支持代理检索的所有 API 版本的破坏性更改和非破坏性更改。

迁移说明旨在帮助你在较新的 API 版本上运行现有解决方案。本文中的说明可帮助你解决 API 级别的中断性变更，以便应用像以前一样运行。有关添加新功能的帮助，请从 Azure AI 搜索中的新增内容开始。

提示

使用Azure SDK而不是 REST？在升级包并应用相关的迁移更改之前，请检查 SDK 语言的更改日志，以确认对目标 API 版本的支持。

何时迁移

支持代理检索的大多数版本都引入了重大更改。通过保留 API 版本值，可以继续运行旧代码，但要受益于 bug 修复、改进和更新功能，必须更新代码。

如果代码面向预览版，建议仅在用例完全支持 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 服务器工具以及受影响的生成客户端调用。

迁移 Work IQ 知识来源
更新列表分页设置
更新检索响应处理
更新代码和客户端

迁移 Work IQ 知识源

将 Work IQ 知识源迁移到新的身份验证配置：

导出其当前定义。
使用 Knowledge Sources - Create Or Update 更新现有知识源，或为并行迁移创建一个具有唯一名称的替代项。
使用 2026-08-01-preview API 版本并配置 workIQParameters.entraAppAuthentication。 applicationId和federatedCredentialId属性是必需的。该 tenantId 属性是可选的，默认为搜索服务的租户。
如果您创建了替代项，请更新每个引用先前知识源的知识库，使其使用该替代项名称。
更新检索请求，使其在 x-ms-query-work-iq-source-authorization 标头中传递用户断言。

有关设置和示例，请参阅创建工作 IQ 知识源（预览版）。

更新列表分页

若要将基于偏移的分页替换为基于游标的分页，请执行以下操作：

从知识源列表请求中移除 $skip、$count 和 $top。将 pageSize 设置为 1 到 3,000，以控制页面大小。如果省略它，服务会选择页面大小。
若要按名称进行筛选，请设置 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}}
```
参考：知识源 - 列表
如果响应包含 @odata.nextLink，则发送该 URL 与返回的 URL 完全相同。不要解析或修改其延续状态。

更新检索响应处理

若要处理新的工作 IQ 参考和模型支持的活动形状，请执行以下操作：

删除对 attributions、WorkIQAttribution 和 seeMoreWebUrl 的依赖项。从 Work IQ 参考中的 searchSensitivityLabelInfo 读取敏感度标签的元数据。
在查询规划、答案合成和网页摘要活动记录中，从嵌套的model对象中读取modelName和deploymentId。嵌套对象和两个属性都是可选的。

以下片段显示了响应形状的更改。

{
  "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 的代码和客户端

若要完成迁移，请执行以下操作：

在每个 MCP 服务器 tools 项上，将 inclusionMode 替换为 resultsProcessing。将rerank映射到reranked，并将always映射到none。 rerank 值为默认值。该值 none 绕过重新调整，并保留工具的基础结果顺序。有关设置，请参阅配置 MCP 服务器知识源的工具。
如果您使用 Azure SDK，请安装支持 2026-08-01-preview 的程序包，并检查以位置参数方式调用列表时是否需要根据参数顺序的变化进行调整。 REST 调用方不受影响，因为 HTTP 参数是以名称为键的。在 C# 中，首选命名参数，如 GetKnowledgeSourcesAsync(search: ..., pageSize: ...). 在Python中，将列表选项作为关键字参数传递。
在更新生产环境之前，先测试 Work IQ 的身份验证和引用功能、基于游标的分页、活动记录反序列化、MCP 服务器结果排序以及生成的客户端调用。
如果您创建了替代的 Work IQ 知识源，则只有在迁移通过所有测试、更新后的应用程序已部署，并且没有任何知识库引用先前名称之后，才能删除原有的知识源。

2026-05-01-预览

如果要从 2026-04-01 或 2025-11-01-preview 迁移，可以直接移动到 2026-05-01-preview。来自这些版本的请求、响应和持久化对象仍然兼容。区别在于累加功能和语言 SDK 重命名。

在 REST 请求中，将 API 版本更新为 2026-05-01-preview。 SDK 客户端使用包的默认 API 版本，因此无需传递显式 serviceVersion 参数。而是升级到 2026-05-01-preview SDK 包。
如果使用 Python 或 JavaScript SDK，请将检索客户端更新为 KnowledgeBaseRetrievalClient，并调用 retrieve(...)，而不是旧的 retrieveKnowledge(...)。有关完整的 SDK 形状映射，请参阅 2026-05-01-preview 的更新代码和客户端。
（可选）采用这些新功能 2026-05-01-preview，例如新鲜度感知检索、每个源文档上限和最终结果文档上限、持久化的检索默认设置、知识库 CORS，以及检索响应中的 Purview 敏感度标签元数据。无需这些功能即可使现有解决方案正常工作。

更新 2026-05-01-preview 的代码和客户端

2026-05-01-preview SDK 在所有受支持的语言中引入了代码结构变更：

语言	迁移更新
Python	将检索客户端创建为 `KnowledgeBaseRetrievalClient(endpoint=..., credential=..., knowledge_base_name=...)`. 构造推理工作实例，例如 `KnowledgeRetrievalLowReasoningEffort()` ，在知识库上传递字符串 `output_mode="answerSynthesis"` 或检索请求。使用资源根端点而不是 `AzureOpenAIVectorizerParameters(resource_url=...)` 端点来传递 `resource_uri`（由 `/openai/v1` 重命名而来）。
.NET	将检索客户端创建为 `new KnowledgeBaseRetrievalClient(endpoint, knowledgeBaseName, credential)`，并传递 `AzureKeyCredential` 或令牌凭据。若要将基于密钥的 Azure OpenAI 模型附加到知识库，请在 `AzureOpenAIVectorizerParameters.ApiKey` 上设置模型 API 密钥。
Java	使用 `KnowledgeBaseRetrievalClientBuilder` 创建检索客户端，并将结果读取为 `KnowledgeBaseRetrievalResult`。 `KnowledgeBaseRetrievalOptions` 现在除了 `setMessages(...)` 外，还公开了 `setIntents(...)`、`setRetrievalReasoningEffort`、`setOutputMode`、`setMaxOutputSize` 和 `setMaxOutputDocuments`，因此基于消息的检索和答案合成无需语义意图变通方法即可工作。 `KnowledgeBase` 添加 `setOutputMode`、 `setRetrievalReasoningEffort`、 `setRetrievalInstructions`、 `setAnswerInstructions`和 `setCorsOptions`。 `SearchIndexKnowledgeSourceParams` 添加 `setAlwaysQuerySource`、 `setFailOnError`、 `setMaxOutputDocuments`和 `setEnableImageServing`。
JavaScript 和 TypeScript	使用 `KnowledgeRetrievalClient.retrieve({ intents: [{ type: "semantic", search: query }] })`。之前的 `retrieveKnowledge(...)` 方法已移除，改用 `retrieve(...)`。

更新客户端形状后，运行完整流，创建索引、上传文档、创建知识库、发出检索请求并清理资源以确认迁移端到端。

2026-04-01

如果要从 2025-11-01-preview 迁移，可以直接迁移到 2026-04-01。索引和内容保持不变。只需更新知识库架构和检索请求形状。

迁移知识源
迁移知识库
更新检索请求
更新计费许可
更新代码和客户端

迁移知识源

在 2026-04-01 中，searchIndex、azureBlob、indexedOneLake 和 web 知识源类型现已正式可用。其他知识源类型仍为预览版。

使用知识源 - 获取（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

在响应中，确定要转发的内容以及要删除的内容：
- 对于 searchIndex 和 web，传递所有属性值。
- 对于azureBlob和indexedOneLake，传递所有属性值，但从ingestionPermissionOptions中省略ingestionParameters。 2026-04-01 不支持此属性。

使用知识源 - 创建或更新（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并删除答案生成设置。在创建新对象之前，请查看当前定义。

使用知识库 - 获取（REST API）获取当前定义。

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

在响应中，确定要转发的内容以及要删除的内容：
- 注意 knowledgeSources 引用。将这些内容转发到新的知识库中。
- 如果存在，请删除outputMode和answerInstructionsretrievalInstructions。这些属性在 2026-04-01 中不受支持。
- 如果知识库使用 web 知识源，请保留 models。 Web 检索需要模型支持的摘要。对于所有其他知识源类型，请删除 models。

使用知识库 - 创建或更新（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-01知识检索 - 检索版本（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 代码，则知识库已成功从知识库检索到内容。

从 2026-04-01 API 版本开始，代理检索计费许可由独立于semanticSearch的专用knowledgeRetrieval属性控制，该属性现在仅适用于语义排名器计费。 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年4月1日

若要完成迁移，请执行以下操作：

更新客户端调用以使用 2026-04-01 API 版本。
更新代码中的任何硬编码知识库或知识库名称，以引用在迁移过程中创建的新对象。
如果迁移 azureBlob 或 indexedOneLake 知识源，请更新引用关联索引、索引器、数据源或技能集的任何代码或脚本（按名称指向新对象）。
更新处理检索响应的代码。响应返回具有 activity 和 references 的提取基础内容，而不是合成答案。
仅在对新对象进行完全验证和部署后删除预览对象。

2025-11-01-preview

如果要从 2025-08-01-preview 迁移，“知识代理”将重命名为“知识库”，并且多个属性将重新定位到对象定义中的不同对象和级别。

更新 searchIndex 知识库
更新 azureBlob 知识源
将知识代理替换为知识库
更新检索请求并发送查询以测试更新
更新客户端代码

更新 "searchIndex" 知识源

此过程在与以前的2025-08-01版本相同的功能级别创建新的2025-11-01-previewsearchIndex知识源。基础索引本身不需要更新。

按名称列出所有知识源以查找知识源。

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

获取当前定义以查看现有属性。

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

将创建知识源请求制定为迁移的基础。

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

针对 2025-11-01-preview 迁移进行以下更新：

为知识源提供新名称。
将 API 版本更改为 2025-11-01-preview.
重命名 sourceDataSelect 字符串 sourceDataFields 并将其更改为包含要查询的每个可检索字段的名称/值对的数组。这些是搜索结果中要返回的字段，类似于经典查询中的 select 子句。

查看更新，然后发送请求以创建对象。

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 使用了正确的属性规范。

响应包括新对象的完整定义。有关此知识源类型可用的新属性的详细信息（现在可以通过更新执行此操作），请参阅如何创建搜索索引知识源。

更新 Azure Blob 知识源

此过程在与以前的2025-08-01版本相同的功能级别创建新的2025-11-01-previewazureBlob知识源。它创建了一组新的生成对象：数据源、技能集、索引器、索引。

按名称列出所有知识源以查找知识源。

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

获取当前定义以查看现有属性。

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

将创建知识源请求制定为迁移的基础。

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

针对 2025-11-01-preview 迁移进行以下更新：

为知识源提供新名称。
将 API 版本更改为 2025-11-01-preview.
添加ingestionParameters为以下子属性的容器："embeddingModel"、、"chatCompletionModel""ingestionSchedule""contentExtractionMode"。

查看更新，然后发送请求以创建对象。为索引管道创建新生成的对象。

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 知识源”。

将知识代理替换为知识库

知识库需要知识来源。在开始之前，请确保你有一个面向 2025-11-01-preview 的知识源。

获取当前定义以查看现有属性。

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

将创建知识库请求作为迁移的基础。

从 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"
    }
}
```
针对 2025-11-01-preview 迁移进行以下更新：
- 替换终结点： /knowledgebases/{{knowledge-base-name}}. 为知识库指定唯一的名称。
- 将 API 版本更改为 2025-11-01-preview.
- 删除 requestLimits。 maxRuntimeInSeconds 和 maxOutputSize 属性现在可直接在检索请求上指定。
- 更新 knowledgeSources：
  - 删除maxSubQueries并将其替换为retrievalReasoningEffort（请参阅“设置检索推理工作”（预览版）。
- 移动alwaysQuerySource、includeReferenceSourceData、includeReferences和rerankerThreshold到knowledgeSourceParams检索操作的部分。
- 没有更改 models。
- 更新 outputConfiguration：
  - 将 outputConfiguration 替换为 outputMode。
  - 删除 attemptFastPath。它不再存在。通过retrievalReasoningEffort设置为最小值来实现等效行为（请参阅“设置检索推理工作”（预览版）。
  - 如果模式设置为 answerSynthesis，请确保将检索推理工作量设置为低（默认值）或中等。
- 将 ingestionParameters 添加为创建 2025-11-01-preview azureBlob 知识源的必要条件。

查看更新，然后发送请求以创建对象。为索引管道创建新生成的对象。

 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 处理。有关此预览版中检索的详细信息，请参阅使用知识库检索数据。本部分介绍如何更新代码。

将 /agents/retrieve 终结点更改为 /knowledgebases/retrieve.
将 API 版本更改为 2025-11-01-preview.
如果你使用的是 medium 或 messages 检索推理工作量，则无需对 low 进行任何更改。如果您使用minimal推理（请参阅设置检索推理强度（预览）），请将messages替换为intents。
修改knowledgeSourceParams以包括从代理中删除的任何属性：rerankerThreshold、、alwaysQuerySourceincludeReferenceSourceDataincludeReferences。
如果使用的是 retrievalReasoningEffort，请将 minimum 设置为 attemptFastPath。如果使用 maxSubQueries，则它不再存在。使用retrievalReasoningEffort设置指定子查询处理（请参阅“设置检索推理工作”（预览版）。

若要使用查询测试知识库的输出，请使用2025-11-01-preview知识检索 - 检索（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-preview 的代码和客户端

若要完成迁移，请遵循以下清理步骤：

仅对于 Blob 知识源，请更新客户端以使用新索引。如果你有运行索引器或引用数据源、索引或技能集的代码或脚本，请确保更新对新对象的引用。
将所有代理引用替换为 knowledgeBases 配置文件、代码、脚本和测试。
更新客户端调用以使用 2025-11-01-preview.
清除或重新生成使用旧形状创建的缓存定义。

2025-08-01-preview

如果使用 2025-05-01-preview 创建了知识代理，则代理的定义包括内联 targetIndexes 数组和可选 defaultMaxDocsForReranker 属性。

从 2025-08-01-preview API 版本开始，可重用的知识源取代了 targetIndexes，并且 defaultMaxDocsForReranker 不再受支持。这些重大更改要求你：

获取当前 targetIndexes 配置
创建等效的知识源
更新代理以使用 knowledgeSources 而不是 targetIndexes
发送查询以测试检索
删除使用 targetIndexes 和更新客户端的代码

获取当前配置

若要检索智能体的定义，请使用知识智能体 - Get (REST API) 的 2025-05-01-preview。

@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 blob 作为目标。有关详细信息，请参阅创建知识源。

更新代理

若要在代理定义中将targetIndexes替换为knowledgeSources，请使用知识代理 - 创建或更新（REST API）中的2025-08-01-preview。将 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 版本筛选器。

重大更改
非破坏性更改

workIQParameters 是 Work IQ 知识源所必需的，且必须包含 entraAppAuthentication。在原位置更新源，或为并行迁移创建一个替代项。在检索请求中通过 x-ms-query-work-iq-source-authorization 标头传递用户断言。
Work IQ 引用将删除 attributions、WorkIQAttribution 形状和 seeMoreWebUrl。重塑后的引用暴露出 searchSensitivityLabelInfo。删除已删除字段的依赖项，并更新新敏感度标签形状的引用处理。
仅限预览的 $top、$skip 和 $count 参数已被移除。集合列表操作使用 search、pageSize 和 searchType。响应使用 @odata.nextLink 进行继续分页。更新列表请求，并完全按照返回的每个 @odata.nextLink 进行操作。
查询规划、答案合成和 Web 汇总活动记录将删除标量 modelName。替换 model 对象包含 modelName 和 deploymentId。为以模型为后盾的活动记录反序列化嵌套的 model 对象。
McpServerTool.inclusionMode 已删除。在每个 MCP 服务器tools项中，将reranked映射到resultsProcessing: "rerank"，并将always映射到resultsProcessing: "none"。如果省略， resultsProcessing 则默认为 rerank; none 将绕过重新调整并保留基础结果顺序。
新的列表参数更改生成的方法参数顺序，但不会影响 REST 参数绑定。安装支持 2026-08-01-preview 的 SDK 包后，查看位置相关调用。在可用的情况下，优先使用命名参数或选项。

私有网络数据引入支持 blob、索引的 SharePoint、索引的 OneLake 以及索引的 Azure SQL 知识来源。
文件知识源元数据、文件更新、筛选的文件列表和 corsOptions 配置。
知识库支持gpt-5.6-sol、gpt-5.6-terra和gpt-5.6-luna模型名称。
关于持久化检索请求限制的知识库 retrieveDefaults。
在Accept: text/event-stream中，通过请求标头支持服务器发送事件（SSE）响应。
使用 auto 值针对 retrievalReasoningEffort 进行自动检索推理。
将 queryHints 存储在由搜索索引支持的知识来源定义中，将请求级 queryHintOverrides 存储在每个适用的 knowledgeSourceParams 项中。
使用 neverQuerySource 进行请求时知识源排除。
使用 resultsProcessing 按来源进行重排序控制。
索引知识来源引用中的服务生成的 citationUrl 值。
elapsedMs中的活动时间字段（、startedAt和completedAt）。

2026-05-01-预览

2026-05-01-preview 在 2025-11-01-preview 的基础上添加知识库、知识库和检索功能，而无需删除以前保留的属性。在早期预览版本中创建的现有知识库和知识源将继续正常工作。此版本主要公开新功能，并还原一些仅限预览的限制。

若要查看此版本的 REST API 参考文档，请选择 2026-05-01-preview 页面顶部的 API 版本筛选器。

重大更改
非破坏性更改

2025-11-01-preview和2026-05-01-preview之间没有重大变更。当你将 API 版本更改为 2026-05-01-preview 时，现有的以 2025-11-01-preview 为目标的请求仍可继续工作。

提供 2026-05-01-preview 支持的语言 SDK 会引入代码结构变更，而这些变更在 SDK 层面属于破坏性变更。有关完整的 SDK 形态映射，请参阅 2026-05-01-preview 的更新代码和客户端。

通过 freshnessPolicy 在 ingestionParameters 上实现基于已索引知识来源的新鲜度感知检索。
用于对 REST 检索终结点进行浏览器源访问的知识库 corsOptions。
GPT-5 模型系列的知识库支持（例如 gpt-5.4-mini）。
每个来源的 knowledgeSourceParams.maxOutputDocuments，用于限制每个知识来源的候选文档数量。
在检索请求的顶层设置 maxOutputDocuments，以限制最终基础文档数量的上限。
每个源 knowledgeSourceParams.failOnError 要求知识来源在检索过程中成功。
搜索索引知识来源（例如 searchIndexParameters.baseFilter）上的持久化检索默认设置以及运行时 filterAddOn 覆盖。
可选 semanticConfigurationName：用于受支持检索流的搜索索引知识来源
检索响应中的 Purview 敏感度标签元数据：每个引用 sensitivityLabelInfo 和响应级别 metadata.responseSensitivityLabelInfo。
modelName 当在检索请求上设置 includeActivity 时，在模型支持的活动记录上。
服务统计信息计数器 knowledgeBasesCount 和 knowledgeSourcesCount。
知识库和知识库列表操作和其他预览列表终结点的分页支持（$top、$skip、$count）。
对于 minimal、low 和 medium 检索推理工作量，每个知识库的知识来源数量上限是相同的。较早的预览版 API 版本对于 low 和 medium 仍保留较低的限制。

2026-04-01

2026-04-01 是用于代理检索的第一个稳定 API 版本。它确立了一个简化的提取检索协定，并去除了预览时代特性中的基于消息的查询规划和答案合成功能。

若要查看此版本的 REST API 参考文档，请选择 2026-04-01 页面顶部的 API 版本筛选器。

重大更改
非破坏性更改

以下更改会影响知识库架构和检索请求：

retrievalReasoningEffort 已删除。以前配置的 low 知识库或 medium 推理工作不兼容 2026-04-01 ，必须重新创建。
outputMode 已删除。默认情况下，检索将返回提取性地面内容。不支持答案合成。

以下更改仅影响检索请求：

intents 替换 messages。
alwaysQuerySource 已从 knowledgeSourceParams 移除。
maxOutputSize 已重命名为 maxOutputSizeInTokens.
不会在请求之间维护会话状态。不支持基于 messages 的多轮次模式。

以下更改会影响 azureBlob 和 indexedOneLake 知识源：

ingestionPermissionOptions 已从 ingestionParameters 移除。包含此属性的 azureBlob 和 indexedOneLake 知识源必须在没有此属性的情况下重新创建。

注意

发送已删除字段会返回 HTTP 代码 400 Bad Request。检索请求不会删除或容忍此版本中不再存在的字段。

searchIndex、azureBlob、indexedOneLake 和 web 知识源类型现已在 2026-04-01 中正式可用。现有索引内容仍然有效;迁移需要重新创建知识源对象，而不是重新生成索引。
已建立索引的 SharePoint 知识源和远程 SharePoint 知识源仍处于预览阶段，并且在 2026-04-01 中不可用。
知识源操作现在直接包括知识源 status 类型，并提供更丰富的索引错误详细信息。
如果从检索请求中省略， maxRuntimeInSeconds 则默认为 90 秒， maxOutputSizeInTokens 默认为 5,000 个令牌。
检索请求中的 knowledgeSourceParams 运行时源代码控制仍然有效： includeReferences、 includeReferenceSourceData和 rerankerThreshold （所有知识源类型），以及 filterAddOn （仅搜索索引知识源）。
如果知识库不包含 models 知识源，web 数组则是可选的。 web 知识源存在时，models是进行 Web 内容汇总所必需的，如果汇总失败，检索可能会返回206 Partial Content。
检索响应仍包含activity 和references，尽管请求契约更为局限。
在 2026-04-01 及更高版本中，一个新的管理平面属性 knowledgeRetrieval 独立于 semanticSearch 控制智能体检索计费。默认值为 free. 若要启用付费使用情况，请设置为 knowledgeRetrievalstandard。有关详细信息，请参阅启用或禁用代理检索计费。

2025-11-01-preview

若要查看此版本的 REST API 参考文档，请选择 2025-11-01-preview 页面顶部的 API 版本筛选器。

重大更改
非破坏性更改

知识代理已重命名为知识库。

上一个路径新路由

/agents /knowledgebases

/agents/agent-name /knowledgebases/knowledge-base-name

/agents/agent-name/retrieve /knowledgebases/knowledge-base-name/retrieve
知识代理（base）outputConfiguration 被重命名为outputMode，并从对象更改为字符串枚举器。多个属性受到影响：
- includeActivity 直接从 outputConfiguration 移至检索请求上。
- 在 attemptFastPath 中，outputConfiguration 已完全删除。新的 minimal 推理工作是替代方案。
已移除知识智能体（基础）中的 requestLimits。 maxRuntimeInSeconds和maxOutputSize的子属性将直接移至检索请求中。
知识智能体（基本）knowledgeSources 参数现在仅列出知识源使用的名称。原来位于 knowledgeSources 下的其他子属性已移至 retrieve 请求的 knowledgeSourceParams 属性中：
- rerankerThreshold
- alwaysQuerySource
- includeReferenceSourceData
- includeReferences
该 maxSubQueries 属性已消失。它的替代是新的检索推理工作属性。
知识代理（基础）检索请求：semanticReranker 活动记录已替换为 agenticReasoning 活动记录类型。
知识源对于azureBlob和searchIndex：顶级属性identity、embeddingModel、chatCompletionModel、disableImageVerbalization、以及ingestionSchedule现在是知识源中ingestionParameters对象的一部分。从搜索索引拉取的所有知识源都有一个 ingestionParameters 对象。
仅对于searchIndex知识源：sourceDataSelect被重命名为sourceDataFields，这是一个接受fieldName和fieldToSearch的数组。

上一个路径	新路由
`/agents`	`/knowledgebases`
`/agents/agent-name`	`/knowledgebases/knowledge-base-name`
`/agents/agent-name/retrieve`	`/knowledgebases/knowledge-base-name/retrieve`

为 OneLake、SharePoint（本地）、SharePoint（远程）添加知识源，这些源可直接从 SharePoint 检索内容，以及 Web（Bing）从 Bing 索引中提取内容。
所有从搜索索引提取内容的知识来源都新增了提取选项：ingestionPermissionOptions：用于支持特定数据源的访问控制模型；contentExtractionMode：在 Foundry Tools 集成中启用 Azure 内容理解；当 aiServices 时，使用 "contentExtractionMode": "minimal" 端点以支持 Azure 内容理解。
从搜索索引拉取的所有知识源都有一个 status 操作，该操作返回知识源与其数据源的同步状态。
searchIndex 知识源添加了 semanticConfigurationName，该配置会覆盖检索请求使用的默认语义配置。
searchIndex 知识源添加了 sourceDataFields 和 searchDataFields，以指定在查询时使用哪些字段，并在响应中返回哪些字段。
知识代理（基础）检索响应现在返回 HTTP 206 状态代码，表示部分成功。检索请求现在采用指定 LLM 处理的级别的可选retrievalReasoningEffort属性（请参阅“设置检索推理工作量”（预览版）。
知识智能体（基础）新增了一个用于 intent 检索推理工作量的 minimal 对象，在该模式下由 intent 替代传递给 LLM 的 messages。 intent 是一个直接传递到搜索引擎的查询字符串，没有中间的 LLM 查询规划步骤。
检索响应中的活动记录现在具有可选 error 输出，指示活动是否表示失败的操作。

2025-08-01-preview

若要查看此版本的 REST API 参考文档，请选择 2025-08-01-preview 页面顶部的 API 版本筛选器。

重大更改
非破坏性更改

将知识源介绍为定义数据源的新方法，支持 searchIndex （一个或多个索引）和 azureBlob 类型。有关详细信息，请参阅创建搜索索引知识源和创建 Blob 知识源。
代理定义中需要 knowledgeSources 而不是 targetIndexes。有关迁移步骤，请参阅如何迁移。
删除 defaultMaxDocsForReranker 支持。此属性以前存在于其中 targetIndexes，但不存在任何替换项 knowledgeSources。

向代理定义中添加 knowledgeSources、outputConfiguration 和 retrievalInstructions。有关支持的属性的信息，请参阅 “创建知识代理”。
重命名 defaultRerankerThreshold 为 rerankerThreshold 和 defaultIncludeReferenceSourceData 重命名为 includeReferenceSourceData。这些属性以前存在于targetIndexes中，但现在您需要在knowledgeSources的每个知识源引用中指定它们。

2025-05-01-preview

此 API 版本引入了代理检索和知识代理。每个代理定义都需要一个 targetIndexes 数组，该数组指定单个索引和可选属性，例如 defaultRerankerThreshold 和 defaultIncludeReferenceSourceData。

若要查看此版本的 REST API 参考文档，请选择 2025-05-01-preview 页面顶部的 API 版本筛选器。

反馈

此页面是否有帮助？

Last updated on 2026-09-17

将代理检索代码迁移到最新版本

何时迁移

迁移之前

如何迁移

2026-08-01-preview

迁移 Work IQ 知识源

更新列表分页

更新检索响应处理

更新 2026-08-01-preview 的代码和客户端

2026-05-01-预览

更新 2026-05-01-preview 的代码和客户端

2026-04-01

迁移知识源

迁移知识库

更新检索请求

更新计费许可

更新代码和客户端至2026年4月1日

2025-11-01-preview

更新 "searchIndex" 知识源

更新 Azure Blob 知识源

将知识代理替换为知识库

更新并测试 2025-11-01-preview 更新的检索功能

更新 2025-11-01-preview 的代码和客户端

2025-08-01-preview

获取当前配置

创建知识源

更新代理

测试 2025-08-01-preview 更新的检索功能

更新 2025-08-01-preview 的代码和客户端

版本特定的更改

2026-08-01-preview

2026-05-01-预览

2026-04-01

2025-11-01-preview

2025-08-01-preview

2025-05-01-preview

相关内容

反馈

其他资源