前阵子接了个离线知识库的小项目语料里既有产品说明书又有一堆截图和参数表格。一开始我打算用常见的文本嵌入模型做向量化结果检索效果一言难尽图片里的信息完全进不去凡是问到“图上标识的是什么”“表格里那个参数是多少”这类问题就翻车。后来把方案切到 EmbeddingGemma 2 这种 740M 规模的多模态嵌入模型才把离线 RAG 真正跑通。这篇就把选型思路、多模态嵌入的核心细节、以及从零搭一套离线 RAG 的完整过程整理出来给正在折腾同样问题的朋友一个参考。标题里三个关键词值得拆开看740M 是参数量级多模态嵌入是输入输出形态离线 RAG 是最终落地场景。这三个点基本决定了整套方案的技术选型——硬件要求不高、能处理图文混合文档、不用联网就能稳定跑。文章里涉及的具体参数、代码和排查思路都是我实际踩过坑之后整理出来的可以直接照着抄。1. 先从选型说起为什么放着更轻的纯文本模型不用非要选 740M1.1 什么场景下我才会选 EmbeddingGemma 2 这类模型很多朋友选嵌入模型第一反应是“越轻越好”。如果是纯文本、领域相对单一、查询语句也比较规整那确实不需要这么大的模型普通的开源嵌入模型完全够用。但这个判断在我接触的这批离线 RAG 项目里不成立。这类项目的典型特征是知识库内容不“干净”文档里有截图、流程图、界面示意图关键信息直接画在图上表格不是简单的 markdown 表格而是 PDF 里扫描出来的图片版表格用户查询往往是“这个功能在设置页的哪个位置”“这张图里的告警灯代表什么”这类图文混合的语义。这种时候纯文本嵌入模型会把图片直接丢掉或者只能靠 OCR 出的糟糕文字来猜意思。而 EmbeddingGemma 2 这种能处理多模态输入、同时输出统一向量的模型才是真正适合做底座的选择。简单说如果你的原始材料里“图”占比超过 10%就别在纯文本模型上死磕了直接上多模态嵌入方案更省事。1.2 740M 参数的规模感显存、内存、延迟到底怎么算“740M”这个数字听起来不大但要判断它能不能跑在目标环境里最好把它换算成具体的资源占用。按一个参数占用的字节数去估算fp324 字节约 2.96GB 权重fp16 / bf162 字节约 1.48GB 权重int81 字节约 0.74GB 权重。实际运行时还要加上中间激活、token 序列缓存和推理框架的额外开销所以当模型用 fp16 加载并设置合理的最大输入长度时整机需要预留 4GB 左右的内存或显存才算踏实。精度权重占用约离线推理场景建议fp322.96GB纯 CPU 内存充足时可用速度一般fp16 / bf161.48GB消费级 GPU 或 16GB 内存的 CPU 机器首选int8 量化0.74GB极致省资源但要验证向量质量是否下降我实际跑下来在普通 16GB 内存、无独显的机器上用 fp32 做批处理嵌入一段 512 token 的文本大约需要几百毫秒如果在带 6GB 显存的消费级显卡上切到 fp16单段延迟能压缩到 100 毫秒以内。这个量级对离线知识库建索引完全没问题做实时检索也够用。1.3 为什么不直接拿大模型隐藏层输出当向量有一种很常见的误区反正要接大模型做生成不如直接复用它的隐藏层向量。听起来省了一个模型实际踩坑概率很高。大模型的隐藏层面向的是“生成下一个 token”的目标它的表示空间不是为相似度检索设计的。同义词、不同表述方式可能距离很远而语义无关但在语料里共现频繁的词反而不小心贴在一起。嵌入模型经过专门的对比学习训练核心目标就是让“语义接近的句子在向量空间里接近”这个目标和生成任务是完全不同的。用生活里的例子说大模型的隐藏层像一本字典你需要翻到具体页面才能得到释义嵌入模型的向量像图书馆的目录卡片卡片上面的分类号直接决定这本书放在哪个书架。做 RAG 检索你需要的正是这种稳定的“放哪”的能力而不是“详细解释”的能力。2. 多模态嵌入到底在做什么如何让图片和文字挤进同一个向量空间2.1 一个向量空间同时装下文字和图像视觉塔、投影层和统一表示很多人第一次听到“多模态嵌入”会以为是个黑盒图片丢进去向量出来然后奇迹般地能和文本比较。实际拆开看不管模型叫什么名字离线 RAG 里最常采用的方案是大同小异的“视觉塔 投影层 嵌入底座”三段式。视觉塔负责把图像编码成一系列视觉特征本质上是对图片做了一次“局部语义抽取”比如哪个区域有文字、哪个区域像按钮、哪个区域颜色异常投影层把视觉特征映射到文本 token 所在的语义空间这一步很关键相当于让图说“人话”嵌入底座负责把文本 token 和映射后的视觉特征统一编码成最终的检索向量。当我用 EmbeddingGemma 2 做离线 RAG 时实际负载就是这么分配的。EmbeddingGemma 2 本身充当嵌入底座负责整个语义空间的组织和最终向量的输出视觉塔负责消化图片信息。两者组合起来之后“一张截图 一句关于它的描述”与“一段纯文字描述”的距离就会变得可比较检索系统才能做到“用户问图片内容”时召回正确文档。2.2 池化和归一化决定向量检索质量的两个核心细节模型本身能力再强向量化的“最后一跳”做不好检索效果也会打折扣。这里有两个细节几乎决定了最终质量我挨个说。第一个是池化方式。多头 Transformer 模型输出的 last_hidden_state 是一个序列序列里每个位置代表一个 token 的语义。要得到整段文本的向量需要把序列压缩成一个向量。最常见的做法是 mean pooling也就是把所有 token 的向量按 attention mask 做加权平均。还有一种做法是直接用 [CLS] 位置的输出但在很多开源嵌入模型上[CLS] 的效果往往不如 mean pooling 稳定。我到现在仍然保留这个习惯凡是加载新模型优先试 mean pooling 基线再对比看官方的参考实现。第二个是 L2 归一化。归一化之后向量长度为 1此时“向量内积”和“余弦相似度”在数值上完全等价。这带来的实际好处是可以用浮点内积快速计算相似度不用每次算完整的余弦公式检索库的索引效率会高不少。归一化还能让向量之间的相似度分数分布更集中方便后续设定统一的检索阈值。完整的向量化路径可以抽象成下面这样def encode(model, tokenizer, text: str) - list[float]: inputs tokenizer( text, return_tensorspt, truncationTrue, max_length512, paddingTrue, ) with torch.inference_mode(): output model(**inputs) hidden output.last_hidden_state mask inputs[attention_mask].unsqueeze(-1) mean_vec (hidden * mask).sum(dim1) / mask.sum(dim1) # L2 归一化让向量长度变成 1 normalized torch.nn.functional.normalize(mean_vec, p2, dim-1) return normalized[0].tolist()2.3 图文混合文档的三个表示策略图像单独入库、图注拼接、混合块多模态嵌入不是把图片硬塞给模型就完了关键是怎么把图放进一个可检索的“文档块”里。离线知识库的场景下我常用三种策略各有各的适用范围图像单独成块适合信息高度集中的截图、单张指标告警图。图片本身单独走视觉塔抽向量块标题或附带说明作为辅助检索字段。图注拼接适合“图片 一个简短的表格标题”这种常见排版把图注文本和图片特征拼进同一个块检索时既能命中标题里的关键词又能匹配图画内容。混合块适合文中直接引用图片且上下文高度相关的场景把图片前后各一段正文与图片特征绑定成一个块避免拆开后语义被扯断。我在实际建库时不是只选一种策略而是按文档类型混用。“图注拼接”默认兜底“图像单独成块”用于信息密度高的图“混合块”用于流程图、操作截图这类强解释性配图。怎么判断看离线知识库的查询风格如果高频问题都集中在“图中是什么”“界面上哪里能找到”那么图像单独成块的比例就得提高。3. 离线 RAG 的整体架构先解决“能跑”再解决“跑得好”3.1 离线部署前的一次性物料准备模型、依赖、索引库离线 RAG 与在线最大的区别是一旦机器断网所有运行时依赖都得提前备好。这个环节我建议当成一个独立工程来做不要按“到时候缺啥补啥”的思路否则会很痛苦。首先明确离线环境的边界目标机器不允许访问外网所有 Python 包必须从联网的电脑上下载好再拷贝进去。我通常在内网干净环境里先随便建一个虚拟目录反复跑一遍脚本把缺的依赖一个个收集齐。第一次就把缺依赖的问题解决后面所有开发都顺畅。比较稳妥的依赖准备方式# 在联网机器上把依赖包下载到本地目录 pip download torch transformers faiss-cpu pillow -d ./wheelhouse # 在离线机器上安装 pip install --no-index --find-links./wheelhouse torch transformers faiss-cpu pillow然后把模型权重从模型托管平台下载好连同 tokenizer、配置文件、以及可能需要的视觉塔权重一起放进一个固定的 models 目录。这里有一个容易忽略的点不要只拷权重大文件visual encoder 的配置文件、preprocessor 配置、tokenizer 的 added_tokens 都得带上缺一个就可能在加载时报出莫名其妙的 key 错误。3.2 多模态知识库的分块方案不是所有切片都该切RAG 检索质量很大程度取决于分块。多模态环境下这个问题的复杂度更高因为一个“块”可能是文字段落、也可能是图文组合、还可能是整张表格。我常用的分块规则如下文字段落按章节和语义段落划分每块控制在 500 词以内超出就按句子边界截断不让句子被从中间切开图片所在位置先判断上下文如果图有明确的图注优先把图注和图合在一起表格独立成块不做横向切割因为表格的语义通常依赖完整行列结构流程图、架构图不切整图作为一块。分块之后的块都要保留来源元数据比如“原始文档名 章节号 块序号”。后面做问题定位时能直接从元数据追溯到原文档哪里。如果你的检索目标是“找一段话”过度分块会让上下文丢失如果目标是“找一个参数”切得太粗又会让无关文本冲淡语义。没有绝对最优的分块长度实操时最好的办法是先按上面规则切跑一批查询观察命中的块是否“信息刚刚好”再微调。3.3 向量索引、召回与重排本地小资源下的最优顺序向量化只是第一步检索还有三个环节需要设计索引、召回、重排。索引上离线环境通常不用启动独立的数据库服务本地嵌入式向量检索库是实现成本最低的选择。用一个支持 HNSW 索引的库建索引时把图的出度设成 32 到 64 之间检索性能已经很够十万级向量上单次查询在几毫秒到几十毫秒。召回上第一轮先取一个较大的候选集。比如最终要 5 条结果第一轮可以先取 20 到 50 条。原因很简单嵌入模型的向量是“语义近似”精度有限第一轮把候选集扩大后面有足够空间做精细化排序。重排上如果知识库比较大建议加一个交叉编码器做一次粗排精排。交叉编码器会把查询和候选文档同时送进模型计算更细粒度的相关性分数。它比“双塔式”嵌入模型的向量相似度更准确但速度慢所以只适合对第一轮召回的少量候选做重排不能全量跑。整个顺序就是嵌入召回快、粗 → 候选重排慢、准 → 输出 TopK。小资源环境下优先保证召回率再用重排控制精度这个顺序基本不会错。4. 实操记录用 EmbeddingGemma 2 跑通离线多模态 RAG4.1 运行环境与参数配置参考我这次搭建验证环境的配置并不高大家可以对照着看配置项推荐值CPU8 核以上优先看单核频率内存16GBGPU可选显存 6GB 以上无 GPU 也能跑操作系统Linux 或 Windows 均可Python 3.10模型精度fp16有 GPU/ fp32无 GPU输入 max_length512 到 1024按分块大小调整这个配置可以支撑十万级向量索引和日常离线检索超出这个规模建议先优化分块策略而不是盲目换更大的模型。4.2 加载模型与向量化的最小实现下面这段代码是我在实际项目里验证过的最小实现。重点在于本地模型路径、离线模式、mean pooling L2 normalize 三个动作。import os import numpy as np import torch from transformers import AutoTokenizer, AutoModel # 关键让 Transformers 强制走离线模式不尝试访问网络 os.environ[TRANSFORMERS_OFFLINE] 1 os.environ[HF_HUB_OFFLINE] 1 MODEL_PATH /models/embeddinggemma-2-740m TOKENIZER_PATH /models/embeddinggemma-2-740m tokenizer AutoTokenizer.from_pretrained(TOKENIZER_PATH) model AutoModel.from_pretrained( MODEL_PATH, trust_remote_codeTrue, torch_dtypetorch.float16 if torch.cuda.is_available() else torch.float32, ) model.eval() if torch.cuda.is_available(): model model.to(cuda) def mean_pool_embed( model, tokenizer, texts: list[str], max_length: int 512, batch_size: int 8, ) - np.ndarray: vectors [] for i in range(0, len(texts), batch_size): batch texts[i : i batch_size] inputs tokenizer( batch, return_tensorspt, paddingTrue, truncationTrue, max_lengthmax_length, ) if torch.cuda.is_available(): inputs {k: v.to(cuda) for k, v in inputs.items()} with torch.inference_mode(): outputs model(**inputs) hidden outputs.last_hidden_state mask inputs[attention_mask].unsqueeze(-1) pooled (hidden * mask).sum(dim1) / mask.sum(dim1) pooled torch.nn.functional.normalize(pooled, p2, dim-1) vectors.append(pooled.cpu().numpy()) return np.concatenate(vectors, axis0)如果要做多模态嵌入思路也很直接图像先经过视觉塔得到视觉特征再通过投影层拼接到文本序列的 hidden state 中最后进入同一个 pooling 流程。实际工程里可以利用 Hugging Face 的 MultiModalPipeline 之类的接口完成不过离线环境建议先把视觉塔单独跑通输出特征后缓存成 .npy 文件避免每次重复加载图像编码器。4.3 建库与检索一个最小可复用的离线检索流程向量库选择上我用过嵌入式本地库和 faiss 类库。如果只做离线验证百亿级以下我用一个足够简单的方案向量存为 .npy 文件索引用 HNSW 实现查询时先 TopK 召回再决定是否重排。import faiss def build_index(vectors: np.ndarray) - faiss.Index: dim vectors.shape[1] # 使用 HNSW 索引出度设 32faiss 会自动对向量做内积 index faiss.IndexHNSWFlat(dim, 32) index.hnsw.efConstruction 200 index.hnsw.efSearch 64 # 注意这里假设向量已经做过 L2 归一化内积等价于余弦相似度 index.add(vectors.astype(float32)) return index def search(index: faiss.Index, query_vec: np.ndarray, top_k: int 10): # query_vec 形状为 [1, dim]且已归一化 distances, indices index.search(query_vec.astype(float32), top_k) return distances[0], indices[0]检索后的关键在于后处理要不要重排、相似度阈值设多少。我用的经验值是从相似度 0.6 开始观察低于 0.6 的候选基本就不值得交给生成模型了。重排阶段如果知识库超过五万块建议必须加一个交叉编码器否则 TopK 里一定会有无效结果混进来。4.4 一个小范围评测图文混合文档里的对比结果为了验证“多模态嵌入到底值不值”我做过一个小测评用同一份混合文档分别用纯文本嵌入模型和 EmbeddingGemma 2 这套方案建库查询三个典型问题。查询语句纯文本模型召回情况多模态方案召回情况“告警灯亮红色时对应哪一条处理建议”漏召回图注文字无索引命中对应图注块分数 0.83“防抖参数默认是多少”命中文字块但块内容不完整命中表格块附带完整行列分数 0.91“上级菜单入口在哪”无法定位关键截图命中截图块分数 0.77纯文本模型的问题很典型它只认 OCR 错字后的文本或干脆只能匹配到描述性句子导致重要细节大量丢失。多模态方案因为把图像特征纳入向量明显改善了图文混合场景下的召回位置和置信度。尤其当查询里带着“图”“菜单”“位置”这类空间语义时纯文本模型基本无助。5. 常见问题与排查技巧实录5.1 模型加载失败key 对不上和框架版本不一致这是离线部署时出现频率最高的问题。现象往往是加载权重时报出类似 size mismatch 的错误比如某些层的维度对不上。原因基本都是两个一是模型文件下载不完整或拷贝时漏文件二是本地 transformers 版本太旧不兼容模型结构定义。处理步骤是固定的先比对模型托管平台给出的 sha256 校验值确认文件完整然后确认 Python 环境和 transformers 版本符合模型发布说明的要求最后用最小复现脚本单独加载模型避免被项目的其他依赖干扰。这一套下来能解决绝大部分加载失败。5.2 离线依赖补不齐不要相信“感觉缺一个装一个”离线环境最忌讳边跑边缺包。我强烈建议拿到一个目标机器的 Python 版本和系统架构后先在联网机器上搭一个一模一样的虚拟环境把整个流程完整跑一遍缺什么补什么最后一次性打包 wheelhouse。这样做还有一个好处能够提前发现某些包在离线安装时需要编译依赖如果没有编译工具链会很麻烦此时要找带预编译 wheel 的版本而不是依赖源码编译。5.3 检索速度慢和显存不够的优化动作速度慢通常有两个瓶颈向量化阶段和检索阶段。向量化阶段如果 CPU 推理太慢优先加大 batch size把多条文本同时送进模型充分利用多核并行同时把可变的 max_length 从 1024 降到一个刚好覆盖块长的值也会显著提速。检索阶段的优化更直接HNSW 索引比暴力检索快一个量级另外可以把索引文件预先加载到内存避免每次查询时反复读磁盘。显存不够时最低成本的方案是把模型切成 fp16再不行直接放到 CPU 上跑。多模态嵌入通常不是实时高并发场景CPU 推理慢一点问题不大。我实际验证过用 16GB 内存的纯 CPU 机器分 32 个批次向量化一万个文档块半小时内能完成全量建索引完全可接受。5.4 多模态向量“同质化”召回结果看不出图片差异有时你会发现一批截图、图标产生的向量相似度都很高导致检索结果“看着都对细看都不对”。这个问题的核心原因是视觉塔对图像的局部特征抽取不足或者图片本身尺寸差异大、预处理时被过度压缩。我的排查顺序是先检查图片预处理参数确保最长边不被压到 256 以下再确认视觉塔输出的特征已经是“区域级”而不是“整图平均”否则每个图都变成了一个模糊的平均值最后检查投影层训练数据集是否覆盖了你的图片类型。如果是截图类图像不要用纯自然图片训练的视觉塔效果会有明显差别。5.5 避坑速查表现象可能原因解决动作加载权重报 size mismatch文件不完整 / 框架版本旧校验哈希、升级 transformers、最小复现完全离线却发起网络请求未开离线模式设置 TRANSFORMERS_OFFLINE 和 HF_HUB_OFFLINE检索结果定位偏差分块太粗 / 太细按“一句一段 图文绑定”规则重新分块多模态向量区分度低视觉特征被平均化检查预处理、视觉塔选型、投影层阈值设多少全乱猜未做分数分布分析抽样查询观察正确命中的分数区间写在最后的一个小技巧如果你在离线环境里已经跑通了上面这套流程我建议再做一件事把重排模型的权重也提前准备一份。很多刚上手的朋友觉得第一轮向量召回效果“还行”就跳过了重排。真实场景里尤其语料一上十万级召回里混入的相似但错误的文档会越来越多多一步重排往往比换更强的嵌入模型更划算。我个人现在的路线是固定不变的embedding 负责从全库筛出一个高质量候选集交叉编码器负责把这个候选集排序。这套组合下来离线 RAG 的检索稳定性会明显好于单靠一个 740M 模型硬扛而且费用只是多一个几百 MB 的权重文件和一点推理时间。