企业官网建设流程全解析

大模型项目的落地永远绕不开一个问题：怎么让它“懂”你自己的私有知识。去年我们团队接过一个企业知识库问答的活儿，试过直接拿通用大模型硬上，文档内容一问就编，引用出处全靠猜，根本没法交付。折腾了两周，最后换成了检索增强生成（Retrieval-Augmented Generation, RAG）路线，把企业内部的制度文档、技术手册、历史工单全部接进去，效果立竿见影。而这个过程中，我们内部从零攒起来的一套顺手框架，开源之后就取名叫OpenRig。

OpenRig不是那种上来就给你几十个模块的重型平台，它更像一套“开箱即用但留有改装余地”的乐高积木：文档解析、文本切分、向量化、混合检索、重排序、答案生成，全链路都能独立替换。适合刚接触RAG的开发者快速跑通验证，也适合已经在做知识库问答、需要对各环节精细调参的算法工程师。这篇文章我就用OpenRig作为主线，把RAG落地时的整体设计、核心模块、实操细节和踩坑记录完整拆一遍。

1. 项目到底解决什么问题：先弄清RAG的核心价值

1.1 为什么是检索增强而不是微调

很多第一次接触RAG的朋友都会问：既然大模型不懂我公司的业务，那直接微调一个专属模型不就行了？这个问题的答案其实决定了整个项目的大方向。

微调的本质是把新知识“焊死”进模型参数里，成本高、周期长，而且每次知识更新都要重新训练。更关键的是，微调最容易犯的毛病是“背下来了但不会用”：你给模型喂了一批文档，模型记住了大概内容，但当你问“2024年报销标准中住宿费上限是多少”这种需要精确数值的问题，它还是有可能把年份数字张冠李戴。检索增强的思路完全不同——模型不用强记任何业务细节，它只负责“读资料”和“组织答案”。

OpenRig在设计上坚定走RAG路线，还多考虑了一层：企业知识库的内容是持续变化的，今天刚出一份新制度，明天就废掉一版旧流程。检索增强方案里，新文档只需入库索引，旧文档立刻下架，模型本身不用动。这在微调方案里是不可想象的——动一次参数就可能影响全量能力。

1.2 OpenRig的整体架构思路

OpenRig的架构可以用一句话概括：把检索增强生成的完整链路拆成五个可插拔的阶段。

• 文档接入层：负责加载不同格式的源文件，支持PDF、Word、Markdown、HTML、纯文本，也能直接对接数据库导出的CSV。
• 索引构建层：对文档内容做清洗、分段、向量化，最终为每一段文本生成一个语义向量，写入向量库。
• 检索层：针对用户问题做召回，同时支持向量相似度检索和关键词检索，两种结果做融合，保证既懂语义又不丢关键词。
• 重排序层：对召回的候选段落做精细打分，把最相关的几条挑出来送给大模型。
• 生成层：把用户问题、检索到的段落、系统提示词组合成Prompt，调用大模型生成最终答案。

这五层之间通过统一的数据结构衔接，每一层都能独立替换。什么意思呢？比如说你不想用默认的Embedding模型，OpenRig只要求你实现一个encode方法，返回一个浮点向量列表就行。今天我们默认用开源的BAAI/bge-large-zh-v1.5做中文向量化，明天如果出了更好的模型，改一行注册即可，后面的检索和生成逻辑完全不用动。

这种分层思路最大的好处是降低了试错成本。RAG的效果受每个环节影响，如果所有环节耦合死，出了问题根本不知道在哪一层。拆开之后，你就可以单独验证每一层的输出质量：文档解析完有没有内容丢失？切分出来的段落语义是否完整？检索召回的Top5是不是真的相关？每一步都有独立的评测手段，问题自然能快速定位。

2. 核心模块拆解：从文档解析到答案生成的完整链路

2.1 文档解析与清洗：垃圾进，垃圾出

很多RAG项目死掉的第一个地方不是向量检索，而是文档解析。我曾经处理过一批政府公开的政策文件，PDF文件里大量内容是扫描图片加文字图层，常规的PDF解析库抽出来的文字顺序错乱，表格干脆变成了一堆散落的数字。用这种脏数据建索引，后面的工作全白费。

OpenRig把文档清洗作为一个独立的强处理模块。默认策略里有几条值得借鉴：

