构建可追溯的企业知识助手
本实战使用两份虚构的支持制度文档，构建一个只根据已入库资料回答问题的知识助手。完成后，可以在 Playground 中验证单文档问题、跨文档问题和资料缺失问题，并通过 Trace 确认智能体实际进行了知识检索。
准备条件和样例
开始前需要：
- 一个可用的模型凭证和模型。
- 创建智能体模板、智能体实例、Collection 和知识库组的权限。
- 上传 Markdown 文件的权限。
下载并解压知识助手样例包。压缩包包含 support-policy.md、escalation-guide.md 和 test-cases.json。另外可以查看：
本文使用固定的 recipe-support-* 名称，便于识别和清理实战资源。如果环境中已经存在同名资源，请为本文中的 Collection、知识库组、智能体模板和智能体实例统一追加简短后缀，例如 -team-a；不要修改或复用来源不明的同名资源。
样例中的组织、制度和事件均为虚构内容，不要替换为包含密钥、个人信息或生产事件详情的文件。
验证模型调用
创建 Collection 之前，使用创建第一个智能体并完成基础验证中创建的最小智能体实例发送一条消息，并确认模型返回有效回复，以此作为凭证验证结果。模型凭证出现在选择列表中、模型名称已经显示或 Playground 显示 已连接，只表示相应配置已经加载。
如果最小智能体没有回复，或返回模型凭证、模型服务相关错误，请先由凭证负责人修复模型链路。此时继续上传资料、调整检索参数或修改知识提示词，不能解决模型调用失败。
理解构建路径
Collection 保存已经入库的资料。知识库组选择 Collection 并提供检索参数。智能体模板通过插件关联知识库组，智能体实例才是实际接受问题并执行检索的运行对象。
以下入口仅在租户已启用知识库能力时可用。按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。
创建并填充 Collection
打开 知识库管理。
也可以从控制台左侧导航进入 知识库管理。
单击 新建 collection，输入
recipe-support-knowledge-v1。在 说明（可选，最多 2000 字） 中填写
虚构的支持响应制度和事件升级指南。保持 向量维度（可选）、chunk_overlap（可选） 和 distance（可选） 的页面默认值，然后选择 确认创建。
在 选择 Collection 中选择刚创建的 Collection。
选择 上传文件，添加
support-policy.md和escalation-guide.md。单击 生成 RAG 知识库。
在 构建历史 中等待两个文件都进入成功状态，并打开 日志 确认没有解析、分块、Embedding 或写入错误。
警告
“文件已选择”或“任务已提交”不表示资料已经可以检索。只有构建任务成功，才能继续创建知识库组。
检查点 1：Collection 列表中存在 recipe-support-knowledge-v1，构建历史 显示两份文件均已成功处理。
创建知识库组
打开 知识库组。
也可以从控制台左侧导航进入 知识库组。
在 模板 中单击 新建。
在 新建模板 中，将 名称 * 设为
recipe-support-group-template-v1，把 默认检索条数（top_k） 保持为4，并在 默认知识库集合 * 中选择recipe-support-knowledge-v1。选择 创建。
切换到 实例，单击 新建。
在 新建实例 中，通过 模板 选择刚创建的模板，将 名称 设为
recipe-support-group-v1，确认 知识库集合 * 为recipe-support-knowledge-v1且 默认检索条数（top_k） 为4，然后选择 创建。
这里的 top_k=4 是知识检索没有另外指定 top_k 时使用的默认值，不是每次检索的固定上限。实际检索可以使用不同的值。先保留样例默认值，再通过固定问题和 Trace 核对实际请求值与检索结果；更换为真实资料后，重新测试并选择适合文档粒度和问题类型的值。
检查点 2：知识库组的实例列表中存在 recipe-support-group-v1，并显示目标 Collection。
创建知识助手
打开创建智能体模板页面。
也可以打开 智能体模板，再选择 创建智能体模板。
将 模板名称 设为
recipe-support-assistant-v1，并选择可用的 模型凭证和 模型。在 系统提示词 中输入以下内容：
language-text你是星河设备支持助手。 回答支持制度和事件升级问题前，必须先检索知识库。 只根据检索到的资料回答，不要补充资料中没有的政策、时限或金额。 如果资料没有答案，明确说明样例资料未提供该信息，并建议查询对应合同或联系制度负责人。在 插件配置 中单击 添加插件。
选择 知识库 RAG - 实例，再选择
recipe-support-group-v1。选择 创建智能体模板，并在智能体模板的 插件 页签中确认知识库组实例的名称和资源 ID。
选择 创建实例，将 实例名称 设为
recipe-support-assistant-test-v1。创建后打开实例的 Playground，确认页面显示 已连接。
这里直接关联知识库组实例，是为了让这次实战的 Collection 和检索配置保持固定。需要让每个智能体实例从同一套默认值生成独立知识库组资源时，再使用 知识库 RAG - 模板。参见模板和实例如何影响资源。
检查点 3：智能体实例已经创建，Playground 显示 已连接，来源智能体模板的插件页签显示 recipe-support-group-v1。
运行固定验收问题
在智能体实例的 Playground 中依次提问。每条固定问题都使用一个新会话，避免上一条问题的对话内容和检索结果影响下一条测试：
| 测试 | 问题 | 应观察到的结果 |
|---|---|---|
| 单文档 | P1 事件的首次响应目标是多少？ | 回答包含 15 分钟 |
| 跨文档 | 生产服务完全不可用，而且确认 P1 后 30 分钟仍没有技术负责人，应该如何响应和升级？ | 回答包含 P1 的 15 分钟响应目标、通过值班热线升级，以及事件编号、影响范围、已完成操作和当前阻塞项 |
| 资料缺失 | P1 事件可以获得多少合同赔付？ | 明确说明样例资料没有赔付金额，并建议查询对应合同；不得编造金额 |
每次测试后打开 Trace，展开知识检索调用，并完成以下检查：
- 调用参数中的
collection_name与知识库组中目标 Collection 的资源 ID 一致。该字段显示资源 ID，而不是 Collection 的显示名称。 - 调用中实际使用的
top_k符合本次测试预期。它可能与知识库组中的默认值不同。 - 检索结果包含回答所依据的样例内容。
要确认知识能力已经按预期生效，除核对回答外，还应在 Trace 中确认发生了目标知识检索。 如果刚完成的调用没有出现在 Trace 列表中，刷新智能体实例详情页，再重新打开该页签核对。
检查点 4：三条固定问题符合预期，每条问题的 Trace 都显示知识检索，并且 collection_name 指向 recipe-support-knowledge-v1 对应的 Collection 资源 ID。
排查失败
根据可见现象检查对应配置和运行证据，再采取处理措施。
| 现象 | 先检查 | 处理方式 |
|---|---|---|
| Playground已连接 但没有模型回复 | 使用同一凭证的最小智能体是否能返回回复 | 先修复模型凭证或模型服务，再继续知识检索测试 |
| 构建任务失败 | 构建历史 中的状态和 日志 | 修正文件、权限或 Collection 配置后重新上传；不要先调提示词 |
| 回答没有使用资料 | 智能体模板的 插件 页签、智能体实例是否已更新、Trace | 重新关联知识库组实例，更新智能体实例后再测试 |
| Trace 列表没有刚完成的调用 | 实例详情页是否保持在测试前打开的旧状态 | 刷新实例详情页，重新打开 Trace 后再判断调用记录是否缺失 |
| 跨文档问题缺少部分事实 | Trace 中的检索结果和 top_k | 先确认两份文件都已入库，再小幅调整 top_k 并重跑全部固定问题 |
| 资料缺失问题出现编造 | 系统提示词和 Trace | 加强“资料没有答案时明确说明”的约束，并保留负向测试作为回归项 |
调整为自己的场景
根据资料范围、共享方式和调用入口调整知识资源及其关联方式。
- 多个团队维护不同资料域：为资料域建立不同 Collection，使用 Collection 说明帮助智能体选择，再在知识库组中组合。
- 多个智能体实例共享相同资料和检索配置：复用经过验证的知识库组实例，并记录数据负责人。
- 每个智能体实例需要独立选择 Collection：在智能体模板中关联 知识库 RAG - 模板，把确实需要变化的字段设为创建实例时可配置。
- 由业务系统发起问答：保持知识配置不变，改用通过 API 调用智能体。
- 资料需要定期更新：使用支持的网页或 Sitemap 定时任务，或者建立人工上传和固定问题回归流程。
准备上线和清理
上线前为 Collection 指定内容负责人，记录固定问题和可接受结果，制定更新窗口，并把 Trace、任务失败和实例状态纳入运行检查。参见将智能体投入生产和查看 Trace、指标和运行记录。
仅清理本实战创建的资源，并先确认没有其他智能体模板或智能体实例引用它们。建议顺序为：
- 删除测试智能体实例。
- 删除测试智能体模板。
- 删除知识库组实例。
- 删除知识库组模板。
- 删除对应构建记录。
- 最后删除 Collection。
删除知识库组实例不会删除 Collection。删除 Collection 会移除其中的向量内容，因此不要把共享的生产 Collection 当作实战资源清理。