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

如果使用早期预览版 REST API 编写代理检索代码，本文介绍何时以及如何迁移到最新版本。 它还介绍了支持代理检索的所有 REST API 版本的中断性变更和非中断性变更。

何时迁移

应用以下任一作时，迁移代理检索代码：

• 你使用的 REST API 版本将宣布停用或进入弃用窗口。

• 较新的 REST API 版本引入了影响你使用的功能的重大更改。 例如，如果代码面向代理定义中使用的 2025-05-01-preview， targetIndexes 则必须解决中断性变更问题。

• 你希望仅在较新的 REST API 版本中提供的功能。

• 当 REST API 响应中返回无法识别的属性时，代码会失败。 最佳做法是，应用程序应忽略它无法理解的属性。

如何迁移

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

从 2025-08-01-preview 开始，可重用的知识源将替换 targetIndexes， defaultMaxDocsForReranker 不再受支持。 这些重大更改要求你：

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

获取当前配置

若要检索代理的定义，请使用知识代理的 2025-05-01-preview - Get （REST API）。

@search-url = <YourSearchServiceUrl>
@agent-name = <YourAgentName>
@api-key = <YourApiKey>

### Get agent definition
GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    api-key: {{api-key}}

响应应类似于以下示例。 indexName复制后续步骤中使用的值defaultRerankerThreshold和defaultIncludeReferenceSourceData值。 defaultMaxDocsForReranker 已弃用，因此可以忽略其值。

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

创建知识来源

若要创建searchIndex知识源，请使用知识源的 2025-08-01-preview - 创建（REST API）。 设置为 searchIndexName 之前复制的值。

@source-name = <YourSourceName>

### Create a knowledge source
PUT https://{{search-url}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index" // Use the previous value
        }
    }

此示例创建表示一个索引的知识源，但可以面向多个索引或 Azure Blob。 有关详细信息，请参阅 创建知识源。

更新代理

若要在代理的定义中替换为targetIndexesknowledgeSources，请使用知识代理的 2025-08-01-preview - 创建或更新（REST API）。 设置 rerankerThreshold 和 includeReferenceSourceData 复制到之前复制的值。

### Replace targetIndexes with knowledgeSources
POST https://{{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

    { 
        "name": "{{agent-name}}", 
        "knowledgeSources": [  
            {  
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5, // Use the previous value
                "includeReferenceSourceData": true // Use the previous value
            }
        ]
    } 

此示例更新定义以引用一个知识源，但你可以面向多个知识源。 还可以使用其他属性来控制检索行为，例如 alwaysQuerySource。 有关详细信息，请参阅 创建知识代理。

测试检索

若要使用查询测试代理的输出，请使用知识 检索 - 检索 （REST API） 的 2025-08-01-preview。

### Send a query to the agent
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<YourQueryText>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

如果响应具有 200 OK HTTP 代码，则代理已成功从知识源检索内容。

更新代码和客户端

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

• 将所有 targetIndexes 引用替换为 knowledgeSources 配置文件、代码、脚本和测试。
• 更新客户端调用以使用 2025-08-01-preview。
• 清除或重新生成使用旧形状创建的缓存代理定义。

特定于版本的更改

本部分介绍以下 REST API 版本的中断性变更和非中断性变更：

• 2025-08-01-预览版
• 2025-05-01-preview

2025-08-01-preview

2025-05-01-preview

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

相关内容

• 创建知识代理
• 创建知识来源