你当前正在访问 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 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

在代理检索中，可以指定用于查询规划和答案表述的大型语言模型（LLM）处理级别。使用检索推理强度（预览版）来设置会影响成本和延迟的 LLM 处理级别。额外的 LLM 处理可提高相关性，但还需要更长的时间并使用可计费的 LLM 资源。

可以在知识库或检索请求中设置此属性。知识库设置为所有查询建立默认值，而检索请求设置会基于查询替代默认值。如果两个设置都不存在，服务将使用 low。

使用支持

Azure 门户	Microsoft Foundry 门户	.NET SDK	Python SDK	Java SDK	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

先决条件

具有至少一个知识库和模型配置的现有知识库。
更新和查询知识库的权限。使用分配给用户帐户的搜索服务参与者和搜索索引数据读取者角色（建议）或使用管理员 API 密钥配置无密钥身份验证。

最新的 Azure.Search.Documents 预览包：dotnet add package Azure.Search.Documents --prerelease
对于无密钥身份验证，请使用 Azure.Identity 软件包：dotnet add package Azure.Identity

最新的 azure-search-documents 预览包：pip install --pre azure-search-documents
对于无密钥身份验证，请使用 azure-identity 软件包：pip install azure-identity

搜索服务 REST API 的 2026-08-01-preview 版本。
对于无密钥身份验证，请在每个 HTTP 请求的标头中包含AuthorizationMicrosoft Entra ID令牌。

选择推理强度

根据所需的延迟、成本和检索深度之间的权衡选择推理工作。

推理努力程度级别

级别	描述	建议	限制
`minimal`	禁用基于 LLM 的查询计划，以提供代理检索的最低成本和延迟。它跨知识库中列出的知识源发出直接文本和矢量搜索，并返回最佳匹配段落。由于知识库中的所有知识源始终进行搜索，并且不会执行任何查询扩展，因此行为是可预测的且易于控制。这也意味着在检索请求中，`alwaysQueryKnowledgeSource` 属性将被忽略。	在从`minimal` 迁移或你想自行管理查询规划时使用。	`outputMode` 必须设置为 `extractiveData`. 不支持答案合成（预览版）和 Web 知识。每个知识库最多有 10 个知识库。
`low`	代理式检索的默认模式，执行一次基于大语言模型（LLM）的查询规划和知识源选择。代理检索引擎生成子查询，并将其分散到选定的知识源，然后合并查询结果。您可以启用答案合成（预览版），以生成带有内联引文的、基于依据的自然语言响应。	想要在最小延迟和更深入的处理之间实现平衡时使用 `low` 。	5,000 个应答令牌。语义排名最多 50 个文档，如果语义排名器使用 L3 分类，则最多 10 个文档。
`medium`	将更深入的搜索和增强的检索堆栈添加到代理检索，以最大程度地提高完整性。第一次搜索后，高精度语义分类器将评估检索到的文档。如果初始结果不够相关，该服务将使用修订的查询计划执行一次后续迭代。	使用 `medium` 可最大限度地提升 LLM 辅助知识检索的效用。	10,000 个应答令牌。语义排名最多 50 个文档，如果语义排名器使用 L3 分类，则最多 20 个文档。在选择区域中可用。
`auto`	先从轻量级检索阶段开始。如果第一次处理提供了足够的依据，服务将返回结果。否则，它会继续使用基于 LLM 的查询规划，工作量最多达到中等程度。	当希望服务平衡每个请求的检索深度和延迟时使用 `auto` 。	需要 2026-08-01-preview REST API。需要知识库中的模型。在所有支持代理检索的区域都可用。早期 API 版本返回 `400 Bad Request`。

迭代搜索以检索媒介

如果初始结果不够相关，则中等检索推理工作可提供迭代搜索。调用额外的 语义分类器模型 以确定是否需要第二次迭代。

语义分类器：

