离线知识问答系统实战：企业文档解析与RAG检索生成-平芜编程栈

你的公司里是不是也有这么一批文件——扫描存档的合同、供应商发来的PDF手册、几个部门攒了五年的制度文档，占着共享文件夹几个G的空间，真到用的时候谁也找不到里面写了什么。我做过一个项目，把这一堆“沉睡资产”捞了出来，接上本地跑的大模型，做成了一套离线知识问答系统。说白了，就是让员工用自然语言提问，系统从文档里找出答案，带着引用出处返回。整个过程从文档解析、向量化到问答链路，全部在内网完成，数据不出门。

这篇就把我的完整做法拆开讲清楚，包括为什么这么设计、每步的关键参数、踩过哪些坑，以及一些能直接拿来用的经验。

1. 先想清楚：一套离线知识问答系统到底在解决什么

1.1 文件躺在文件夹里吃灰的三重原因

我接手的时候，先说下现场的真实情况。

共享盘里有三个历史遗留的文档库：一个是扫描版的合同档案，大量是拍照或传真件；一个是产品手册库，有PDF也有Word，版本还新旧混淆；还有一个是行政制度汇总，基本是领导签发过的红头文件扫描件。总计大概700多份文档，大小从一页到两百页不等。

这些文件“吃灰”的原因，说起来其实就三个。第一，形式不统一，有纸质的扫描件、有电子版、有格式不规范的表格，天然不方便检索。第二，检索手段太弱，共享盘里的文件名是编号规则混乱的手工命名，全文检索几乎等于没有，想找一份合同要打开十几个文件碰运气。第三，信息是静态的，即使你找到了PDF，里面的一段关键条款、一个产品的参数，还得自己用眼睛翻十几页才能定位到。

这套方案要解决的，就是把“以文件为单位存放”变成“以内容为单位检索”，再进一步变成“以问答为入口获取”。这不是什么玄乎的概念，本质就是把文档内容结构化、向量化，然后用大模型做推理回答。

1.2 为什么企业偏偏要“离线”方案

选“离线”这个路线，不是因为我喜欢折腾机房，而是大多数企业场景根本没得选。

这些文档里装的是真实的客户名单、采购价格、合同条款、内部流程。这些信息一旦发送到外部云端API，哪怕只是切片打散之后发出去，在合规层面也很麻烦。尤其是一些对信息安全有硬性要求的行业，明文规定核心数据不允许出内网。所以，与其在外网API和内网数据之间做出一套复杂的脱敏和审计方案，不如一开始就把整套链路放在内网里。

离线的另一个好处是可解释性。内部审查的时候，你可以拍着胸脯说“数据全程没出过内网”，这句话在合规评估里值很多钱。

代价当然也有。你需要自己搞定GPU服务器，自己维护大模型推理服务，自己处理OCR和解析的算力分配。一套能用的离线方案，在选型和部署上要花的时间、精力，远比调一个云端API多得多，但换来的是你能够安全处理这些敏感数据。这个置换，我认为非常值。

1.3 整套系统由哪几块拼起来

这套系统听起来复杂，拆开看其实是四块标准件。

第一块是文档解析层。负责把扫描件、PDF、Word等各式文件变成干净的纯文本，这是整套系统数据质量的源头。第二块是知识库构建层。把文本切成合适的片段，用嵌入模型向量化，再灌入向量数据库，同时保留一份原始文本用于检索后的引用。第三块是检索层。收到用户提问后，把问题向量化，去向量库里做相似度检索，同时配合关键词检索做混合召回。第四块是问答生成层。把检索到的候选片段拼进提示词，交给本地大模型，让它根据这些片段生成回答。

我用了FastGPT这个开源框架来做应用层的编排，后端用FastAPI写了一些定制接口，索引和检索的部分是自己写的Python代码。你完全可以替换成Dify或者干脆全用LangChain自己串，选型上我更倾向于“框架负责界面和流程，核心逻辑自己掌控”，这套架构后面会讲。

