基于DeepSeek Harness构建LLM Wiki：知识图谱与可溯源问答全解析

前两周一个朋友跟我抱怨：他们团队花了三周做了一个知识库问答系统，对话效果看起来还行，但真放到生产环境就露馅了——文档更新之后，系统还在用旧答案回答；问一个跨文档的问题，回答里只给出一个相似段落，说不清为什么是这段；最糟糕的是，当领导问“这个回答的依据是什么”，团队根本答不上来。

这个感受很典型。很多人以为，用大模型做知识库，就是把文档切碎、向量化、接一个问答接口。能回答问题的 demo 到处都是，能长期维护的知识系统却很少。

最近我在实际项目中完整跑了一遍基于 DeepSeek Harness 的 LLM Wiki 构建流程。这里说的 LLM Wiki，核心不在于界面，而在于一种知识组织方式：让大模型基于一套“可读、可更新、可追溯”的结构去管理文档和事实，同时人也能看懂、能审查、能修改。整个过程经过 10 轮提示迭代，把最初只能回答一句话的演示原型，逐步变成具备知识图谱、可溯源问答、增量编译和在线评估的完整系统。这篇文章就沿着这条路径，讲清楚每一轮在解决什么问题，以及落地过程中真正决定成败的细节。

1. LLM Wiki 的底层逻辑：不是把文档变成聊天记录

1.1 传统 RAG 在真实生产中遇到的四个问题

在展开 DeepSeek Harness 之前，有必要先讲清楚 LLM Wiki 与普通 RAG（检索增强生成）的差别。

常规做法是：文档切块 → 向量化 → 建立向量库 → 用户提问时先做相似度检索 → 把检索段落拼进提示词 → 生成回答。这个流程在 demo 阶段非常顺畅，但进入生产环境后，会遇到几个很现实的问题。

• 更新不可控。文档更新后，如果不重新向量化，回答还是旧的；如果全量向量化，成本和耗时又很高。时间一长，团队就懒得更新了。
• 溯源不完整。向量检索返回的是“相似段落”，但一个完整答案往往要综合多个文档的信息。系统只给出一段证据，说不出完整的推导链条。
• 关系无法表达。两份文档里都没有出现相同的关键词，但存在依赖关系、前后版本关系、项目归属关系。向量检索很难把这些跨文档关联找出来。
• 评估缺失。上线之后，没有人知道回答质量是在变好还是在变差。靠几个人抽样看几轮对话，很难有稳定结论。

LLM Wiki 的思路，是改变“文档作为整体被检索”的方式。它不是简单地把文本装进一个容器，而是在文档之上构建实体、连接、来源和版本。LLM 在做问答时，可以沿着这些结构走，而不只是做一次向量匹配。

1.2 DeepSeek Harness 在这套工作流里承担什么角色

DeepSeek Harness 的核心目标，是把知识库从“若干文档的堆叠”变成“可编译、可追踪、可评估的知识系统”。从项目自身的定位和实际使用场景看，这套工作流主要由四块能力构成：

1. 知识图谱：从文档中提取实体和关系，构建跨文档的关联网络。
2. 可溯源问答：每个回答都能追溯到原文片段、实体路径和更新时间。
3. 增量编译：只在内容变化时重新构建对应部分，而不是每次全量重建。
4. 在线评估：在真实使用中持续评估回答质量，让系统可以按数据驱动的方式迭代。

这四块能力不是相互独立的。它们更像一条流水线：增量编译决定系统能否长期跟上文档变化，知识图谱决定系统能否回答跨文档的复杂问题，可溯源问答决定输出是否可信，在线评估决定系统会不会悄悄退化。

提醒：如果只是给几十篇静态文档做一个小型问答机器人，DeepSeek Harness 可能是杀鸡用牛刀。它的价值，要到文档规模变大、更新频繁、且对准确性要求较高的场景，才会完全体现出来。

2. 10轮提示：从一个“会说话的原型”走到“工业级系统”

2.1 为什么用“轮”而不是“天”或“周”

LLM 应用的开发方式和传统软件开发有一个本质区别：传统开发以“功能是否完成”作为阶段节点，LLM 应用则以“一次提示质量是否达到目标”作为演化单元。每一轮提示迭代，不是简单改一版 prompt，而是一个完整闭环：提出问题、设定输入、执行、观察输出、分析失败、改进提示或流程、再次验证。