识别何时有足够的上下文来回答问题。
在结果不足时重试，使用现有信息作为上下文。新查询可能会向下钻取以获取更集中的详细信息，或扩大搜索范围。响应中的活动日志显示了生成的查询，旨在提供更全面的答案。
使用 L3 分类重新评分。该范围与 L2 排名相同，绝对范围为零到 4.0。

只有一次重试。每次迭代都会增加延迟和成本，因此系统会将重试限制为一次传递。第二次迭代将输入令牌加入到查询管道中，从而增加了整体计费的输入令牌数量。

迭代可以重复使用现有知识源或选择不同的源。第二轮选择最有可能提供缺失信息的知识来源。

对中级检索的区域支持

如果搜索服务位于以下区域之一，则可以设置中等检索推理工作：

美国东部 2
美国东部
美国中南部
美国西部 3
美国西部 2
美国西部
德国中西部
北欧
瑞士北部
瑞典中部
西班牙中部
英国南部
韩国中部
日本东部
东南亚

在知识库中设置推理强度

在知识库定义中设置 retrievalReasoningEffort ，以为其查询建立默认值。 auto推理工作需要模型配置。以下示例保留现有 knowledgeSources 和 models 配置，设置推理工作 auto并更新知识库。

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";

var indexClient = new SearchIndexClient(endpoint, credential);
var knowledgeBase = (
    await indexClient.GetKnowledgeBaseAsync(knowledgeBaseName)).Value;
knowledgeBase.RetrievalReasoningEffort =
    new KnowledgeRetrievalAutoReasoningEffort();
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);

参考：KnowledgeBase

若要使用另一个级别，请替换为KnowledgeRetrievalAutoReasoningEffortKnowledgeRetrievalMinimalReasoningEffort或 KnowledgeRetrievalMediumReasoningEffortKnowledgeRetrievalLowReasoningEffort。

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeRetrievalAutoReasoningEffort,
)

endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"

index_client = SearchIndexClient(endpoint, credential)
knowledge_base = index_client.get_knowledge_base(knowledge_base_name)
knowledge_base.retrieval_reasoning_effort = (
    KnowledgeRetrievalAutoReasoningEffort()
)
index_client.create_or_update_knowledge_base(knowledge_base)

参考：KnowledgeBase

@api-version = 2026-08-01-preview
@knowledge-base-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}

PUT {{knowledge-base-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "{{knowledge-base-name}}",
  "knowledgeSources": [
    {
      "name": "{{knowledge-source-name}}"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "{{aoai-endpoint}}",
        "authIdentity": null,
        "deploymentId": "{{model-deployment-name}}",
        "modelName": "{{model-name}}"
      }
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "auto"
  }
}

参考：知识库 - 创建或更新

若要使用另一个级别，请设置为retrievalReasoningEffort.kindminimal或 mediumlow。

在检索请求中设置推理工作

在检索请求中设置 retrievalReasoningEffort 以替代该请求的知识库默认值。以下示例发送一条消息，使用 low 来覆盖上一节中的 auto 默认值，并启用答案合成（预览）。

using Azure.Identity;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";

var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint, knowledgeBaseName, credential);
var request = new KnowledgeBaseRetrievalRequest
{
    RetrievalReasoningEffort =
        new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis
};

request.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What is the return policy?")
        }
    ) { Role = "user" }
);

var result = await kbClient.RetrieveAsync(request);

参考：KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalLowReasoningEffort,
)

endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"

kb_client = KnowledgeBaseRetrievalClient(
    endpoint,
    credential,
    knowledge_base_name=knowledge_base_name,
)
request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="What is the return policy?"
                )
            ],
        )
    ],
    retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
    output_mode=KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
)

result = kb_client.retrieve(request)

参考：KnowledgeBaseRetrievalRequest

@api-version = 2026-08-01-preview
@retrieve-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve

POST {{retrieve-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the return policy?"
        }
      ]
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "answerSynthesis"
}

参考：知识检索 - 检索

检索请求会根据知识库中配置的知识源返回有依据的答案。

反馈

此页面是否有帮助？

Last updated on 2026-09-17