2. 让扫描件和合同先被“读懂”：文档解析与OCR

2.1 文档格式千差万别，一次解析的坑你就得踩一个晚上

文档解析是整个流程里最不起眼、但最容易翻车的环节。

不同格式的文档，处理工具完全不同。纯电子版PDF可以用PyMuPDF提取文本，又快又准；Word文档用python-docx读取段落和表格；但扫描版的PDF没有文字层，必须先OCR。最头疼的是那些混合型的PDF——一部分页面是电子生成的，另一部分是扫描贴上去的，这种情况你得逐页判断，否则就会得到一堆乱码或空文本。

我当时的策略是这样的：

先看文件扩展名和头部标识，区分PDF、Word、图片等主类型。
对PDF，用PyMuPDF尝试提取每一页的文本，并计算文本密度。
如果某页文本密度极低或提取为空，就判定为扫描页，转入OCR流程。
OCR结果与原有文本按页码拼接，保持页码对应关系。

这个混合解析的策略，在实际项目中非常实用，因为真实的企业文档很少干干净净只属于某一类格式。

2.2 OCR选型：为什么我最后锁定了PaddleOCR

OCR是整套系统里直接影响准确率的一环，尤其中文场景，我对比过好几个方案。

开源社区里，Tesseract是老牌选择，但它对中文印刷体的识别效果比较一般，尤其是碰到表格、水印、印章压字的情况，输出的文本经常乱七八糟。商用云OCR精度很高，但它又违背了离线的前提。最终我选择了PaddleOCR，它的PP-OCRv4模型在中文场景的识别率、速度和对复杂版面的适应能力都比较均衡，而且支持整卡或CPU推理。

我用的核心参数组合是文本检测加方向分类加文本识别三段式，语言设为中文。还有一个被很多人忽略但极其重要的点：置信度过滤。

PaddleOCR不仅能输出文字内容，还能输出每个文本框的置信度分数。我在代码里设置了一个阈值：低于0.6的识别结果，宁可丢掉也不放进知识库。原因很简单，一个错误识别的合同金额（比如把“伍佰”识别成“伍仟”），放进知识库里就是一颗定时炸弹。与其让错误的OCR文本污染检索结果，不如让它消失，让系统性检索去别的地方找答案。

下面这行代码是我在批量处理时用到的核心片段：

import paddleocr from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) def ocr_page(img_path: str): result = ocr.ocr(img_path, cls=True) lines = [] if result and result[0]: for box, line in result[0]: text, score = line[0], line[1] if score >= 0.6: # 置信度过滤，宁可丢不可错 lines.append((text, score, box)) return lines

有人会问，0.6是不是太保守了？我试验过，大部分清晰扫描件的置信度都在0.9以上，0.6能兜住那些模糊又关键的边缘case。对于文本较长、需要保持段落语义的场景，0.5是另一个可调档位，后面在调优部分我详细解释。

2.3 表格、印章、双栏排版：合同处理的三块硬骨头

合同和手册相比，最大的难度不在文本识别，而在结构解析。

第一块硬骨头是表格。合同里常见的付款计划表、价格列表、交付清单，OCR按阅读顺序输出的时候很容易把行列关系打乱。比如发票信息这类表格，OCR出来的文本可能是“开户行账号地址”挤在一行，完全没有表格关系。对此，我采用了PaddleOCR的表格识别能力，识别表格结构（行列坐标），再把每个单元格的内容按行重建为Markdown格式的表格，这样大模型就能更好地理解行列表述。

第二块硬骨头是印章。合同扫描件上经常盖着红章，章的位置恰好压住文字区块。PaddleOCR默认会把印章上的文字也识别成文本，包括“XX公司合同专用章”之类的字样。这在检索阶段其实还好，更棘手的是章会遮挡底下的文字，导致识别结果缺字。我的处理策略是对扫描页做预处理：在送入OCR前，先通过颜色通道检测红色区域，把红色通道压低或置灰，再去识别，印章文字就会被削弱，底下被压住的正文识别率会提升不少。

