118 lines
7.8 KiB
Markdown
118 lines
7.8 KiB
Markdown
# Wiki 数据流转与本地编码验收（2026-09-03）
|
||
|
||
## 结论
|
||
|
||
本地 BGE-M3 小批量编码已安装、配置并实际运行。已有 Wiki 的向量化、自动沉淀、
|
||
普通库文件导出、助手库异步导入、助手库文件导出、空普通库回流及两端向量检索已实测通过。
|
||
**技能自动生成 Wiki 尚未完成验收**：WeKnora 的两个生成模型都返回 HTTP 402
|
||
`Insufficient Balance`。不能把后半段通过等同于全链路通过。
|
||
|
||
本次修改运行在本地 DeerFlow 开发服务（前端 5175、后端 8001），连接用户提供的远端
|
||
WeKnora；没有把业务代码发布到服务器，没有提交 Git，也没有直接写 WeKnora 图数据库。
|
||
|
||
## 本地编码配置
|
||
|
||
- 实现：FastEmbed / ONNX Runtime CPU，官方 `BAAI/bge-m3` 权重。
|
||
- 配置名：`bge-embedding-m3`，1024 维，每批 2 条，2 个 CPU 推理线程。
|
||
- 运行依赖：FastEmbed 随标准后端依赖安装；模型必须提前放在离线目录中，仍按需加载，不影响主服务启动。
|
||
- 权重：约 2.3 GB，持久缓存 `C:\Users\ji\.cache\deerflow\embeddings`，不进入业务仓库。
|
||
- 配置：`llmwiki.local_wiki_index.embedding.provider: local`；可用
|
||
`local_model_path` 指定离线权重目录，详见后端 README。
|
||
- 查询向量在本地实时编码。已有 Wiki 在内容哈希、模型指纹匹配且向量非空时直接复用。
|
||
不同模型或维度不能混用；导入不静默重新编码。
|
||
- 原始文档分段向量与模型生成后的 Wiki 文本不同，不能相互冒用。本次新建的是 Wiki
|
||
正文的 BGE-M3 索引，不是把既有 512 维文档向量改名为 1024 维。
|
||
|
||
## 实际数据验收
|
||
|
||
来源是已有普通知识库“图片测试111”，没有改写其 Wiki 内容。
|
||
|
||
| 阶段 | Wiki | Wiki 向量 | 实体 | 引用关系 |
|
||
| --- | ---: | ---: | ---: | ---: |
|
||
| 普通知识库导出 | 19 | 101 | 19 | 108 |
|
||
| 助手知识库导入后导出 | 19 | 101 | 19 | 108 |
|
||
| 新建普通知识库回流后导出 | 19 | 101 | 19 | 108 |
|
||
| 知识梳理总库导出（7 个来源记录） | 19 | 101 | 19 | 108 |
|
||
|
||
逐项断言通过：
|
||
|
||
1. 三份包的 Wiki slug、标题、正文、摘要、页面类型、别名、分类路径、出链一致。
|
||
2. 101 条向量的原始 float32 字节、分段编号、维度和模型指纹完全一致。
|
||
3. 将导入前后实体 ID 映射回原 Wiki slug 后，108 条关系的端点及谓词集合完全一致。
|
||
4. 总库导出没有因多个来源重复同步而重复导出同一当前页面的分段向量。
|
||
5. 元数据回归测试另覆盖 tags、目录恢复、原始文档片段不计入 Wiki 数量、原生技能无
|
||
ownership 记录时可被选中、短 Wiki 不漏向量、模型指纹不兼容时不假装向量检索。
|
||
|
||
普通包约 1.01 MB，助手包约 0.79 MB，回流包约 0.83 MB。普通包还带 2 个原始文档及
|
||
108 个原始片段；助手导出提供 Wiki、Wiki 向量和关系，不重新上传原始文档触发二次生成。
|
||
|
||
### 检索
|
||
|
||
实际查询：“军方用什么工具评估极端天气带来的风险？”
|
||
|
||
- 回流普通库 `/api/llmwiki/search` 返回 `mode=vector`，首条“国防气候评估工具”。
|
||
- 助手库 `/api/assistant-knowledge/search` 返回 `retrieval_mode=vector`，首条同上；
|
||
首个命中分段余弦相似度约 0.6343。
|
||
- 浏览器实际提交总库检索，显示“向量检索 · 余弦相似度”和相同命中；不是只检查返回字段。
|
||
- 普通库采用已有页面级聚合评分，因此页面最终分数与单分段余弦值不必相等。
|
||
- 回流的向量写入 **DeerFlow 管理的本地 Wiki 索引**。未写入 WeKnora 原生向量数据库，
|
||
本次结论适用于本系统问答检索，不能声称原生 WeKnora 自身的检索也已完成该向量导入。
|
||
|
||
### 页面
|
||
|
||
普通与助手库复用同一 Wiki 阅读组件：目录树、类型/标签筛选、分类面包屑、别名标签、
|
||
正文内链、出链、反向链接及邻接关系视图。窄窗口可收起目录。
|
||
|
||
浏览器验证了“索引 → 国防气候评估工具”、展开关系视图、助手 Wiki 跳回普通库来源，
|
||
以及普通 Wiki 的“在知识梳理中查看”反向跳转。
|
||
|
||
### 验收数据位置
|
||
|
||
- 原有普通库：`48f669dc-433e-4aab-b5ea-897b6f7a3d2f`
|
||
- 知识梳理总库：`c3fd9841-0718-44dc-860e-aae3020fd485`
|
||
- 最终助手测试库：`489be905-08c8-40fe-8d60-42ac21dd945a`
|
||
- 最终普通回流测试库：`428162aa-03f6-4c61-8994-360f2f39e0c9`
|
||
|
||
新建测试库名称均以“Wiki链路验收-0903-1826”开头，保留用于复核；未删除用户已有库。
|
||
本地 `.runtime/wiki-live-result.json` 保存验收结果，`.runtime/wiki_live_acceptance.py`
|
||
保存本次验收流程，均为忽略的运行产物，不包含认证口令。
|
||
|
||
## 这次实际修复的问题
|
||
|
||
- 内置技能只有磁盘目录、没有归属记录时，被错误判定为不存在。
|
||
- 技能应上传去代码后的知识正文，让 WeKnora 生成 Wiki，而不是伪造一个 `skill` 类型页面。
|
||
- Wiki 生成等待使用实际 stats 接口；零页结果明确失败，不无期限等待。
|
||
- 向量化完成后自动导出沉淀到总库，并阻断导出回调重复触发全量同步。
|
||
- 短摘要和短正文同时存在时，旧分段阈值会将整页过滤为零向量。
|
||
- 分类路径必须先创建 WeKnora folder 并绑定 folder_id；只传 category_path 会被服务端清空。
|
||
- Wiki 的标签/分类/别名/原始引用保留；图节点绑定真实 Wiki，避免生成重复的空实体页面。
|
||
- 保留归一化 float32 原始字节；导入中不能用 `section_index or index`，因为合法编号 0 会被改写。
|
||
- 总库多个来源保留审计，但检索与导出只使用当前 Wiki 版本对应的向量，避免旧贡献污染检索。
|
||
- 包解析改为同盘临时 SQLite，上传先落盘再异步导入，导出完成后才提供文件下载。
|
||
|
||
## 阻塞与未通过的范围
|
||
|
||
1. 技能 `knowledge-base-ingest` 已送入专门创建的普通测试库，但远端
|
||
`deepseek-v4-flash` 和 `qwen3.6-flash` 均因余额不足失败。WeKnora 即使失败也可能把
|
||
文档 parse_status 标为 completed。需恢复可用生成模型后重新运行技能全链路验收。
|
||
2. 已采用磁盘暂存和有界批处理，但本次只有约 1 MB 实测，**未做数 GB 压测、断点续传、
|
||
进程中断恢复验收**。大包部署仍需磁盘容量、代理 body size 和超时配置。
|
||
3. 当前实体去重主要按类型及规范化名称；这次没有完成跨别名、歧义实体的模型对齐及
|
||
多来源事实冲突合并验收，不能视为这一历史需求已全面完成。
|
||
4. 重复上传仍会保留独立来源记录。向量导出已消除旧版本重复，但上传身份幂等、部分远端
|
||
写入失败后的无损重试、跨实例图片资源打包仍需独立验证。
|
||
5. 当前版本已补充自动增量链路：服务启动立即补扫，之后默认每 30 秒扫描全部普通
|
||
知识库；Wiki 抽取完成后无需手工点击向量化，并自动以来源快照覆盖同步到知识梳理总库。
|
||
6. 回流当前只允许新建空 Wiki 普通库，避免覆盖已有页面。普通库现有页面列表的超大规模
|
||
分页与助手问答的最终生成回答不属于这轮通过结论。
|
||
|
||
## 自动化检查
|
||
|
||
- 后端相关测试：118 passed（assistant repository、Wiki sync、package roundtrip、
|
||
WeKnora 接口、向量检索与知识库管理）。
|
||
- 修改的 Python 功能文件 Ruff 检查通过；app.py 既有启动顺序导致的 E402 不在此次改动中处理。
|
||
- `git diff --check` 通过（只有仓库换行提示）。
|
||
- 前端完整 `pnpm typecheck` 未通过：57 个既有/本轮范围外错误，涉及 nextra 缺失、Markdown
|
||
插件类型及其他模块；本轮新建/修改的 Wiki 组件、助手 API、技能面板没有出现在错误清单中。
|
||
浏览器实际页面与跳转已验证，但不能声称全项目构建通过。
|