前两周一个朋友跟我抱怨他们团队花了三周做了一个知识库问答系统对话效果看起来还行但真放到生产环境就露馅了——文档更新之后系统还在用旧答案回答问一个跨文档的问题回答里只给出一个相似段落说不清为什么是这段最糟糕的是当领导问“这个回答的依据是什么”团队根本答不上来。这个感受很典型。很多人以为用大模型做知识库就是把文档切碎、向量化、接一个问答接口。能回答问题的 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 的核心目标是把知识库从“若干文档的堆叠”变成“可编译、可追踪、可评估的知识系统”。从项目自身的定位和实际使用场景看这套工作流主要由四块能力构成知识图谱从文档中提取实体和关系构建跨文档的关联网络。可溯源问答每个回答都能追溯到原文片段、实体路径和更新时间。增量编译只在内容变化时重新构建对应部分而不是每次全量重建。在线评估在真实使用中持续评估回答质量让系统可以按数据驱动的方式迭代。这四块能力不是相互独立的。它们更像一条流水线增量编译决定系统能否长期跟上文档变化知识图谱决定系统能否回答跨文档的复杂问题可溯源问答决定输出是否可信在线评估决定系统会不会悄悄退化。提醒如果只是给几十篇静态文档做一个小型问答机器人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 如下表所示实体类型说明示例Document文档本体承载原始内容的根节点api-spec.md、incident-2024.mdConcept文档中出现的核心概念或术语事件队列、幂等、重试Service系统或服务实体订单服务、用户服务Person负责人或作者张三、李四关系集合可以这样控制关系说明示例service_depends_on服务依赖订单服务 - 依赖 - 事件队列document_describes文档描述api-spec.md - 描述 - 订单服务concept_related_to概念相关重试 - 相关 - 幂等person_responsible_for负责人张三 - 负责 - 用户服务version_supersedes版本取代v2.1 - 取代 - v2.0这个量级下模型在稳定提示词中已经能抽取得比较干净。后面发现不够再逐步增加。3.3 建图过程中的三个高频坑坑一不设置信度。不设置信度模型就会把猜测也写进图里。常见结果是知识库里出现大量弱关系噪音极大。建议在提示词中明确不确定的三元组不要输出或者单独放在“低置信度候选表”里不参与构建查询路径。坑二不去重。同一个实体在文档中往往有几种写法。“订单系统”“订单服务”“订单模块”可能指同一个东西。不做别名归并图谱会变成一团散沙。至少要做一层名称归一化最简单的做法是维护一个同义词表或者让模型在抽取前先做一次实体对齐。坑三不做更新。文档更新后旧文档中抽取的关系如果还在图里会和新关系冲突。增量编译的一个关键子任务就是让图谱和文档版本绑定。文档更新时旧关系必须被标记“已过时”或直接删除。提醒图谱只是手段不是目的。如果常识性问答用向量检索就能解决得很好没有必要为了展示图谱而强行建图。知识图谱最值得投入的场景是跨文档关联、因果链、依赖关系、版本追溯这类问题。4. 增量编译决定知识库能否长期使用的分水岭4.1 为什么全量重建不可持续全量重建知识库在 demo 阶段没有任何问题。几篇文档几分钟就处理完了。但真实项目里文档可能有几百上千份每次全量重建要几十分钟甚至几小时。而且全量重建会带来两个隐蔽问题第一新版本和旧版本之间存在一个较长的空窗期。重建期间用户访问的还是旧库很容易出现“文档已经更新了答案还是旧的”的情况。第二全量重建会重新生成所有索引、图谱、缓存风险很高。一旦中途失败可能导致整个系统处于不可用状态。增量编译的思路来自软件工程不重新编译没改过的模块。所以你需要一层“变更检测”来判断哪些内容需要重新处理。4.2 变更检测的三种做法在常见实践里变更检测通常有三种设计思路文件级哈希定期扫描文件计算哈希和上一次的哈希比较。优点是逻辑简单、结果可靠缺点是仍然要扫一遍所有文件。文件元数据用 mtime、文件大小做初步判断。速度快但可能漏掉内容没变、mtime 被改的情况。外部事件如果文档来自 API、CMS 或者 Git 仓库可以让上游在内容变化时主动发回调。这是最理想的方式但依赖上游配合。我自己的建议是先用文件哈希配合一个“源目录扫描”的定时任务。确认逻辑稳定之后再考虑事件驱动。4.3 增量编译的执行顺序文本 → 图谱 → 索引文档变化后不是只重新向量化就结束了。正确的顺序是检测出变更文档。重新解析文本生成新的分块。对变更分块重新抽取实体和关系。在图谱中移除或标记旧版本产生的三元组。更新向量索引中对应的分块。更新引用映射和快照。一个常见错误是只做了第 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 提示词中证据的使用方式把证据塞进提示词时不要把所有检索结果一股脑全放进去。证据过多模型会在大信息量中迷失反而容易编造。我一般会先做两步把证据按与问题的相关性排序。限制在 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 一条完整的排查链路无论遇到什么问题建议按这个顺序排查不要一开始就乱调配置先看现象是启动失败、运行卡顿、回答错误还是结果为空。看输入路径、文件名、格式、编码、上下文是否完整。看环境系统版本、Node 版本、依赖版本、磁盘空间、权限。看配置模型路径、数据目录、端口、日志级别、并发参数。看日志这是最后一步但也是信息量最大的一步。不要凭感觉改配置。看工具边界是不是某个功能在当前版本还不支持或者设计上就不支持你的使用场景。很多用户卡在安装或运行阶段往往不是代码本身有问题而是参数配置或环境差异导致的。8. 这个方案的适用边界适合谁不适合谁 基于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 的核心目标是把知识库从“若干文档的堆叠”变成“可编译、可追踪、可评估的知识系统”。从项目自身的定位和实际使用场景看这套工作流主要由四块能力构成知识图谱从文档中提取实体和关系构建跨文档的关联网络。可溯源问答每个回答都能追溯到原文片段、实体路径和更新时间。增量编译只在内容变化时重新构建对应部分而不是每次全量重建。在线评估在真实使用中持续评估回答质量让系统可以按数据驱动的方式迭代。这四块能力不是相互独立的。它们更像一条流水线增量编译决定系统能否长期跟上文档变化知识图谱决定系统能否回答跨文档的复杂问题可溯源问答决定输出是否可信在线评估决定系统会不会悄悄退化。提醒如果只是给几十篇静态文档做一个小型问答机器人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 如下表所示实体类型说明示例Document文档本体承载原始内容的根节点api-spec.md、incident-2024.mdConcept文档中出现的核心概念或术语事件队列、幂等、重试Service系统或服务实体订单服务、用户服务Person负责人或作者张三、李四关系集合可以这样控制关系说明示例service_depends_on服务依赖订单服务 - 依赖 - 事件队列document_describes文档描述api-spec.md - 描述 - 订单服务concept_related_to概念相关重试 - 相关 - 幂等person_responsible_for负责人张三 - 负责 - 用户服务version_supersedes版本取代v2.1 - 取代 - v2.0这个量级下模型在稳定提示词中已经能抽取得比较干净。后面发现不够再逐步增加。3.3 建图过程中的三个高频坑坑一不设置信度。不设置信度模型就会把猜测也写进图里。常见结果是知识库里出现大量弱关系噪音极大。建议在提示词中明确不确定的三元组不要输出或者单独放在“低置信度候选表”里不参与构建查询路径。坑二不去重。同一个实体在文档中往往有几种写法。“订单系统”“订单服务”“订单模块”可能指同一个东西。不做别名归并图谱会变成一团散沙。至少要做一层名称归一化最简单的做法是维护一个同义词表或者让模型在抽取前先做一次实体对齐。坑三不做更新。文档更新后旧文档中抽取的关系如果还在图里会和新关系冲突。增量编译的一个关键子任务就是让图谱和文档版本绑定。文档更新时旧关系必须被标记“已过时”或直接删除。提醒图谱只是手段不是目的。如果常识性问答用向量检索就能解决得很好没有必要为了展示图谱而强行建图。知识图谱最值得投入的场景是跨文档关联、因果链、依赖关系、版本追溯这类问题。4. 增量编译决定知识库能否长期使用的分水岭4.1 为什么全量重建不可持续全量重建知识库在 demo 阶段没有任何问题。几篇文档几分钟就处理完了。但真实项目里文档可能有几百上千份每次全量重建要几十分钟甚至几小时。而且全量重建会带来两个隐蔽问题第一新版本和旧版本之间存在一个较长的空窗期。重建期间用户访问的还是旧库很容易出现“文档已经更新了答案还是旧的”的情况。第二全量重建会重新生成所有索引、图谱、缓存风险很高。一旦中途失败可能导致整个系统处于不可用状态。增量编译的思路来自软件工程不重新编译没改过的模块。所以你需要一层“变更检测”来判断哪些内容需要重新处理。4.2 变更检测的三种做法在常见实践里变更检测通常有三种设计思路文件级哈希定期扫描文件计算哈希和上一次的哈希比较。优点是逻辑简单、结果可靠缺点是仍然要扫一遍所有文件。文件元数据用 mtime、文件大小做初步判断。速度快但可能漏掉内容没变、mtime 被改的情况。外部事件如果文档来自 API、CMS 或者 Git 仓库可以让上游在内容变化时主动发回调。这是最理想的方式但依赖上游配合。我自己的建议是先用文件哈希配合一个“源目录扫描”的定时任务。确认逻辑稳定之后再考虑事件驱动。4.3 增量编译的执行顺序文本 → 图谱 → 索引文档变化后不是只重新向量化就结束了。正确的顺序是检测出变更文档。重新解析文本生成新的分块。对变更分块重新抽取实体和关系。在图谱中移除或标记旧版本产生的三元组。更新向量索引中对应的分块。更新引用映射和快照。一个常见错误是只做了第 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 提示词中证据的使用方式把证据塞进提示词时不要把所有检索结果一股脑全放进去。证据过多模型会在大信息量中迷失反而容易编造。我一般会先做两步把证据按与问题的相关性排序。限制在 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 一条完整的排查链路无论遇到什么问题建议按这个顺序排查不要一开始就乱调配置先看现象是启动失败、运行卡顿、回答错误还是结果为空。看输入路径、文件名、格式、编码、上下文是否完整。看环境系统版本、Node 版本、依赖版本、磁盘空间、权限。看配置模型路径、数据目录、端口、日志级别、并发参数。看日志这是最后一步但也是信息量最大的一步。不要凭感觉改配置。看工具边界是不是某个功能在当前版本还不支持或者设计上就不支持你的使用场景。很多用户卡在安装或运行阶段往往不是代码本身有问题而是参数配置或环境差异导致的。8. 这个方案的适用边界适合谁不适合谁