• 页眉页脚剔除：做文件处理的多，真正的页眉页脚会在每页重复出现，如果不清理，索引库里会有大量重复语义块，检索时严重干扰打分。
• 表格结构化：文本抽取时，只要检测到表格结构，就转为Markdown表格语法后单独保存。原因是纯粹抽出裸文本，行与列的对应关系就丢失了，而大模型其实擅长阅读Markdown格式的表格，保留结构能明显提升问答效果。
• 乱码检测与过滤：解析PDF时偶尔会出现方块字符或异常符号，OpenRig会用字符覆盖率做一个简单判定，低于阈值的段落直接标记为待人工复核，而不是硬着头皮进入索引。

一个务实建议是：无论解析器号称多智能，入库之前一定要抽样人工检查。我习惯的做法是每个批次文档随机抽3%打印出解析后的纯文本，大致扫一眼有没有乱码、有没有内容缺失。这一步花10分钟，能省下后面调检索效果的一天时间。

2.2 文本切分策略：chunk_size和overlap怎么定

文档解析出来是一整篇长文，直接整体向量化是不可能的。你需要先把文本切成一个个段落块，每个块独立向量化并入库。切多长合适，这是个真问题。

OpenRig默认支持两种切分模式：固定长度切分和语义切分。固定长度切分实现简单，按字符数硬切，比如每500个字符一块，块与块之间保持50个字符的重叠。语义切分更聪明一点，它先按段落标记拆成小段，再用相邻小段的向量相似度做聚合，语义相近的合并成一个大块，遇到主题跳变就切开。

参数怎么选？根据我的实测经验，中文场景下chunk_size在300到800个字符之间是比较合理的区间。块太小，单块包含的上下文信息太少，检索时关键词匹配准确但对问题的完整理解不足；块太大，Embedding模型的平均向量会“稀释”关键语义，检索精度明显下降。这里有一个可以量化的参考思路：假设一段常规制度条款是200到400字，那chunk_size设500，一段话刚好能完整落入一个块；如果设成1000，一段话可能要跟相邻内容共享一个向量，精确匹配时会产生干扰。

overlap的作用是避免切分把一句完整的话拦腰斩断。我建议overlap设为chunk_size的10%到20%。比如500字符的块，overlap设50到100字符，既能保留边界上下文，又不至于让索引库膨胀太多。

2.3 Embedding模型选型与向量索引参数

Embedding是RAG检索能力的基石。OpenRig的默认配置用BAAI/bge-large-zh-v1.5，这个模型在中文语义匹配上的表现比较均衡，而且对长文本支持到512个token，足够处理上面的chunk。如果你手头有充足的显卡显存，可以换用bge-m3，它是多语言模型，还支持稀疏向量和稠密向量的混合检索，效果更精准，但显存占用也会涨一大截。

这里插一个冷知识：Embedding模型不是越大越好。对大多数知识库场景来说，一个参数量在1亿到3亿之间的中文模型已经完全够用，再大的模型投入产出比很低，反倒会拖慢索引构建速度。关键是向量维度要和向量库匹配，bge-large-zh-v1.5的向量维度是1024，开箱即用。

向量索引我用的是HNSW（Hierarchical Navigable Small World）算法。它的核心思路是先构建一张多层图，检索时从顶层粗筛、逐层细化到底层精确查找，在百万级向量规模下都能保持毫秒级召回。OpenRig的向量库支持配置三个关键参数：M（每个节点的最大连接数）、efConstruction（构建索引时的动态候选列表大小）、efSearch（检索时的候选列表大小）。我的经验是M设16，efConstruction设200，efSearch设64，在检索速度和召回率之间比较均衡。如果索引库特别大，优先调高efSearch看效果，M值不建议动不动就翻倍，否则索引文件会大得吓人。

2.4 检索、重排序与生成：怎么把最终答案做准

向量检索能解决语义相似问题，但它有一个典型的盲区：对精确关键词和专有名词不敏感。比如用户问“OpenRig的chunk_size默认值是多少”，向量检索有可能召回一堆Embedding参数相关的泛泛内容，而真正写了chunk_size默认500的那一段反而排名靠后。

所以OpenRig在检索层默认做“双路召回”：一路走Embedding向量相似度，另一路走BM25关键词匹配。两路结果合并之后，用一个简单的加权公式做初步融合。这个融合逻辑不复杂，但效果很实在。权重默认向量值0.7，关键词值0.3，如果你的知识库里有大量英文缩写和型号编码，建议把关键词权重提到0.4以上。

融合之后的候选段落会进入重排序模型再打一次分。重排序模型和Embedding模型的区别在于，Embedding负责“找候选”，重排序负责“精打分”。通俗地理解，Embedding是海选HR，快速筛出100份简历；重排序是业务主管，仔细看最匹配的10份简历，排出最终顺序。OpenRig默认接入bge-reranker-base，它会对每一对问题和段落分别计算相关性分数，效果比向量余弦相似度准得多。

