다음을 통해 공유

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

注释

此功能目前处于公开预览状态。 此预览版未随附服务级别协议，建议不要用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

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

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

小窍门

使用 Azure SDK 而不是 REST？ 阅读本文，了解重大更改，然后安装更新的预览包以开始更新。 在开始之前，请检查 SDK 更改日志以确认 API 更新： Python、 .NET、 JavaScript、 Java。

何时迁移

每个支持代理检索的新 API 版本都引入了重大更改，从原始 2025-05-01-preview 到 2025-08-01-preview，到最新的 2025-11-01-preview。

如果保留 API 版本值，则可以继续运行没有更新的旧代码。 但是，若要受益于 bug 修复、改进和更新功能，必须更新代码。

如何迁移

  • 支持的迁移路径是增量的。 如果代码面向 2025-05-01-preview，请先迁移到 2025-08-01-preview，然后迁移到 2025-11-01-preview。

  • 若要了解更改的范围，请查看每个版本的 中断性变更和非中断性变更 。

  • “迁移”意味着创建新的唯一命名的对象，这些对象可实现以前版本的行为。 如果在 API 上添加或删除属性，则不能覆盖现有对象。 创建新对象的一个优点是能够在开发和测试新对象时保留现有对象。

  • 对于迁移的每个对象，首先从搜索服务获取当前定义，以便可以在指定新属性之前查看现有属性。

  • 仅在完全测试并部署迁移后，才删除旧版本。

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

  1. 更新 searchIndex 知识源。
  2. 更新 azureBlob 知识源。
  3. 将知识代理替换为知识库。
  4. 更新检索请求并发送查询来测试更新。
  5. 更新客户端代码。

更新搜索索引的知识源

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

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

    ### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
api-key: {{api-key}}
Content-Type: application/json

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

    ### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
api-key: {{api-key}}
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. 将 创建知识源 请求用作迁移的基础。

    从 08-01-preview JSON 开始。

    POST {{url}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
api-key: {{key}}
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子句。

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

    PUT {{url}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
api-key: {{key}}
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-08-01 版本相同的功能层级创建新的 2025-11-01-preview azureBlob 知识源。 它创建一组新的生成的对象：数据源、技能集、索引器、索引。

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

    ### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
api-key: {{api-key}}
Content-Type: application/json

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

    ### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
api-key: {{api-key}}
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. 将 创建知识源 请求用作迁移的基础。

    从 08-01-preview JSON 开始。

    POST {{url}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
api-key: {{key}}
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"。

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

    PUT {{url}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
api-key: {{key}}
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 的正确属性规范。

响应包括新对象的完整定义。 有关此知识源类型可用的新属性的更多信息，您现在可以通过更新完成此操作，请参阅 如何创建 Azure 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
api-key: {{api-key}}
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. 制定 创建知识库 请求作为迁移的基础。

    从 08-01-preview JSON 开始。

    PUT {{url}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
api-key: {{key}}
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/{{your-object-name}}. 为知识库指定唯一的名称。

    • 将 API 版本更改为 2025-11-01-preview.

    • 删除 requestLimits。 现在直接在检索请求对象上指定了属性 maxRuntimeInSeconds 和 maxOutputSize 属性

    • 更新 knowledgeSources：

      • 删除 maxSubQueries 并替换为检索推理努力（请参阅 设置检索推理努力）。

      • 移动alwaysQuerySource、includeReferenceSourceData、includeReferences和rerankerThreshold到knowledgeSourcesParams检索操作的部分。

    • 没有更改 models。

    • 更新 outputConfiguration：

      • 将 outputConfiguration 替换为 outputMode。

      • 删除 attemptFastPath。 它不再存在。 通过 retrievalReasoningEffort 设置为最小值来实现等效行为（请参阅 设置检索推理工作）。

      • 如果模式设置为 answerSynthesis，请确保将检索推理工作量设置为低（默认值）或中等。

    • 添加 ingestionParameters 作为创建 2025-11-01-preview azureBlob 知识源的要求。

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

     PUT {{url}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
 api-key: {{key}}
 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. 将 API 版本更改为 2025-11-01-preview.

  3. 如果使用messages或low检索ReasoningEffort，则无需更改medium。 如果您使用intent推理（请参阅minimal ），请将消息替换为。

  4. 修改knowledgeSourceParams以包括从代理中删除的任何属性：rerankerThreshold、、alwaysQuerySourceincludeReferenceSourceDataincludeReferences。

  5. 如果您正在使用retrievalReasoningEffort，请将设置添加到minimumattemptFastPath。 如果使用 maxSubQueries，则它不再存在。 使用 retrievalReasoningEffort 设置指定子查询处理（请参阅 设置检索推理工作）。

若要使用查询测试知识库的输出，请使用 2025-11-01-preview 的 Knowledge Retrieval - Retrieve (REST API)。

### Send a query to the knowledge base
POST {{url}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
api-key: {{key}}
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 的代码和客户端

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

  1. 仅对于 Azure Blob 知识源，请更新客户端以使用新索引。 如果你有运行索引器或引用数据源、索引或技能集的代码或脚本，请确保更新对新对象的引用。

  2. 将所有代理引用替换为 knowledgeBases 配置文件、代码、脚本和测试。

  3. 更新客户端调用以使用 2025-11-01-preview 版本。

  4. 清除或重新生成使用旧形状创建的缓存定义。

特定于版本的更改

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

2025-11-01-预览

若要查看此版本的 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 下原有的其他子属性已移至 knowledgeSourceParams 检索请求对象的属性中：

    • rerankerThreshold
    • alwaysQuerySource
    • includeReferenceSourceData
    • includeReferences

    该 maxSubQueries 属性已消失。 它被新推出的检索推理努力属性所取代。

  • 知识代理（基）检索请求对象：semanticReranker 活动记录被 agenticReasoning 活动记录类型替换。

  • 知识源为azureBlob和searchIndex：identity、embeddingModel、chatCompletionModel、disableImageVerbalization及ingestionSchedule的顶级属性现在是知识源上ingestionParameters对象的一部分。 从搜索索引拉取的所有知识源都有一个 ingestionParameters 对象。

  • 仅对于 searchIndex 知识源：sourceDataSelect 被重命名为 sourceDataFields，并且是一个接受 fieldName 和 fieldToSearch 的数组。

2025-08-01-preview

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

  • 将知识源介绍为定义数据源的新方法，支持 searchIndex （一个或多个索引）和 azureBlob 类型。 有关详细信息，请参阅创建搜索索引知识来源和创建 Blob 知识来源。

  • 需要 knowledgeSources 而不是 targetIndexes 代理定义。 有关迁移步骤，请参阅 如何迁移。

  • 删除 defaultMaxDocsForReranker 支持。 此属性以前存在于其中 targetIndexes，但不存在任何替换项 knowledgeSources。

2025-05-01-preview

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

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

相关内容

  • Last updated on