所以，这里的“10轮提示”不是指十次聊天，而是指十次“提示工程 + 流程编排 + 验证反馈”的开发循环。每一轮都有明确目标和可验证的产出。

2.2 前 3 轮：先打通最小闭环

很多人会低估这一阶段。实际上，10 轮里最容易被跳过、但最值得花时间的，就是前 3 轮。

第 1 轮：定义数据源与目录结构。不要一上来就写抽取实体、构建图谱的代码。先想清楚：文档从哪里来，是什么格式（Markdown、Word、PDF、HTML），放在哪个目录，文档之间有没有父子关系、版本关系。

以一个技术团队内部知识库为例，我会这样设计目录：

knowledge-base/ ├── architecture/ # 系统架构文档 ├── api/ # 接口文档 ├── incidents/ # 线上事故记录 ├── on-call/ # 值班手册 └── llm-wiki.json # 全局配置文件，描述目录和权限

目录本身就是给人和模型看的导航图。你希望模型优先理解哪些内容、文档优先级怎么排、哪些目录可以互相引用，都可以在目录结构中提前设计好。这一步看起来简单，却决定了后续所有检索和更新能力的起点。

第 2 轮：文档解析与分块。文档要被解析成可检索的块，并且每个块都要有稳定的标识，比如文件路径、锚点、版本。切块大小要取决于文档结构，按章节切、按段落切，而不是机械地按固定 token 数切。

为什么强调这一点？因为可溯源问答要求每一块能对应到原文的一个可理解片段。切得太碎，单个块丢失上下文；切得太整，检索精度下降。我通常会先用标题结构做第一层切分，再对过长的段落做二次切分。

第 3 轮：做最简问答。先用最简单的检索方式，比如关键词匹配或向量检索，把相关块取进来，拼进提示词，让模型生成回答。这一轮的目的不是效果好，而是让“文档 → 分块 → 检索 → 生成 → 回答”这条链路全部跑通。

前 3 轮的验证标准很简单：

• 一个人问 10 个预置问题，系统都能在 1 分钟内给出一个可读回答。
• 每一条回答都能追溯到具体文档和章节。
• 工程链路里没有任何断点。

2.3 中间 4 轮：把“相似搜索”升级为“知识检索”

第 4 轮：设计知识图谱 Schema。这是整个系统最关键、也是最容易翻车的环节。你需要先搞明白，这个 wiki 要回答什么类型的问题。如果是一个技术团队知识库，实体可能是：服务、接口、技术栈、模块、负责人、文档、版本。关系可能是“A 依赖 B”“A 是 B 的 API”“A 由 B 负责”。如果是研究笔记，实体又完全不同。设计 Schema 的核心原则是：以问答问题为导向，不要试图构建百科全书式的全量本体。

第 5 轮：实体抽取。让 LLM 从文档中抽取实体和关系。这一轮的坑有三个：提示词里没有给出 Schema 约束；没有做去重；把所有低置信度实体都放进了图谱。我一般会要求模型对每个三元组建一个置信度分数，低于阈值的只记录、不建图。

第 6 轮：图谱检索。在问答时，除了向量检索，还要把用户提问转成实体，沿图谱路径找到关联文档。这相当于给问答加了一张“关系网地图”，系统不仅能回答“这个文档说了什么”，还能回答“文档 A 和文档 B 之间有什么关系”这类问题。

第 7 轮：追问溯源。这一轮专门设计回答的输出格式。答案不仅要有正文，还要带上引用块：来源文件、章节路径、实体路径。可溯源问答的核心思想是：用户不要“一个答案”，而要知道“答案依据什么得出”。

2.4 最后 3 轮：编译、评估、迭代

第 8 轮：增量编译。

你要把知识库的构建从一个“批处理任务”升级成一个“增量可更新任务”。文档变了，只重建变化的部分；新文档加入，不触发全量重建。这是从演示系统走向生产系统最关键的一步。

第 9 轮：在线评估。

