文档中心

Appearance

控制台

构建可追溯的企业知识助手 ​

本实战在智能体开发服务平台（AgentWorks）中使用两份虚构的支持制度文档，构建一个只根据已入库资料回答问题的知识助手。完成后，可以在 Playground 中提出需要综合两份文档的问题，并通过 Trace 确认智能体实际检索了对应资料。

本实战将帮助你理解 ​

  • Collection 如何保存已经入库的资料，知识库组如何指定智能体可以检索的 Collection 和检索参数。
  • 为什么构建任务成功只表示资料已经入库，还需要通过实际回答和 Trace 确认检索参与了运行。
  • 如何让知识助手在资料没有答案时说明信息不足，而不是补充未经检索证实的内容。

准备条件和样例 ​

开始前需要：

  • 一个已经在 Playground 中确认模型返回有效回复的模型凭证和模型。凭证出现在选择列表中、模型名称已经显示或页面显示 已连接，只表示相应配置已经加载；尚未验证实际回复时，先运行创建第一个智能体并完成基础验证。
  • 创建智能体模板、智能体实例、Collection 和知识库组的权限。
  • 上传 Markdown 文件的权限。

下载并解压知识助手样例包。压缩包包含 support-policy.md、escalation-guide.md 和 test-cases.json。另外可以查看：

本文使用固定的 recipe-support-* 名称，便于识别和清理实战资源。如果环境中已经存在同名资源，请为本文中的 Collection、知识库组、智能体模板和智能体实例统一追加简短后缀，例如 -team-a；不要修改或复用来源不明的同名资源。

注意

只上传用于实战的非敏感资料

样例中的组织、制度和事件均为虚构内容。不要替换为包含密钥、个人信息、客户资料或生产事件详情的文件；入库内容会提供给知识检索，并可能显示在 Trace 中。

理解构建路径 ​

图表预览

Collection 保存已经入库的资料；知识库组实例选择本实战使用的 Collection，并保存 top_k 等检索参数；智能体模板再关联这个知识库组实例。最后创建的智能体实例才是接受问题并执行检索的运行对象。参见区分能力、插件和能力资源。

构建知识助手 ​

先让两份样例文档完成入库，再创建固定检索范围的知识库组实例，最后把它关联到智能体模板。以下入口仅在租户已启用知识库能力时可用。

按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。

创建并填充 Collection ​

知识库管理中的 Collection 选择、上传来源、文档选择和生成 RAG 知识库操作

  1. 打开 知识库管理。

    打开知识库管理

    也可以从 AgentWorks 管理控制台左侧导航进入 知识库管理。

  2. 单击 新建 collection，输入 recipe-support-knowledge-v1，然后选择 确认创建。

  3. 在 选择 Collection 中选择刚创建的 Collection。

  4. 选择 上传文件，添加 support-policy.md 和 escalation-guide.md，然后单击 生成 RAG 知识库。

  5. 在 构建历史 中等待两个文件都进入成功状态。

    重要

    构建成功后资料才可以检索

    “文件已选择”或“任务已提交”只表示入库任务已经开始。两份文件都显示成功后再继续；如果任务失败，请打开 日志，根据解析、分块、Embedding 或写入错误处理后重新上传。

创建知识库组 ​

新建知识库组模板时的默认检索条数和 Collection 选择

  1. 打开 知识库组。

    打开知识库组

    也可以从 AgentWorks 管理控制台左侧导航进入 知识库组。

  2. 在 模板 中单击 新建。

  3. 在 新建模板 中，将 名称 * 设为 recipe-support-group-template-v1，把 默认检索条数（top_k） 保持为 4，并在 默认知识库集合 * 中选择 recipe-support-knowledge-v1。

    注意

    为什么本实战使用 top_k=4？

    top_k 控制一次检索返回的候选片段数量。本实战先使用样例值 4，再通过固定问题和 Trace 检查是否取得了两份文档中的相关内容。更换为自己的资料后，请根据文档粒度和问题类型重新测试，不要把 4 当作适用于所有资料的固定值。

  4. 选择 创建。

  5. 切换到 实例，单击 新建。

  6. 在 新建实例 中，通过 模板 选择刚创建的模板，将 名称 设为 recipe-support-group-v1，确认 知识库集合 * 为 recipe-support-knowledge-v1 且 默认检索条数（top_k） 为 4，然后选择 创建。

  7. 打开知识库组实例详情，确认 引用的知识库集合 包含 recipe-support-knowledge-v1，并记录该 Collection 的资源 ID，供后续核对 Trace 使用。

创建知识助手 ​

  1. 打开创建智能体模板页面。

    创建智能体模板

    也可以打开 智能体模板，再选择 创建智能体模板。

  2. 将 模板名称 设为 recipe-support-assistant-v1，并选择可用的 模型凭证和 模型。

  3. 在 系统提示词 中输入以下内容：

    language-text
    你是星河设备支持助手。
