企业官网建设流程全解析

在 azure-search-openai-demo 中使用 Agentic Retrieval：让 RAG 检索具备 LLM 规划能力

【免费下载链接】azure-search-openai-demoA sample app for the Retrieval-Augmented Generation pattern running in Azure, using Azure AI Search for retrieval and Azure OpenAI large language models to power ChatGPT-style and Q&A experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo

Agentic Retrieval（智能体式检索）是 Azure AI Search 面向 RAG 场景推出的检索增强能力：由 LLM 分析对话上下文并生成多条搜索查询，从而为复杂、多面问题找到更相关的资料。本文围绕 agentic_retrieval.md 讲解该功能在 azure-search-openai-demo 中的部署步骤、推理档位（reasoning effort）选择、Web/SharePoint 知识源扩展，并结合仓库源码说明其底层调用链与前端表现，读完即可在自己的部署中启用并调优该能力。

什么是 Agentic Retrieval，它解决了什么问题

在默认的 "Read–Retrieve–Read" 流程中（见 chatreadretrieveread.py），应用先把用户问题重写为一条搜索查询，再用这条查询去 Azure AI Search 索引里取回 top-N 文档，最后交给 LLM 生成回答。这种方式对"单意图"问题效果良好，但当用户提问是复杂、多面向的（例如同时涉及多个主题、需要综合不同来源信息时），单条查询往往难以一次性覆盖全部检索意图。

Agentic Retrieval 的改进在于：检索本身变成一个由 LLM 驱动的"规划—执行"过程。Azure AI Search 中的 Knowledge Agent 会分析用户提问与对话历史，生成多条子查询，逐一对各知识源执行检索，再按合并策略汇总结果。文档（agentic_retrieval.md）指出该功能"use a LLM to analyze the conversation and generate multiple search queries"，可显著提升复杂问题的回答质量。

需要说明的是，Agentic Retrieval 背后的规划过程会额外计费 token（文档第 7 步明确提到"uses additional billed tokens behind the scenes for the planning process"），因此在启用前需要结合成本与延迟做权衡，这正是下文"推理档位"设计的出发点。

启用前置条件

启用该功能前，需确认以下前提（对应 servicesetup.py 中的校验逻辑）：

• 必须为 Agentic Retrieval 指定一个可用的 Azure OpenAI 模型部署。源码中 servicesetup.py 在use_agentic_knowledgebase=True且未指定azure_openai_knowledgebase_deployment时会直接抛出ValueError；
• 部署完成后，post-provision 脚本会在 Azure AI Search 中创建一个指向搜索索引的 Knowledge Agent（文档第 5 步）；
• 若启用 SharePoint 知识源，还必须同时启用访问控制（AZURE_ENFORCE_ACCESS_CONTROL），因为该源依赖登录用户令牌的 on-behalf-of 流（app.py 中有对应告警日志）。

部署步骤：从环境变量到azd up

1. 开启 Agentic Retrieval 开关

使用 azd 设置环境变量：

azd env set USE_AGENTIC_KNOWLEDGEBASE true

该变量在 app.py 中按"true"字符串解析，并在 main.bicep 中注入USE_AGENTIC_KNOWLEDGEBASE应用设置。只有该值为 true 时，应用才允许前端展示 Agentic Retrieval 开关（对应 app.py 的showAgenticRetrievalOption配置）。

2.（可选）自定义检索模型

默认使用gpt-5.4。可通过以下环境变量更换：

azd env set AZURE_OPENAI_KNOWLEDGEBASE_DEPLOYMENT knowledgebase azd env set AZURE_OPENAI_KNOWLEDGEBASE_MODEL gpt-5.4 azd env set AZURE_OPENAI_KNOWLEDGEBASE_MODEL_VERSION 2026-03-05

其中AZURE_OPENAI_KNOWLEDGEBASE_MODEL与AZURE_OPENAI_KNOWLEDGEBASE_DEPLOYMENT在 app.py 中读取，并作为 main.bicep 中的knowledgeBase.modelName与knowledgeBase.deploymentName传入基础设施。文档提醒：只能更换为 Azure AI Search Agentic Retrieval 官方支持的模型列表中的模型。该模型既承担规划（生成子查询），也承担检索阶段的知识源选择。

3.（可选）选择默认检索推理档位

Agentic Retrieval 支持minimal、low、medium三档，默认minimal：

azd env set AZURE_SEARCH_KNOWLEDGEBASE_RETRIEVAL_REASONING_EFFORT low

三档语义对照如下：