搭建一个评估体系，把真实用户问题记录下来，人工或自动打质量分。每次改动之后，用这批问题重新问一遍，对比新旧答案。没有这一步，后续所有优化都只能靠感觉。

第 10 轮：反馈闭环。

把低质量回答的数据当成下一次迭代的输入。分析是提示词问题、文档缺失、检索参数问题，还是图谱错误关系。这轮之后，系统进入可持续改进状态。

2.5 每一轮都要有验收标准

“花了一周做完”不是目标，“有验收标准”才说明你真的完成了一轮。我建议每轮记录三样东西：改了哪个提示或流程、观察到什么失败、验收结果是什么。这样 10 轮下来，你得到的不是一个碰巧能跑的系统，而是一套可复盘、可交接的演化日志。

3. 知识图谱层：从“相似段落搜索”升级为“证据链检索”

3.1 为什么纯向量检索不够

举一个具体例子。假设知识库里有三份文档：

• 文档 A 说：“用户服务依赖事件队列做异步消息解耦。”
• 文档 B 说：“事件队列的消费端在处理消息失败时会重试三次。”
• 文档 C 说：“重试可能导致订单服务在高峰期出现延迟。”

用户问：“为什么订单系统在高峰时可能变慢？”

纯向量检索很容易把 A、B、C 中与“订单”“延迟”“高峰”相似的段落找出来，但很难把它们组织成一条完整的因果链。如果知识图谱里存在“用户服务 → 依赖 → 事件队列”和“事件队列 → 影响 → 订单服务”这些边，模型就可以顺着图路径走过去，把三份文档串联成一段有逻辑推进的回答。

所以我始终强调“证据链检索”这个概念：目的不是找一个最像的段落，而是找一条能支撑结论的链条。

3.2 Schema 设计不要贪大

知识图谱失败的项目，一半以上是 Schema 设计过于宏大。如果定义一个 20 种实体、50 种关系的本体，模型抽取时必然充满错误。我更建议这样做：

• 从 3 到 5 种核心实体开始。比如：文档、概念、服务、负责人、版本。
• 关系类型控制在 8 到 10 种以内。超出这个范围，抽取质量会明显下降。
• 每个三元组务必带上来源文档 ID 和置信度。

一个可选的最小 Schema 如下表所示：

关系集合可以这样控制：

这个量级下，模型在稳定提示词中已经能抽取得比较干净。后面发现不够，再逐步增加。

3.3 建图过程中的三个高频坑

坑一：不设置信度。不设置信度，模型就会把猜测也写进图里。常见结果是知识库里出现大量弱关系，噪音极大。建议在提示词中明确：不确定的三元组不要输出，或者单独放在“低置信度候选表”里，不参与构建查询路径。

坑二：不去重。同一个实体在文档中往往有几种写法。“订单系统”“订单服务”“订单模块”可能指同一个东西。不做别名归并，图谱会变成一团散沙。至少要做一层名称归一化，最简单的做法是维护一个同义词表，或者让模型在抽取前先做一次实体对齐。

坑三：不做更新。文档更新后，旧文档中抽取的关系如果还在图里，会和新关系冲突。增量编译的一个关键子任务，就是让图谱和文档版本绑定。文档更新时，旧关系必须被标记“已过时”或直接删除。

提醒：图谱只是手段，不是目的。如果常识性问答用向量检索就能解决得很好，没有必要为了展示图谱而强行建图。知识图谱最值得投入的场景，是跨文档关联、因果链、依赖关系、版本追溯这类问题。

4. 增量编译：决定知识库能否长期使用的分水岭

4.1 为什么全量重建不可持续

全量重建知识库，在 demo 阶段没有任何问题。几篇文档，几分钟就处理完了。但真实项目里，文档可能有几百上千份，每次全量重建要几十分钟甚至几小时。而且全量重建会带来两个隐蔽问题：

第一，新版本和旧版本之间存在一个较长的空窗期。重建期间，用户访问的还是旧库，很容易出现“文档已经更新了，答案还是旧的”的情况。

第二，全量重建会重新生成所有索引、图谱、缓存，风险很高。一旦中途失败，可能导致整个系统处于不可用状态。

增量编译的思路来自软件工程：不重新编译没改过的模块。所以，你需要一层“变更检测”来判断哪些内容需要重新处理。

