AI 文档助手知识库：先清理旧文档，再接检索

AI 文档助手知识库：先清理旧文档，再接检索

一、知识库质量决定回答质量

很多独立产品想做 AI 文档助手，第一步就是把所有文档丢进向量库。这样很快能上线一个聊天入口，但回答质量往往不稳定：旧文档和新文档冲突，接口说明过期，FAQ 重复，版本差异没有标注。

AI 文档助手不是把文档搬进向量库，而是先让知识库变干净。

二、先做文档盘点

flowchart TD A[现有文档] --> B[有效] A --> C[过期] A --> D[重复] A --> E[缺失] B --> F[入库]

盘点时要记录文档类型、适用版本、最后更新时间、负责人和是否允许被 AI 引用。过期文档最好先下线或标记，不要指望模型自动判断。

doc_inventory: title: "导入数据说明" product_version: ">=2.0" owner: "growth" status: active ai_indexable: true

知识库没有治理，检索再强也会引用错材料。

盘点的另一个关键是标注文档之间的引用关系。一篇 API 文档被五篇教程引用，那它过期的影响远超单篇独立文档。在盘点阶段建立引用图谱，后续文档更新时可以高亮受影响的其他文档，要求同步修订，而不是让用户在不同页面看到矛盾的说明。

三、切片要尊重任务

文档切片不能只按固定长度。安装步骤、错误排查、API 参数、价格说明、版本差异都适合不同粒度。切得太碎，答案缺上下文；切得太大，检索不准。

chunk_strategy: faq: question_answer_pair api_doc: endpoint_section troubleshooting: symptom_solution

每个切片要带元数据：标题、路径、版本、更新时间、产品模块。回答时才能展示来源。

切片的粒度定好后，还要设计更新触发机制。文档改了但切片不更新，用户就会拿到新旧混合的答案。常见的方案是给每篇文档维护一个 hash，变更时触发重新切片和 re-embedding：

async function syncDocToIndex(doc: DocInventory): Promise<SyncResult> { const currentHash = computeHash(doc.content) const storedHash = await kv.get(`doc_hash:${doc.id}`) if (currentHash === storedHash) { return { synced: false, reason: "内容未变化" } } // 删除旧切片，重新分片和 embedding await vectorDB.delete({ filter: { docId: doc.id } }) const chunks = chunkByStrategy(doc.content, doc.chunkStrategy) const embeddings = await embedBatch(chunks) await vectorDB.insert(chunks.map((c, i) => ({ ...c, embedding: embeddings[i], metadata: { docId: doc.id, version: doc.version, updatedAt: new Date().toISOString() }, }))) await kv.set(`doc_hash:${doc.id}`, currentHash) return { synced: true, chunks: chunks.length } }

实际部署里还有一个容易被忽略的细节：embedBatch调用有速率限制和成本。如果一次内容变更触发了全库重新 embedding，不仅消耗大，而且旧切片在清理完成前会和新切片共存，导致检索到重复信息。所以要按文档粒度逐个更新，而不是全量刷新。

四、回答要引用来源

AI 文档助手必须给来源链接。用户不是只要一个答案，还要知道答案来自哪一页，是否适用于当前版本。

type Answer = { text: string; sources: Array<{ title: string; url: string; version: string }>; };

如果检索不到可靠依据，助手应该承认不知道，并引导用户提交问题。强行编答案会伤害信任。

最后，文档助手要反向推动文档建设。用户反复问但检索不到的问题，就是文档缺口；回答点击率低的问题，可能说明文档写得不清楚。

还要设计召回评测集。挑选真实用户问题，人工标注应该命中的文档片段，每次切片策略、embedding 模型或排序规则变化后都跑一遍。没有评测集，文档助手调优只能靠感觉。

retrieval_eval: queries: real_user_questions expected_sources: manually_labeled metrics: - hit_at_3 - answer_grounded_rate

回答生成也要有边界。涉及价格、隐私、删除数据、计费和安全配置时，助手应该引用官方文档并提醒用户确认当前版本，不能用“通常来说”糊过去。

最后，知识库更新要有延迟监控。文档改了多久能被检索到，旧切片多久清理，索引失败有没有告警，这些都是文档助手可靠性的组成部分。

还要给答案做人工抽检。每周抽取高频问题、低置信问题和用户点踩问题，检查是否引用正确来源、是否回答过度、是否遗漏版本限制。抽检结果要回写到切片和提示词策略里。

answer_review: sample_high_traffic: true sample_low_confidence: true sample_negative_feedback: true update_docs_when_needed: true

如果产品支持多语言，知识库还要处理语言回退。中文问题是否只能检索中文文档，英文文档是否能被翻译引用，都要提前定义。

五、总结

AI 文档助手要先清理旧文档、标注版本、按任务切片、保留来源，并把用户问题反哺文档建设。

先清理旧文档，再接检索。知识库干净，助手才可靠。