这段逻辑说白了就是OpenCV的颜色过滤：

import cv2 import numpy as np def remove_red_stamp(img_path: str, save_path: str): img = cv2.imread(img_path) hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV) # 红色在HSV中的范围 lower_red = np.array([0, 43, 46]) upper_red = np.array([10, 255, 255]) mask1 = cv2.inRange(hsv, lower_red, upper_red) lower_red2 = np.array([156, 43, 46]) upper_red2 = np.array([180, 255, 255]) mask2 = cv2.inRange(hsv, lower_red2, upper_red2) mask = mask1 + mask2 # 将红色印章区域的饱和度降低，文字变淡 hsv[mask > 0, 1] = 0 hsv[mask > 0, 2] = 255 img_no_stamp = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR) cv2.imwrite(save_path, img_no_stamp) return save_path

这个方法的代价是盖在文字正中间的印章仍然可能遮挡笔画。实测下来，颜色过滤能让扫描版合同的可用性提升一个档次。

第三块硬骨头是双栏排版。很多产品手册是双栏或三栏设计，OCR按版面从上到下扫描，会把左栏的下半截和右栏的上半截切割到一起，产生语义断裂。为了解决这个问题，我用OCR返回的坐标信息做了重排逻辑——先按Y坐标聚类出栏位置，再按“X坐标优先、Y坐标其次”的顺序重组。如果你用的是带layout分析的OCR模型，这个工作会更省力，但坐标自绘重排的代码逻辑也不复杂，关键是意识到这个坑。

3. 把解析结果变成“可检索的知识”：分块、嵌入与向量库

3.1 分块策略：为什么块大小直接影响问答准确率

文本解析完成后，下一步是分块。这一环节的理论看起来简单，实际效果差距非常大。

分块大小太大会造成什么问题？假设你把整个合同文件切成一个9000字的超级块，检索召回时，这块文本和用户问题的相关性会被平均化——里面只有一小段提到了“付款条件”，但整块嵌入向量会被其余大量“不可描述”的合同条款稀释，检索排序时它很难排到前面。就算划入了上下文窗口，大模型要从一大堆无关文本里找出正确答案，也容易跑偏。分块太小呢？只有一两句话的块往往缺乏上下文，模型无法判断这个声明的主体是谁、前提是什么。比如单独一块“验收合格后30日内支付”，没有前文说明“乙方”，大模型就会乱猜。

我的经验是：优先按章节标题切分，再按长度二次截断。具体逻辑是先把解析好的长文本按标题位置切成语义完整的大段，然后对每个大段做长度检查。如果超过800字，再按句号、分号等边界继续切，每块控制在300到500字之间，并且前后保留50字的重叠区。这个重叠区非常关键，它能让分块边界附近的信息在多个块里都有出现，避免检索时被边界卡掉。

举个例子，某个产品手册中“安全注意事项”这一节有600字，我会整体作为一块保留而不强行截断，因为这一节内部逻辑完整。下一节“技术参数”可能是表格类的Markdown文本，则按表格行拆成小段。

分块的产出要带上原始元数据：文档名、页码、章节路径、所属文件名。这样检索到大模型回答时，才能准确标注“出处来自哪份文件第几页”，用户拿到引用后能人工复核。

3.2 嵌入模型选型：本地跑BGE家族的实操体验

选嵌入模型的时候，企业用户有一个朴素的需求：中文效果好、离线能部署、对显存要求不离谱。

目前广泛认可的中文嵌入方案里，BGE系列（智源开源的中文嵌入模型）是一个很实惠的选择。我这里用的是bge-m3，它是多语言模型，支持中文和英文混合的场景效果很好。bge-large-zh的中文纯精度更专精，如果文档几乎全是纯中文，可以换它。两个模型在句子和段落级语义表征上的表现，足够支撑大多数企业知识库的中文检索场景。

