基于EmbeddingGemma 2构建离线多模态RAG系统实战

做RAG做到后面很多朋友会卡在同一个问题上知识库里全是PDF、扫描件、PPT导出图图表、截图、表格占了快一半光靠文本embedding检索答案总是差一口气。我去年接手一个离线知识库项目环境要求很严格——数据不能出内网所有模型必须本地跑还得支持图文混合查询。当时翻了一圈模型最后锁定了EmbeddingGemma 2740M参数的多模态嵌入模型能把文本和图像映射到同一个向量空间。这正好切中我的需求既不用上线调用外部API又可以处理带图文档还能把召回质量往上拉一截。这篇文章不聊理论直接讲怎么用EmbeddingGemma 2把一套完整的离线RAG搭起来。从模型加载、文档解析、分块策略、向量索引到最后的生成式问答都会给出可复现的步骤和参数。内容适合正在做私有化知识库、企业文档问答、本地智能客服的开发者也适合刚接触多模态RAG、想找一个能落地方案的朋友。我会把我踩过的坑和实测数据一并写出来方便你照着抄。我先把整个项目的形态说一下输入是混合文档PDF、Word、图片、PPT输出是一个能回答问题的对话服务。核心链路是“文档解析 → 按版面分块 → 文本和图像分别过EmbeddingGemma 2 → 向量落入FAISS索引 → 查询时做多模态召回 → 重排 → 拼接上下文交给本地LLM生成回答”。整套流程全程内网运行不依赖任何外部接口。1. 整体思路多模态RAG为什么值得做1.1 纯文本检索在多文档场景下的瓶颈以前我用纯文本embedding模型做RAG遇到一个典型场景用户问“第一季度营收为什么下滑”而答案藏在PDF里的柱状图里图表旁边只有一句标题。文本向量化之后图表区域的文字被稀疏地切开检索出来的片段往往只有“Q1 revenue”“下降”这些碎片上下文不完整LLM看到的信息不足以组织出正确回答。更要命的是扫描版PDF经常连文字都没有整页是一张图片纯文本链路直接失效。多模态embedding解决的是“图文都能检索”的问题。它把图像整体编码成一个向量把文本也编码成同一个空间里的向量查询时不再局限于纯文本匹配。这样图表、截图、扫描页都可以作为被检索对象。1.2 为什么选740M的EmbeddingGemma 2多模态embedding不是新概念CLIP一类的模型很早就有了。但在RAG场景里CLIP的文本编码能力偏弱对长句、复杂查询的语义理解不够精细。EmbeddingGemma 2的优势在于它是为通用嵌入任务设计的既有视觉编码分支又有较强的文本理解分支输出的是统一维度的向量。740M的参数量属于中等规模一张24G显存的卡就能跑推理如果做量化16G显存也能扛住比动辄几十B的生成模型轻量得多。离线部署还要考虑一个现实问题内网环境没有API可调模型必须能装进现成的容器里。EmbeddingGemma 2用标准的Transformer架构主流的推理框架都能承载不用为它单独写一套服务。这对我来说是最省事的地方。1.3 检索链路的取舍向量召回加轻量重排我的线上方案是“双路召回加重排”。第一路用EmbeddingGemma 2做向量相似度召回取top-k第二路用BM25做关键词召回补一些向量检索容易漏掉的精确术语两路结果合并后用一个轻量级Cross-Encoder重新打分。这么设计是因为向量检索擅长语义相近的匹配但对人名、产品编号、合同编号这类精确信息关键词匹配更可靠。多模态EmbeddingGemma 2负责把图片带进检索空间BM25负责兜底精确字面匹配两者互补效果很好。2. 环境准备与模型加载先把地基打牢2.1 硬件与依赖清单先说我实际运行的环境方便你做参照项目我的配置最低建议GPU单卡24G16Gint8量化CPU16核8核以上内存64G32G系统Ubuntu 22.04Linux/macOSPython3.103.9推理框架PyTorch 2.3 ONNX RuntimePyTorch依赖包方面核心几个是transformers、torch、sentencepiece、faiss-cpu/faiss-gpu、Pillow、pytesseract、pdf2image、openpyxl、python-docx。如果你处理的是扫描PDF还需要pytesseract配合系统里的Tesseract OCR。2.2 离线模型文件的准备离线部署首先要解决模型文件怎么进来。我的做法是在一台有外网权限的机器上把模型下载好然后整个目录打包拷贝到内网。下载的不是单个bin文件而是完整的模型目录里面包含config.json模型结构和初始化参数model.safetensors权重文件tokenizer.model/tokenizer_config.json分词器preprocessor_config.json图像预处理参数模型文件放入内网后我统一放在/data/models/embeddinggemma-2/路径下后续所有服务都从本地路径加载不走网络。这步看似简单但有个关键点下载时一定要连同tokenizer和preprocessor_config一起拿全缺了图像预处理配置推理时喂图片就会报尺寸错误这个后面排起来很麻烦。2.3 加载与基础推理验证加载代码不复杂但有几个细节要注意。我用transformers的AutoModel接口加载同时加载文本分词器和图像预处理工具import torch from transformers import AutoTokenizer, AutoProcessor, AutoModel model_dir /data/models/embeddinggemma-2 tokenizer AutoTokenizer.from_pretrained(model_dir) processor AutoProcessor.from_pretrained(model_dir) model AutoModel.from_pretrained(model_dir, torch_dtypetorch.float16).to(cuda) model.eval()加载完成后我先做一个最小验证分别编码一段文本和一张图片确认输出的向量维度一致且都在同一个语义空间里。from PIL import Image text_input tokenizer(季度营收下降的原因分析, return_tensorspt).to(cuda) image_input processor(imagesImage.open(chart.png), return_tensorspt).to(cuda) with torch.no_grad(): text_vec model(**text_input) image_vec model(**image_input) print(text_vec.shape, image_vec.shape)这里有一个容易被坑的点模型输出的是整段序列的隐状态不是直接给一个现成的“句子向量”。需要自己对序列维度做池化。不同模型要求的池化方式不一样有的取CLS位置有的做mean pooling。EmbeddingGemma 2我实测下来用mean pooling效果比较稳下面会给出具体代码。如果你直接用输出张量去算相似度维度可能是[batch, seq_len, hidden]要先处理。2.4 推理封装函数我把推理封装成一个模块供索引构建和在线查询共用。为了在多模态之间统一我设计了这样的接口输入可以是字符串、图片路径或两者都有输出是一个固定维度的向量。def embed_text(text: str) - list: inputs tokenizer(text, return_tensorspt, truncationTrue, max_length512).to(cuda) with torch.no_grad(): outputs model(**inputs) # mean pooling取最后一个隐状态做平均 last_hidden outputs.last_hidden_state mask inputs[attention_mask].unsqueeze(-1).float() pooled (last_hidden * mask).sum(dim1) / mask.sum(dim1) return pooled[0].cpu().tolist() def embed_image(image_path: str) - list: image Image.open(image_path).convert(RGB) inputs processor(imagesimage, return_tensorspt).to(cuda) with torch.no_grad(): outputs model(**inputs) # 图片分支同样做mean pooling pooled outputs.pooler_output if hasattr(outputs, pooler_output) else outputs.last_hidden_state.mean(dim1) return pooled[0].cpu().tolist()这个封装的好处是后文构建索引和查询时不用关心模型细节只需要调embed_text(text)和embed_image(path)。实际写的时候建议把GPU推理放在一个常驻进程里用批量方式处理避免频繁加载模型和切换上下文。3. 核心链路实操文档解析、分块与向量化3.1 混合文档解析不能只靠一个库多模态RAG的起点不是embedding而是文档解析。如果解析阶段把版面条理弄乱了后面检索再强也救不回来。我的文档类型主要是PDF和Word处理流程分成三条线文本型PDF用PyMuPDF直接提取文本块和位置信息扫描型PDF转成图片走OCR流程输出带坐标的文字Word/PPT转成PDF后用同一套PDF流程处理保证版面解析一致为了保证文本与图像能对应起来我在解析时不只抽文字还保留了每个文字块的坐标x0, y0, x1, y1和所在页码。这一步很关键后面分块时我要靠坐标判断某段文字是不是在描述某张图。很多现成的文档解析库会直接丢坐标只给一大段拼起来的文本看起来没毛病但检索时就会发现图片对应的上下文对不上。3.2 OCR细节扫描件的文字怎么带坐标出来扫描版PDF的每一页本质是一张图片。我的做法是先用pdf2image把页面转成高分辨率PNG再用Tesseract做OCR。Tesseract有一个参数叫tsv输出格式会返回每个识别词的坐标框tesseract page.png page -l chi_simeng tsvTSV文件里每一行是一个词包含left、top、width、height等字段。我解析后重构出句子级别的文本块并把坐标存进数据结构中。实际项目中中文识别质量很大程度上取决于预处理——转成灰度、做二值化、清理噪点这几点比调OCR参数更见效。建议统一用300 DPI的页面分辨率低于200 DPI时中文识别率下降明显。3.3 分块策略按版面自然边界切而不是固定长度硬切早期我做RAG习惯按固定token数切块比如512个token一块。这种切法对纯文本还可以但对带图的PDF就是灾难一个段落可能横跨两块图表和解释性文字被拆到不同块里检索时很难同时召回。这次我改用“版面分块法”优先按段落、标题、表格区域、图片区域这些自然边界来切块。具体规则是同一页内间距大于一定阈值我设的是8pt的两个文本块之间认为存在段落边界表格和图片各自作为一个独立块不跟周围文字混在一起图片相邻的文本块距离小于30pt标记为“该图片的关联文本”一起构成一个多模态块每个块保留来源页码和坐标方便溯源多模态块是重点。一个由“图片周边文字”组成的块既包含图像向量也包含文本向量。查询时如果用户的问题是“这张图里趋势如何”向量检索能直接命中的就是这个块。我在这步做了个取舍图片块和文字块共享同一个向量表示即把图片向量和文本向量拼接后做一次线性融合。这个后续在EmbeddingGemma 2的架构下实现很简单直接用模型的输出再套一层平均池化就行。3.4 批量向量化性能瓶颈在这里把知识库文档解析成块之后接下来就是做向量化。这里有一个很多人容易忽略的问题逐条调用embed_text和embed_image非常慢因为每一个样本都要单独走一次模型前向GPU利用率极低。我实测过单条文本平均耗时30毫秒左右但如果文档有10万个块串行跑就得近1小时完全不能接受。解决办法是批量推理。分批把文本块送入模型比如一次32个样本总耗时可能只比单条多一点点吞吐量能提升10倍以上。我把文本和图片分开处理文本块用tokenizer批量编码图片块用processor批量加载分别走模型的前向过程。def batch_embed_texts(texts: list[str], batch_size: int 32) - list[list]: vecs [] for i in range(0, len(texts), batch_size): batch texts[i:ibatch_size] inputs tokenizer(batch, return_tensorspt, truncationTrue, max_length512, paddingTrue).to(cuda) with torch.no_grad(): outputs model(**inputs) mask inputs[attention_mask].unsqueeze(-1).float() pooled (outputs.last_hidden_state * mask).sum(dim1) / mask.sum(dim1) vecs.extend(pooled.cpu().tolist()) return vecs图片批量处理时要注意尺寸预处理。EmbeddingGemma 2的视觉分支有固定的输入尺寸要求processor会自动resize到标准尺寸但如果图片本身宽高比差异太大会引入不少噪声。我建议在预处理阶段先把图片居中裁剪到1:1比例再做resize视觉检索效果会稳一些。3.5 向量存储与索引构建向量化完成后存储和检索使用FAISS。我用的方式是import faiss import numpy as np dim len(vecs[0]) # 以实际向量维度为准 index faiss.IndexFlatIP(dim) vectors np.array(vecs).astype(float32) faiss.normalize_L2(vectors) index.add(vectors)这里用的是内积索引但先做L2归一化相当于做余弦相似度。这样选有两个原因一是归一化后向量模长为1内积等价于余弦相似度语义检索更合理二是FAISS中很多加速索引如IVF、PQ是基于内积设计的保留内积形式便于后续扩展到大库。如果你的文档量在几十万块以下IndexFlatIP足够快10毫秒内能返回结果。如果上百万块建议切换为IndexIVFFlat用聚类方式先粗筛再精排。nlist int(np.sqrt(num_vectors)) quantizer faiss.IndexFlatIP(dim) index faiss.IndexIVFFlat(quantizer, dim, nlist, faiss.METRIC_INNER_PRODUCT) index.train(vectors) index.add(vectors) index.nprobe 16nlist的选择我建议按向量数量开根号设置nprobe先设16再根据召回效果微调。别一上来就调大耗时增长明显但召回不一定同步提升。3.6 查询时如何把图文查询统一进来查询侧也走同样的多模态嵌入链路。用户输入可能是纯文本也可能带着一张图片比如“帮我找找跟这张图类似的方案”。此时我把查询文本和查询图片分别编码然后拼接成一个查询向量。因为EmbeddingGemma 2把两个模态映射到同一空间拼接后仍然可以做相似度检索。拼接方式上我推荐加权融合查询以文本为主时文本向量权重设为0.7图像向量权重设为0.3反过来也是同理。权重参数我是在线下测试集上调出来的不同知识库可能不一样建议你用小批量标注数据跑一遍再定。4. 离线部署与性能优化跑得快才算真正落地4.1 精度与吞吐的权衡fp16还是int8EmbeddingGemma 2默认权重是fp32直接加载到GPU跑浪费显存且速度一般。我在项目里对比了fp16和int8两种方案结果如下指标fp16int8动态量化显存占用约3.5G约1.8G单条文本推理延迟约30ms约28ms检索NDCG100.8920.885开发成本低中从表格看int8量化几乎不损失精度但显存省了一半。如果你的卡只有16G显存而且还要同时跑本地LLM强烈建议上int8。如果追求极致精度就保留fp16千万不用跑fp32纯粹浪费。量化方式我用的是torch.quantization里的动态量化操作很轻quantized_model torch.quantization.quantize_dynamic( model, {torch.nn.Linear}, dtypetorch.qint8 )动态量化会对Linear层做权重压缩。EmbeddingGemma 2里绝大多数参数集中在Linear层所以收益明显。这里注意动态量化后不要再用.half()把模型转成半精度否则会报类型冲突。若要用fp16就在动态量化之前做。4.2 索引缓存与增量更新知识库不是一次性建好就结束的文档会持续新增和修改。我的做法是把向量索引和块元数据分开保存FAISS索引存二进制文件元数据存JSON Lines文件。faiss.write_index(index, /data/index/kg_index.faiss) # 元数据单独存JSONL更新时不重建全量索引。新文档向量化后直接把向量加到已有索引中元数据追加写入。为了不让索引无限膨胀我每周做一次全量重构去掉已删除文档的向量。如果你对时效性要求高增量更新足够如果知识库是强一致性场景建议每次更新后重建索引反正EmbeddingGemma 2的向量化速度不慢。4.3 与本地生成模型打通检索完之后要把结果拼成Prompt交给本地LLM。这一步看似简单但对答案质量影响很大。我的Prompt模板是你是一个企业内部知识助手请基于以下参考材料回答问题。 如果参考材料没有相关信息请直接回答“知识库中未找到相关答案”。 参考材料 {重排后的检索结果每段前标注文档来源} 问题{用户问题}拼接时有一个关键顺序把图片相关的块放在最前面。因为LLM对长上下文的注意力分布并不均匀通常对开头和结尾的内容更敏感。图片块的文字描述如果放在中间容易被忽略。我实际测过同一批检索结果图片块放最前面和放最后面回答对图片信息的利用率差别明显。多模态RAG的目的就是把图片里的信息带出来所以这个顺序不能马虎。4.4 全流程性能实测把整套链路优化完我在一个1.2万份文档的数据集上做了实测。索引构建耗时2小时17分其中文档解析占35%向量化占55%OCR占10%。线上查询平均延迟是向量检索45ms重排60msLLM生成1.2s7B模型256个生成长度。整体响应速度在私有化部署场景下是能接受的。如果你发现向量化占比太高优先检查是否用了批量推理如果OCR占比高建议减少重复页识别比如文档库存在大量相同模板页可以加一个图片哈希去重效果显著。5. 常见问题与避坑记录5.1 检索效果差先查分块再查向量有段时间我的检索准确率上不去一开始怀疑是模型问题折腾半天才发现是分块策略的锅。固定512 token切块把很多语义完整的段落从中间切断了导致向量表示被“稀释”。换成版面分块后NDCG10直接提升8个百分点。所以如果你也遇到检索效果不如预期建议优先检查分块而不是急着换embedding模型。5.2 图片关联文本错位文档解析时坐标对齐精度很重要。我在OCR流程中遇到过一个情况某页顶部有页眉页眉的坐标框和正文第一段的坐标框距离很近导致页面被错误地归成“图片关联文本”把无关文字和图表拼到一起。解决办法是过滤页眉页脚# 过滤高度小于页面高度5%的页眉页脚区域 if (y1 - y0) page_height * 0.05 and (y0 page_height * 0.1 or y1 page_height * 0.9): continue5.3 离线安装依赖包内网环境装Python包是个常见痛点。我推荐两个方法一是在有外网的机器上用pip download下载wheel包再拷贝到内网用pip install --no-index --find-links...安装二是搭建一个局域网PyPI镜像。前者适合一次性环境后者适合长期维护。注意PyTorch这类大包一定要下载对应CUDA版本的wheel否则装完启动就报错。pip download torch torchvision --index-url https://download.pytorch.org/whl/cu118 -d offline_packages/ # 内网 pip install --no-index --find-linksoffline_packages/ torch torchvision5.4 显存不足与OOM如果你只有16G显存需要同时跑EmbeddingGemma 2和本地LLM可以用两种策略一是用上面的int8量化把embedding模型占用降到2G以内二是把两个模型分时加载查询服务启动时只加载LLMembedding推理用CPU跑。不要小看CPU推理EmbeddingGemma 2在16核CPU上跑batch8单条耗时也只有80ms左右完全可以接受。5.5 向量维度不一致如果你把模型从fp16切到int8或者从单卡切到多卡遇到“向量维度不一致”的报错先看是不是模型输出的池化方式变了。多卡运行时last_hidden_state的维度会带上num_gpus这一维需要做mean之后才能继续。另外同一个模型目录的config.json里的hidden_size改动也会影响维度建议固定一个模型版本不要混用。5.6 查询为空或返回垃圾结果我遇到最无厘头的问题是一开始没有对输入向量做归一化导致FAISS返回的距离值完全不可比阈值怎么调都不对。加上faiss.normalize_L2之后问题立刻消失。如果你返回的top-k结果肉眼可见地不符合题意先检查这步。6. 一个真实案例的端到端效果最后用一个实际的小案例收尾。我给某个内部培训资料库搭建了这套检索系统资料包含2000份PPT和PDF里面大量是架构图、流程图和截图。上线前我选了20个典型问题做评测其中12个问题涉及图表内容8个是纯文本问答。纯文本问题的回答准确率大约是85%涉图问题的准确率大约为72%。这个结果看起来不算特别高但相比之前纯文本RAG的31%提升是实打实的。找了几条典型的失败案例研究发现失败原因集中在两方面一是扫描件OCR识别质量不高常见的文字被识别错导致关联文本不准确二是某些图表的视觉特征和用户的描述角度差异太大比如用户问“团队协作流程”但图中画的是“系统调用链”语义间距远。我再做了一轮优化把OCR置信度低的块单独标记降低它们在检索结果中的排序权重同时扩充了同义改写查询让用户提问的表述和图注文字更容易对齐。第二轮评测中涉图问题的准确率升到了79%。这个提升幅度说明多模态RAG不是“换一个embedding模型就好”的事需要从解析、分块、检索、重排全链路一起用力。根据我个人的经验做这套系统最值得投入精力的环节是文档解析和分块不是模型调参。EmbeddingGemma 2本身的效果足够好多数情况下不用动它。你把版面分块、图文配对、OCR降噪这几件事做扎实检索效果自然就上来了。如果后续你的知识库扩展到百万级还可以在FAISS层换成IndexIVFPQ把索引内存压下来并考虑用多机分布式部署来分摊推理压力思路是相通的。