4.2 变更检测的三种做法

在常见实践里，变更检测通常有三种设计思路：

• 文件级哈希：定期扫描文件，计算哈希，和上一次的哈希比较。优点是逻辑简单、结果可靠；缺点是仍然要扫一遍所有文件。
• 文件元数据：用 mtime、文件大小做初步判断。速度快，但可能漏掉内容没变、mtime 被改的情况。
• 外部事件：如果文档来自 API、CMS 或者 Git 仓库，可以让上游在内容变化时主动发回调。这是最理想的方式，但依赖上游配合。

我自己的建议是：先用文件哈希，配合一个“源目录扫描”的定时任务。确认逻辑稳定之后，再考虑事件驱动。

4.3 增量编译的执行顺序：文本 → 图谱 → 索引

文档变化后，不是只重新向量化就结束了。正确的顺序是：

1. 检测出变更文档。
2. 重新解析文本，生成新的分块。
3. 对变更分块重新抽取实体和关系。
4. 在图谱中移除或标记旧版本产生的三元组。
5. 更新向量索引中对应的分块。
6. 更新引用映射和快照。

一个常见错误是只做了第 2 步和第 5 步，没有处理图谱。这样会导致图谱里出现“文档已经更新了，但旧关系还留在图上”的不一致状态。图谱是结构化数据，错误的传播比向量检索更隐蔽，也更难排查。

5. 可溯源问答：回答要能被审计，才真正可信

5.1 为什么生成式回答天然难以溯源

大模型的生成过程是一个概率解码过程，它会从多个文档片段中融合信息，最终生成通顺语句。问题在于：生成结果里有多少来自文档 A、多少来自文档 B、多少来自模型的预训练知识，模型自己并不记录。

如果只在提示词里写一句“请引用信息来源”，模型仍然可能生成与输入不一致的引用。原因不是模型不想遵守，而是没有机制保证引用和生成一一对应。

正确的做法，是从架构上把“生成”和“证据”绑定：先检索证据，再由模型在证据集内生成，最后把证据呈现给用户。

5.2 回答的结构化输出

可溯源问答的输出不应该是一段纯文本，而应该是一个结构化对象。一个比较实用的输出格式如下：

{ "answer": "订单服务在高峰期变慢，主要原因是事件队列消费端重试导致的消息堆积。", "evidence": [ { "source_file": "docs/architecture/event-queue.md", "source_version": "2024-11-03", "snippet": "消费端在处理消息失败时会重试三次，高峰期间可能造成队列积压", "path_in_graph": "订单服务 -> 依赖 -> 事件队列" }, { "source_file": "docs/incidents/2024-10-02-latency.md", "source_version": "2024-10-02", "snippet": "事件队列的积压最终导致订单确认接口延迟增大", "path_in_graph": "事件队列 -> 影响 -> 订单服务" } ], "confidence": "medium", "updated_at": "2024-11-05T10:23:00Z" }

这样，用户在界面上看到回答，同时可以用鼠标点开每个引用，看到原始段落、文件版本、图谱路径和更新时间。

要实现这个效果，前端展示层需要处理结构化数据。后端则要保证：模型只能在给定的证据集内做摘要和整合，证据集之外的信息，除非模型能明确识别，否则不写进 answer 中。

5.3 提示词中证据的使用方式

把证据塞进提示词时，不要把所有检索结果一股脑全放进去。证据过多，模型会在大信息量中迷失，反而容易编造。

我一般会先做两步：

1. 把证据按与问题的相关性排序。
2. 限制在 5 到 8 块以内。

如果核心证据很多，可以先用一个较小的模型生成“证据链摘要”，再把这个摘要和原文一起交给主模型。这样可以降低噪音，也更容易保持回答结构清晰。成本会有所上升，但可溯源问答的价值本身就需要这些投入来支撑。

6. 在线评估：没有固定尺子，就无法判断迭代方向

6.1 离线评估和在线评估缺一不可

离线评估指的是：准备一批固定的、人工标注好答案的问答题，每次系统改动后，用这批题跑一遍，记录分数。它的作用是防止改了一版提示词后，整体效果不升反降。

