私有知识库从 demo 到生产，中间差了 8 层工程

✍ Ando🕐 2026-07-08📦 21.3 KB 🟢 已读 𝕏 文章列表

文章探讨了私有知识库项目在实际落地中遇到的挑战。许多 Demo 看起来聪明，但在生产环境中常因检索链路混乱而答非所问。作者指出单纯升级模型无济于事，根本在于构建稳固的 RAG 底座。文章详细拆解了从数据源、解析、清洗、切分、Embedding 到索引、检索、生成及评估的 8 层最小可用架构，并阐述了 Agentic RAG 如何通过决策层优化检索策略。最后提供了从 0 到 1 的搭建步骤及技术选型建议，强调权限过滤、混合检索与持续评估的重要性。

RAG 私有知识库 Agentic 向量检索工程架构 LlamaIndex LangChain

# 私有知识库从 demo 到生产，中间差了 8 层工程 **作者**: Ando **日期**: 2026-07-03T15:45:46.000Z **来源**: [https://x.com/ando_w/status/2073070705789329561](https://x.com/ando_w/status/2073070705789329561) --- ![Image](/doc/2818/image/img_c9097fd6406a.jpg) # 这一篇要解决的问题这篇文章不先讲概念，先解决一个更现实的问题：为什么很多私有知识库demo 看起来很聪明，一到日常使用就开始答非所问、漏掉关键资料、引用来源混乱。看懂这个问题以后，再谈 Agentic RAG 才有意义。 # 正文 ## 一、很多 RAG 项目失败，不是因为模型不够强先看一个很常见的场景。团队把几十份制度文档、产品手册、会议纪要导进知识库，接上向量库，再套一个 Chat UI。演示时问“公司的报销标准是什么”，系统能答；问“某个 API 怎么鉴权”，也能从文档里找出一段。看起来事情已经成了。真正使用时，问题开始出现： - 用户问的是“新人出差住酒店能报多少”，文档里写的是“差旅住宿标准”。 - 用户问的是“上季度客户最关心什么”，答案需要跨 5 份会议纪要和 1 份产品路线图。 - 用户问的是“这个报错怎么处理”，正确线索藏在历史 issue、代码注释和接口文档的不同位置。 - 用户没有权限看财务附件，但检索阶段已经把相关 chunk 塞进了模型上下文。这时再换一个更强的模型，通常只能让错误答案写得更顺。问题的根源在检索链路、知识颗粒、权限过滤、评估和更新机制。Agentic RAG 可以帮忙，但它补不了一个混乱的知识库底座。企业和个人做私有知识库，目标其实很朴素： - 把散落在文档、网页、会议纪要、代码仓库、客服记录里的知识集中起来。 - 问问题时，让 AI 基于这些资料回答。 - 回答必须能追溯来源，不能凭空编。 - 知识更新后，系统要跟着更新。 - 不同人只能看自己有权限看的内容。普通聊天模型擅长基于已有参数回答。私有知识库里的资料可能是内部制度、项目文档、产品手册、客户案例、最新会议记录，这些内容通常不在模型训练数据里。RAG，也就是 Retrieval-Augmented Generation，做的事情是：先从你的知识库里找出相关材料，再把这些材料交给模型生成回答。一个基础 RAG 链路通常是这样： ``` 用户问题 -> 问题向量化 -> 向量库检索相似片段 -> 拼接上下文 -> 大模型生成答案 -> 返回答案和引用来源 ``` 这条链路能解决很多简单问答： - “公司的报销标准是什么？” - “这个 API 的鉴权方式在哪里写了？” - “合同模板里付款周期是怎么规定的？” 复杂问题会让基础 RAG 开始吃力： - “对比今年 3 月和 6 月的销售策略变化，哪些地方会影响渠道团队？” - “根据最近 5 次客户会议，整理客户真正关心的 3 个问题，并给产品团队建议。” - “这个报错在文档、历史 issue 和代码注释里分别怎么解释？” - “如果我现在要上线一个内部知识库，哪些文件应该进库，哪些不应该？” 这些问题需要拆解、判断、二次检索、跨来源对比，甚至调用工具。Agentic RAG 就是在这个位置出现的。 ## 二、Agentic RAG 多出来的是“决策层” 如果只记一句话：Agentic RAG 的核心变化，是让大模型参与检索策略的决策。基础 RAG 像一条固定流水线：每个问题都走同样流程，检索一次，生成一次。Agentic RAG 更像一个会工作的研究助理：它会先判断问题需不需要查资料，查哪个知识库，用什么关键词，查完是否足够，是否需要改写问题再查一次，最后再组织答案。可以把两者的差异放在一张表里： ![Image](/doc/2818/image/img_f25b230b9d8d.jpg) LangChain 的 LangGraph 文档里把 retrieval agent 的用途说得很直接：当你希望模型决定是否使用检索工具时，检索型 Agent 就有价值。LlamaIndex 的 RAG 文档则强调了从数据接入、索引到检索的完整链路。落地时可以选 LangGraph、LlamaIndex，也可以自己写轻量编排。框架不是第一原则，链路设计才是。 ## 三、私有知识库的最小可用架构先别急着上 Agent。我会先看一个更朴素的指标：用户问一个真实问题时，正确资料有没有进 top-k。如果 top-k 里根本没有答案，Agent 再努力也只是在错误材料里绕路。一个可靠的 Agentic RAG 系统，底座仍然是一个干净的 RAG 系统。最小架构可以拆成 8 层： ``` 1. 数据源 2. 文档解析 3. 清洗与切分 4. Embedding 5. 索引与存储 6. 检索与重排 7. 生成与引用 8. 评估与观测 ``` 1. 数据源：先定边界私有知识库的第一步不是写代码，而是定义“哪些知识应该被系统回答”。常见数据源包括： - PDF、Word、Markdown、HTML、飞书/Notion/Confluence 文档。 - FAQ、客服工单、CRM 记录。 - 产品说明、接口文档、数据库字典。 - 会议纪要、周报、项目复盘。 - 代码仓库里的 README、注释、设计文档。一开始建议选一个窄场景，例如“内部产品文档问答”或“销售资料知识库”。场景越窄，评估越清楚。把所有文件一次性塞进去，通常会得到一个看似宏大、实际很难调优的系统。 2. 文档解析：保留结构比提取文字更重要很多 RAG 项目的质量问题出在解析阶段。PDF 里有标题、表格、脚注、页眉页脚、图片说明；网页里有导航栏、广告、正文、代码块；Word 文档里有层级标题和表格。如果解析后只剩一坨纯文本，后面检索会很痛苦。解析时要尽量保留： - 标题层级。 - 段落边界。 - 表格结构。 - 图片或图表说明。 - 文档来源、更新时间、作者、权限标签。 - 原始链接或文件路径。这些信息以后会变成 metadata，用于过滤、排序和溯源。 3. 清洗与切分：chunk 是知识库的基本颗粒切分 chunk 的目标，是让每个片段都足够完整，又不要大到塞满上下文。常见策略有 4 种： - 固定长度切分：实现简单，适合早期原型。 - 按标题切分：适合文档结构清晰的资料。 - 语义切分：根据语义边界拆段，质量更高。 - 父子切分：小 chunk 用于检索，大段落或章节用于生成。推荐从“标题结构 + 适度重叠”开始。比如每个 chunk 500 到 1,000 个中文字，重叠 80 到 150 字。技术文档、制度文档、FAQ 的最佳大小会不同，后面通过评估集调整。每个 chunk 至少保存这些字段： ``` { "chunk_id": "doc_001_sec_003_chunk_002", "doc_id": "doc_001", "title": "报销标准", "text": "正文片段...", "source": "财务制度.pdf", "url": "https://...", "updated_at": "2026-07-03", "permission_group": "finance_all", "section_path": ["财务制度", "差旅报销", "住宿标准"] } ``` 4. Embedding：把文本变成可搜索的向量 Embedding 模型会把文本映射成向量，语义相近的文本在向量空间里距离更近。用户问题也会被转成向量，然后和知识库里的 chunk 做相似度搜索。选择 Embedding 模型时看 5 件事： - 中文效果。 - 长文本处理能力。 - 成本。 - 延迟。 - 是否允许你的数据发送到外部 API。如果知识库涉及敏感数据，可以优先考虑私有化部署的 Embedding 模型，或使用满足合规要求的云服务。无论选哪种，都要记录 embedding model 的版本。模型换了，旧向量通常需要重建。 5. 索引与存储：向量库不是唯一数据库向量库负责相似度检索，但私有知识库还需要保存原文、metadata、权限、导入记录、任务状态和评估日志。常见选择： - PostgreSQL + pgvector：适合团队已经使用 Postgres，希望把业务数据、权限、metadata 和向量放在一起。pgvector 支持在 Postgres 中做向量相似度搜索，并保留事务、备份、JOIN 等数据库能力。 - Qdrant、Milvus、Weaviate：适合向量检索规模更大、检索能力更复杂的场景。Qdrant 官方文档提供了 hybrid query、RRF、DBSF 等混合检索能力。 - Elasticsearch / OpenSearch + 向量能力：适合本来就有全文检索体系的团队。早期原型可以选 PostgreSQL + pgvector。它工程心智简单，权限和业务表也容易放在同一个系统里。数据量、并发、检索策略复杂后，再评估专门向量库。 6. 检索：只靠向量相似度不够向量检索擅长语义相近的问题，但它会遇到几类麻烦： - 精确词：产品型号、错误码、接口名、合同编号。 - 新词和内部黑话。 - 表格里的短字段。 - 用户问题很短，语义信息不足。 - 多个 chunk 都相似，但真正答案只在其中一个。所以私有知识库常用混合检索： ``` 向量检索 dense retrieval + 关键词检索 sparse / BM25 + metadata 过滤 + reranker 重排 -> 最终上下文 ``` 混合检索的好处是兼顾语义和精确匹配。比如用户问“ERRAUTH401 怎么处理”，关键词检索能抓住错误码，向量检索能抓住“鉴权失败”“token 过期”等近义表达。 7. 生成：回答要带证据生成阶段要给模型清楚的约束： - 只根据提供的上下文回答。 - 不知道就说不知道。 - 每个关键结论尽量标注来源。 - 多个来源冲突时说明冲突。 - 回答要区分事实、推断和建议。一个可用的回答结构可以是： ``` 结论：依据：操作步骤：相关来源：仍需确认： ``` 私有知识库的信任感来自“可检查”。答案写得漂亮没有用，用户需要知道它从哪里来。 ## 四、Agentic RAG 的工作流怎么设计有了基础 RAG 后，再加入 Agent 层。一个实用的 Agentic RAG 流程可以这样设计： ``` 用户问题 -> 意图判断 -> 是否需要检索 -> 选择知识源或工具 -> 查询改写 / 问题拆解 -> 一次或多次检索 -> 判断证据是否足够 -> 必要时补充检索 -> 生成答案 -> 引用与自检 ``` 1. 意图判断先判断用户问题属于哪一类： - 闲聊或通用解释：可以直接回答。 - 私有知识问答：需要检索。 - 对比分析：需要多次检索和综合。 - 操作任务：可能需要调用工具。 - 权限敏感问题：先检查身份和权限。 2. 工具选择 Agent 可以访问多个工具： - search_policy_docs：查制度文档。 - search_product_docs：查产品文档。 - search_meeting_notes：查会议纪要。 - search_code_docs：查代码说明。 - get_user_permission：检查用户权限。 - summarize_document：对长文档做摘要。问题来了以后，Agent 不必把所有库都查一遍。它可以根据问题选择最可能相关的工具。 3. 查询改写用户经常不会用文档里的原词提问。Agent 可以把问题改写成更适合检索的形式。例如用户问： ``` 新人出差住酒店能报多少？ ``` Agent 可以改写成： ``` 差旅报销住宿标准新员工酒店报销额度 ``` 也可以拆成两个查询： ``` 差旅报销住宿标准新员工报销政策是否特殊限制 ``` 4. 证据充足性判断检索回来以后，Agent 要判断材料是否足够回答。如果上下文只有“住宿费按城市级别执行”，但没有城市级别表，它应该继续查“城市级别”“住宿标准表”。如果查不到，就在回答里说缺少标准表，不能给出具体金额。 5. 多跳检索复杂问题常常需要先查 A，再根据 A 查 B。例如： ``` 本季度客户最关心的问题有没有被产品路线图覆盖？ ``` 合理步骤是： 1. 查本季度客户会议纪要，提取高频问题。 2. 查产品路线图，找到相关功能。 3. 对齐问题与功能。 4. 标出未覆盖的部分。基础 RAG 很难稳定完成这种链路，Agentic RAG 更适合。 ## 五、从 0 到 1 的搭建步骤下面是一条适合个人或小团队的落地路线。第一步：选一个窄场景建议从下面三种里选一个： - 内部制度问答。 - 产品文档问答。 - 项目资料问答。不要一开始做“公司全部知识库”。先做一个能评估的小系统。第二步：准备 30 到 100 个高质量文档文档数量不用多，质量要稳定。每个文档要有清晰来源和更新时间。整理一个文档清单： ![Image](/doc/2818/image/img_53a055a1508a.jpg) 第三步：做入库脚本入库脚本做 5 件事： 1. 读取文档。 2. 解析成结构化文本。 3. 清洗无效内容。 4. 切分 chunk。 5. 生成 embedding 并写入存储。最小数据表可以这样设计： ``` create table documents ( id text primary key, title text not null, source text not null, url text, updated_at timestamptz, permission_group text, raw_hash text ); create table chunks ( id text primary key, document_id text references documents(id), section_path text[], content text not null, metadata jsonb, embedding vector(1536) ); ``` vector(1536) 的维度要和你选择的 Embedding 模型一致。第四步：先做基础检索基础检索接口输入用户问题，返回 top-k 个 chunk。需要记录： - query。 - 命中的 chunk。 - 分数。 - 文档来源。 - 检索耗时。这一步先别急着生成答案。先人工看检索结果是否靠谱。如果检索已经找不到正确材料，后面生成再强也很难救。第五步：加生成层把检索结果拼成上下文，交给模型生成答案。prompt 可以这样写： ``` 你是一个企业私有知识库助手。请只根据给定资料回答用户问题。如果资料不足，请说明缺少什么信息。回答中必须列出引用来源。用户问题： {question} 资料： {contexts} ``` 输出格式建议固定： ``` 答案：依据：来源：补充说明： ``` 第六步：加入混合检索和重排当基础问答能跑通后，再加入： - BM25 或全文检索。 - metadata 过滤。 - reranker。 - chunk 去重。 - 来源多样性控制。不要一次加太多优化。每加一个模块，都要看评估集有没有变好。第七步：加入 Agent 编排 Agent 层可以先做 3 个能力： 1. 判断是否需要检索。 2. 把用户问题改写成 1 到 3 个检索查询。 3. 检索后判断是否需要补查。先限制 Agent 的自由度。工具越多，行为越难预测。早期可以只给它 2 到 3 个工具，并把最大检索轮数限制为 2。第八步：做评估集评估集是私有知识库长期可用的关键。准备 50 到 200 个真实问题，每个问题记录： - 标准答案。 - 正确来源文档。 - 允许的答案范围。 - 问题类型。 - 难度。评估分两层： - 检索评估：正确文档是否进入 top-k。 - 生成评估：答案是否正确、是否有引用、是否胡编、是否遗漏限制条件。上线前至少要知道：系统在哪些问题上表现好，在哪些问题上不可靠。 ## 六、权限、安全与更新机制私有知识库的“私有”不是口号，它会落实到工程细节。权限过滤权限过滤必须发生在检索阶段。用户没有权限看的 chunk，不应该进入候选上下文。常见做法： ``` 用户身份 -> 权限组 -> metadata filter -> 检索允许范围内的 chunk ``` 如果先检索全库，再让模型“不要回答没权限的内容”，风险会变高。模型看到的上下文越少，越容易控制。敏感信息处理入库前要识别敏感信息： - 身份证、手机号、邮箱。 - 客户名称、合同金额。 - 密钥、token、数据库连接串。 - 未公开财务数据。根据场景决定脱敏、排除或加密存储。增量更新文档会变化，所以入库系统要支持增量更新。可以为每个文档计算 hash： - hash 没变：跳过。 - hash 变化：重新解析、切分、生成 embedding。 - 文档删除：标记失效或删除对应 chunk。知识库还要保留版本。用户追问“这个答案依据哪版制度”时，系统应该能说清楚。 ## 七、一个推荐的技术选型如果你要快速搭一个可控版本，可以这样选： ![Image](/doc/2818/image/img_1edafacb0cb2.jpg) 这个组合的好处是：早期工程复杂度可控，后面也能逐步替换模块。如果你的文档规模很大、检索策略复杂，可以把向量存储换成 Qdrant、Milvus 或 Weaviate。如果你已经深度使用 Elasticsearch，也可以优先从现有全文检索体系扩展。 ## 八、上线前检查清单真正上线前，至少检查这些问题： - 用户问 100 个真实问题，正确来源进入 top-5 的比例是多少？ - 答案里有多少比例给出了可点击来源？ - 系统遇到资料不足时，会不会承认不知道？ - 权限过滤是否在检索前生效？ - 文档更新后多久能被检索到？ - 错误答案能否追踪到检索结果和 prompt？ - 成本是否可预测？ - 延迟是否能接受？ - 是否有敏感信息进入模型上下文？ - 是否有人工反馈入口？私有知识库最怕“演示时惊艳，日常使用时不可信”。上线前别只看模型回答得顺不顺，要看它有没有找对资料、有没有挡住权限、有没有记录错误、有没有在文档更新后跟着变。评估、权限、更新、观测这些工程能力，决定了它能不能从 demo 变成生产系统。 ## 九、常见坑坑 1：只优化生成，不看检索很多答案错误，根源是检索没找对。先看 top-k，再看回答。只要 top-k 里没有正确材料，漂亮的答案反而更危险。坑 2：chunk 太碎 chunk 太碎会丢上下文。用户问制度细节时，检索到了半句话，模型只能猜。坑 3：chunk 太大 chunk 太大会稀释相似度，也会浪费上下文窗口。大段文档里只有一小段相关，模型却要读很多噪音。坑 4：没有 metadata 没有来源、时间、权限、章节路径，后面很难过滤、排序、追溯。坑 5：Agent 太自由 Agent 可以提升复杂任务能力，也会带来不可控的成本和行为。早期要限制工具、轮数和输出格式。先让它稳定做 3 件事：判断是否检索、改写查询、决定要不要补查。坑 6：没有评估集没有评估集，优化就靠感觉。每次换模型、换切分策略、换检索参数，都不知道是变好了还是变差了。 ## 十、一条现实的迭代路线可以按 4 周推进：第 1 周：基础知识库 - 选定一个场景。 - 接入 30 到 100 个文档。 - 完成解析、切分、embedding、向量检索。 - 人工检查 top-k。第 2 周：基础问答 - 加入生成层。 - 输出答案和引用。 - 做 50 个问题的评估集。 - 调整 chunk 和检索参数。第 3 周：检索增强 - 加入关键词检索。 - 加入 metadata 过滤。 - 加入 reranker。 - 记录检索与生成日志。第 4 周：Agentic 能力 - 加入问题改写。 - 加入工具选择。 - 加入最多 2 轮补充检索。 - 加入回答前自检。这条路线的重点是每周都能验收一次。第 1 周验收检索，第 2 周验收回答，第 3 周验收检索增强，第 4 周再验收 Agent。这样系统每一步都站得住，不会把所有问题都留到最后一起爆。 ## 参考资料 - LangGraph：Build a custom RAG agent - LangChain：Build a RAG agent - LlamaIndex：Introduction to RAG - Qdrant：Hybrid Queries - pgvector GitHub README # 小结 1. 很多私有知识库失败，不是模型不会写答案，而是系统没找对资料。 2. Agentic RAG 多了一层检索决策能力，适合查询改写、多轮检索、工具选择和复杂综合任务。 3. 好的私有知识库先从窄场景开始，先把 top-k、引用、权限和更新跑稳。 4. 文档解析、chunk、metadata、权限过滤和评估集，决定系统能不能长期可用。 5. Agent 要逐步加入，并限制工具、轮数和输出格式。先让它可靠，再让它聪明。 # 下一篇预告下一篇会把这套架构落成一个最小可运行工程：用 FastAPI、PostgreSQL + pgvector 和一个简单 Chat 接口，完成文档入库、向量检索、基础问答和引用返回。 # 学习反馈你可以写： 1. 哪里看懂了？ 2. 哪里没看懂？ 3. 哪个地方想展开？ 4. 这个主题和你的真实问题有什么关系？请写在这行下面： ## 相关链接 - [Ando](https://x.com/ando_w) - [@ando_w](https://x.com/ando_w) - [843](https://x.com/ando_w/status/2073070705789329561/analytics) - [LangGraph：Build a custom RAG agent](https://docs.langchain.com/oss/python/langgraph/agentic-rag) - [LangChain：Build a RAG agent](https://docs.langchain.com/oss/python/langchain/rag) - [LlamaIndex：Introduction to RAG](https://developers.llamaindex.ai/python/framework/understanding/rag/) - [Qdrant：Hybrid Queries](https://qdrant.tech/documentation/search/hybrid-queries/) - [pgvector GitHub README](https://github.com/pgvector/pgvector) - [Upgrade to Premium](https://x.com/i/premium_sign_up) - [11:45 PM · Jul 3, 2026](https://x.com/ando_w/status/2073070705789329561) - [843 Views](https://x.com/ando_w/status/2073070705789329561/analytics) --- *导出时间: 2026/7/8 15:54:03*

🔗 相关文档