部署方式很简单。把模型文件下载到本地指定目录后，用Python加载就行，不需要联网。关键点在于调用方式：BGE系列模型在推理时有一个“指令前缀”的约定，中文场景就是给查询语句加前缀“为这个句子生成表示以用于检索相关文章：”，而文档入库时不加前缀。这么做是因为模型在训练时对query和document用了不对称的编码，加了指令能略微提升检索精度。虽然只是微调级别的影响，但细节做对了，总比后面在线上去折腾强。

嵌入模型还有一个部署细节：如果你用CPU推理，速度会比较慢，千万条文档入库时会明显拖后腿。我项目的文档量是几百份，切块后大约四万块，CPU嵌入总耗时不到半小时，还能接受。但如果你要处理几十万块，建议上一张用于推理的显卡，并且开启批处理模式，把一批文本一次性送入模型，而不是一行行循环调用。

3.3 向量数据库选型：Milvus、Qdrant还是Elasticsearch？

向量数据库这层，市面上选择很多，但企业场景下我的核心标准是：部署链路轻、检索性能够用、能本地长期跑。

Milvus：功能非常全，支持十亿级别的向量规模，适合大规模集群部署，但组件较多（依赖etc和MinIO），单机部署成本偏高。
Qdrant：Rust实现，单机性能强劲，部署简单，支持丰富的过滤条件，是我这个项目的最终选择。
Chroma：轻量好用，适合快速验证demo，但企业级场景下其稳定性和元数据查询能力偏弱。
Elasticsearch：自带向量检索能力，如果公司已经用了ES，可以复用，避免多套系统。

我最后选了Qdrant，原因是它既能本机运行，也支持Docker部署，Python客户端很成熟，且它能原生支持payload过滤——这一点在做文档权限粒度的检索时非常实用。例如，某用户只能访问A部门的文档，就可以在检索条件上加一个“部门=A”的payload过滤。

Qdrant的搭建非常简单，Docker方式一行命令：

docker run -p 6333:6333 -v /data/qdrant:/qdrant/storage qdrant/qdrant

系统启动后，Python端用client创建collection并指定向量维度（我用的bge-m3输出1024维），就可以把分块文本一把一把灌进去了。检索时，调用query接口传入问题向量和top-k参数，返回候选块列表。

有一点很重要：向量数据库存储的是向量和元数据，不是原始文本。真正要返回给大模型的是原始文本块，所以我在向量库的payload里直接存了原文和文档元数据，这样检索出来就能直接拼提示词，少一次跨系统取数的麻烦。

向量库	部署复杂度	适合规模	中文检索体验	备注
Milvus	高	千万级以上	高	组件多，适合重度场景
Qdrant	低	百万级	高	单机推荐，企业够用
Chroma	最低	十万级	中	适合原型验证
ES	中	千万级	中	需要已有ES基础设施

4. 让大模型“开口回答”：检索、提示词与系统集成

4.1 从“模糊匹配”到“精确命中”：混合检索加即时重排

向量检索解决了“语义相似”的问题，但它不是万能的。最典型的翻车场景：用户问“付款条件的补充协议在哪份合同里”，向量检索很容易优先返回“付款条件的定义”相关的文本，而不是“补充协议变更了付款条款”那块。

这里面有个常识：向量嵌入是做语义压缩，专有名词、数字、精确短语会被压缩成大局语义的一部分，导致细节匹配精度不足。所以我在检索阶段用了混合策略：向量检索（语义召回）+ BM25关键词检索（字面精确召回），最后用RFF（Reciprocal Rank Fusion）算法把两路结果的排名融合。

这个思路非常像搜索引擎的“召回-粗排-精排”三段式：向量和BM25负责从宽泛的候选集中捞回足够多的相关块，融合排序解决两路分数不可比问题，再把排序靠前的候选块送给重排模型做精排。

RFF融合的Python逻辑很短但很实用：

