企业官网建设流程全解析

别人跑通一个 RAG Demo 只需要半天，我见过不少同学在本地 demo 里把文档一切、一向量化，检索问答跑得有模有样，觉得“RAG 不过如此”。结果一上真实知识库，就开始翻车：检索结果牛头不对马嘴，回答经常引用到完全不相关的文档，想按时间或部门筛一下还筛不出来。

这个系列写到 Day 10，正好到了“从 Demo 到工程化”这段最容易糊弄、也最容易被忽视的路。我常说一句话：RAG 的上限不是模型，而是你在入口处怎么建模。具体来说，就是三个关键词——Document 怎么设计、Chunk 怎么切、Metadata Filter 怎么用。这篇文章就围绕这三件事，把我自己从那些“能跑但不好用”的 Rag 系统里踩出来的经验，一次讲透。

1. RAG Demo 与工程化的真实差距

1.1 Demo 能跑和能上线是两码事

先泼一盆冷水：本地 demo 里用的是精挑细选的几篇 PDF，格式规整、内容独立、问题也都是自己设好的。工程化环境里是公司攒了几年的全部文档：有 Markdown、有扫描件、有导出的 HTML、有一半内容是重复表格的周报。这时候“切一切、向量化、查一查”这套流程，每个环节都会出问题。

我给你一个更好理解的类比。检索增强生成整个过程，很像是在一个图书馆里做参考咨询：用户问一句，你要去书架里找到最相关的那一页，然后把这一页连同上下文一起拿给答复者。Demo 阶段相当于图书馆只有十本书，你闭着眼都能摸到；工程化阶段是几万册书、不同分类、不同版本、不同权限，你不仅要知道书放哪，还得能回答“哪一版才是最新的”“这个内容属于哪个部门能看不能看”。

所以工程化的 RAG，其实不是在“做检索”，而是在“管理知识”。而知识的入口，就是我们传给索引系统的那个Document对象。

1.2 工程化之后才会暴露的问题清单

很多东西是上了线才暴露出来的，我先列个清单，你看是不是已经踩到过其中几个：

• 检索 top-5 的结果里，只有一两条和问题相关，剩下的都是“似像非像”的干扰项。
• 同一篇文档被重复导入，向量库里出现大量重复 chunk，回答时同样内容被反复引用。
• 文档更新后旧版本没有清理，用户问的是新问题，检索到的却是三个月前的旧资料。
• 想限定“只看某个项目、某段时间”的文档，向量检索做不到这种条件约束。
• 结果里混入了权限外内容，回答直接泄露不该出现的信息。

这些问题，最后都会指向三个根源：Document 的建模太粗、Chunk 的切分太糙、Metadata Filter 的缺失。想不明白这三件事，你后面加什么模型、换什么向量库都治标不治本。

2. Document 设计——不只是把文本塞进向量库

2.1 Document 对象到底应该长什么样

很多 demo 里，Document 就是一个字符串：直接把文件读进来，.split("\n")或者按固定长度切开，就丢给 embedding 模型。这样当然能跑通，但它丢掉了所有可以用来做约束、做追溯、做更新的信息。

工程化之后，文档应该是一个完整的数据结构：

class Document: def __init__(self, doc_id: str, content: str, metadata: dict): self.doc_id = doc_id # 文档级唯一 ID self.content = content # 清洗后的正文内容 self.metadata = metadata # 元数据字典 doc = Document( doc_id="internal-manual-001", content="这是清洗后的正文……", metadata={ "source": "内部运维手册_v3.pdf", "title": "故障恢复流程", "author": "平台组", "date": "2025-06-01", "category": "运维", "version": "3.2", "permissions": "admin", "content_hash": "7d8f3a..." } )

这里每个字段都有它的用处：doc_id是用来做更新和删除的锚点；content直接影响向量化效果，原文里那些页眉页脚、重复的导航栏文字、乱码符号，都应该提前清洗掉；metadata则是后续做过滤、权限控制和结果归因的“后门”。

我建议你把 metadata 理解成 Document 的“索引卡片”。正文是书的内容，卡片记录的是这本书放哪个架、谁写的、什么时候更新、归哪个分类。检索的时候，你不能永远靠全文语义去找，很多场景先用卡片把范围缩到一个小区域，再去正文里找，效率和质量都会高一个量级。

2.2 元数据字段的设计规范

到底要放哪些元数据？我自己的经验是：宁多勿缺，因为后面补字段是一件非常痛苦的事——已经入库的几十万 chunk，要全部重新打标、重新索引。下面是一套我常用的字段模板：

设计这些字段的时候，一定要问自己一句：将来用户可能会按什么条件筛选？如果业务上有人会问“只看售后部门的知识”，那category或department字段就必须有；如果有人要“只查 2025 年之后的”，那date字段必须在导出时统一格式化，不能一天一个写法。

