做 PDF RAG 时间长了你会发现最头疼的不是模型效果而是 PDF 解析这一关。文字还好办PyPDF2、pdfplumber 都能应付但一旦文档里出现架构图、表格截图、产品实拍图传统解析管线的信息断层就暴露出来了——检索能召回文字却召回不了图里的结论和数据。我自己跑通的一套解法是PyMuPDF 负责把 PDF 里的文字块和图片块按坐标拆出来Qwen-VL 负责把图片翻译成结构化描述两者一起进向量库最终实现图文兼容的 PDF RAG。这套方案我从年初开始搭在生产环境里跑了大半年踩了不少坑也沉淀了一些稳定可靠的做法这篇就把完整的实战过程分享出来。1. 传统 PDF RAG 的信息断层图表几乎全丢1.1 一个典型的翻车场景我最早接的业务需求是给一批产品技术手册做内部问答机器人手册里大量出现系统架构图接口时序图参数对照表。第一版方案很朴素PDF 转纯文本 → 按段落切分 → embedding → 向量检索。上线后用户反馈很一致——问这张架构图里模块之间怎么连接系统要么答不上来要么只回一个图见文档第 X 页。问题不在 RAG 流程本身而在输入端PDF 里的图片在转文本阶段被直接丢弃了。知识库索引里根本没有图的内容检索再准也白搭。这不是个别现象。技术文档、产品手册、行业报告里信息密度最高的往往是图一张架构图的文字密度可能抵得上两三页正文一张趋势图能准确表达数据走势。传统 PDF RAG 方案默认把图和文割裂等于把文档里最有价值的一半信息拒之门外。1.2 PDF 里的图其实有三种形态在处理图片之前要先搞清楚 PDF 里的图到底长什么样。我在实战中把它们分成三类内嵌位图直接嵌入 PDF 的图片文件常见格式是 JPEG、PNG。比如产品截图、扫描的印章、拍照的现场图。矢量图形PDF 内部用路径、填充、渐变等方式绘制的形状比如流程图里的方框和连线、柱状图的柱子。它们不是独立的图片文件而是一组绘图指令。整页扫描件整个页面本身就是一张大图没有文字层。老资料、盖章文件里特别多。这三种形态对解析工具的考验完全不同。位图还能用传统 OCR 硬扛矢量图如果没有渲染步骤OCR 根本无从下手整页扫描件如果按文本库处理读出来就是空的。1.3 只解析文本会损失多少信息我在处理一份 80 页的产品白皮书时做过统计全书有 47 张图片其中 25 张包含关键数值或结构关系比如系统组件拓扑图、性能压测柱状图、接口字段映射表。如果只索引文本这 25 张图对应的知识点全部丢失。更隐蔽的是跨图文信息。文档里经常出现如上图所示服务端与客户端通过长连接通信但上图的内容并不会出现在文本流里。检索长连接通信时如果图里正好画了连接方式纯文本索引只能召回这句话本身无法关联图中的细节用户还得手动翻 PDF。所以我后来的结论是PDF RAG 的解析层必须做到图文分离提取 语义合并回填而不是简单地把页面拉平成一串文字。这正是 PyMuPDF Qwen-VL 这套组合要解决的核心问题。2. 技术选型PyMuPDF 配 Qwen-VL 的底气从哪来2.1 PyMuPDF 和 pdfplumber、PyPDF2 的差异选 PyMuPDF 不是因为它名气大而是它解决了一个关键问题它能同时拿到文本块和图片块并且都带坐标。我用过的几个库差异很明显库文本提取图片块定位坐标精度渲染能力上手成本PyPDF2一般只能取图片对象弱无低pdfplumber好不擅长中无中fitz / PyMuPDF极好原生支持高强中PyPDF2 偏轻量适合简单场景但是它把文本和图片的信息拆得很碎想重建某段文字旁边有张图的关系很费劲。pdfplumber 做表格和文本定位是一把好手但图片块不是它的主攻方向提取坐标布局时需要自己绕弯。PyMuPDFimport 名是 fitz最大的价值在于它是解析引擎级的工具。它有原生 API 直接返回页面里的 block 列表每个 block 自带 bounding box 坐标而且文本块和图片块共用一个坐标系。这意味着我可以非常自然地回答这一页有哪些图、这些图分别挨着哪些文字。2.2 Qwen-VL 凭什么比 OCR 更适合做图片理解传统 OCR 方案的第一反应是把图片转成文字但这条路在 RAG 场景里有两个明显缺陷OCR 只解决把图里的字抠出来不解决这张图表达什么意思。一张架构图 OCR 出来的可能是一堆散落的模块名和箭头没有逻辑关系。OCR 对矢量图直接无能为力——矢量图没有像素层必须先渲染成位图才能识别而 OCR 厂商往往不提供渲染能力。Qwen-VL 这类视觉语言模型解决的是理解层面的问题。它直接把图片作为输入模型会结合图像里的文字、布局、颜色、形状给出语义化描述。我在实测中让 Qwen-VL 描述架构图它能输出服务层包含三个微服务通过负载均衡连接到数据层数据层使用主从复制这样的完整句子并且能准确捕捉箭头方向和数据流向。而且 Qwen-VL 对中文场景的适配很友好处理中文标注的架构图、中文表格时识别效果比通用 OCR 方案更稳定。这一点在技术文档类场景里价值很大毕竟英文模型看不懂中文图和中文界面截图是常有的事。2.3 整体的双通道架构整套方案的设计思路可以概括成一句话用 PyMuPDF 做版面解析把文档拆成文字块和图片块两条通道文字块直接走文本处理图片块渲染成位图后交给 Qwen-VL 生成描述最后按坐标顺序把描述插回文字流统一切片、统一向量化。整个管线分成四个阶段版面解析阶段PyMuPDF 读取每一页产出带坐标的文本块和图片块列表。图片理解阶段图片块按 bbox 渲染成高分辨率位图调用 Qwen-VL 生成结构化描述。内容合并阶段按版面坐标把图片描述插到对应的文本上下文中间形成图文混合的内容单元。索引检索阶段对混合内容切片、embedding配合元数据实现混合检索与重排。这样做的好处是检索时不会出现文字和图各查各的。图片描述被嵌入了它们在版面中的原始位置检索长连接通信时既有邻近文本被召回也有图片描述中的连接关系被召回召回内容更完整。3. 核心实现用 PyMuPDF 拆出文字与图片的对应关系3.1 读取页面 Block坐标是第一生产力先看最基础的一段代码用 PyMuPDF 读出一个页面里所有文本块和图片块。import fitz doc fitz.open(product_manual.pdf) page doc[3] # 以第 4 页为例 blocks page.get_text(blocks) for b in blocks: x0, y0, x1, y1, text, block_no, block_type b if block_type 0: print(f[TEXT] ({x0:.1f}, {y0:.1f}) - ({x1:.1f}, {y1:.1f}): {text[:50]}) elif block_type 1: print(f[IMAGE] ({x0:.1f}, {y0:.1f}) - ({x1:.1f}, {y1:.1f}))这里的关键是page.get_text(blocks)返回的每一行是一个 block里面包含了完整的 bounding box 坐标。block_type 0表示文本块block_type 1表示图片块。坐标单位是 PDF 的点point和页面坐标系一致。有一类特殊情况要注意部分 PDF 的图片不会出现在 block 列表里尤其是作为背景水印的图片或者用 PDF 绘图指令直接画在页面上的矢量图。遇到这种情况建议再用page.get_images(fullTrue)查一遍页面关联的图片对象结合坐标做交叉验证。3.2 图片按区域裁剪和渲染清晰度决定识别上限拿到图片块坐标之后下一个问题是怎么把它变成 Qwen-VL 能吃的输入。这里我踩过一个坑直接用doc.extract_image(xref)提取原始图片二进制分辨率往往不够。因为 PDF 页面里的图片很可能被压缩过或者原始图很小但被拉伸铺满整个版面。正确的思路是用 PyMuPDF 的渲染能力把图片块的矩形区域重新渲染成位图。这样能保证输出分辨率与版面中的显示效果一致识别准确率明显更高。import io from PIL import Image clip fitz.Rect(x0, y0, x1, y1) # 矩阵参数控制缩放倍数2.0 表示放大一倍 pix page.get_pixmap(matrixfitz.Matrix(2.0, 2.0), clipclip) img Image.open(io.BytesIO(pix.tobytes(png)))这里有两个细节值得展开缩放倍数不是越大越好。我实测过 1x、2x、3x、4x 四档大部分图表在 2x 时已经能稳定识别3x 以上提升有限但渲染耗时和内存占用翻倍增长。推荐默认 2x遇到小字号密集表格再单独提升到 3x。长图会被 Qwen-VL 压缩。如果图片块占比特别大比如一张横跨半页的架构图渲染出来的位图尺寸可能超过模型输入上限。建议把最长边限制在 1600 像素左右超出就等比缩放避免模型端自动压缩导致细节丢失。3.3 按版面顺序重排让图片描述插进正确的上下文图片描述本身是有意义的但它必须放在正确的上下文里才有意义。同一页里一张图可能出现在第 1 段和第 2 段之间也可能出现在页尾作为附表。如果粗暴地把图片描述全部追加到页面末尾检索时的相关性就会错乱。我的做法是把该页所有文本块和图片块按y0顶部 y 坐标排序然后按顺序拼接遇到图片块就把它的描述插入当前位置。def page_to_content(page, img_desc_map): blocks page.get_text(blocks) items [] for b in blocks: x0, y0, x1, y1, text, block_no, block_type b items.append((y0, block_type, text, (x0, y0, x1, y1))) items.sort(keylambda x: x[0]) content_parts [] for _, btype, text, bbox in items: if btype 0: content_parts.append(text.strip()) elif btype 1: desc img_desc_map.get(bbox, ) if desc: content_parts.append(f[图片描述] {desc}) return \n.join(content_parts)img_desc_map的 key 是图片块的坐标元组value 是 Qwen-VL 生成的描述。实际项目中建议用 block_no 作为 key因为坐标存在浮点误差直接比较可能匹配不上。这样处理之后一页的内容结构就从文字、图片、文字、图片变成了一段连贯的、图文混合的文本语义上更接近人阅读时的顺序。4. 图片描述生成、切片与混合检索落地4.1 写给 Qwen-VL 的提示词别只说图片里有什么Qwen-VL 能力再强也要看你怎么问。我第一次接入时提示词写的是请描述这张图片结果输出是一堆图中有一个表格表格里有若干行若干列的车轱辘话没有信息量。调试几轮后我总结了一套更适合文档场景的提示词模板你是一名技术文档分析助手。请详细分析这张图片输出以下内容图片类型架构图/流程图/柱状图/表格截图/产品图等图中出现的所有关键文字、数字、模块名称图中的结构关系例如模块之间的连接、箭头方向、层级关系如果是表格请用 Markdown 表格形式还原关键数据一句话总结这张图表达的核心信息。 注意保留原始数据不要自行推断或补充原图没有的信息。实测下来要求输出 Markdown 表格这条非常关键。直接说描述表格模型容易输出概括性语言丢数据要求表格格式后模型会尽量保数据完整性检索时能精确命中关键数字。调用代码用 DashScope 兼容模式OpenAI SDK 直接就能跑from openai import OpenAI import base64 client OpenAI( api_key你的_API_KEY, base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) def describe_image(img: Image.Image) - str: buf io.BytesIO() img.save(buf, formatPNG) b64 base64.b64encode(buf.getvalue()).decode() resp client.chat.completions.create( modelqwen-vl-plus, messages[{ role: user, content: [ {type: image_url, image_url: {url: fdata:image/png;base64,{b64}}}, {type: text, text: PROMPT_TEMPLATE} ] }] ) return resp.choices[0].message.content4.2 切片与元数据检索时能定位到具体页面图文内容合并完成后进入切片环节。这里有个和纯文本 RAG 不一样的要点切片时不能简单按固定长度硬切否则一条图片描述可能被拦腰截断语义完整性受损。我的策略是两级切片第一级按页面内容切。每个页面生成的内容单元作为一个大的文档块。第二级在页面内按段落切。当页面内容长度超过 800 token 时以合并后的文本块为单位切分同时保证每个切片要么完整包含某张图片的描述要么完全不包含。切片时同步写入元数据这是后续定位答案的关键元数据字段说明示例source_file原始 PDF 文件名product_manual.pdfpage_num页码4block_type内容类型text 或 imageimageimage_bbox图片在页面中的坐标(120.5, 300.1, 400.8, 500.2)有了 page_num 和 image_bbox回答生成后可以直接定位到第几页的哪个区域用户翻 PDF 时秒级找到依据体验比纯文字引用好很多。4.3 混合检索与重排的实测对比切片完成之后我把内容向量化存进 FAISS同时保留一份 BM25 文本索引用于混合检索。from rank_bm25 import BM25Okapi import jieba # 向量检索 top 20 vec_hits vector_storage.search(query_embedding, top_k20) # BM25 检索 top 20 tokenized_corpus [list(jieba.cut(doc)) for doc in all_docs] bm25 BM25Okapi(tokenized_corpus) bm25_hits bm25.get_top_n(list(jieba.cut(query)), all_docs, n20) # 合并去重后进 rerank candidates deduplicate(vec_hits bm25_hits) reranked reranker.rerank(query, candidates)为什么要混合检索因为向量检索擅长语义匹配但精确关键词——比如MCU-48、TCP 端口 8080这类编号和参数——BM25 命中率更高。我做了组对比实验三组方案的召回效果差异明显纯向量检索语义相关片段召回好但含偶发参数错误。纯 BM25精确名词召回强但语义近似表达召回差。混合 重排综合表现最稳关键参数命中率明显提升最终答案准确率高出一截。目前我线上用的配置是向量检索取 top 20BM25 取 top 20合并去重后交给 reranker 取 top 5 输入给大模型。这个配置在不同文档集上效果都比较稳定。5. 实测踩坑记录长文档、扫描件与复杂版面5.1 大 PDF 处理管线怎么避免内存暴涨第一次处理 300 页 PDF 时我直接把所有页面渲染结果都留在内存里机器 16G 内存直接爆掉。后来做了三处调整算是彻底解决了逐页处理、逐页释放。循环中处理完一页立即把该页的 pixmap、图片对象、内容单元全部置空不保留跨页引用。限制 Qwen-VL 并发数。同时并发 20 个请求API 端容易出现超时和限流控制在 8 个并发时速度和稳定性平衡最好。渲染结果落盘缓存。图片渲染成位图后按页码和 block_no 命名存到本地缓存目录。同一个 PDF 二次处理时直接读缓存省掉重复渲染的时间。缓存这点特别有用。调提示词时经常要重新生成整批图片描述没有缓存的话每调一次提示词就要重新跑一遍全量渲染一次几十个 PDF 的批次能省下好几十分钟。5.2 扫描版 PDF 的兜底策略扫描版 PDF是这套方案里最考验兜底设计的场景。PyMuPDF 的get_text()在扫描版上返回空字符串文本块列表直接为空但图片块通常还在。此时我做了统一兜底如果某页的文本块数为 0则把整页渲染成位图直接交给 Qwen-VL 做端到端识别。if len(text_blocks) 0: pix page.get_pixmap(matrixfitz.Matrix(2.0, 2.0)) img Image.open(io.BytesIO(pix.tobytes(png))) desc describe_image(img) page_content f[扫描页识别] {desc}扫描版页面的识别提示词和普通图片不同需要额外强调这是一份扫描文档页请还原页面中所有段落、标题和关键数据。因为扫描页经常有手写批注、盖章遮挡提示词里也要加上忽略与正文无关的手写痕迹。这里要注意整页渲染会显著增加 Qwen-VL 的输入消耗建议扫描版单独走一个处理队列别和普通文档混在一起抢并发。5.3 表格和复杂版面误判与失败的真实案例表格识别是图文兼容 RAG 里最难的关卡之一我这里有几个真实案例可以分享。表格误判为图片。PyMuPDF 对部分表格区域会把每一行识别成文本块但也有些跨页大表格会被识别成图片块。如果按图片块处理Qwen-VL 的表格还原能力虽然能兜底但描述长度和 token 消耗都会明显上升。建议对图片块先做一次启发式判断如果图片块宽高比接近表格常见比例且上方或下方 50 点范围内存在表头文本优先尝试合并相邻文本块做结构化表格抽取抽不干净再降级给 Qwen-VL。复杂流程图的方向误判。我遇到过一次 Qwen-VL 把流程图的箭头方向描述反了——A 依赖 B被识别成B 依赖 A。排查下来发现是该图用了曲线箭头、交叉连线多模型单次看图确实容易混淆。缓解办法是把同一个图片块分两次送入模型一次正向、一次反向提示请特别关注箭头方向和依赖关系取两次输出中信息量更完整的一次。多图表并列。一个页面里四张小型柱状图并排PyMuPDF 会把它们识别为多个图片块但坐标之间挨得很近。如果每个图片块单独送 Qwen-VL模型会因视野受限而无法理解四张图之间的对比关系。我的处理是当检测到多个相邻且高度接近的图片块时将它们合并为一个大区域整体渲染后一次识别效果比分开识别好很多。6. 方案能力边界与适用场景判断6.1 什么场景适合这套方案经过半年的线上运行我认为这套PyMuPDF 解析 Qwen-VL 图生成描述的方案在以下场景里表现最好技术手册和产品说明书架构图、接口图、参数表密集图文混排比例高。行业研究报告数据图表、柱状图、饼图占比大文字描述偏概括。合同和投标文件盖章扫描页、带表格附件的混合型 PDF。企业内部制度文档流程图多、带审批节点的规范图的关系比文字本身更值钱。这些场景的共同点是图里藏着关键决策信息如果只做文本 RAG等于让模型闭着眼睛回答看图才能回答的问题。6.2 什么时候不必硬上图文识别反过来我也踩过一些过度设计的坑。有些文档图占比极低或者图片只是装饰性配图这时引入 Qwen-VL 反而增加了处理耗时和成本。判断标准很简单先抽样 5 页数一下图片块里有多少是信息型图片包含数据、结构、逻辑关系如果占比低于 10%纯文本 RAG 就够了。另外这套方案不适合处理超大批量的低质量扫描件。扫描件渲染整页后Qwen-VL 的输出质量受原始扫描清晰度影响很大模糊扫描件的识别结果会带幻觉比不做识别更危险。这类文档我建议优先用户外专门的扫描优化流程而不是直接进 RAG 管线。6.3 后续可以扩展的方向这套方案本身是模块化的后续扩展我留了几个口子知识图谱融合图片描述中的模块 A 通过协议 B 连接到模块 C这类关系可以进一步用抽取模型转成三元组喂给图数据库支撑图谱问答。当前已经有相关实践在推进效果上能补足纯 RAG 在多跳推理上的短板。分段模型选择普通图片用 qwen-vl-plus复杂表格和精密工程图切换到更强的 qwen-vl-max成本与精度按线路分流。增量索引PDF 文档经常更新版本我现在只做全量重建。做增量的话需要把图片内容的 hash 作为内容指纹版本更新时只处理变化页能大幅节省带宽和算力。方案跑到现在我最大的感受是RAG 的瓶颈往往不在模型侧而在输入侧的数据工程。PyMuPDF 把页面里文字和图片的组织关系完整暴露出来Qwen-VL 恰好补齐了看懂图这块拼图两者配合才让 PDF RAG 真正做到了图文兼容。对正在被检索结果缺图、答案找不到依据困扰的朋友这套方案可以直接作为起点按文中管线搭一遍再根据自己文档的特点调优就行。