from scipy.stats import rankdata def rff_fusion(vector_hits, bm25_hits, k=60): scores = {} for rank, hit in enumerate(vector_hits): scores[hit['id']] = scores.get(hit['id'], 0) + 1 / (k + rank + 1) for rank, hit in enumerate(bm25_hits): scores[hit['id']] = scores.get(hit['id'], 0) + 1 / (k + rank + 1) fused = sorted(scores.items(), key=lambda x: x[1], reverse=True) return fused

检索结果的top-k一般设成15，也就是把两路的候选块合并取分最高的15块，再交给重排层挑选最终进入提示词的5到8块。这样做的原因是：大模型的上下文窗口有限，塞得越多，注意力越分散，反而容易出错。

4.2 本地大模型推理：做成一个标准服务

知识库把“上下文”准备好了，生成回答的任务交给了大模型。

离线场景下，模型推理方案一般有两种路线：一是用Ollama这种简易推理框架，适合快速试验和个人场景；二是用vLLM起一个OpenAI兼容的服务端，适合并发较高、需要流式输出的企业场景。我最后选了后者，因为它暴露的是OpenAI格式的API，业务系统接入成本几乎为零——只需改一下base_url指向内网服务器。

模型选型上，我用的是Qwen系列的中型模型，量化版。显存只有一块24G的卡，跑7B到14B的量化版本比较舒服。14B版本在中文长文本理解上比7B更稳，尤其是在处理合同条款、制度细则这种语体规范的文字时，很少出现丢前提的毛病。

核心体验是：大模型本身不是重点，重点是提示词结构。我写了一个固定模板，把系统指令和检索片段按严格格式拼起来：

你是一个企业知识库问答助手。请根据用户提供的【参考片段】回答用户问题。 要求： 1. 只能基于参考片段回答，不得使用片段之外的知识。 2. 如果片段中没有相关答案，请明确回答“未在文档库中找到相关信息”。 3. 回答中引用片段时，标注来源文件名和页码，格式见片段标记。 4. 保持简洁、客观、结构化。

关键是“只能基于参考片段回答”和“未找到要直说”这两条指令。如果缺失这段约束，大模型很容易用自己的内部知识“脑补”出看似合理的答案，这在企业场景中是致命的。

4.3 从个人脚本到企业服务：接口封装和权限控制

当所有核心逻辑跑通了，下一个任务是如何把它变成内网某个地址可以访问的服务。

我在FastAPI层封装了一个统一接口，核心流程是接收问题->调用嵌入模型/检索/融合/重排/调用大模型->以流式方式返回结果。这个接口同时接收用户身份参数，用于在检索阶段做元数据过滤——这是前面选Qdrant时埋的伏笔，每个文档块在入库时就带上了“可见部门”的payload，用户名不在允许列表里的请求，直接检索不到那些块。

权限过滤的威力在于，它从根源上杜绝了越权读取：就算某个部门的文件被问题命中，也会因为payload过滤直接被丢出候选集，不会进入大模型的提示词。对于想实现“管理员能看到全部，普通员工只能看到自己部门文档”这种需求，这是一条看起来很简单的路。

前端把老的共享文件夹浏览界面换成简洁搜索框。非技术部门同事不用再背文件编号，而是用日常问题提问，比如“去年X项目的验收报告结论是什么”。这个从文件浏览到对话式检索的转变，才是这次知识库改造真正能够落地的原因。

5. 常见问题与排查技巧实录

5.1 为什么合同里的关键条款总是检索不到

一个典型问题是用户问“XX合同的违约金比例是多少”，系统回答“未找到相关信息”，但你明明知道这些内容就在文档里。

排查思路分几步：先验证PDF解析结果是否是空文本，再确认OCR是否正确输出了那几个关键数字。我遇到过的一种情况是PDF本身是图片版，OCR处理的文本没全部存入知识库，因为某些页被“索引跳过”了——我的解析脚本有一个页面长度上限逻辑，个别超长的合同只处理了前几十页，导致遗漏。解决办法很朴素：去掉页面上限，并把分块数量纳入监控指标，入库前统计每一份文档的块数是否有明显异常。