回答支持制度和事件升级问题前，必须先检索知识库。
只根据检索到的资料回答，不要补充资料中没有的政策、时限或金额。
如果资料没有答案，明确说明样例资料未提供该信息，并建议查询对应合同或联系制度负责人。

  4. 在 插件配置 中单击 添加插件。

  5. 选择 知识库 RAG - 实例，再选择 recipe-support-group-v1。

    注意

    为什么直接选择知识库组实例？

    本实战选择已经创建并检查过的知识库组实例，使智能体使用固定的 Collection 和检索参数。需要让每个智能体实例根据同一套默认值创建各自的知识库组实例时，再选择 知识库 RAG - 模板。参见知识库 RAG 模板和实例有什么区别？。

  6. 关闭默认开启的 启用文件系统，不添加其他插件或工具权限。本实战只验证模型回答和知识检索。

  7. 选择 创建智能体模板，并在智能体模板的 插件 页签中确认知识库组实例的名称和资源 ID。

  8. 选择 创建实例，将 实例名称 设为 recipe-support-assistant-test-v1。创建后打开实例的 Playground，确认页面显示 已连接。

运行固定验收问题 ​

在智能体实例的 Playground 中新建会话，发送这个需要综合两份样例文档的问题：

language-text
生产服务完全不可用，而且确认 P1 后 30 分钟仍没有技术负责人，应该如何响应和升级？

注意

回答包含正确事实还不能证明发生了知识检索

模型可能根据自身知识或对话上下文生成看似合理的内容。核对 Trace 中的检索参数和结果，才能确认本次回答实际使用了目标 Collection。参见智能体没有使用已经添加的能力时，应该检查什么？。

确认：

  1. 回答包含 15 分钟的首次响应目标，并要求通过值班热线升级。
  2. 回答要求提供事件编号、影响范围、已完成操作和当前阻塞项。
  3. Trace 显示知识检索调用；collection_name 与前面记录的 Collection 资源 ID 一致，而不是显示名称。
  4. 检索结果包含回答所依据的 support-policy.md 和 escalation-guide.md 内容。

如果刚完成的调用没有出现在 Trace 列表中，请刷新智能体实例详情页，再重新打开该页签核对。

完成结果：知识助手综合两份已入库文档回答支持问题，Trace 证明本次运行检索了目标 Collection 中的相关内容。

可选：验证资料不足时不编造 ​

在新会话中发送：

language-text
P1 事件可以获得多少合同赔付？

回答应明确说明样例资料没有提供赔付金额，并建议查询对应合同，不应编造金额。需要继续做单文档和其他回归检查时，可以使用样例包中的 test-cases.json。

排查失败 ​

根据可见现象检查对应配置和运行证据，再采取处理措施。

现象先检查处理方式
Playground已连接 但没有模型回复使用同一凭证的最小智能体是否能返回回复先修复模型凭证或模型服务，再继续知识检索测试
构建任务失败构建历史 中的状态和 日志根据日志修正文件、权限或 Collection 配置后重新上传；不要先调整提示词
回答没有使用资料智能体模板的 插件 页签、智能体实例是否已更新、Trace重新关联知识库组实例，更新智能体实例后再测试
Trace 列表没有刚完成的调用实例详情页是否保持在测试前打开的旧状态刷新实例详情页，重新打开 Trace 后再判断调用记录是否缺失
跨文档问题缺少部分事实Trace 中的检索结果和 top_k先确认两份文件都已入库，再小幅调整 top_k 并重跑全部固定问题
资料缺失问题出现编造系统提示词和 Trace加强“资料没有答案时明确说明”的约束，并用资料缺失问题重新验证

调整为自己的场景 ​

完成固定问题后，再根据资料范围、共享方式和调用入口调整知识资源及其关联方式。

  • 多个团队维护不同资料域：为资料域建立不同 Collection，使用 Collection 说明帮助智能体选择，再在知识库组中组合。
  • 多个智能体实例共享相同资料和检索配置：复用经过验证的知识库组实例，并记录数据负责人。
  • 每个智能体实例需要独立选择 Collection：在智能体模板中关联 知识库 RAG - 模板，把确实需要变化的字段设为创建实例时可配置。
  • 由业务系统发起问答：保持知识配置不变，改用通过 API 调用智能体。
  • 资料需要定期更新：使用支持的网页或 Sitemap 定时任务，或者建立人工上传和固定问题复测流程。

准备上线和清理 ​

上线前为 Collection 指定内容负责人，记录固定问题和可接受结果，制定更新窗口，并把 Trace、入库任务失败和实例状态纳入运行检查。真实资料的访问范围、更新责任和删除流程也应经过审批。参见将智能体投入生产和查看 Trace、指标和运行记录。

仅清理本实战创建的资源，并先确认没有其他智能体模板或智能体实例引用它们。建议顺序为：

  1. 删除测试智能体实例。
  2. 删除测试智能体模板。
  3. 删除知识库组实例。
  4. 删除知识库组模板。
  5. 删除对应构建记录。
  6. 最后删除 Collection。

删除知识库组实例不会删除 Collection。删除 Collection 会移除其中的向量内容，因此不要把共享的生产 Collection 当作实战资源清理。