2.3 文档更新与去重

文档更新是工程化里最容易被忽略的事。本地 demo 建好库就完事了，生产环境里文档天天在变：手册改版、流程更新、旧文档下线。你没有做更新的机制，系统就会一直回答旧内容。

我的做法是：入库时先把同一个doc_id下的所有 chunk 全部删除，再把新文档分块写入。这能保证同一个文档永远只有一个有效版本。同时用content_hash做去重，同一文档如果内容没变，直接跳过，避免多次导入造成重复。

这里有一个我踩过的坑：一开始为了省事，只按doc_id去删，结果有些文档被复制到不同路径，产生不同doc_id，内容却一模一样。后来加上content_hash才把这种冗余堵住。所以别嫌麻烦，去重这一步做不好，检索结果的质量会肉眼可见地下滑。

3. Chunk 分块策略——决定 RAG 上限的隐形变量

3.1 分块为什么是隐形变量

很多人觉得分块就是“按字符数切一刀”，但分块这个动作，实际上决定了两个东西：一是向量化时的语义颗粒度，二是检索后能带给大模型的上下文量。

如果切得太小，一句话可能只剩半句，语义不完整，embedding 表示就不准确；如果切得太大，整个向量的语义被稀释成一锅粥，检索时什么都能沾上边，大模型的输入长度也被白白浪费。分块粒度的大小，直接决定“召回准不准”和“生成够不够”的平衡点。

做菜备料的类比永远好用：菜切太碎了，口感没了；切太大块，炒不入味。RAG 也一样，分块要配合下游大模型的上下文长度，以及回答一个问题通常需要多少背景信息来决定。

3.2 常见分块方式及适用场景

我没有一套“万能分块法”，但可以把手头试过的几种方式放在一起比较：

前两种适合做批量导入的“保底方案”，后两种更适合做有结构化内容的文档库。实际项目里，我几乎不会只用一种方式，而是先按结构切一层，再按长度做二次校验。

3.3 chunk_size 与 chunk_overlap 的调节逻辑

分块参数里，最常调的就是chunk_size和chunk_overlap。我一般把chunk_size初始值设在 800 到 1200 字符，chunk_overlap设在 100 到 200 字符。overlap的作用是保证切分边界处的内容不会因为“腰斩”而丢失关键上下文。

举个例子，某团队在做内部知识库时，所有文档按固定 500 字符硬切，结果技术文档里一段完整的 SQL 经常被从中间切断，检索时经常只有一半的 SQL 片段，回答当然也是错的。后来改成按 Markdown 的标题层级切：先用一级标题分到章节，再对特别长的二级、三级章节按段落做二次切分，命中率一下子就上来了。

但这里没有银弹，参数必须靠评测去验证。我给的初始值只是起点，真正要做的，是准备一批“问题 → 期望命中的文档”的评测数据，然后不断调参，让检索命中率说话。一切不基于评测的参数调整，都是玄学。

4. Metadata Filter——从语义搜索到精准筛料的升级

4.1 工程化之后为什么必须做过滤

纯向量检索的核心是“语义相似度”，它擅长回答“意思相近的内容”，但不擅长回答“限定条件下的内容”。比如用户问“上季度的故障复盘”，数据库里包含历史所有季度的故障文档，向量检索很可能把去年的结果也捞出来，因为语义上都相关。这时候你就需要 Metadata Filter 出场了。

元数据过滤的本质是：把“条件筛选”交给数据库层面处理，让语义检索只负责语义匹配，两者各司其职。类比来说，向量检索是给你在全校范围里找“有某句话的书”，元数据过滤是把范围先缩小到“三楼的计算机分类书架、2024 年以后入馆”的书籍上。没有这一步，检索结果里会混入大量“语义沾边但条件不符”的噪声。

更现实的问题是：不用元数据过滤，就得让大模型在生成前二次筛选检索结果，成本高、延迟高，而且结果不稳定。生产系统根本经不起这种消耗。

4.2 过滤机制的核心逻辑：预过滤与后过滤

Metadata Filter 的实现上有两条路线，原理完全不同，踩坑点也不同。

预过滤（pre-filter）是先按元数据条件把候选集缩小，再做向量检索。它的优点是检索结果天然干净，相关度高；缺点是如果筛选条件太严，候选池太小，可能漏掉一些相关性很高但元数据不够精确的结果。

后过滤（post-filter）是先按向量相似度取 top-K，再对结果集做元数据筛选。它的优点是召回阶段比较宽松，不容易漏；缺点是浪费了大量算力，而且如果 K 值不够大，过滤完可能没剩几条结果。