还有一种情况是关键词本身的匹配方式问题。比如用户问的是“违约金”，但文档通篇只写了“违约金比例”或“逾期付款责任”，字面不一致导致BM25召回遗漏，向量召回又不够精准。优化方案是给索引增加同义词扩展和纠错逻辑，或者提高重排序的权重，让向量排队时把语义近义的对齐。

排查这些问题的最终方法论，就是“把链路分段打点”：每一段都输出日志，解析出文本了没有、分块分成了几块、检索召回了哪些块、大模型看到了哪些内容——每一步都能单独验证，问题自然水落石出。

5.2 扫描件识别率低、错字多怎么办

扫描件的OCR质量受拍摄角度、光照、清晰度影响很大，识别率低的时候，直接硬调OCR参数往往越调越乱。

我踩过的坑里，最值得说的是“图像预处理比换模型更管用”。遇到分辨率低、字迹淡的扫描件，先用OpenCV做灰度化、二值化、去噪、矫正歪斜，对识别率的提升比换OCR模型版本更明显。实测下来，一张A4扫描件，在未做任何处理的情况下，识别结果满屏乱码；简单做了中值滤波和自适应阈值之后，准确率从70%提升到了92%，基本达到入库标准。

另一项实质经验是置信度阈值不能一刀切。我一开始全库都是用0.6作为过滤阈值，后来发现一些历史文件，字体小、墨迹淡，识别出来的文本普遍只有0.5到0.7的置信度，很多有用的信息被误删了。最终我把策略改为：对页面做整体质量评估，页面质量高的用0.6阈值，页面质量差的降到0.45，但只保留那些整页无高置信度替代的低置信度文本，并打上“低置信度片段”标记，在检索时排在最后一位。这样做既没让噪声污染太多，又保住了历史文件的可用性。

5.3 大模型一本正经地胡编怎么破

第一次给业务部门演示的时候，我就遇上了一次翻车：有人问“公司内部对差旅报销的标准是什么”，大模型自信地报出了答案，但实际上这个标准在文档里根本不存在，完全是模型的内部知识在作怪。

后来我把模型换成对指令遵循更强的新版本，并在提示词里增加了“无法回答必须直说”的约束。但光靠提示词还不够，根本性的解法是“无答案判定”逻辑：不强制大模型一定要找到答案，而是在检索层面就给一个问题是否命中做出判断。我加了一个步骤：如果检索召回的所有候选块与问题的相关度得分都低于某个阈值，直接返回“文档库中没有找到相关信息”，不再调用大模型。这个阈值需要基于测试数据标定，一般用0.25到0.35之间。

另一个有效方法是在提示词里明确要求大模型回答时引用块编号，并且代码层把没有引用块编号的回答打上“AI补充”的标签。这样用户至少知道，带标签的部分有可能是模型知识而不是文档原文，防止误导。

5.4 文档库越来越大，性能怎么扛

这套系统跑了两三个月后，文档量涨到了一千多份，分块数六七万，检索响应开始出现明显劣化。排查下来主要瓶颈不是向量库，而是嵌入模型推理和大模型生成并行度不够。

做的最重要优化是把嵌入模型从CPU前向推理改成GPU推理，这几乎是一次五到十倍的响应提升。其次是向量检索本身，Qdrant的HNSW索引默认参数量级下依然很稳，只要打开索引优化参数（比如设置ef_construct和m值），检索延迟基本不用担心。

另一个容易被忽略的存储问题：向量库里的payload字段存了原文，这会导致存储膨胀，因为这些原文文本本来就可以通过数据库外置关联。如果不在乎每次检索多几次IO，可以只存文档ID和块编号，原文通过MySQL或文件路径反查。按我的经验，在几百到几千文档的规模下，直接把原文存payload更方便，配合定期快照备份就好。