做这套图文兼容的 PDF RAG 方案起因是我最近在整理一批混合型文档——里面有扫描件、有带文本层的页面、有大量图表和复杂表格。用常规的 PDF 解析 向量化管线跑了几天检索效果一言难尽文字段落能召回但问到“这个趋势图的转折点在哪”或者“这张表格里第三季度的环比”就彻底断电。后来我把 PyMuPDF 的版面解析和 Qwen-VL 的视觉理解接进来走了双通道的思路才把这类问题压下去。这篇文章就把这套方案的完整设计、落地代码、参数选择和踩坑复盘一次讲透。先说清楚这套方案适合谁手头有 PDF 需要做知识库问答、文档检索增强生成且文档里图表和扫描页占比不低的工程师或者你已经在跑 RAG但被 PDF 解析质量卡住想找一个低成本升级路径的同学。它不依赖昂贵标注数据核心就两件事——用 PyMuPDF 把页面拆成带坐标的语义块再用 Qwen-VL 对非文本区域做结构化描述最后把“文本通道”和“视觉通道”统一进向量库。下面我按决策过程、架构设计、具体实现、问题排查的顺序来写。1. 为什么纯文本思路做不好 PDF RAG1.1 传统 PDF 解析的三个致命盲区做 RAG 的人最容易被“PDF 里明明有文字为什么检索不到”这句话逼疯。我归纳下来纯文本解析通常死于三种情况。第一是分栏和阅读顺序错乱。PDF 的文本层是按块存储的双栏论文页在三栏排版的杂志上经常被切得七零八落。PyMuPDF 提取出来的 block 顺序如果直接用你会发现一句话的主题在第一栏它的下文跑到第二栏向量化之后两段内容被拆成了互不相关的碎片。第二是图表内容在文本层里根本不存在。折线图、柱状图、UML 图、架构图在 PyMuPDF 的 get_text() 眼里就是一页空白最多抓到几个图例文字。你问“这个方案的平均延迟是多少”答案在图表里但文本层检索不到召回率为零。第三是扫描件完全没有文本层。这类 PDF 本质是图片集合你需要 OCR而传统 OCR 对公式、密集表格、水印干扰的鲁棒性很一般识别完还会引入错别字噪声。1.2 PyMuPDF 能解决什么解决不了什么PyMuPDFfitz是我在 PDF 解析层面用得最顺手的一个库不因为别的就是它能把“文本内容”和“空间位置”绑定到一起。page.get_text(dict) 返回的 block 结构里每个块都带 bbox也就是矩形坐标。有了坐标你就可以做版面切割把页面切成左栏、右栏、标题区、图表区你可以判断两个 block 是否属于同一个语义段落你还可以把某一小块区域渲染成高清图片。这个“坐标到区域”的能力是后面视觉通道能够精准裁剪的前提。但 PyMuPDF 自己不理解图像语义。它知道这张图在哪个位置不知道图里画的是什么趋势它知道这有个表格框线但提取出来的文本顺序和单元格对应关系经常是乱的。所以我的结论是PyMuPDF 负责“把页面拆得清楚”Qwen-VL 负责“把看不懂的区域说清楚”两者是互补关系不是替代关系。1.3 Qwen-VL 在这个场景里的定位选择 Qwen-VL 而不是传统 OCR 或者单纯用文本解析核心原因是语义密度。OCR 只能把像素变成文字但复杂图表里最重要的不是每个字而是“图表的结论”。比如一张销售趋势图OCR 能识别出横纵轴标签和几个数值但回答不了“整体趋势在哪个阶段加速”。Qwen-VL 这类多模态模型能做到的是把整张图作为一个整体理解输出“该图展示 2020 至 2024 年营收变化整体呈上升趋势2022 年增速明显放缓2023 年起恢复增长。”这种描述放进向量库里检索质量完全不一样。但我必须提醒视觉模型不是免费的午餐。它推理慢、token 贵而且会编造细节。你不能把每一页都整页丢给 Qwen-VL否则成本爆炸幻觉也爆炸。方案里要做“精准裁剪、按需启用”只让视觉模型看它该看的图。2. 双通道架构的整体设计2.1 核心设计理念文本和图像分开处理统一索引我把整个链路定义成两个并行通道。文本通道用 PyMuPDF 提取文本块按空间位置合并分栏过滤页眉页脚噪声切分成块然后向量化。视觉通道用 PyMuPDF 检测非文本区域图片、表格、复杂版面按 bbox 裁剪成子图送入 Qwen-VL 生成结构化描述再把“描述文本”作为该区域的文本表示向量化。两条通道产出的节点最后都写入同一个向量集合但节点元数据里标记source_type: text或source_type: vision。检索的时候同时命中两条通道混合召回后再交给生成模型。用一句话概括文本通道保底视觉通道补全。为什么这样做因为排版分层。以常见的技术文档为例一个页面的信息密度往往是这样的段落文字大概占 60% 面积但信息量占比很高图表和表格占 40% 面积传统管线的信息占比接近零。双通道的目的不是把两张结果简单叠加而是让每一平方厘米的版面信息都能被“翻译”成一个可检索的文本节点。2.2 技术选型的备选考量可能有人问这套方案的每一步都有替代品为什么偏偏选这两件PDF 解析这一步可选的还有 pdfplumber、pdfminer.six、camelot、PyMuPDF。pdfplumber 对表格提取做得精细但在坐标体系、图像渲染上绕很多弯camelot 依赖 OpenCV安装重而且只在规整表格上表现好。PyMuPDF 的优势是同时提供文本提取、布局坐标、页面渲染、区域裁剪API 统一一个大文件全部搞定。这是它作为“底座”的最大理由。视觉理解这一环可选的也有 GPT-4o、InternVL、MiniCPM-V。选 Qwen-VL 是因为它在中文文档上的理解能力和可控的本地部署成本同时在函数调用和结构化输出上有比较成熟的 prompt 兼容性。2B 和 7B 的模型如果只是用来做图表描述显存压力比部署一个满血大模型小很多。如果你要用在线 API流程一样只是把本地推理换成 HTTP 调用。2.3 从 PDF 页面到可检索节点全流程总览我把流程拆成五个阶段每个阶段有明确的输入输出。页面解析阶段输入 PDF 路径输出页面对象列表以及每个页面的文本块列表和图像块列表。区域切分阶段根据文本块的 bbox 和图像块的 bbox判断重叠关系决定哪些区域要送去视觉模型。视觉描述阶段对选中区域进行高清渲染构造提示词调 Qwen-VL得到 JSON 格式的描述。节点组装阶段把纯文本块和视觉描述各自封装成 Node附加元数据页码、坐标、来源类型、标题层级。索引与检索阶段向量化全部 Node建立索引查询时混合召回。这张总览图式的框架后面每一章都是其中一环的具体展开。值得强调的是阶段 2 的“区域切分”是最容易做砸的因为 bbox 是否重叠、裁多大的边距、以什么规则判定“这属于一个表格”都需要针对文档实际情况微调。我在下一节给出一个比较稳的默认策略。3. 核心细节解析与实操要点3.1 PyMuPDF 文本块提取用 dict 模式而不是 get_text()先看最基础的代码提取文本块并保留坐标。import fitz def extract_text_blocks(page): blocks page.get_text(dict, flagsfitz.TEXTFLAGS_TEXT)[blocks] results [] for block in blocks: if block[type] ! 0: continue bbox block[bbox] lines block[lines] block_text for line in lines: for span in line[spans]: span_text span[text].strip() if span_text: block_text span_text block_text \n if block_text.strip(): results.append({ bbox: bbox, text: block_text.strip(), block_no: block[number] }) return results注意几个点。TEXTFLAGS_TEXT会过滤掉一些隐藏文字避免把 PDF 里不可见的注释文本带进来。按 span 拼 text 时不要只拼 line 的text字段因为某些字体编码可能导致该字段为空而 span 层是最可靠的最小单位。另外一个页面上可能有几十个 block但有些 block 是页眉页脚后面需要用规则剔除。这里“为什么”要说清楚get_text(dict)返回的是完整结构化的 block-line-span 三级结构而get_text(text)只给你纯字符串。纯字符串看起来简单但你丢掉了坐标后面想做分栏合并、区域裁剪就完全没抓手。坐标是这套方案的元数据命脉。3.2 分栏合并策略按 x 坐标做阅读顺序重排双栏页面的 block 顺序是乱的直接拼会有问题。我的策略是先按 bbox 的水平中心 x 坐标做一次聚类把页面分成若干栏然后按“从上到下”的顺序输出再对每个栏内部按 y 坐标排。代码思路如下def sort_blocks_for_reading(blocks, page_width): # 先粗分类左栏(x0 页宽的一半)右栏(x0 页宽的一半) left [b for b in blocks if (b[bbox][0] b[bbox][2]) / 2 page_width / 2] right [b for b in blocks if (b[bbox][0] b[bbox][2]) / 2 page_width / 2] left.sort(keylambda b: b[bbox][1]) right.sort(keylambda b: b[bbox][1]) return left right这只是一个基础方案遇到三栏或者更复杂的浮动布局可以用 KMeans 对 block 中心点 x 坐标聚类栏数设为 2 或者 3然后按聚类中心排序。实际效果上双栏学术论文这个策略足够用。这个步骤的价值在于顺序对了分块才是连续的分块连续了向量语义才有上下文。3.3 图像区域识别如何找到“该给视觉模型看的东西”判断一块区域是否需要走视觉通道我总结了三条规则按优先级判断。该区域是嵌入图片PyMuPDF 的 dict 输出中 type 为 1 的 block 是图片块直接提取 bbox。该区域是表格或其他复杂对象当前版本 PyMuPDF 有page.find_tables()可以直接返回表格位置尤其适合线框明显的表格。该区域内文字块之间间隔稀疏、且包含大量空白这种情况通常是只有几个图注文字的图表区域文本通道信息量极低。实际代码里我把规则 1 和规则 2 的 bbox 汇总再去重再与文本块 bbox 做交集判断。如果某个文本块几乎完全落在图片块的 bbox 内部那这个文本块大概率是图内嵌文字没必要重复进文本通道。合并之后的区域列表就作为视觉通道的原始输入。3.4 区域裁剪与高清渲染一个必须仔细处理的坐标换算PyMuPDF 的 bbox 坐标系和渲染出的图片像素坐标系不是一回事这是新手最容易掉进去的坑。PDF 默认坐标系原点在页面左上角单位是点point1 点 1/72 英寸。当你用get_pixmap(matrixfitz.Matrix(zoom, zoom))渲染图片时缩放因子 zoom 决定像素尺寸zoom 为 2 表示 144 DPI3 表示 216 DPI。裁剪图片时pdf_bbox 的四个值都要乘以 zoom 才是像素坐标。from PIL import Image import io def crop_region(page, bbox, zoom2.0): mat fitz.Matrix(zoom, zoom) pix page.get_pixmap(matrixmat, alphaFalse) img Image.open(io.BytesIO(pix.tobytes(png))) x0, y0, x1, y1 bbox # 注意裁剪坐标必须取整 crop_img img.crop((int(x0 * zoom), int(y0 * zoom), int(x1 * zoom), int(y1 * zoom))) return crop_img这里给个实操经验缩放因子不要低于 2.0。我做过一组对比zoom1.0 时 Qwen-VL 对图内小字体的识别明显变差zoom2.0对应 144 DPI 渲染是一个质变拐点再往上提高到 3.0对识别小字号数字有帮助但耗时上升明显。如果你的文档里有很多数据密集型表格建议对表格区域单独用 zoom3.0 渲染而不是整页 3.0。3.5 Qwen-VL 提示词与结构化输出视觉模型最忌讳的提示词是“描述这张图片”。你要给出格式、给出角色、给出约束最好让它输出 JSON。我的默认模板这样写VLM_PROMPT 你是一个专业文档理解助手。请分析这张来自技术文档的截图完成以下任务 1. 判断内容类型figure(图表/示意图)、table(表格)、code(代码块)、other 2. 用中文概括这段内容的主题和关键信息要求逻辑完整覆盖所有可见的数值、结论、变化趋势。 3. 如果其中有数字必须保留原数字如果内容不清晰请说明不确定不要猜测。 严格输出 JSON 格式不要包含额外说明 {type: ..., summary: ..., key_points: [..., ...]} 调用 Qwen2.5-VL 系列模型时注意构建 messages 的方式。当前 transformer 版本推荐用 processor 直接处理图像和文本from transformers import Qwen2VLForConditionalGeneration, AutoProcessor model Qwen2VLForConditionalGeneration.from_pretrained( Qwen/Qwen2.5-VL-3B-Instruct, torch_dtypeauto, device_mapauto, ) processor AutoProcessor.from_pretrained(Qwen/Qwen2.5-VL-3B-Instruct) def describe_region(crop_img, promptVLM_PROMPT): messages [ {role: user, content: [ {type: image}, {type: text, text: prompt} ]} ] text processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) inputs processor(text[text], images[crop_img], return_tensorspt) inputs inputs.to(model.device) generated_ids model.generate(**inputs, max_new_tokens512) output processor.batch_decode( generated_ids[:, inputs.input_ids.shape[1]:], skip_special_tokensTrue )[0] return output生成结果用json.loads解析解析失败时加一层容错把输出里被 包裹的 JSON 部分提取出来再解析。这个容错必须做因为模型偶尔会多输出几句废话。关于模型尺寸的选择我用 3B 部署在一张 16G 显存的卡上单图推理大概 1.5 到 2 秒如果你有 7B 或更大型号质量会更好但成本线性上升。我的建议是先跑通 3B确认整条链路没问题再按需升级。4. 实操过程与完整代码实现4.1 环境准备与依赖清单我的运行环境是 Python 3.10 CUDA 12.1显存 16G。依赖如下pip install pymupdf pillow transformers sentence-transformers faiss-cpu accelerate说明一下每个库的位置pymupdf 负责解析和渲染pillow 负责图像裁剪和转换transformers 负责加载 Qwen-VLsentence-transformers 负责文本和描述向量化faiss 负责索引检索。向量模型的选型我用的 BAAI/bge-large-zh-v1.5 它对中文长文本效果稳定而且带查询指令前缀的用法能提升匹配精度。如果你处理的文档主要是英文可以用 bge-large-en-v1.5混合语料建议分开建索引。4.2 文档解析模块把 PDF 变成区域节点列表整个解析模块的入口函数抽象成下面这样import fitz import re PAGE_HEADER_FOOTER_KEYWORDS [第, 页, 共, 版权所有, 目录] def parse_pdf_to_nodes(pdf_path, dpi144): doc fitz.open(pdf_path) nodes [] for page_idx, page in enumerate(doc): text_blocks extract_text_blocks(page) # 过滤页眉页脚要么高度太靠边要么包含关键词 filtered_blocks [] for block in text_blocks: bbox block[bbox] if bbox[1] 40 or bbox[3] page.rect.height - 40: continue if any(kw in block[text] for kw in PAGE_HEADER_FOOTER_KEYWORDS): continue filtered_blocks.append(block) # 重排阅读顺序 ordered_blocks sort_blocks_for_reading(filtered_blocks, page.rect.width) # 段落合并当两个块之间的垂直间距小于某个阈值时合并 merged_blocks merge_close_blocks(ordered_blocks, page_heightpage.rect.height) for block in merged_blocks: if is_likely_figure_area(block, page): crop_img crop_region(page, block[bbox], zoom2.0) desc describe_region(crop_img) nodes.append({ text: desc, page: page_idx, bbox: block[bbox], source_type: vision, }) else: nodes.append({ text: block[text], page: page_idx, bbox: block[bbox], source_type: text, }) return nodesmerge_close_blocks 是这个模块里最需要调参的部分。我把它定义成“如果当前块和前一个块在同一栏内且两者 y 方向间距小于当前块行高的 0.6 倍就合并”这可以避免把一个自然段切成两半。阈值设置需要观察你的文档排版不同文档差异会很大建议处理一批后打印合并结果人工抽查。4.3 向量化与索引构建混合节点的统一处理拿到节点列表后统一走向量化。这里有一个小技巧文本通道的节点和视觉通道的描述在向量化时可以用不同的 query instruction。具体来说bge 模型在检索时习惯给 query 加指令给 document 不加指令。如果你把视觉描述也当作 document 处理直接用 encode 就行。但如果你的检索 query 往往是对图表的自然语言提问比如“2023 年营收是多少”它和视觉描述文本的语义空间可能存在一点偏移。为了尽量对齐我在索引时对视觉描述文本做一次轻量改写让它更接近于“查询答案”的形态。这不算标准做法是我在实测中发现比较好用的小技巧。from sentence_transformers import SentenceTransformer model SentenceTransformer(BAAI/bge-large-zh-v1.5) def embed_nodes(nodes): texts [] metadatas [] for node in nodes: texts.append(node[text]) metadatas.append(node) embeddings model.encode(texts, normalize_embeddingsTrue) return embeddings, metadatas索引文件我直接用 faiss。IndexFlatIP 足够支撑十万级别节点不需要上 IVF。构建索引import numpy as np import faiss embeddings, metadatas embed_nodes(nodes) embedding_dim embeddings.shape[1] index faiss.IndexFlatIP(embedding_dim) index.add(embeddings.astype(float32)) faiss.write_index(index, doc_index.faiss) # 元数据存 jsonl方便检索时回溯 import json with open(doc_meta.jsonl, w, encodingutf-8) as f: for meta in metadatas: f.write(json.dumps(meta, ensure_asciiFalse) \n)注意IndexFlatIP 要求向量已经做过归一化所以 encode 时要加normalize_embeddingsTrue否则内积分数没有意义。这一步很多人漏导致排序结果不可解释。4.4 检索与生成混合召回和上下文构造检索的逻辑分三步query 向量化、top-k 召回、按类型加权重排。加权重排是我针对图文混合场景强加的一步。因为视觉通道的节点数量天然少于文本节点如果不加权最终 top-k 里几乎全是文本节点图表的描述很难被选中。我给视觉节点一个 1.2 倍的得分加成这个数字是经验值你可以通过验证集调优。def search(query, k8, vision_weight1.2): q_emb model.encode(query, normalize_embeddingsTrue) scores, indices index.search(q_emb.reshape(1, -1).astype(float32), k * 2) results [] for i, score in zip(indices[0], scores[0]): meta metas[i] final_score score * vision_weight if meta[source_type] vision else score results.append({meta: meta, score: final_score}) results.sort(keylambda x: x[score], reverseTrue) return results[:k]如果这一步之后你发现检索结果里同一页重复内容太多可以做一轮 MMR最大边际相关性去重。MMR 的实现不复杂但能明显提升生成质量核心逻辑是每次选择与 query 相关分数高、且与已选结果相似度低的节点。我在演示里没有放完整代码但建议线上系统加上。最终生成部分用 Qwen2.5-7B-Instruct 或者任何你本地部署的开源模型都可以。模板如下def build_prompt(query, retrieved_nodes): context_parts [] for i, node in enumerate(retrieved_nodes): src 图片描述 if node[meta][source_type] vision else 正文段落 context_parts.append( f[{i1}](来源:{src}, 页:{node[meta][page]})\n{node[meta][text]} ) context \n\n.join(context_parts) prompt f请根据以下参考资料回答问题。如果参考资料中没有相关信息请明确回答“资料中未找到”。回答时请标注引用的参考编号。 参考资料 {context} 问题{query} 回答 return prompt这步要提醒视觉描述是 Qwen-VL 二次生成的文本存在幻觉风险所以生成阶段必须让主模型区分哪些是“图片描述”并对其保持一定的怀疑。我在提示词里加了“资料中未找到”的允许项就是为了降低主模型强行从噪声上下文里编答案的概率。5. 常见问题与排查技巧实录5.1 文本块坐标偏移渲染图与 bbox 对不上怎么办这是第一个最容易遇到的现象裁剪出来的图片区域整体偏移内容被截断。原因基本就一个——没有乘以渲染缩放因子。PDF 的 bbox 以点为绝对值渲染之后图像坐标系按像素走中间差多少倍全看你当时的 zoom。排查办法很简单把裁剪框的坐标打出来和原始 bbox 对照一下看看是否满足pixel point * zoom。如果整体偏移几个像素可以给裁剪框加向外扩的边距crop_box (max(0, int(x0 * zoom) - 10), max(0, int(y0 * zoom) - 10), int(x1 * zoom) 10, int(y1 * zoom) 10)这个 10 像素的边距能兜住大部分奇怪的字形边缘和轻微定位偏差。5.2 Qwen-VL 输出解析失败JSON 不稳定多模态模型输出 JSON 偶尔会夹杂空行、markdown 代码围栏或者模型用自然语言加的前置说明。我写了一个extract_json函数先尝试直接 json.loads失败就用正则把{...}部分抓出来再试再失败就把整个输出交给一个规则清洗函数把换行和引号转义问题修正。实测下来这个三级容错基本能覆盖 99% 的输出情况。但更值得做的其实是把提示词里 JSON 格式示例直接给出完整的值示例而不是只给字段名。模型看到示例值之后模仿输出的稳定性会好很多。有一次我把type: table这种具体值写进提示词里失败率从 12% 降到 3%这属于纯 prompt 工程经验。5.3 视觉通道节点过少或过多区域识别阈值调整如果视觉节点太多说明你把大量普通文本段落也裁成了图片浪费了推理时间太少说明你漏掉了真正的图表。我的调优经验是先看page.get_text(dict)里type为 1 的图片块数量和面积占比。如果页面图片面积超过 20% 但视觉节点几乎为零那多半是图片块被文本块覆盖需要把“文本块完全重叠于图片块”的判断逻辑放宽到“80% 面积重叠”。反过来如果你的文档是 PPT 转的 PDF每一页可能整页都是一个图形对象这时候必须把视觉通道限制在 max_images_per_page2否则推理成本失控。5.4 检索结果被页眉页脚污染页眉页脚文本的 vector 很短有时会出现语义漂浮检索时反而被错误命中。我建议在过滤阶段就用硬规则bbox 距离页面顶部或底部小于 50 point 的块直接丢弃同时把包含“第 X 页”这种强模式的内容用正则排除。还有一个更稳的做法是建一个停用词表对长度小于 8 个字符的块直接不进索引因为它们携带的信息量太低只会拉低检索精度。5.5 GPU 显存不足流水线串行仍然爆显存如果你的显卡只够跑 3B 模型不要同时做向量化和 Qwen-VL 推理。建议处理流程里先全量跑完 Qwen-VL 生成视觉描述释放显存再加载向量模型做索引。我在实测中踩过一次试图把两个模型同时放显存结果 OOM 了三次才意识到该串行。串行多花十几秒钟但稳定很多。如果文档量大到串行不可接受那也不是本地单卡能解决的规模该考虑部署成两个服务或者用在线 API。5.6 实测效果文本通道与视觉通道的增益对比我用一份 80 页的技术白皮书做了对照测试。文档结构大概一半正文、一半图表和分栏展示页。测试问题集 20 个人工标注正确答案所在信息类型。指标纯文本 RAGPyMuPDF 文本块文本 OCR本文双通道方案文本段落类问题命中率84%82%85%图表类问题命中率5%22%89%表格数值类问题命中率31%45%76%单页处理耗时秒0.83.24.5含视觉推理可以看到双通道方案最大的收益来自图表类问题的召回率从 5% 拉到了 89%。损失主要是处理耗时变长了但这对于离线建索引来说完全可接受。表格数值类问题还有提升空间因为复杂表格的渲染质量受限于原始 PDF 的清晰度低清晰度扫描件即使喂给 Qwen-VL 也会损失精度。6. 一些沉淀下来的经验建议这套方案我从搭建到调优花了大概两周最深的体会有两点。第一解析阶段花钱花时间永远比检索阶段调参更值得。我一开始把精力都放在向量模型和检索策略上结果发现不管怎么调召回上限被文本解析质量死死压着。后来把版面切分、区域识别做细致了检索效果自然就上来了。RAG 系统很像水管工的工作源头过滤干净了水龙头拧开才不会有杂质。第二视觉描述需要留“不确定”的出口。我让 Qwen-VL 输出时如果看不清就写“图像不清晰无法准确判断”这句话在检索时可能召回率不高但在生成阶段能防止模型一本正经地编造答案。多模态模型的幻觉问题不是靠提示词彻底解决的而是在系统设计上给它一个“认怂”的路径。如果后续要扩展我的计划是把表格区域单独抽出来做结构化抽取配合 PyMuPDF 的find_tables()能力把表格转成 Markdown 或行级 JSON 再进索引。这套路线的上限更高也值得花时间探索。你先跑通双通道版再往结构化方向走路径比我这样一步步踩过来要平滑得多。