该默认值在 app.py 中读取（AGENTIC_KNOWLEDGEBASE_REASONING_EFFORT，默认minimal），由 main.bicep 传入defaultRetrievalReasoningEffort，并最终通过 app.py 的/config接口以defaultRetrievalReasoningEffort暴露给前端。文档强调：显式的部署环境变量与前端 Developer 设置覆盖项优先级高于该默认值——即用户在 UI 中手动选择的检索档位优先于环境变量默认值。

从源码看三档的具体差异（approach.py）：

• minimal时，应用先用query_rewrite.system.jinja2提示词把对话重写为单条查询，再以KnowledgeRetrievalSemanticIntent(search=...)形式传入检索请求（intents字段），并构造KnowledgeRetrievalMinimalReasoningEffort；
• low/medium时，应用把完整对话消息转换为KnowledgeBaseMessage列表传给 Knowledge Agent，由 Azure AI Search 自行完成查询规划与扩展，分别对应KnowledgeRetrievalLowReasoningEffort/KnowledgeRetrievalMediumReasoningEffort。

4.（可选）启用 Web 或 SharePoint 知识源

默认只检索搜索索引中的文档。两种扩展知识源可独立或同时开启：

Web 源：允许检索公开网页。

azd env set USE_WEB_SOURCE true azd env set AZURE_SEARCH_KNOWLEDGEBASE_RETRIEVAL_REASONING_EFFORT low

SharePoint 源：允许检索 SharePoint 文档，要求已启用登录认证，并通过 on-behalf-of 流使用当前登录用户的令牌：

azd env set USE_SHAREPOINT_SOURCE true

两个源在 app.py 中分别读取，基础设施中对应useWebSource/useSharePointSource参数（main.bicep）。启用后，应用会按需构造不同的 KnowledgeBaseRetrievalClient：-with-web、-with-sp、-with-web-and-sp三种后缀（app.py），并在运行时通过_select_knowledgebase_client（chatreadretrieveread.py）按 Web/SharePoint 组合挑选合适的客户端，多个源检索结果按配置的合并策略融合。

启用知识源时必须注意的约束（文档中的重要提示，务必逐条核对）：

• Web 源与minimal不兼容：minimal要求extractiveData输出，而 Web 知识源与答案合成（answer synthesis）不支持该模式。因此USE_WEB_SOURCE=true时必须显式把AZURE_SEARCH_KNOWLEDGEBASE_RETRIEVAL_REASONING_EFFORT设为low或medium。源码中 chatreadretrieveread.py 会在use_web_source and retrieval_reasoning_effort == "minimal"时直接抛异常，app.py 也会在启动时检测该组合并记录警告；
• Web 源强制使用答案合成模式：这会禁用部分 UI 定制项，包括流式输出（streaming）、追问问题（follow-up questions）和 LLM 参数选项。前端 Chat.tsx 中streamingDisabledByOverrides = useAgenticKnowledgeBase && webSourceEnabled即对应这一限制；chatreadretrieveread.py 在流式模式下启用 Web 源会抛 "Streaming is not supported with agentic retrieval when web source is enabled" 异常；
• 数据合规提示：发送到 Web Knowledge Source 的数据不适用 Microsoft 数据保护附录（Data Protection Addendum）；
• SharePoint 源许可：要求用户持有 Microsoft Copilot 许可证。

5. 更新基础设施与应用

azd up

azd up会完成两部分工作：其一，按需只新增部署缺失的资源（若此前已up过，则只新增 Knowledge Agent 使用的模型）；其二，以更新后的环境变量重新部署应用代码。部署后的 post-provision 脚本会在 Azure AI Search 中配置好指向搜索索引的 Knowledge Agent。

6. 验证功能

打开 Web 应用并新开一个会话提问。应用将自动通过 Agentic Retrieval 检索所有来源。判断是否真正走通 Agentic 路径，可以观察前端设置区：只有USE_AGENTIC_KNOWLEDGEBASE=true时，设置面板才会显示 Agentic Retrieval 相关选项（Settings.tsx），包括检索推理档位选择（Settings.tsx）、Web 源开关（Settings.tsx）与 SharePoint 源开关（Settings.tsx），这些开关最终随请求体中的use_agentic_knowledgebase、retrieval_reasoning_effort、use_web_source等字段传给后端（Chat.tsx）。

底层调用链与请求构造

从源码可以把整条调用链串联起来：

1. 前端/chat请求携带use_agentic_knowledgebase覆盖项进入 ChatReadRetrieveReadApproach.run_until_final_call；
2. 若开启，则调用run_agentic_retrieval_approach（chatreadretrieveread.py），从中读取检索档位、Web/SharePoint 覆盖项、reranker 阈值、ACL 令牌等；
3. 底层run_agentic_retrieval（approach.py）按档位构造请求：
   • 始终以SearchIndexKnowledgeSourceParams描述主索引知识源（含include_references、include_reference_source_data、reranker_threshold等参数）；
   • Web/SharePoint 开启时追加WebKnowledgeSourceParams/RemoteSharePointKnowledgeSourceParams；
   • minimal档只传intents（单条语义意图），其余档位传完整messages让 Azure AI Search 自行规划；
   • 非 Web 场景强制output_mode="extractiveData"，即只抽取证据不生成综合答案；