我个人的建议是：工程首选预过滤，但要给候选池留够余量。比如你要 10 条结果，可以把候选放宽到 200 条再过滤，这样既能保证质量，也不会漏太多。下面是一段我常用的查询逻辑示意：

# 预过滤：先按条件缩小候选集，再做向量检索 candidates = collection.query( query_embeddings=query_vector, where={ "category": "售后", "date": {"$gte": "2024-01-01"} }, n_candidates=200, n_results=10 ) # 返回结果前再校验一遍 metadata，防止脏数据混入 validated = [r for r in candidates if r.metadata["category"] == "售后"]

这里有个细节：写where条件时，日期字段的格式必须统一，比如全都存成2025-06-01，不然字符串比较会出错。嵌套字段的过滤大多数数据库也支持，但会增加一层复杂性，能扁平的字段尽量扁平。

4.3 落地时的元数据过滤实践

拿一个比较典型的场景来说：客服知识库。团队最开始没有做过滤，用户问“退款政策”，检索结果里既有售前的促销说明，也有售后的退款流程，还有内部运营的培训资料，全部混在一起。回答的质量完全靠大模型在文本里硬找。

加了category字段后，用户的问题先被判定为售后场景，检索时预过滤条件直接带上category == "售后"，检索结果干净了很多。后来业务方又要做时间维度，我们又加了date字段，实现“只看 2024 年之后的政策”。这一步看着简单，但对回答准确率的提升非常明显。

还有权限场景：某些文档只有特定角色能看，那permissions字段就必须在检索阶段作为过滤条件之一，而不是等检索完再人工筛。这个话题如果再展开，就是各行各业的权限模型怎么和 RAG 结合了，但原理都一样：元数据是权限系统的地基，越早设计越好。

5. 从 Demo 到工程化的关键一跳

5.1 没有评测就没有优化

做工程化最容易陷入“拼命堆功能”的误区，今天加个 rerank，明天换个 embedding 模型，效果却说不清是变好还是变坏。我花了很多时间才意识到：不管怎么优化，第一步都应该是建立评估基准。

准备几十到几百条“问题 → 期望命中文档 ID”的评测数据，把检索流程跑一遍，统计命中率，尤其是“命中是否在 top-5 内”。这个数据会告诉你，当前系统的真实水平在哪里，也让你每次改动都有了对照。

def evaluate(queries, expected_doc_ids, top_k=10): hit_at_5 = 0 hit_at_10 = 0 for q, eid in zip(queries, expected_doc_ids): results = retrieve(q, top_k=top_k) doc_ids = [r.doc_id for r in results] if eid in doc_ids[:5]: hit_at_5 += 1 if eid in doc_ids: hit_at_10 += 1 return hit_at_5 / len(queries), hit_at_10 / len(queries)

我见过一个团队，把 docs 从 500 字符切到 1000 字符，召回率反而掉了 5 个百分点，因为切分粒度变大后，同一个 chunk 里混合了两个主题，向量表达变得模糊。这种问题，不靠评测根本发现不了。

5.2 索引与检索的全链路设计

工程化的 RAG 流程，说到底是一条完整流水线，每一个环节都有明确的责任边界。入库链路我一般是这样设计的：

清洗解析 → 结构识别 → 分块切分 → 元数据附加 → 向量化 → 写入向量库

查询链路则是另一条线：

查询理解 → 向量化 → 元数据过滤 → 向量召回 → 重排（可选） → 组装上下文 → 交给大模型

写到最后这段流程，我想特别强调一点：RAG 不是“embedding + 向量检索”这么简单。前面那些环节里的清洗、分块、元数据设计，占掉了工程化 80% 的工作量，但也是最容易被忽略的部分。你去看很多翻车的 RAG 系统，问题几乎都不在模型上，而是在入口处就已经烂了。

5.3 我的实操体会

说实话，我早期也走过弯路：第一次做知识库，直接拿整本手册开刀，几千字符的 PDF 段落不做任何切分就塞进向量库，检索时每个 chunk 都是一大段，回答时上下文窗口根本放不下，效果惨不忍睹。还有一次忘了在导入时写date字段，后面业务方要按时间过滤，我不得不写脚本全量重灌。

现在我的固定习惯是：先小批量跑通全流程，用 20 篇文档把 Document 结构、Chunk 方式、Metadata 字段全部定好，再评估一轮，之后才放量导入。任何参数调整都先跑评测，不让“感觉好像变好了”骗自己。最后分享一个特别实用的排查技巧：检索结果不对的时候，先把命中的 chunk 原样打出来看一遍。大部分问题一眼就能看出来——要么是切分切在了半句话上，要么是 metadata 没写对，要么是过滤条件拼错了。RAG 调优并不玄学，找到病根永远比调一堆参数更重要。