排查与边界
日志和调试页面在哪,常见问题怎么处理,以及目前做不到的事。
日志与排查
知汇自带的页面
- 知识库(知汇) › 资料接入里点「读取同步记录」,看每次测试连接和同步的结果与说明。
- 知识库(知汇) › 运行记录(页面标题「知汇 · 日志」):知汇的运行日志,可按「资料来源」「操作」「结果」筛选。列表显示时间(北京时间)、操作、结果和调用来源(控制台、Agent Key 或定时同步),每条记录还有 HTTP 状态、耗时和追踪 ID,点「查看详情」可看请求链和结果。日志不保存检索词、正文、请求内容或凭据,最多保留 2,000 条。Agent 的 Key 没有日志权限。
- 知识库(知汇) › 调试 › 调试:点「运行自检」,看知识模块是否可用、控制台权限、来源和可检索文档数量、提取器执行路径、运行日志状态和检索方式。自检不联系来源平台,不扫描来源目录。下方可选一个来源,用关键词做「只读检索验证」或「读取资料目录」,核对命中片段和引用版本。
- 知识库(知汇) › 调试 › 调用:按模块的调用契约试用各个只读操作,查看输入输出契约。
调试和调用用的是当前控制台身份,验证的不是某个 Agent 的授权范围。要核对某个 Agent 能读到什么,用它自己的 Key 从 Nexus 助手或核心接口验证。
常见问题
| 现象 | 原因和处理 |
|---|---|
| 「测试连接」「同步资料」按钮不可用 | 表单有未保存的修改,或非本地来源还没保存凭据。先保存或放弃修改,补全凭据 |
| 连接测试未通过,提示检查平台权限、范围与应用凭据 | 核对范围字段和凭据。飞书缺权限时提示会列出要开通的权限名,并确认应用能打开该文档(加入知识空间,或成为文件夹的协作者)。多维表格开了高级权限时,应用要在可读角色里 |
| 提示暂时无法连接资料平台 | 检查应用授权和平台连接状态。内网地址未放行时,请部署管理员把地址加入 ECHOMIND_EGRESS_ALLOW;明文 HTTP 要列入 ECHOMIND_KNOWLEDGE_INSECURE_ORIGINS。自签名证书可通过 NODE_EXTRA_CA_CERTS 信任,需要部署管理员在 compose 覆盖配置里设置 |
| 提示来源配置已更新,或该来源正在同步 | 定时同步或另一个同步正在运行,稍后重新读取再操作 |
| 同步成功,但目录里没有资料,「可检索」显示「暂无可检索资料」 | 读取范围里没有受支持格式的文件,或范围填错。文档显示「暂无文本」时,看是不是图片、扫描件或旧版 Office 缺少 OCR 或 LibreOffice |
| 「部分完成」,说明里写不支持的内容 | 范围里有不支持的文档类型。同步仍会读取其余资料,但这一轮不会撤回来源里已消失文档的索引,处理后重新完整同步一次 |
| WeKnora 里刚改了文档,知汇里没变 | 知汇按文档的更新时间判断变化,只编辑分块不会更新这个时间。在 WeKnora 里触发重新解析,使文档的更新时间变化后再同步。也可以对这个来源开启「实时联合检索」 |
| WeKnora 的文档没有同步 | 只同步解析完成且启用的文档。解析中的下次再读,解析失败的会跳过,连接测试会提示解析失败的份数 |
| 检索不到旧版制度 | 默认只检索今天有效的现行文档。指定「生效日期」,或让 Agent 带上日期条件 |
| 新旧版本同时出现,或旧文件仍在现行 | 看「目录与检索」顶部有没有「待确认的废止」,在那里确认。识别错了的状态,在文档详情里手动修改 |
| 检索只有关键词的效果 | 在「知识库(知汇) › 调试 › 调试」运行自检,看「检索方式」和原因:没有为「知识向量化」单独指定模型,数据库没有 pgvector,或向量化还没覆盖足够多的文本块 |
| 标准答案变成「需复核」 | 它引用的文档有了新版本或被撤回。更新引用,重新审核 |
| 提示当前身份没有管理资料来源的权限 | 请联系控制台管理员授予来源管理权限 |
| Agent 读不到某份文件 | 在「接入中心 › 授权管理」核对该 Agent 的有效权限里有没有这份文件或它所在的文件夹,以及来源最近是否因为修改范围或凭据而撤回过索引 |
目前的边界
- 只读:对来源系统只读,不修改、不删除原文件,也不提供原件下载。控制台没有上传入口,也不能手工建知识库,资料都来自已登记的来源。索引是最近一次成功同步的快照,不是来源系统的实时内容。
- 来源范围:不支持 Confluence Cloud,也不接 Notion、Google Drive、SharePoint 这类境外 SaaS。企业微信文档、WPS 365、语雀和企业微信微盘也不在支持范围内。知汇只同步你指定的范围,不会发现企业的全部文库。
- 验证程度:九种来源里,WeKnora 只通过模拟接口测试,没有对真实实例验证,实时联合检索同样如此。其余八种用真实账号或服务验证过,但范围有限:WebDAV 只测了 Apache 的实现,Nextcloud、群晖和坚果云没有测;S3 兼容只测了 MinIO,AWS S3、阿里云 OSS 和腾讯云 COS 没有测,虚拟主机寻址只在模拟服务里测过;Confluence 只测了 9.2 版,Basic 认证、带上下文路径的站点和 HTTPS 站点没有在真实实例上测。选择 WeKnora 时表单会提示这一点,保存后请先做连接测试。
- 飞书表格:云盘里的文档、电子表格和多维表格(文本、单选、日期、数字、人员、复选框字段)实测过。知识库里的表格节点,多维表格的关联、查找引用、公式和附件字段还没有实测,遇到未知字段类型时整份读取失败,不会静默丢数据。
- 腾讯文档、钉钉:能否读到取决于应用开通、内容授权和平台套餐。腾讯文档的企业空间不在文件夹连接的范围内。钉钉只遍历配置的知识库或起始目录。
- OCR 与旧版 Office:OCR 默认关闭,默认镜像不带 Tesseract,真实识别质量没有评估过。旧版 Office 的转换在 14 份真实的公开文件上通过,带宏、加密或损坏的文件没测过,转换后只取文字。OFD 各厂商的真实样本没有验证。
- 检索:默认是关键词检索,向量化与混合检索要单独启用并指定模型。知汇不调用对话模型,不生成答案。
- 表格:没有框线的 PDF 表格和扫描件不抽取表格,已有文档要等文件变化后重新同步才会补抽。
- 生效版本:只有 S3 能映射自定义字段,其余来源靠规则识别,规则只认固定的几种写法。