第一次使用可以先按产品资料问答助手指南完成一份资料的导入、角色绑定与语音问答。本篇详细说明检索、导入限制与资料管理。
知识库让助手查找你提供的参考原文。资料独立保存在当前用户的资源库中，多名角色可以关联同一份资料；更新一次，所有关联角色的下一次检索都会读取新版本。记忆仍按用户和角色隔离。
希望同时验证记忆与多轮上下文，可直接按知识库 Demo、Memory 与续聊操作。该文还说明了当前历史记录与继续会话的实现边界。
先了解当前的检索方式
当前使用本地文本目录和关键词片段检索：资料被保存为文本，查询时切成相互重叠的片段，按问题中的词与片段的匹配程度排序，默认返回最多 3 个片段。对话模型通过 search_knowledge_base 工具获取这些片段，再组织答案。
资料预览里的「生成知识目录」使用已选模型服务显式生成 LLM Wiki 主题和原文引用，保存后可重复查看；这不训练模型，也不启动本地常驻模型。当前默认对话检索还不使用这些目录，生成成功不代表问答已启用 Wiki 导航。实验导航尚未通过完整回答质量门槛，不能据此保证同义问法、例外条件或回答语言正确。
如果已保存的目录损坏、版本不匹配或引用不属于原文，预览会提示目录已失效，仍可查看原文并点击重新生成。普通读取不会自动调用模型，也不会修改磁盘中的原文；重新生成仍使用当前模型配置和调用额度限制。
这是检索增强生成（RAG）的一种基础实现。目前未接入 embedding 模型、向量数据库、BM25 或重排序模型。同义词、改写问题和跨文档推理的检索效果有限，提问时尽量使用原资料里的产品名、术语或关键词。
知识库资料与长期记忆分别配置：资料提供明确的参考原文；长期记忆保存对话中形成的信息。导入知识库不会训练模型，也不意味着每一轮都会搜索，是否调用检索工具由对话模型判断。
第一步：导入资料
打开知识库资源页，默认查看全部资料，无需先选择角色。资料按用户隔离，共享使用说明是只读示例。角色关联统一在角色配置页维护，知识库页只管理资料。
选择下面任意一种方式：
| 方式 | 操作 | 注意事项 |
|---|---|---|
| 粘贴文本 | 填写「资料名称」，在「资料内容」粘贴原文，点击「创建资料」 | 名称必填，最多 120 字；内容不能为空 |
| 导入文件 | 选择文字型 PDF、DOCX、Markdown（.md）或 TXT，点击「导入文件」 | 名称可选，未填写时使用文件名；单文件最多 5,000,000 字节；不支持 DOC、XLSX、PPTX 或图片 |
| 导入网页 | 输入公开 HTTPS 网页地址，点击「导入网页」 | 名称可选；适合能直接返回正文的 HTML 或纯文本网页 |
每份资料提取后的正文最多 32,000 UTF-8 字节，中文通常一个字占 3 字节，不能将此限制理解为 32,000 个汉字。超过限制时，请按主题拆成多份资料再导入。
PDF 导入依赖文件中的可提取文字，当前没有 OCR。空白或纯扫描 PDF 会提示没有可提取文本，损坏或需密码的文件会提示无法读取。DOCX 读取正文文本，不提取内嵌图片中的文字。TXT、Markdown 支持 UTF-8，以及带 BOM 的 UTF-16；其他文件编码请先转换为 UTF-8。
网页导入不执行浏览器脚本，不登录网站，也不抓取页面链接指向的其他资料；登录页、仅由 JavaScript 加载正文的页面或复杂在线文档，建议先导出文件或粘贴正文。HTML 会去除脚本、样式与注释，并解码常见和数字实体；按响应头或 meta 声明处理字符编码。网页响应正文还有 200,000 字节的下载上限。
同一用户重复粘贴相同正文会提示已存在，可直接关联原资料。文件和网页按来源更新：重复导入同名文件或同一网址时更新原资料，保持 ID 和全部角色关联。旧版不同角色导入过同名来源时，系统保留各份资料；来源有歧义会提示冲突，请在列表选择具体资料后编辑更新，避免误覆盖。
预览、增量更新与删除
点击「预览」展开完整正文，再在资料列表点击「编辑」，可执行以下操作：
- 修改名称和正文后点击「保存修改」。可追加、修改或删除部分段落，也可替换全文；所有关联角色都会读取新内容。
- 在编辑弹窗切换到「文件」，选择新文件后点击「保存修改」。即使文件名变化，也会更新当前编辑的资料。
- 网页资料会带出原网址，在编辑弹窗切换到「网页」，点击「保存修改」重新抓取正文；也可输入新的公开网址替换来源。
- 点击「删除资料」并确认，删除资料及其所有角色关联，后续检索不再返回它。
更新后，资源页测试和 Python 会话的下一次检索读取最新正文。编辑页面带有版本检查，另一页面已修改该资料时会提示冲突，请刷新后重新编辑。版本号用于冲突检查，当前不保存可回滚的历史版本。
网页资料保存的是抓取时的快照。当前提供手动增量更新，没有定时抓取、目录监听或平台自动同步。已经进入会话上下文的旧引用仍可能影响后续回答；验证最新规则时明确重新检索，或开启新会话。
第二步：测试检索
- 在「资料列表」勾选一份或多份资料。
- 在「测试检索」输入问题，点击「检索」。问题最多 500 字符。
- 展开「查看引用片段」，检查是否包含回答所需的原文。网页资料还能点击「查看原网页」。
勾选决定测试范围；在角色配置页勾选资料并保存，才能提交角色启用范围。取消勾选并保存是解除该角色关联，不删除原资料。知识库页新建资料只保存到资源库，需在角色配置中选择使用。测试返回原文片段，不生成助手回答。
可以先使用下面这份小资料验证完整流程：
资料名称：星河商店售后说明 v1
星河商店的退货期限为签收后 7 天。
退货条件：商品未使用、包装完整，并提供订单号。
客服服务时间为工作日 09:00—18:00。
退货运费规则：商品质量问题由商店承担，其他情况由买家承担。
导入后勾选它，检索「星河商店退货期限」，应能看到包含「签收后 7 天」的片段。再尝试「退货运费规则」，确认对应条款能被找到。无命中时，换成原文关键词，并检查勾选范围和导入后的正文预览。
第三步：检查角色的检索范围
- 进入角色列表，打开准备使用的角色。
- 打开角色配置中的「知识库」，确认已导入的资料处于选中状态，可取消不希望会话使用的资料。每个角色最多启用 30 份。
- 等待配置保存完成，确认没有保存错误，再从该角色开始对话。角色详情页支持自动保存；从角色配置中的「新建」导入资料后，返回角色确认选中状态和保存结果。
多个角色可关联同一份用户资料。未关联的资料不会进入该角色的会话检索范围。修改或删除共享资料会影响全部关联角色；只想让一个角色停用时，取消关联并保存。
旧版角色资料会进入统一资源库，保留文档 ID、正文、版本和已有绑定，不创建新副本，也不自动合并已有重复资料。共享只读示例继续允许各角色选用。
实时数字人同样通过其角色标识关联资源库资料。将角色配置应用到实时数字人时复制关联，保留同一文档 ID，不复制正文。
第四步：在对话中验证
从绑定了示例资料的角色进入对话，提问：「请查一下知识库，星河商店的退货期限是多少？」预期答案应包含「签收后 7 天」。随后问「需要哪些退货条件」，核对是否符合原文。
再问一个资料没有覆盖的问题，例如「退款多久到账」。正确的行为是说明资料没有提供该信息，而不是编造一个时间。若需要稳定的业务回答，可在 Persona 中加入：「涉及业务规则时先检索知识库；依据资料回答；资料不足时明确说明，并询问需要补充的信息。」这能指导模型使用工具，但仍需用实际问题验证效果。
资源页的测试结果展示引用片段；对话是否显示来源文字取决于模型回答，当前不能把回答中的来源展示视为必然行为。
怎样整理资料更容易检索
- 一份资料聚焦一个主题，例如售后规则、产品参数或服务流程，避免混入无关内容。
- 在正文中写出完整的产品名与条款名；当前检索评分依据正文，资料名称主要用于标识来源。
- 用标题、短段落和问答形式组织内容；每个条款保留条件、例外、日期和版本。
- 为常见说法补充别名，例如「退货期限（退货时间、几天内可以退）」；通过测试检索判断是否改善命中。
- 保留原文出处，绑定当前有效版本；对合同、价格和政策等内容尤其要核对生效日期。
Obsidian 笔记可以直接选择 Markdown 文件导入；Notion、Workflowy、腾讯文档可先导出为支持的格式或粘贴正文。当前没有这些平台的自动同步连接器。选型与后续同步方式见知识库选型与接入方案。
常见问题
| 现象 | 排查方式 |
|---|---|
| 提示先登录 | 使用同一账号导入资料、配置角色并开始会话；本地开发授权与线上账号不是同一资料空间 |
| 「检索」按钮不可点 | 勾选至少一份资料，并输入非空问题 |
| 文件没有可提取文本 | 检查是否为扫描 PDF、图片或空文件；先转为文本再导入 |
| 网页导入失败 | 确认是公开 HTTPS 正文页；受登录、脚本加载或下载大小限制时，改用文件或粘贴文本 |
| 提示非公开网络或 Fake-IP | 检查部署机器的 DNS；代理模式返回 198.18.* 时使用正常公网解析，或按下方配置显式启用 HTTPS DNS |
| 测试能命中，对话没使用 | 核对角色绑定与保存结果、进入会话的角色，以及模型是否调用检索工具；尝试明确要求查知识库 |
| 对同义表达搜索效果差 | 补充原文别名，或按接入方案升级为语义与关键词混合检索 |
| 导入成功，语音服务搜索不到 | 自行部署时检查两个进程的资料目录和登录身份是否一致，见下方说明 |
自行部署时的启用条件
Next.js 与 Python 语音服务都读取本地知识目录，默认位置为项目工作目录下的 .openrealtime/knowledge/catalog.json。当进程工作目录不同或分别运行在容器中时，为两者设置相同的 KNOWLEDGE_CATALOG_DIR 绝对路径，并挂载同一持久化卷。
本地语音服务需要启用工具调用，例如 .env.example 中的 VOICEAGENT_DEMO_TOOLS=1，并配置支持工具调用的模型。经过服务端 admission 验证的会话也会建立工具注册表。单纯能录音和播放语音，不代表检索工具已经可用。
会话启用角色的 search_knowledge_base 后，「退款政策是什么」等自然问题会交给可检索的对话模型处理，无需先加「查一下」。模型仍决定是否实际读取资料；工具关闭时恢复普通聊天路径。这不自动启用实验 Wiki 导航，也不增加独立的路由模型。
网页导入默认使用系统 DNS，并在每次跳转时检查和固定公网 IPv4。当前机器的代理 DNS 若返回 Fake-IP，可在网页服务环境设置 KNOWLEDGE_WEB_DNS=cloudflare-doh 后重启。该选项通过固定的 Cloudflare HTTPS DNS 解析目标域名，目标 IP 仍需通过公网校验；域名查询会发送给该解析服务。参见Cloudflare 官方接口说明。
排查时按顺序确认：资源页可见资料 → 测试可命中 → 角色绑定已保存 → 会话传入角色配置 → 服务端启用 search_knowledge_base → 模型实际调用工具。检索为空与服务故障要分别排查。
统一管理与备份
资料增删改、版本冲突、记忆重置和历史清理的区别，见数据管理指南。删除资料当前没有回收站；版本号用于并发控制，不提供历史还原。部署时将知识目录和角色绑定目录纳入一致备份。
页面 Demo
进入「资源库 → 知识库」，点击「体验示例」打开已填入内容的弹窗，再「创建资料」，检索「营业时间」。点击「预览」可查看完整内容；点击「编辑」将 18:00 改为 20:00 并保存，检索会读到新版本。删除会同时移除所有角色关联。
示例是普通用户资料，可关联多个角色。Demo 验证管理与检索片段，不代表模型最终回答质量。
记忆管理位于「资源库 → 记忆管理」，支持按角色查看、新增、编辑、删除、清空及记忆开关。原 /settings/memory 地址会自动跳转。
页面操作
主页面显示资料列表。点击「新增资料」或「编辑」立即打开编辑弹窗，按文本、文件、网页切换输入；保存后关闭弹窗并显示结果。点击「预览」查看全文。测试检索默认折叠，展开后勾选资料并搜索。角色关联统一在角色详情页配置，知识库页不再显示角色选择。