最后一步是生成。Prompt的组装模板直接决定答案质量。我踩过的一个大坑是把检索结果一股脑全塞到Prompt里，也不管长度和格式。后来摸索出一套比较稳的模板结构：先设定角色和任务，再强调“只能依据提供的资料回答，资料不足时明确说明不知道”，然后把参考资料按序号列出，最后才是用户问题。实测这种做法能显著降低幻觉概率，模型也更容易在答案里标明“根据文档第几条”这类出处信息。

生成模型这块，OpenRig默认对接的是通过API调用的通用大模型，同时支持本地部署的对话模型。选型的核心是上下文的承载长度，至少8K起步，否则切分出的5到6段参考材料加上问题本身，很容易把上下文撑爆。

3. 从零到一搭建OpenRig：实操过程全记录

3.1 环境准备与快速部署

OpenRig对硬件的要求相当克制。官方推荐的最低配置是4核CPU、16GB内存，不需要独立显卡——Embedding推理和重排序推理即使在CPU上也能跑，只是批量处理文档时稍慢。如果非要加GPU，一张显存12GB的消费级显卡就能覆盖小团队的全部场景。

我用Docker Compose部署过一次，整个过程比较顺。核心服务一共三个：API服务、向量数据库、基础依赖模型容器。

# 克隆项目并进入目录 git clone https://example.com/openrig.git cd openrig # 启动核心服务（API + 向量库） docker compose up -d # 查看服务状态 docker compose ps

启动完成后，打开管理界面，第一步是配置Embedding模型和对话模型的信息。界面里提供了模型注册表单，填上模型名称和接口地址，点保存即可。OpenRig会优先读取本地模型目录，其次走远端API调用，有网没网都能跑。

3.2 配置文件逐项讲解

如果不想走界面配置，直接改YAML配置文件更精确。这里是一份加了注释的简化配置：

embedding: model: "BAAI/bge-large-zh-v1.5" device: "cpu" dimension: 1024 chunker: chunk_size: 500 overlap: 80 mode: "semantic" # fixed | semantic retriever: search_top_k: 20 fusion_weight_vector: 0.7 fusion_weight_keyword: 0.3 reranker: model: "BAAI/bge-reranker-base" top_n: 5 llm: provider: "openai-compatible" model: "qwen2.5-14b-instruct" api_base: "http://localhost:8000/v1" temperature: 0.2 max_tokens: 2048

参数含义都很直白，但我特别想强调三处，都是实际调出来的经验：

• search_top_k不是越大越好。从索引库里捞回的原始候选越多，重排序环节要精读的内容越多，延迟自然升高。20是性价比比较高的档位。
• temperature设为0.2而不是默认的0.7。问答场景需要稳定和忠实，温度太高会助长模型的发散倾向，答案容易偏离原文。
• chunker的mode用semantic而不是fixed。语义切分虽然慢一点，但切出来的块语义更完整，检索效果好很多。

3.3 首次运行与效果验证

配置好之后，在管理界面创建一个新的知识库，上传一份测试文档，等待索引状态显示“就绪”。OpenRig会把整个流程的日志打得很清楚：文档解析完成了多少字符、切分出了多少个块、向量化进度条走到百分百。

然后就可以在界面上问问题验证了。我一般会准备三个类型的测试问题来快速判断系统是否“上线”：

1. 事实型问题：直接问文档里的具体数值或结论，检验召回是不是精确。
2. 推理型问题：问需要跨多个段落归纳总结的内容，检验生成模型的阅读理解能力。
3. 边界型问题：问一个文档里完全没有答案的问题，看模型能不能老老实实说不知道。

第一次跑通后，用上面三类问题过一遍，系统大体靠不靠谱心里就有数了。如果事实型问题都答不对，先别调Prompt，回头检查解析和切分；如果事实型没问题但推理型不行，再考虑升级对话模型或增加参考段落数量。

4. 实战中那些绕不开的坑：问题排查与优化

4.1 召回不准：先别急着换模型

“检索结果不相关”是出现概率最高的头号问题，但不要一上来就怀疑Embedding模型实力不够。我的排查顺序是固定的：

第一步打开调试面板，看文档解析后的纯文本。如果文本乱成一团，甚至存在大段内容消失，解析层就是罪魁祸首。

第二步检查切分块的长度分布。如果大量块的字符数只有一两百，说明文档里可能有大量换行符，切分器被干扰了，应优先清洗空行和无效换行。