在线评估则针对真实用户提出的真实问题。真实问题往往和预置测试题的分布很不一样。很多团队只做离线评估，忽视了用户的实际提问方式，结果测试集分数很高，真实体验很差。

6.2 四个核心评估指标

实际项目中，我建议至少跟踪四个指标：

回答准确率。把回答和人工判断对比，按 0 到 3 分打分。这个指标最直接，但需要人工审查，成本较高，建议抽样评估。

溯源完整率。一条回答是否包含足够的证据链，可以分等级：

• 0 级：只给了答案，没有任何引用。
• 1 级：有引用，但只是单个相似段落，无法形成链条。
• 2 级：有多个引用，且引用之间能构成因果或依赖链。

新鲜度。回答引用的文档是否已过期。跟踪引用文档的最近更新时间和版本号，如果回答引用了旧版本而新版本已经存在，说明增量编译或检索排序有问题。

覆盖率。真实问题中有多少被系统成功回答，多少明确告知“没有找到相关信息”。一个可靠的知识库系统，应该知道什么时候说不知道，而不是强行生成。

6.3 评估结果如何反哺系统

评估分数下降时，要能定位是哪一层出了问题。按照下面这个方向排查：

• 如果回答准确率低，但溯源完整率高：问题可能在生成提示词，或模型对证据的理解。
• 如果溯源完整率低：问题大概率在检索部分，检索到的文档片段不够相关。
• 如果引用的是旧版本：问题在增量编译的触发机制。
• 如果回答准确，但用户反馈仍然不好：问题可能在表达方式、交互体验或覆盖范围。

在线评估不是上线以后才开始。在第 9 轮就把评估脚本搭好，第 10 轮以后，每次系统变更都跑一遍。

7. 实际落地时的常见卡点与排查思路

7.1 安装与启动阶段

从实际使用者的反馈看，DeepSeek Harness 的安装过程里，有几个出现频率较高的卡点，集中在 Node 和 pnpm 环节，比如在 pnpm dsh web 相关步骤停滞，以及下载速度过慢、本地部署时找不到入口等。

由于不同版本的安装步骤差异较大，这里不抄官方文档，只给通用排查建议：

• 先确认 Node.js 和包管理器版本符合项目要求。很多安装失败不是网络问题，而是 Node 版本太新或太旧。
• 如果长时间停在某个安装步骤，先检查网络是否可达、包源是否稳定，可以切换到镜像源重试。
• 桌面版和命令行版尽量分开理解。桌面版适合个人使用和快速体验；服务器部署更适合长期运行。插件用来扩展现有能力，不要在一开始就装一大堆插件。

7.2 使用阶段的几个高频问题

实际使用中，下面几个问题出现频率很高，但并不是复杂毛病。

对话归档在哪里。多轮问答通常会产生对话记录。如果找不到了，先检查配置里是否打开了持久化，以及数据目录是否指向了正确路径。这类问题，大概率是路径配置不一致造成的。

本地部署后怎么让别人访问。如果只是本机使用，默认监听回环地址就够了。如果要让同局域网的人访问，需要把服务绑定到局域网 IP，并确认防火墙放行。注意，不要随意暴露到公网，除非已经做好访问控制。

模型路径配置。当模型文件不在默认目录时，会遇到找不到模型的问题。排查思路是：先确认配置的路径是绝对路径还是相对路径，再看启动服务的用户有没有读取权限，最后看日志里报的是文件缺失还是权限拒绝。

7.3 一条完整的排查链路

无论遇到什么问题，建议按这个顺序排查，不要一开始就乱调配置：

1. 先看现象：是启动失败、运行卡顿、回答错误，还是结果为空。
2. 看输入：路径、文件名、格式、编码、上下文是否完整。
3. 看环境：系统版本、Node 版本、依赖版本、磁盘空间、权限。
4. 看配置：模型路径、数据目录、端口、日志级别、并发参数。
5. 看日志：这是最后一步，但也是信息量最大的一步。不要凭感觉改配置。
6. 看工具边界：是不是某个功能在当前版本还不支持，或者设计上就不支持你的使用场景。

很多用户卡在安装或运行阶段，往往不是代码本身有问题，而是参数配置或环境差异导致的。

8. 这个方案的适用边界：适合谁，不适合谁