前阵子在整理一批技术手册类 PDF 时我遇到一个很典型的场景几十页文档里既有大段说明文字又有架构图、流程图和参数表格。按以前的常规做法直接用解析库抽完文本就扔进向量库检索结果总觉得不对劲。问“架构里网关后面接的是哪几个服务”模型答得牛头不对马嘴。仔细排查后发现答案其实清清楚楚画在第 3 页的架构图里只是文本抽取时把图里的标注全丢了。这就是图文混排文档在 RAG 场景下的经典痛点。今天想分享的这套基于 PyMuPDF 和 Qwen-VL 的 PDF RAG 方案就是专门解决这类问题的。核心思路不复杂PyMuPDF 负责把 PDF 解析成可定位的文本块、图像和版面结构Qwen-VL 负责对图像内容做视觉理解并结构化成可检索的文本描述两者结合后进入向量检索链路。这套方案适合处理手册、讲义、论文、带截图的技术文档也适合想从“纯文本 RAG”升级到“多模态 RAG”的工程实践者参考。1. 为什么我要做图文兼容的 PDF RAG1.1 传统 PDF RAG 的先天不足先聊聊“RAG 瓶颈”这个话题。很多人把 RAG 效果不好归咎于向量模型不够强或者大模型理解能力差但我在实际项目里的感受是一半以上的 badcase 死在解析这一层。知识库里的 PDF 文档一旦涉及图文混排传统“PDF 转文本”的链路就非常脆弱。拿 PyMuPDF、pdfplumber 这类工具直接抽文本能拿到的是文字块本身但拿不到“这张图旁边的文字是它的注释”“这个表格的标题在上一行”这类版面语义。架构图里的服务名、流程图里的判断条件、截图里的告警信息在文本层要么完全消失要么被抽成一堆乱序的碎片。更麻烦的是文档里常见“图片被切成上下两半”“表格跨页”这类情况纯文本抽取会把语义割裂得七零八落。而如果换一个方向把所有页面都渲染成图片再交给视觉模型去理解又会带来两个新问题。一是成本暴涨上百页的 PDF 每一页都走一遍视觉模型的推理费用和延迟都很难接受二是精度不均衡大段密集文字的页面用视觉模型去 OCR 转写出错率反而比直接用文本抽取更高。所以最合理的方式不是二选一而是把两种能力组合起来各管一段。1.2 PyMuPDF Qwen-VL 组合的定位为什么选 PyMuPDF而不是常见的 pdfplumber 或 Apache PDFBox我的使用体感是PyMuPDF 在“版面解析”和“图像渲染”上综合能力最强。它的fitz模块能拿到文本块在页面上的精确坐标能枚举页面里嵌入的图片对象也能把任意页面渲染成高分辨率 PNG。这三个能力恰好是图文兼容 RAG 需要的三大基础定位文本、抓取图像、渲染版面。Qwen-VL 在这个方案里的角色是“视觉理解引擎”。它不是用来替代 OCR 的而是用来理解图像内容、把图像转写成结构化描述。比如一张架构图Qwen-VL 能输出“网关 → 认证服务 → 业务服务”这样的语义链一张数据报表截图它能按表格结构转写成 markdown。这些描述会被当成一种特殊的“文本块”进入向量库与正文文本块一起参与检索。这个组合的定位说白了就是一句话文本的归文本图像的归视觉模型。PyMuPDF 做外科手术级的版面切分Qwen-VL 做图像内容的语义翻译两者配合出的效果远好于单靠任何一种方案。同时这也回应了搜索里常被问到的“rag知识库和结构知识库怎么区分”——RAG 知识库和 KG 知识库不是替代关系图文解析的产物天然适合先做 RAG 再做知识图谱抽取后面我会讲到这一步的扩展思路。2. 整体架构与核心设计思路2.1 解析链路的拆分原则我搭这套系统的时候最核心的一个设计原则是解析链路必须分层每一层只负责一件事。第一层是 PyMuPDF 版面解析。获取每一页的文本块、图片块、表格区域坐标同时把整个页面渲染成高清图。第二层是块级路由。判断一个区域是纯文本、纯图片还是图文混排块文本直接走文本清洗图片块裁剪出来交给下一层。第三层是 Qwen-VL 图像理解。对裁剪出来的图片生成结构化描述必要时配合版面坐标把附近的文本也拼进提示词让视觉模型“看图识字”。第四层是索引与检索。文本块向量化和图像描述向量化进入同一个向量库检索阶段做融合召回。这个拆法有几个明显好处。一是容错率高任何一层出问题都可以单独重跑比如 PyMuPDF 解析漏了一张图只需要重新跑图像提取不需要把整个文档重新灌一遍。二是成本可控纯文本页根本不需要调用视觉模型只有真正含图的页面才消耗视觉推理资源。三是后续扩展方便如果以后想换更强的视觉模型只需要替换第二层和第三层的实现向量库和检索链路完全不用动。2.2 切块、多模态映射与索引策略切块策略直接影响检索效果。我在处理图文混排文档时没有采用常见的固定字符数切块而是走“版面感知切块”先拿到 PyMuPDF 输出的块级坐标再按视觉区域做合并。一个自然段落、一张图及其图注、一个表格及其标题会被合并成同一个“语义块”。这样切出来的块比按 token 数硬切要合理得多检索时命中上下文也更完整。索引策略上我建了两类索引放在同一个向量库里。第一类是文本块向量直接用文本 embedding 模型生成第二类是“图像描述文本”向量用 Qwen-VL 输出的描述生成。每个向量都带着同一套元数据文档 ID、页码、块类型、块坐标。这样在检索阶段既能召回正文内容也能召回“由图像转写而来”的内容。另外还做了一版“文本-图像对齐映射表”用 PyMuPDF 的坐标信息把正文文本块和同页图像块做关联。用户问的问题如果命中了文本块我可以顺带把同区域图像的描述也拉进来拼进上下文提高回答完整性。这个设计其实已经有一点点“多模态融合检索”的雏形了后面做知识图谱抽取时这个映射表也能直接当关系抽取的输入。3. PyMuPDF 解析与版面定位实操3.1 文本块、图像与表格的取出PyMuPDF 的fitz.open()打开文档后最常用的是page.get_text(dict)它能返回带坐标的文本块结构。每一块里有bbox文本框坐标、lines行信息、spans字符片段信息。我一般取块级数据就够了不需要细到 span 级别。文本块按坐标从上到下、从左到右排序后基本能还原版面阅读顺序。图像提取用page.get_images(fullTrue)拿到的是嵌入在 PDF 内部的图像对象。注意这里有个坑get_images返回的图像未必直接显示在页面上可能是被引用但被裁剪或覆盖的图。所以我通常会结合page.get_image_rects(xref)来确认图像实际渲染在页面上的位置只有rect非空的才保留。坐标信息是后续从页面上裁剪图像的依据。表格处理是另一个麻烦事。PyMuPDF 本身没有专门的表格识别接口但它有page.find_tables()新版加入了 PDF table 检测能返回表格的行列结构。不过我用下来感觉它对复杂表头的支持还不够好所以更常见的做法是先用find_tables()拿到表格区域坐标再把这个区域渲染成图片交给 Qwen-VL 转成 markdown 表格。这个策略在多种版式下都比较稳。3.2 页面渲染与区域截图GPU 渲染和区域裁剪是图文 RAG 的关键技术活。渲染整页我用的是page.get_pixmap(matrixfitz.Matrix(2, 2))这个Matrix(2,2)表示 2 倍缩放相当于把 PDF 默认的 72 DPI 提到 144 DPI。实测下来 2 倍缩放对大多数印刷体文档够用但遇到字体偏小或图片精度要求高的文档建议直接上Matrix(3, 3)截图里的中文边缘会更锐利后续交给 Qwen-VL 识别时准确率也能上来一点。区域截图用page.get_pixmap(cliprect)rect可以是fitz.Rect(x0, y0, x1, y1)坐标值从前面解析出来的块坐标里直接拿。这里有一个坐标系比例问题必须提醒PyMuPDF 的坐标单位是 PDF 点渲染成 pixmap 后会乘以缩放系数。比如用Matrix(2,2)时原坐标Rect(100, 100, 200, 200)对应到 pixmap 里就是(200, 200, 400, 400)。如果直接用原坐标去clip截出来的图会偏左上内容截不全。实际操作中我是把clip直接传原坐标PyMuPDF 内部会按 matrix 自动换算但如果你自己用 PIL 二次裁剪就一定要手动乘以缩放系数。每个图像区域截图后我还会把该图像所在的页面编号、区域坐标、同一页最近的文本块坐标打包记录存成一个image_block元组。这一步是后面调用 Qwen-VL 的输入材料也是建立图文对齐关系的基础。建议这一步就顺手把“图片是独立图还是与正文嵌入同一区域”的判断做了如果图像 bbox 和某些文本块 bbox 有交集就把这些文本一并保留后续拼进 VLM 提示词里。4. Qwen-VL 理解与结构化的接入细节4.1 提示词模板与输出结构设计Qwen-VL 调用质量的高低一半取决于提示词怎么设计。我试过几版提示词最稳定的模板是“角色定义 任务描述 输出约束 额外上下文”四段式。角色定义明确告诉模型它是“文档版面分析助手”任务描述要求它详细描述图片里的内容尤其强调“把图中出现的文字、关系、流程、表格数据全部输出”输出约束规定格式比如“如果图片是架构图或流程图输出为 Mermaid 风格文本如果是表格截图输出为 markdown 表格如果是普通插图输出为自然语言描述”。额外上下文则把 PyMuPDF 从该图片附近提取的正文文字拼接进去让模型参考正文语境理解图片。输出结构我强制要求 JSON字段包括image_type图类型、summary一句话概括、structured_content结构化转写内容、text_mentions图中出现的所有关键文本。这样做的好处是后续解析稳定可以直接把structured_content和text_mentions拼成一个描述字符串作为图像块的 embedding 输入。结构化输出还有个额外优势如果想做 KG 知识库structured_content里的“A 指向 B”这种关系可以直接被后续的信息抽取链路利用这和热词里提到的“ontology rag / kg知识库”是天然衔接的。4.2 接口配置与调用治理接口配置上我走的是 OpenAI 兼容的 vLLM 部署方式。用vllm serve起一个 Qwen-VL 的 OpenAI 兼容服务base_url指向本地服务地址model填 Qwen-VL 的模型名。如果你不想本地部署也可以直接用阿里云 DashScope 的兼容接口本质是一样的。我用本地部署的原因是文档量大、后续还要批量跑历史 PDF走 API 成本不好控。批量调用时一定要做调用治理。先说最常见的坑并发数过高会把 GPU 显存打满或者直接把服务压垮。我踩过一次之后定了规矩max_workers4每张图调用前先检查图片尺寸长边超过 1568 像素先压缩因为 Qwen-VL 对超大图会做缩放过大的图反而容易丢失细节。超时设置 60 秒失败自动重试 2 次两次失败就跳过这张图并把日志打出来。延迟方面单张图的推理时间大约在 1.5 到 5 秒之间取决于图像复杂度和 GPU 型号。如果文档量大我建议加一个“图片去重缓存”同一文档里相同 xref 的图片只调用一次 Qwen-VL描述结果复用。很多手册里 logo、背景图、重复出现的示意图会占用不少视觉调用额度这个缓存能省下相当一部分成本。5. 图文混排的 RAG 检索链路实现5.1 向量化与存储向量化分为两条线。纯文本块我用的 embedding 模型是bge-large-zh-v1.5这个模型对中文长文本的支持比较稳并且对技术术语的拟合度不错。图像描述文本块也走同一个 embedding 模型因为 Qwen-VL 输出的描述已经是中文文本不需要额外的多模态对齐模型这样整体链路更简单也更容易维护。存储方面我选了 FAISS主要看中它轻量、好部署、单机够用。如果文档规模上到百万级向量再考虑 ES 或专门的向量数据库。FAISS 索引我建了两类text_index存纯文本向量image_desc_index存图像描述向量。两类向量的维度一致都是 1024 维。每个向量存对应的 doc_id、page_num、chunk_id、chunk_type以及原文文本或图像描述文本检索到之后拿出来直接拼上下文。切块大小和重叠窗口也要说一句。版面感知块因为已经是语义完整的单位我不再按 token 切碎直接以“块”为最小检索单元。如果某个块特别长比如一整页的文字被合并成一个块检索时可能会出现关键词被长文本稀释的问题。这种情况我用两级策略建立块内的段级子索引检索时先粗召回顶层块再用子索引定位到具体段回答时把块内相关段落拼接作为上下文。5.2 召回、融合排序与问答生成检索阶段不是简单地“查到一个向量就完事”。我实现了一个轻量级的融合流程用户问题进来后先同时查询text_index和image_desc_index各自召回 top-k 结果。文本查询用向量相似度同时叠加 BM25 关键词得分做线性融合因为纯向量检索在精确关键词匹配上经常不如 BM25。图像描述索引则主要靠向量相似度。两个索引的结果合并后用bge-reranker-large做交叉排序。重排序这一步很值得加实测能让有效命中率提升 15% 以上。问答生成阶段上下文拼装遵循“先文本后图像描述再原文引用”的顺序。文本块内容放在最前面图像描述紧跟其后每一段前面标注来源页码。Prompt 里明确要求模型优先基于提供的上下文回答并引用页码。这套设计也解决了“RAG 回答容易东拼西凑”的问题——因为图文描述都被强制标注了来源块模型被约束在文档语义范围内作答幻觉率明显下降。多说一个细节检索结果里如果同时出现文本块和同页图像描述我会做一个“同页合并”操作把它们拼成一个复合上下文块再放入 prompt。这一步避免了模型看到“前半段文本 后半段文本描述但中间缺图示说明”的割裂感对架构图、流程图类文档尤其重要。6. 实战中遇到的常见问题与避坑清单问题一区域截图里中文变成乱码。这个现象多半不是 Qwen-VL 的锅而是渲染环节没有正确嵌入字体。PyMuPDF 在渲染某些 PDF 页面时会遇到字体缺失或字体子集化失败。解决办法有两个方向一是安装文档用到的字体到系统字体目录二是渲染时用page.get_pixmap(matrixfitz.Matrix(3, 3), alphaFalse)禁用透明通道有时能绕过部分渲染异常。如果乱码只出现在特定页面先渲染成高分辨率图后再用 PIL 转成 RGB再交给 Qwen-VL能解决大部分字体渲染问题。问题二图像检测漏图。get_images(fullTrue)拿到的图像对象数量不少但真正渲染在页面上的只是一部分。我排查时发现有些图被放在 PDF 的资源对象里但显示时被clip裁剪有些图其实是平铺背景直接过滤。过滤规则是只保留page.get_image_rects(xref)返回非空、且 rect 尺寸大于 32x32 像素的对象。小于这个尺寸的通常是 logo 或装饰线喂给视觉模型只会浪费调用额度。问题三Qwen-VL 返回内容不可解析。偶尔接口会返回非 JSON或者模型输出里带了额外文字。我的处理是在解析层做两层容忍先用正则从模型中提取 JSON 片段如果提取失败直接把raw_output当作structured_content兜底。还有一个经验是提示词里的“只输出 JSON”不如“输出一个 JSON 对象key 包括 image_type、summary、structured_content、text_mentions”有效因为给定了具体 key 之后模型更不容易跑偏。问题四表格跨页被切成两半。这个比较难处理。我的方案是检测表格区域与页面底部边界的重叠情况如果表格 bbox 底部越过页面高度的 90%就把下一页的表格区域也切出来然后在调用 Qwen-VL 时把两个半截图拼成一张长图再输入。拼图时要注意图片高度可能超出模型限制通常先缩放到宽高比合适再压缩宽度。这个方法对表格类 PDF 效果提升很明显。问题五检索时图文块互相干扰。有时候图像描述文本和正文文本意思相近向量检索会把同一页的多个块同时召回导致上下文冗余。我在排序阶段加了去重逻辑同页码的召回块如果文本相似度超过 0.85只保留相似分最高的一条。这个阈值是试出来的太低会误删有效信息太高又起不到去重效果。问题六长文档批量处理速度慢。瓶颈主要在 Qwen-VL 调用。文档里如果有很多重复的边框、图标会拉低整体效率。我给每类图片加了“基础类型分类”前置过滤用 PyMuPDF 的绘图形状信息判断这个区域是否只是装饰性图形是的话直接跳过视觉调用。这个前置分类能过滤掉约 20% 的不必要调用处理速度提升明显。最后再分享一个我踩过几次坑才总结出来的经验如果只是想让 PDF RAG “能用”PyMuPDF 抽文本就够了但要是想让它在图文混排场景下“好用”视觉模型这一步一定不能省。尤其处理手册、课程讲义、带截图的技术文档时图文兼容不是加分项而是刚需。我强烈建议在切块元数据里保留“页面索引”回答问题时把来源页码贴在上下文里用户体验会好非常多。这段时间我还在试验把 Qwen-VL 输出的结构化内容和文档本身的文本块映射成一张简单的知识图谱关系表再结合图谱做混合召回方向已经有雏形了等稳定跑通之后再单独整理一篇出来。