第三步单独验证向量检索。直接在索引管理页输入一段与文档相关但没有原词重复的句子，看召回结果里有没有语义相近的段落。如果这里就翻车，才需要考虑更换Embedding模型或微调索引参数。

第四步看双路融合的权重。如果知识库里全是产品型号和内部编码，关键词召回的权重可以适当提高，因为这类信息靠语义匹配很难精准。

按照这个顺序排查，八成问题能定位在索引构建阶段，而不是模型选型。

4.2 检索快了但答案不准：问题出在Prompt和切片

如果检索引擎已经能召回准确段落，但生成的答案还是答非所问，优先检查两个环节。

第一个是切片和问题的匹配粒度。有一种常见情况：文档里某个问题的答案分散在多个段落，每个段落单独检索都排不到前面，合在一起才是完整答案。解决办法是适当调大chunk_size，或者在语义切分时提高合并阈值，让包含相关上下文的大块内容进入候选集。

第二个是Prompt里的指令约束不够强。OpenRig的Prompt模板里，有两句话特别关键：“请仅依据参考资料中的信息进行回答。如果参考资料中没有相关信息，请明确回答不清楚。”如果你的自定义Prompt把这两句删了或改了，模型的发挥空间一大，就开始自由发挥。我在实测中发现，那些坚持在Prompt里写“你是专家请认真回答”的中文模型，反而更容易产生自信满满的幻觉。更好的表述是“你是信息抽取助手，严格忠实于输入材料”。

4.3 生成延迟太高怎么办

知识库问答对响应时间的容忍度很低，用户点完查询按钮，超过5秒就容易流失。OpenRig的默认处理链路里，从检索到生成是串行的，如果感觉慢，按照以下顺序优化：

• 降级重排序的top_n，从5降到3，生成阶段少读一段材料，节省的token和时间都很可观。
• 在生成环节开启答案缓存。完全相同或高度相似的问题，直接返回之前的结果，不再重复调用模型。
• 对话模型换成更低延迟的服务。实测同一个模型在本地GPU算力不够时，远程API往往快得多，做知识库问答场景不用过分在意数据隐私时，优先选API。

一个更隐蔽的优化点是：OpenRig支持把引用了相同资料块的问题做缓存键。假如有100个人都在问报销流程，他们命中的资料块几乎相同，答案相似度极高，缓存命中率能超过70%。

4.4 常见问题速查表

这张表是我团队内部贴在最显眼位置的速查手册。每个人的知识库场景不同，但排查的着力点大多是这几处。

5. 场景扩展与后续演进思考

5.1 从“读文档”到“懂业务”：多模态和Agent扩展

RAG的基础形态解决的是“文档问答”，但实际业务需求会越来越多地往多模态和行动方向延伸。OpenRig在设计之初就预留了插件接口，其中一个方向是把图片、表格、扫描件纳入知识库，让视觉大模型参与文档理解，而不仅仅依赖文本抽取。比如一份设备故障记录里附带的现场照片，解析层可以调用多模态模型生成一段文字描述，再接入原有索引链路。

另一个方向是跟Agent结合。传统RAG是被动的，用户问什么答什么；Agent化之后，系统可以自主判断需要调用哪些工具、查询哪些知识库、以什么顺序组合信息。我们内部已经在做的一个案例是“智能工单助手”：用户描述故障现象，Agent先检索故障知识库，再触发日志查询接口，最后结合两路信息生成处理建议。OpenRig把检索能力作为Agent的一个专业工具暴露出去，不需要为Agent场景重写框架，这点让我省了很多事。

5.2 我对OpenRig的定位理解

从零写RAG框架到今天，我最深刻的体会是：RAG项目失败很少是因为算法不行，更多是工程细节没打磨到位。OpenRig做的最有价值的事，是把那些决定成败但总被忽略的细节——解析清洗、切分策略、检索融合、重排精排、缓存策略——全部显性化、可配置化。你不需要理解所有内部原理也能快速用起来，但如果你想深入调优，每一层都有调试入口和数据输出。

就我个人而言，OpenRig最适合的场景还是中小团队的知识库问答和私有知识管理。它没有沉重的运维负担，也没有抽象到让人无从下手，一个小团队用一台服务器，半个月内就能上线一个可用性不错的问答系统。

最后再分享一个习惯：每个知识库上线前，我都会主动“写三道难题”让系统答，一道考精确召回、一道考跨段归纳、一道考拒答能力。这三道题不换，持续跟踪版本迭代效果。实测这么做，系统越用越稳，最怕的是永远只跑最简单的演示用例。