做了几年 PDF 相关的知识库最常被朋友问的一句话是“我的 RAG 明明用了最新的大模型为什么还总答不上来”大多数时候答案不在模型也不在向量库而在最前面那道没人愿意细看的关卡——PDF 解析。这篇文章是我最近用 PyMuPDF 搭配 Qwen-VL 搭的一套图文兼容 PDF RAG 方案复盘核心解决的是传统 PDF 解析只抽文本、丢掉图片表格扫描页的问题。如果你正在被 PDF 里的复杂表格、扫描件、图文混排折磨这套流程应该能直接给你提供一份可上手的参考。稍为交代一下背景我在维护一个混合型知识库里面既有正常的数字化 PDF也有大量扫描版合同、带复杂表格的产品手册、以及图文混排的行业报告。最早那版 RAG 只调 PyMuPDF 的get_text()把文字抽出来然后切块、embedding、检索结果图表类问题几乎全挂扫描页干脆查不到。后来我把缺失的信息分成三类去补文本结构、视觉内容、版面位置PyMuPDF 负责前一半Qwen-VL 负责后一半。下面就把整个设计思路、实操步骤和踩过的坑完整展开。1. 为什么 PDF RAG 容易翻车问题不在向量库在解析层1.1 传统 PDF 解析的三类致命伤很多 RAG 项目的处理流程看起来很美PDF 进来、文本抽出、切块、向量化、检索、生成。问题出在“文本抽出”这一步实在做得太粗糙。第一类致命伤是只有纯文本没有结构。get_text()拿到的是散落的字符和行跨页段落、多栏文字、页眉页脚全混在一起切出来的 chunk 语义是散的。第二类是扫描 PDF整页就是一张大图文本层为空不管后续用多强的 embedding 模型都白搭。第三类是图表和复杂表格文字确实在但表头和单元格关系一旦被拉平成纯文本结构信息就没了检索到也答不对。这里要特别强调一个容易被忽略的事实PDF 解析的瓶颈并不只是“抽不出来”还有“位置信息丢失”。同样一句话出现在表格里和出现在正文段落里含义可能完全不同。只保留字符串的 RAG等于把文档的空间布局信息全扔了大模型再强也只能在残缺信息里瞎猜。1.2 “只抽文本”的 RAG 会漏掉哪些关键信息我拿一份真实产品手册举例。手册里有张参数表左边是指标名右边是数值和单位下面还有一行备注。用纯文本抽出来顺序就变成了“指标名 数值 单位 备注”中间还可能混入页脚的页码导致表格语义链全断。检索“最大功率”的时候可能召回的是下一页另一张表格里的数字。还有扫描版合同本质是全页图片纯文本方案直接零召回。更隐蔽的是“图文混排”的案例一份行业报告里关键结论用加粗色块和配图呈现正文只写了一句话。传统解析只能拿到那一句话却拿不到配图里的数据趋势。大模型面对这种输入自然只能泛泛作答回答质量自然大打折扣。这些就是我常跟朋友说的“RAG 瓶颈”——入口丢了信息后面全白搭。2. 整体方案设计让 PyMuPDF 和 Qwen-VL 各司其职2.1 选型理由为什么是 PyMuPDF而不是 pdfplumber 或 PaddleOCR市面上 PDF 解析工具很多我的选择标准是本地依赖轻、既能抽文本又能抽图像、解析速度快、能拿到每个块的坐标信息。PyMuPDF 基于 MuPDFC 扩展实现性能在同类工具里数一数二。它一个库就能覆盖文本块提取、图片导出、页面渲染、表格检测API 还很简洁。对比之下pdfplumber 文本定位确实细致但速度偏慢图像提取能力弱处理几百页的大文档明显吃力。PaddleOCR 中文识别效果优秀但它是完整的 OCR 检测识别链路需要额外部署和计算资源放在 RAG 前置解析里显得偏重。Qwen-VL 则负责视觉语言理解处理和微软直接用 PyMuPDF 渲染所有页面再交给视觉模型不同我坚持“能不视觉就不视觉该视觉才视觉”的原则。原因很现实视觉模型推理成本远高于文本解析而且对高分辨率表格直接整页推理容易丢小字细节。2.2 完整流程拆解文本、图片、扫描页怎么走通整套流程可以拆成八个步骤每一步都有明确产出。第一步遍历 PDF 每页统计文本长度初步判断是文本页、扫描页还是混合页。第二步用 PyMuPDF 按 block 抽取文本块同时记录每个块的 bbox 坐标。第三步用find_tables()检测有线表格把能识别的表格转成结构化数据无线表格或复杂表格标记为待视觉处理。第四步提取页面内嵌图片去重后筛选出有信息量的图。第五步对扫描页、复杂表格区域、高价值图片进行位置裁剪渲染成 PNG。第六步调用 Qwen-VL 对这些视觉区域生成结构化描述比如“图中是一个柱状图显示 Q1 到 Q4 销量分别为 120、180、150、230”。第七步把文本块和视觉描述按阅读顺序拼接成完整块序列再做切分。第八步embedding 后入库检索时执行召回和重排。这个流程强调“先文本后视觉”PyMuPDF 搞不定的区域才交给 Qwen-VL成本和效果都能兼顾。2.3 这类方案的适用边界与扩展方向如果你要做的是客服知识库、政策法规库、论文预印本库、设备说明书库这套图文兼容方案非常契合。尤其是文档里频繁出现截图、表格、扫描页的场景收益最大。如果是纯文本论文或数字原生文档不需要上视觉模型常规 PyMuPDF 文本解析就够。但也要说清边界遇到几千页的超大 PDF全部走视觉理解会产生巨额耗时碰到复杂手写注释Qwen-VL 的识别能力也会到顶此时 PaddleOCR 反而更合适。所以我的建议是不要把方案固定死把各环节做成可插拔文本方案为主、视觉模型补刀必要时降级到 OCR。这样遇到不同类型文档时只需调整规则配置而不必重写管线。3. 核心细节与实操要点PyMuPDF 解析并没有你想的那么简单3.1 从 PDF 页面上拿到文本块和位置信息我先说代码。PyMuPDF 的常见导入方式是import fitz新版也支持import pymupdf函数接口一致。抽取文本时不要用最省事的page.get_text(text)它只返回顺序字符串丢失了块位置。我会用get_text(dict)它按 block、line、span 嵌套返回结构每个 block 还带 bbox 坐标。import fitz doc fitz.open(sample.pdf) page doc[0] blocks page.get_text(dict)[blocks] for b in blocks: if b[type] 0: # 文本块 lines [] for line in b[lines]: spans [span[text] for span in line[spans]] lines.append(.join(spans)) text \n.join(lines) bbox tuple(round(v, 1) for v in b[bbox]) print(fbbox{bbox}, text{text[:60]})bbox非常重要。它不仅能用来恢复阅读顺序还能在后续问答环节做引用定位。比如用户问“最大功率是多少”检索到某个 chunk 后我可以直接把这个 chunk 关联的页码和坐标高亮出来。没有坐标信息的 RAG最多只能告诉用户“在某页”有了坐标就能做到“在这一块”。双栏文档是个典型痛点PDF 内部文本块顺序常常是先左栏再右栏但如果块高度不齐直接按输出顺序拼接会错乱。我的经验是按 bbox 的 y 坐标分簇再把同簇内的块按 x 坐标排序先按行再按列重组能解决大部分双栏问题。3.2 图片提取与去重别被同一个 logo 反复刷屏PDF 里的图有两个来源页面嵌入的图片对象和内嵌图流。用page.get_images(fullTrue)可以拿到页面引用的图片 xref。最常踩的坑是同一张 logo 或背景图出现在每一页导致提取出几百张无效图把视觉模型的成本拉爆。我的处理分两步第一步维护一个seen集合去重第二步过滤掉面积过小或透明背景的图片。seen set() for page in doc: for img_info in page.get_images(fullTrue): xref img_info[0] if xref in seen: continue seen.add(xref) pix fitz.Pixmap(doc, xref) # CMYK、带 alpha 通道的图要转成 RGB否则保存容易异常 if pix.n - pix.alpha 3: pix fitz.Pixmap(fitz.csRGB, pix) if pix.width * pix.height 10000: continue pix.save(fpage{page.number 1}_img{xref}.png)这里补充一个容易踩的坑CMYK 图片直接保存成 PNG颜色是异常的。所以我在代码里判断通道数超过 3 就转成 RGB。另外有些 PDF 图片是“被裁切显示的”提取出来的是完整大图视觉模型读起来干扰很大。这种我建议直接用page.get_pixmap(cliprect)按显示区域渲染而不是提取原始图片对象。3.3 如何判断一个页面究竟是文本页还是扫描页扫描页的检测逻辑不复杂文本层为空或极短。但项目里更常见的是“混合页”文字占了小部分其余是大图。我的阈值规则是如果page.get_text(text).strip()的长度小于 20就视为扫描页整页渲染成图交给 Qwen-VL如果长度在 20 到 200 之间就同时抽文本并渲染页面中面积较大的图像区域给视觉模型看。for page in doc: text page.get_text(text).strip() if len(text) 20: mat fitz.Matrix(2, 2) # 2倍分辨率保证小字也能看清 pix page.get_pixmap(matrixmat, alphaFalse) pix.save(fscan_page{page.number 1}.png)渲染分辨率需要根据文档类型调整。普通文档 2 倍就够微信截图类 PDF 我常开到 3 倍。分辨率太高有两个副作用一是 PNG 文件巨大传图到视觉模型慢二是小号字体可能出现摩尔纹。建议先用低分辨率试跑一页再根据识别效果调。3.4 表格和公式怎么办交给视觉模型补刀PyMuPDF 在 1.23 版本后提供了实验性的find_tables()接口能检测有线表格并转成 DataFrame。这套接口适合那种规规整整的三线表遇到无线表格、合并单元格、跨页表格就会失灵。我的代码会先跑find_tables()成功就转 DataFrame 存成 markdown失败就把表格区域裁剪出来交给 Qwen-VL 输出 markdown 表格。tables page.find_tables() if tables.tables: for i, table in enumerate(tables): df table.to_pandas() print(ftable_{i}:) print(df.to_markdown()) else: # 用 bbox 裁剪表格区域交给 visual 模型 rect fitz.Rect(table_bbox).round() if table_bbox else page.rect pix page.get_pixmap(matrixfitz.Matrix(3, 3), cliprect, alphaFalse) pix.save(ftable_page{page.number 1}_0.png)公式识别同理。Qwen-VL 对 LaTeX 的支持不错我会在提示词里要求“把公式输出成 LaTeX 代码并补充一句自然语言解释”。这里提醒一点不要在提示词里让模型一次输出太多内容一个区域一个小任务识别效果更稳。4. 图文融合的 RAG 检索链路提取、切分、向量化、召回4.1 把 PyMuPDF 文本块与 Qwen-VL 描述按序拼接解决了 PDF 解析接下来要做的是把文本和视觉描述“翻译”成同一种语言——纯文本。我用一个中间结构Block来统一承载dataclass class Block: source: str # text / image / table page: int bbox: tuple content: strPyMuPDF 抽出来的文本块是text类型Qwen-VL 输出的图片描述是image类型find_tables()转出来的表格是table类型。然后按坐标顺序拼起来。视觉描述建议写成自然语言不要只给一句话标签。同样是“产品对比图”更好的描述是“图中是 A、B 两款产品的参数对比表A 的功率为 2200WB 的功率为 1800WA 价格更高”。这样切分后即使 chunk 边界切歪了检索到的内容依然完整。拼接顺序以视觉区域在页面中的位置为准。如果一个文本块和一张图在同一行区域就先文本后图片如果图在文本上方就先图后文本。没必要做得太精细大致符合阅读顺序即可。4.2 切分策略按语义块还是固定窗口对图文兼容方案我不建议用“一页一切”的粗暴策略也不建议只按固定字符硬切。最佳实践是按区块聚合然后引入重叠窗口。简单做法是维护一个 buffer把相邻的 block 依次推进去超过max_chars就切一刀同时把上一个 chunk 的末尾一段重叠带进来。def split_chunks(blocks, max_chars512, overlap64): chunks [] buffer for b in blocks: item f[p{b.page}] {b.content} if len(buffer) len(item) max_chars and buffer: chunks.append(buffer) buffer buffer[-overlap:] \n item else: buffer buffer \n item if buffer else item if buffer: chunks.append(buffer) return chunks这里有几个参数心得。max_chars不要贪大embedding 模型对超长文本往往只关注头尾中间信息被平均掉overlap至少 64 个字符保证跨 chunk 的语义连续。要是文档以英文为主建议按 token 数控制切分而不是按字符数因为英文一个单词 4 到 6 个字符很常见按字符切容易把单词劈开。切分时还要保留来源元数据。我在每个 chunk 文本里嵌入了[p3]这种页码标记这样召回阶段可以直接引用页码对用户更友好。同时这个标记不参与语义计算但在预测影响不大。4.3 embedding 选型与简单召回实现embedding 模型我优先推荐开源的 BGE 系列它在中文长文本上的表现很稳对表格、图片描述这类结构半结构化文本兼容度也高。我用的是BAAI/bge-m3支持中英双语输出 1024 维向量。加载和使用都不复杂from sentence_transformers import SentenceTransformer import numpy as np embedder SentenceTransformer(BAAI/bge-m3) chunk_texts [c for c, meta in data_rows] chunk_vecs embedder.encode(chunk_texts, normalize_embeddingsTrue) def search(query, top_k5): query_vec embedder.encode([query], normalize_embeddingsTrue)[0] scores chunk_vecs query_vec top_idx np.argsort(scores)[::-1][:top_k] return [(scores[i], data_rows[i]) for i in top_idx]注意normalize_embeddingsTrue这一步。如果不做 L2 归一化向量点积结果不等价于余弦相似度直接比较分数会失真。另外查询侧和文档侧建议用同一个模型、同一套归一化设置否则分数不可比。4.4 召回后如何组织 prompt 并生成回答召回只是前半场后半场是把文档片段交给生成模型。我的 prompt 组织逻辑是每个片段都标注来源要求模型只能依据片段作答资料不足时明确承认。这样既能减少幻觉又能让答案可溯源。context_blocks [] for score, (text, meta) in retrieved: context_blocks.append(f[来源{meta[page]}页]\n{text}) system_prompt 你是一个严谨的文档问答助手。请根据资料回答问题资料中没有的信息不要编造。 user_prompt f 资料 {chr(10).join(context_blocks)} 问题 {question} 这里有个细节如果召回片段里存在多个“同页同区域”的重复描述容易干扰模型。我的做法是召回后先按页号和块位置去重同一页同一坐标只保留分数最高的一条。对图文混排的 chunk我会保留文本块的原始内容也保留图片描述但在 prompt 中标注“这条来自图片来源描述”模型会更审慎地使用这类信息。5. 实操过程实测记录从 demo 到能用的完整链路5.1 环境准备PyMuPDF、Qwen-VL 推理服务、embedding 模型我的环境是一台 32G 显存的机器Python 3.10。依赖就三个核心包pymupdf、sentence-transformers、openai。Qwen-VL 我用 vLLM 部署成 OpenAI 兼容接口加载Qwen/Qwen2.5-VL-7B-Instruct。部署后接口地址类似http://127.0.0.1:8000/v1调用方式与 OpenAI SDK 完全一致只需改base_url和api_key。pip install pymupdf sentence-transformers openai这种部署方式的好处是后续切换模型非常方便无论是 Qwen-VL 还是其他多模态模型只要服务端支持 OpenAI 协议客户端代码几乎不用改。embedding 这块我用 BGE-M3向量化在 GPU 上跑几百页的 PDF 几分钟就能完成全部索引。5.2 第一版流程先把文本和图像都抓到第一版我只做了两件事遍历所有页面抽文本导出所有页面里的图片去重。跑完以后统计了一下60 份 PDF 总共抽到 1240 个文本块和 380 张去重图片。看起来数量正常但一测效果就露馅了问“某系列产品支持的接口类型”答案里总混着其他型号的信息。排查后发现是跨页表格被硬切成了三个 chunk单元格拆散了。这版的问题很典型我拿了文本和图片但没拿到“结构”。PDF 里的表格被拆成离散文本块之后光靠 embedding 根本没法还原表头与单元格的对应关系。接下来我引入了find_tables()把成功的表格转成 markdown失败的区域再做视觉识别效果才明显改观。5.3 遇到的第一批坑表格截断、图片重复、扫描页漏检第一个坑是无线表格截断。find_tables()对有线表格效果好但现代文档大量使用无线表格只靠边框检测根本查不出来。我改成规则文本块之间如果存在大量“间距对齐”且长度接近的行就先合并成候选表格区域再交给视觉模型确认。第二个坑是图片重复前面提过去重的问题。光靠 xref 去重依然不够同一张图可能以不同尺寸嵌在不同页面xref 不同但内容一样。我的补救方法是计算图片的感知哈希把相似度高于阈值的图合并成一组只保留信息量最大的一张。第三个坑是扫描页漏检。有一些老文档扫描后还叠了一层 OCR 的隐形文字get_text()有内容但文字和图片是错位的问答时经常抽出毫无意义的句子。这类页面我用“文本块数量少 页面中有超大图片”两个条件联合判断尽量识别为混合页至少对图片区域做一次视觉描述避免喂给模型一堆错位 OCR。5.4 调整后的效果对比问答准确率的变化跑通完整链路之后我做了一个小型评测准备 50 个问题其中 30 个事实类问题、10 个表格类问题、10 个扫描页问题。对比“纯文本解析”和“图文兼容方案”的准确率结果如下问题类型纯文本解析方案PyMuPDF Qwen-VL 方案事实类问题30题82%90%表格类问题10题30%80%扫描页问题10题0%70%表格和扫描页的提升最明显这也是预期内的因为那两类信息在原来方案里几乎全部丢失。事实类问题提升不大说明对普通数字化 PDF 来说纯文本解析基本可堪一用。这个评测集不大数字仅供参考但它直观地说明了方案价值到底在哪。6. 常见问题与排查技巧实录6.1 问题速查表我把实际踩过的坑整理成了一张速查表方便后来者按图索骥。现象可能原因解决思路page.get_text()返回空扫描 PDF 或加密 PDF用doc.authenticate()解锁若文本层为空整页渲染转视觉模型提取出的图片保存失败图片通道为 CMYK 或带 alpha转 RGB 后再保存表格数据混乱无线表格超出了 PyMuPDF 检测能力方案一用find_tables()失败后裁剪区域调用 Qwen-VL方案二扩大 bbox 裁剪范围Qwen-VL 返回空或超时图片尺寸过大、提示词不明确、服务端并发不足压缩图片到合理分辨率提示词明确要求输出格式服务端做并发排队双栏文档顺序错乱未按坐标排序按 bbox 的 y 分簇再按 x 排序检索时图片描述被忽略视觉描述被切成孤立 chunk切分时让图片描述紧跟周边文本块中文小字识别不准渲染分辨率太低Matrix(3, 3)或更高优先保证宽高为原图 3 倍这张表并不能覆盖所有场景但能解决 80% 的入门问题。遇到冷门报错建议先看 PyMuPDF 的异常栈再定位到 PDF 的具体页面编号手动抽一页调试比闷头改代码快得多。6.2 几个值钱的排查思路排查 PDF 解析问题不要只看输出要看源头。拿到一个异常文档第一步先用page.get_text(rawdict)看作原始字符和字体信息判断是编码问题还是布局问题。第二步把该页渲染成高清图片人肉看一眼判断到底是文本层问题还是视觉内容问题。第三步再对症下药。我特别想强调“越小越好”的排查原则。不要把整个 PDF 都交给调试流程先用脚本把有问题的页面裁出来输出本页的所有 block 坐标和文本分门别类放好。这样问题会很快收敛。另一个值钱经验是给视觉模型的提示词一定要要求“只输出结构化结果不要解释”。我最早写的是“请识别图片中的内容”结果 Qwen-VL 返回一大段说明性文字后续解析很麻烦。改成“请以要点列表形式输出图中所有文字和数据不要额外说明”之后输出稳定了很多。6.3 如果想让召回再进一步rerank 与混合检索图文兼容解析做好了不代表召回就完美。我遇到过一个问题表格里的某个数值检索不到因为数值往往不是高频词语义相似度打分偏低。解决办法是引入混合检索。思路很简单对同一个文档同时在 BM25 稀疏检索和 embedding 密集检索上打分然后把两路分数加权合并。BM25 擅长精确匹配适合“型号、编号、人名、法律条款编号”这类场景embedding 擅长语义泛化适合“意思相近但表达不同”的问题。合并之后 top-k 召回质量会显著提升。如果预算充足还可以加一个 rerank 环节用 BGE-reranker 这类交叉编码器对 top-20 结果重新打分精确度更高。在图文兼容方案里我建议对视觉描述 chunk 单独维护索引检索时对视觉 chunk 适当提高相似度阈值避免大段图片描述总被排到前面。7. 最后的经验补充与延展建议整个过程做下来我的体会是图文兼容的 PDF RAG本质是一个“文档工程”问题而不是“模型选型”问题。PyMuPDF 解决了“PDF 里有什么”Qwen-VL 解决了“非文本部分在说什么”两者拼合RAG 的输入才真正完整。不要一上来就追求完美解析先拿自己手头最容易翻车的十份 PDF把流程跑通再逐步加规则、加视觉区域、加 rerank往往比一开始就堆重型方案更有效。如果你准备在生产环境用我建议再做一个很小的服务化封装把 PDF 解析和索引拆成异步任务避免在线问答时同步卡住。对重复上传的文档还可以做个缓存按文件哈希命中能省掉大量重复解析成本。最后还有一个值得尝试的扩展把 Qwen-VL 的描述结果作为“合成文档”单独存一份并在问答时让大模型优先引用原始文本块视觉描述仅作为补充证据。这样既保留了视觉信息又降低了多模态模型输出不稳定带来的误差。我实测下来这个细节对回答质量的影响甚至比换一个更大参数的生成模型还明显。