4. 通过KnowledgeBaseRetrievalClient.retrieve发起请求，并把x-ms-query-source-authorization（ACL/oid 令牌）一并传递；
5. 返回后按ActivityRecord解析各知识源实际执行的子查询，按引用类型把SearchIndexReference、WebReference、RemoteSharePointReference分别映射为Document、WebResult、SharePointResult；
6. 若 Web 源返回了合成答案，则经replace_all_ref_ids把引用占位符替换为真实来源（URL、sourcepage、web_url）后直接作为最终答案，此时不再调用生成 LLM（见 chatreadretrieveread.py 的return_answer逻辑）；
7. 每一步的规划查询、模型、部署名、reranker 阈值、过滤器等被记录为ThoughtStep，随响应返回给前端展示。

查看查询计划与 Token 消耗

Agentic Retrieval 的规划过程会产生额外计费 token，因此文档建议部署后检查实际消耗：在任意一条聊天回答上点击灯泡图标，打开 "Thought process"（思考过程）标签页，即可看到规划过程消耗的 token 数以及规划产生的子查询列表。仓库中的 query-plan.png 展示了该界面中查询计划与 token 用量的形态，可作为验收该功能的参考截图。

从实现上看，"Thought process" 中的数据直接来自前面提到的ThoughtStep序列：规划查询步骤（对应run_agentic_retrieval中的 "Agentic retrieval response" 步骤）会带上query_plan（各知识源的 activity 明细）、模型、部署名、reranker 阈值、过滤器等信息（approach.py），前端 ThoughtProcess.tsx 负责渲染这些内容。若开启多模态，图片来源也会一并进入数据点（get_sources_content中download_image_sources逻辑）。

与普通检索路径的对比

文档明确：Agentic Retrieval 适合"复杂或多面向问题"，通过多条子查询与多知识源合并来提升回答质量；而普通路径在单意图、低成本场景下依然轻量高效。实际选型时应结合问题复杂度、延迟、成本与数据源需求综合判断。

常见问题与排查建议

• 启动报错 "Azure OpenAI deployment for Knowledge Base must be specified"：未设置AZURE_OPENAI_KNOWLEDGEBASE_DEPLOYMENT且开启了USE_AGENTIC_KNOWLEDGEBASE，请先完成第 2 步环境变量配置；
• 启用 Web 源后报 "Web source cannot be used with minimal retrieval reasoning effort"：请把AZURE_SEARCH_KNOWLEDGEBASE_RETRIEVAL_REASONING_EFFORT改为low或medium后重新执行azd up；
• 启用 Web 源后流式输出不可用：这是设计约束，需在 UI 中关闭流式选项（或接受非流式回答）；
• 启用 SharePoint 源但未启用访问控制：日志会提示AZURE_ENFORCE_ACCESS_CONTROL must be true when USE_SHAREPOINT_SOURCE is true，请同步开启 ACL 并在 login_and_acl.md 中了解具体配置；
• Token 用量高于预期：可把检索档位调回minimal（在无 Web 源的场景下），或在 UI 中针对单个会话临时切换档位对比消耗；
• 如何确认走了 Agentic 路径：查看 "Thought process" 中是否出现 "Agentic retrieval response" 步骤及其query_plan字段（含各知识源的子查询），这是最直接的运行证据。

小结

Agentic Retrieval 将"检索"从单次查询执行升级为 LLM 驱动的规划过程：minimal保持轻量单意图、low/medium支持查询扩展与多源规划，配合可选的 Web/SharePoint 知识源，能显著提升复杂问题的召回与回答质量。启用时只需依次设置USE_AGENTIC_KNOWLEDGEBASE、检索模型、检索档位与可选知识源环境变量，再执行azd up即可。与此同时要牢记三组硬约束：Web 源必须配合low/medium档、Web 源会禁用流式与追问、SharePoint 源需要认证与 Copilot 许可证。结合 agentic_retrieval.md 与 approach.py、chatreadretrieveread.py 等源码，即可在部署与调优时快速定位行为与成本来源。

【免费下载链接】azure-search-openai-demoA sample app for the Retrieval-Augmented Generation pattern running in Azure, using Azure AI Search for retrieval and Azure OpenAI large language models to power ChatGPT-style and Q&A experiences.项目地址: https://gitcode.com/GitHub_Trending/az/azure-search-openai-demo