关于 Azure AI Search 与 Foundry Agent 的实用 PDF 问答指南
使用嵌入为私有课程PDF创建索引，将Foundry代理连接到向量索引，并排查导致RAG功能异常的认证与指令问题。
来源: Building a Grounded RAG Agent on Azure AI Search and Azure AI Foundry
简介
一家数字取证培训机构拥有多年积累的PDF课程资料——包括幻灯片、实验内容及参考章节。分析人员需要在数十页资料中查找某个特定概念，而通过分散的文件进行关键词搜索既缓慢又不可靠。理想的产品应能从这些资料中以通俗语言解答问题，而非对通用教科书的改写。
这正是RAG技术的应用方式：从私有文档集中检索相关内容，并以此作为生成内容的依据。该方案在Azure平台上实现了端到端的完整实现——Azure AI Search通过嵌入技术对真实PDF文件进行索引，同时搭配Azure AI Foundry智能体，能够从索引中而非通用知识库中回答问题。
这也成了一种调试叙事。几乎没有任何失败是由于想法有误造成的；故障都源于资源、认证模型以及默认代理行为之间的细微差异。这些问题点被记录下来，而非被消除。
理解架构
四项 Azure 服务负责四项任务。
Blob Storage用于存储原始文档——此处为法证相关 PDF 文件；任何私有领域的文本集都采用相同的存储格式。
Azure AI Search负责索引与检索。该服务会将文档分割成若干块，调用嵌入模型，并存储文本及向量信息。在查询时，它返回语义上相似的文档块，而不仅仅是包含关键字的条目。
Azure AI Foundry用于托管模型及智能体：一种用于索引/查询向量化的嵌入部署方式，以及一种用于生成答案的聊天部署方式。该智能体会将聊天模型与知识源及指令结合在一起。
托管身份与角色基访问控制用于决定谁可以查询什么内容。各连接（搜索→Blob、搜索→嵌入数据、智能体→索引）应优先使用基于角色的权限而非嵌入式密钥。当前版本尚未实现完全无密钥的架构；这一缺陷将在下文中提及。
第一阶段：源文档
一个私有的Blob容器（knowledge-docs）用于存储课程PDF文件。访问权限为私有，不允许匿名读取，这符合将相关资料视为敏感信息的原则。
第二阶段：在Azure AI Foundry中部署模型
在Foundry项目中进行了两项部署：
- 用于生成答案的聊天模型（
chat-deploy）
embed-deploy、text-embedding-3-small）在连接搜索技能集或智能体之前，请确认这两种嵌入模型均已存在；否则日后会导致难以排查的索引错误。
第三阶段：Azure AI Search与向量化索引
首先创建一个搜索服务，然后创建一个索引，其字段需包含分块文本、向量以及文档元数据。还需关联一个技能集，该技能集需执行以下操作：
- 从
knowledge-docs中获取数据块 - 将数据块分割为重叠的部分
- 调用嵌入模型部署服务
- 将向量写入索引中
索引构建工具需要具备读取数据块以及调用嵌入模型端点的权限。即便角色分配看似“差不多正确”，在运行时仍可能出错——请务必核实确切的资源标识符。
Web Api response status: 'NotFound'
DeploymentNotFound: The API deployment for this resource does not exist.
Web Api response status: 'Unauthorized' (401)
Access denied due to invalid subscription key or wrong API endpoint.
Access denied when connecting to the MCP server ... HTTP 403 Forbidden
You are an assistant that answers questions about digital forensics course material.
For every user question, you MUST first search the connected knowledge base before answering.
Only answer using information retrieved from the knowledge base.
If the knowledge base returns no relevant results, say so explicitly rather than answering from general knowledge.
第四阶段：索引失败及其原因
索引失败很少会因为一句简单的说明就能解决。常见的故障表现包括：
- 技能集无法接入嵌入部署（认证问题或端点错误）
- 索引器虽在运行，但文档数量仍为零（容器路径或技能集引用问题）
- 向量数据的维度不正确（索引架构与部署模型不匹配）
应将这些问题视为配置错误，而非RAG概念层面的故障。在同时更改三个设置之前，请先记录索引器的执行历史。
第五阶段：将索引与智能体连接
在Foundry中，需将搜索索引作为智能体的知识来源。指令应要求引用检索到的内容，且当索引未返回相关结果时必须拒绝回答。可用只有某一页PDF中才有答案的问题进行测试——成功意味着引用的是真实内容，而非凭空猜测。
第六阶段：两个行为缺陷
除配置问题外，还出现了两个行为方面的问题：
- 过度辅助的回退机制——当检索结果为空时，聊天模型仍会凭借先前的知识作答。应细化指令，并在可能的情况下增加真实性检查，使得检索为空时返回“不在语料库中”的提示。
- 认证不一致问题——某些链接仍使用密钥进行认证，而其他链接则使用托管身份。混合认证方式不仅会增加切换难度，还会掩盖实际成功的认证主体。
两者都不是门户网站的复选框；它们都是通过指令和身份设计体现出来的产品决策。
幕后实际发生了什么
用户的提问会被嵌入其中，搜索功能会返回最相关的内容片段，智能体提示会收到这些片段以及相关指令，然后聊天模型会在该上下文约束下生成答案。对象存储从不直接与智能体通信；搜索功能是数据检索的边界。Foundry则负责协调工作及托管模型。
面临的挑战与经验教训
- 在创建资源之前必须先确认区域和模型的可用性。
- 索引架构中的嵌入维度必须与所选的嵌入模型完全一致。
- 在查看索引器详细信息之前，RBAC错误看起来就像索引为空一样。
- 智能体指令是保证正确性的关键部分，而非装饰性内容。
核心要点
Azure RAG是由一系列小型组件构成的：数据块隐私保护、技能集→嵌入权限设置、索引架构↔模型维度、智能体知识附加机制，以及基于事实的回答策略。只要这些部分处理得当，整个架构就会显得非常简洁高效；一旦有任何环节出错，你将不得不花费数天时间调试，还误以为“RAG根本不起作用”。
操作建议：准备一份一页纸的操作手册，列出所有具体的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，这份手册比通过门户网站截图进行排查要高效得多。另外可以设置每周自动执行的任务，提出三个关键问题，其答案应存在于已准备的页面中；如果基于事实的回答能力出现下降，则自动终止构建流程。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
运营技巧：准备一份一页纸的操作手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
操作建议：准备一份一页纸的运行手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。
操作建议：准备一份一页纸的运行手册，列出确切的资源名称、部署名称（而非基础模型名称）、索引名称、技能集名称，以及每一步骤所使用的托管身份或密钥。当索引器在凌晨2点出现故障时，只需查看该手册中的门户网站截图即可快速定位问题。此外可设置每周自动执行的任务，提出三个关键问题，其答案均保存在已确定的页面上；如果问题的可靠性下降，则构建过程将失败。