FlagEmbedding 推理 Embedder API 全解析BaseEmbedder、M3Embedder、BaseLLMEmbedder 与 ICLLLMEmbedder 的架构、参数与实战【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇技术指南聚焦 FlagEmbedding 的推理侧inferenceEmbedder API系统讲解仓库 API 文档docs/source/API/inference/embedder/embedder.rst所覆盖的四类嵌入模型封装类面向编码器架构的BaseEmbedder、面向 BGE-M3 多模态检索的M3Embedder、面向解码器 LLM 的BaseLLMEmbedder以及支持上下文学习In-Context Learning的ICLLLMEmbedder。读完本文你将掌握每个类的构造参数含义与默认值、encode_queries/encode_corpus/encode等核心方法的调用约定、底层 pooling 与多设备推理的实现原理并能直接照搬到自己的检索与 RAG 项目中。一、文档结构与四类 Embedder 的总览embedder.rst本身是一个 Sphinx toctree 索引页它挂载了四个子 API 页面分别对应四个推理类子文档对应类适用模型架构代表模型encoder_only/BaseEmbedder.rstFlagEmbedding.inference.embedder.encoder_only.base.BaseEmbedder编码器Encoder-onlyBERT 类BGE v1/v1.5 系列、e5、gte 等encoder_only/M3Embedder.rstFlagEmbedding.inference.embedder.encoder_only.m3.M3Embedder编码器多向量/稀疏/稠密混合BGE-M3decoder_only/BaseLLMEmbedder.rstFlagEmbedding.inference.embedder.decoder_only.base.BaseLLMEmbedder解码器Decoder-onlyLLMbge-reasoner、Qwen3-Embedding、SFR-Embedding 等decoder_only/ICLLLMEmbedder.rstFlagEmbedding.inference.embedder.decoder_only.icl.ICLLLMEmbedder解码器上下文学习BGE-EN-ICL在代码层面这四个类分别定义在 FlagEmbedding/inference/embedder/encoder_only/base.py、m3.py、decoder_only/base.py 与 decoder_only/icl.py并统一从FlagEmbedding/inference/embedder/__init__.py导出为FlagModel、BGEM3FlagModel、FlagLLMModel、FlagICLModel等用户友好的别名。四者都继承自抽象基类AbsEmbedder见 FlagEmbedding/abc/inference/AbsEmbedder.py因此共享一套查询/语料/通用编码接口约定差异集中在 pooling 方式与多模态输出上。二、共同架构抽象基类 AbsEmbedder 与统一编码流程所有 Embedder 的骨架由AbsEmbedder定义FlagEmbedding/abc/inference/AbsEmbedder.py其 docstring 明确说明扩展该类并实现encode_queries、encode_corpus、encode三个方法即可自定义 Embedder。2.1 统一的三入口设计encode_queries(queries, ...)编码查询。内部以self.query_max_length为默认长度上限并自动拼接检索指令query_instruction_for_retrieval见 AbsEmbedder.py 的encode_queries实现。encode_corpus(corpus, ...)编码语料/文档。以self.passage_max_length为默认长度上限并支持通过 kwargs 传入passage_instruction_for_retrieval/passage_instruction_format为语料附加独立的指令默认{}{}。encode(sentences, ...)通用编码入口最终依据设备数量决定走单设备路径encode_single_device还是多进程池路径encode_multi_process。三者均支持输入单个字符串str或字符串列表List[str]返回值可以是numpy.ndarray或torch.Tensor由convert_to_numpy控制默认True返回 numpy 数组。2.2 指令拼接机制get_detailed_instruct(instruction_format, instruction, sentence)AbsEmbedder.py 第 157-170 行按模板把指令与句子组合def get_detailed_instruct(instruction_format: str, instruction: str, sentence: str): if \\n in instruction_format: instruction_format instruction_format.replace(\\n, \n) return instruction_format.format(instruction, sentence)例如query_instruction_formatInstruct: {}\nQuery: {}会把检索指令 查询文本拼成Instruct: 指令\nQuery: 查询。注意源码会对字面量\n做一次显式替换因此既支持在 Python 字符串中写真实换行也支持写\n转义序列。2.3 设备自动探测与多进程并行get_target_devices(devices)AbsEmbedder.py 第 110-154 行是一套完整的设备解析逻辑devicesNone时按优先级自动探测CUDA全部可用卡cuda:0...N→ NPUnpu:0...N→ MUSAmusa:0...N→ MPSApple Silicon→ 兜底cpu传入str如cuda:0、int如0、字符串列表或整数列表均可当检测到多张卡且输入为批量列表时encode会通过start_multi_process_pool启动每卡一个进程的 worker 池配合encode_multi_process分块分发、_concatenate_results_from_multi_process合并结果对象析构时由__del__调用stop_self_pool清理进程与显存。2.4 通用后处理钩子_convert_to_numpy在 bf16 推理且非 CPU 设备上先将bfloat16张量升为float32再转 numpyNumPy 不支持 bfloat16_truncate_embeddings配合 Matryoshka 表示学习模型当truncate_dim不为None时截取前truncate_dim维例如把 4096 维向量截到 1024 维使用。三、BaseEmbedder编码器模型的通用推理封装3.1 构造参数速查BaseEmbedderencoder_only/base.py用于加载任意 HuggingFace 编码器模型AutoModel核心参数与默认值如下参数默认值说明model_name_or_path必填本地模型路径或 HuggingFace Hub 上的模型名normalize_embeddingsTrue是否对输出向量做 L2 归一化use_fp16True半精度推理加速轻微精度损失use_bf16False使用 bfloat16优先于 fp16query_instruction_for_retrievalNone检索任务查询指令文本query_instruction_format{}{}指令拼接模板devicesNone推理设备见上文设备探测逻辑pooling_methodcls池化方式cls或meantrust_remote_codeFalse是否信任远端模型自定义代码cache_dirNone模型缓存目录batch_size256推理批大小query_max_length512查询最大 token 长度passage_max_length512语料最大 token 长度convert_to_numpyTrue输出 numpy 数组而非张量truncate_dimNoneMatryoshka 截断维度构造时使用AutoTokenizer.from_pretrained与AutoModel.from_pretrained加载模型并按get_model_torch_dtypebf16 fp16 fp32设置精度。3.2 池化方法实现pooling(last_hidden_state, attention_mask)第 284-308 行支持两种方法cls直接取last_hidden_state[:, 0]即[CLS]token 的隐状态mean按 attention mask 对非 padding 位置的隐状态做加权平均s / d其中s是掩码加权和、d是有效 token 数其他值抛出NotImplementedError。3.3 单设备编码流水线encode_single_deviceencode_single_device第 174-282 行是理解整个库推理性能设计的关键流程如下单条字符串输入会先包成列表并在返回时还原input_was_string标记预分词先不带 padding 分词记录每条输入的真实长度按长度降序排序np.argsort将长度相近的样本分到同一 batch最大限度减少 padding 浪费batch size 自适应用试跑一个 batch的方式探测显存捕获RuntimeError或torch.cuda.OutOfMemoryError时把batch_size乘以3/4缩小重试正式推理forward 取last_hidden_state→pooling→_truncate_embeddings→ 按需 L2 归一化 → 按需转 numpy按length_sorted_idx的逆序还原样本顺序后返回。这套预排序 自适应 batch的设计在长尾长度的真实语料上能显著提升吞吐是仓库在大量推理场景中推荐的默认实现。四、M3EmbedderBGE-M3 的稠密 稀疏 多向量混合检索M3Embedderencoder_only/m3.py专为 BGE-M3 设计在BaseEmbedder基础上新增了**稀疏词权重lexical weights与ColBERT 多向量colbert vecs**两种输出覆盖稠密检索、稀疏检索、多向量重排三类能力。4.1 独有构造参数除BaseEmbedder的通用参数外还包含参数默认值说明colbert_dim-1ColBERT 线性投影维度-1表示使用模型 hidden_sizereturn_denseTrue是否返回稠密向量return_sparseFalse是否返回稀疏词权重字典return_colbert_vecsFalse是否返回 ColBERT 多向量模型加载走专门的EncoderOnlyEmbedderM3ModelForInference包装类来自FlagEmbedding.finetune.embedder.encoder_only.m3内部负责把 tokenizer、池化与归一化装配在一起。4.2 encode_* 方法的字典返回值encode_queries/encode_corpus/encode的返回类型统一为字典Dict[Literal[dense_vecs, lexical_weights, colbert_vecs], Union[np.ndarray, List[Dict[str, float]], List[np.ndarray]]]dense_vecs归一化后的稠密向量np.ndarraylexical_weights每个样本一个{token_id: weight}字典token_id 为字符串形式已剔除 cls/eos/pad/unk 等特殊 token且同 token 取最大权重见_process_token_weightscolbert_vecs去掉 padding 与[CLS]后的逐 token 向量列表。三个方法的默认长度/开关回退规则各不相同encode_queries用query_max_lengthencode_corpus与encode用passage_max_length若调用时未显式传return_dense/sparse/colbert_vecs则回退到构造时的对应开关。4.3 词级与向量级辅助方法convert_id_to_token(lexical_weights)把{token_id: weight}字典转换为{token: weight}方便直接阅读或对接 BM25 类检索器compute_lexical_matching_score(lw1, lw2)按共享 token 的权重乘积求和计算稀疏匹配分数支持单对单返回 float、批量对返回np.ndarray两种形态colbert_score(q_reps, p_reps)用torch.einsum(in,jn-ij)计算查询-文档 token 相似度矩阵取每行最大值MaxSim后求均值得到 ColBERT 风格的交互分数。4.4 混合打分compute_score 系列compute_score(sentence_pairs, batch_size, max_query_length, max_passage_length, weights_for_different_modes)第 488-538 行直接对(query, passage)对打分返回五档分数Dict[Literal[colbert, sparse, dense, sparsedense, colbertsparsedense], List[float]]单卡时直接走compute_score_single_device多卡时启动M3Embedder._compute_score_multi_process_worker进程池用compute_score_multi_process分块并汇总weights_for_different_modes是稠密、稀疏、ColBERT 三者的权重列表长度必须为 3默认[1.0, 1.0, 1.0]即等权融合sparsedense与colbertsparsedense分别按权重做加权平均。这在 hybrid 检索评测如仓库research/C_MTEB、evaluation下的多个 benchmark中是直接可复用的打分 API。五、BaseLLMEmbedder解码器 LLM 的嵌入封装5.1 与编码器版本的关键差异BaseLLMEmbedderdecoder_only/base.py面向 LLM 类嵌入模型与BaseEmbedder的差异集中在三点默认指令模板不同query_instruction_format默认值从{}{}变为Instruct: {}\nQuery: {}适配 E5、SFR、bge-reasoner 等指令式 LLM 嵌入模型池化方式强制为 last_token构造时校验kwargs.get(pooling_method, last_token)一旦传入非last_token立即抛ValueError(Pooling method must be last_token for LLM-based models.)池化函数不同使用模块级函数last_token_pool第 12-29 行——先判断是否为左 paddingattention_mask[:, -1].sum() batch 行数是则取最后一个位置last_hidden_states[:, -1]否则按每行有效 token 数定位最后一个真实 token 并取对应隐状态从而兼容paddingTrue的 batch 推理。5.2 编码流水线encode_single_device与BaseEmbedder的结构一致预分词 → 长度排序 → 自适应 batch → last_token 池化 → 归一化 → 输出并在参数注释中提示对于 bge-multilingual-gemma2 等模型可在 kwargs 中传pad_to_multiple_of8。由于 LLM 序列较长实际使用中建议配合batch_size与max_length的调优来控制显存占用。六、ICLLLMEmbedder带示例注入的上下文学习嵌入ICLLLMEmbedderdecoder_only/icl.py面向 BGE-EN-ICL 这类通过 few-shot 示例增强检索的模型把指令 示例 查询组装成模型特有的模板再编码使模型针对当前任务自适应。6.1 独有参数参数默认值说明query_instruction_formatinstruct{}\nquery{}查询指令模板构造时自动把\n字面量转为真实换行suffix\nresponse查询后追加的后缀 token 序列examples_for_taskNonefew-shot 示例列表元素为含instruct/query/response键的字典examples_instruction_formatinstruct{}\nquery{}\nresponse{}单个示例的组装模板6.2 示例管理与前缀组装set_examples(examples_for_taskNone)第 133-165 行把示例按examples_instruction_format展开后以\n\n连接末尾再补\n\n作为self.prefix未提供任何示例时prefix为空串get_detailed_example(instruction_format, instruction, query, response)第 167-182 行静态方法负责单条示例的模板拼接构造完成后立即调用self.set_examples()把构造参数中的examples_for_task固化为前缀。6.3 带前缀的查询编码encode_queries_single_device第 322-457 行是 ICL 模式的核心处理链条为用query_instruction_format拼接检索指令与查询文本将self.prefix与self.suffix分词后重新计算有效最大长度new_max_length (len(prefix_ids) len(suffix_ids) max_length 8) // 8 * 8 88 对齐兼顾部分模型对序列长度的对齐要求预分词阶段把每条文本重写为prefix 截断后的查询 suffix之后的长度排序、自适应 batch、last_token 池化、归一化与BaseLLMEmbedder一致。此外ICL 类为查询单独维护了一个query_pool与语料编码的pool分离并在encode_corpus前调用stop_self_query_pool释放查询侧的多进程资源避免两套进程池互相干扰。七、从 API 到自动装配模型映射与统一入口尽管embedder.rst只列出四个类但仓库在 FlagEmbedding/inference/embedder/model_mapping.py 中为它们建立了完整的模型名 → 类 池化方式 指令模板映射表EmbedderModelClass枚举了encoder-only-base、encoder-only-m3、decoder-only-base、decoder-only-icl、decoder-only-pseudo_moe五种类型BGE_MAPPING把bge-m3→BGEM3FlagModel(cls)、bge-en-icl→FlagICLModel(last_token, instruct{}\nquery{})、bge-large-en-v1.5等 →FlagModel(cls)、bge-reasoner-embed-qwen3-8b-0923→FlagLLMModel(Instruct: {}\nQuery: {})此外还有QWEN3_EMBEDDING_MAPPING、E5_MAPPING、GTE_MAPPING、SFR_MAPPING、LINQ_MAPPING、BCE_MAPPING最终合并为AUTO_EMBEDDER_MAPPING由support_model_list()列出全部支持模型名。这意味着在实际项目中多数情况下无需手动实例化上述四个类直接使用统一入口FlagAutoModelFlagEmbedding/inference/auto_embedder.py即可按模型名自动匹配正确的类、池化方式与指令模板需要精细控制时再回到这四个类手工配置。八、典型使用示例与工程建议以下示例演示如何直接使用四类 API均为仓库真实支持的调用形态仓库另附多份可运行的完整示例脚本见 examples/inference/embedder/encoder_only 与 examples/inference/embedder/decoder_onlyfrom FlagEmbedding import FlagModel, BGEM3FlagModel, FlagLLMModel, FlagICLModel # 1) 编码器模型BGE v1.5 系列等cls 池化 model FlagModel(bge-large-en-v1.5, query_instruction_for_retrievalRepresent this sentence for searching relevant passages:, use_fp16True) q_emb model.encode_queries([how to use FlagEmbedding?]) c_emb model.encode_corpus([FlagEmbedding is a library for retrieval., ...]) # 2) BGE-M3 混合输出稠密 稀疏 多向量 m3 BGEM3FlagModel(bge-m3, use_fp16True, return_denseTrue, return_sparseTrue, return_colbert_vecsTrue) out m3.encode_queries([query text]) dense, lexical, colbert out[dense_vecs], out[lexical_weights], out[colbert_vecs] # 词 id 转回 token、并直接算稀疏匹配分 lexical_tokens m3.convert_id_to_token(lexical) scores m3.compute_lexical_matching_score(lexical, lexical) # 或直接对 (query, passage) 混合打分 hybrid m3.compute_score([(q1, p1)], weights_for_different_modes[1., 1., 1.]) # 3) LLM 嵌入模型last_token 池化指令模板自动拼接 llm FlagLLMModel(bge-reasoner-embed-qwen3-8b-0923, query_max_length8192, batch_size16) q_emb llm.encode_queries([query text]) # 4) ICL 上下文学习注入 few-shot 示例 icl FlagICLModel(bge-en-icl, examples_for_task[ {instruct: Given a web search query, retrieve relevant passages..., query: example query, response: example passage} ]) q_emb icl.encode_queries([real query])工程使用建议显存优先LLM 类BaseLLMEmbedder/ICLLLMEmbedder建议调小batch_size并配合use_bf16True超大语料可先encode_corpus批量建索引再encode_queries在线检索多卡扩展传入devices[cuda:0, cuda:1]即可自动走多进程池并行注意每卡一个进程是推荐配置检索评估M3Embedder.compute_score可直接用于 hybrid 检索的分数融合验证仓库的 evaluation 与 research/C_MTEB 目录提供了 MSMARCO、BEIR、MIRACL、MLDR 等基准的完整评测配套回归验证仓库测试目录中的 tests/test_infer_embedder_basic.py 覆盖了 Embedder 的基础推理路径可作为自定义封装后的自检参考。九、小结FlagEmbedding 的推理 Embedder API 用一个抽象基类 四个具体类覆盖了当前主流的两代嵌入模型范式BaseEmbedder与M3Embedder服务于编码器架构单向量检索与稠密稀疏多向量混合检索BaseLLMEmbedder与ICLLLMEmbedder服务于解码器 LLM 架构指令式嵌入与上下文学习嵌入。理解它们的参数默认值、三入口编码约定、池化差异与多设备调度机制是高效使用 BGE 系列模型构建 RAG 与检索系统的基础也是阅读仓库评测与微调代码FlagEmbedding.abc.inference、FlagEmbedding.finetune.embedder的切入点。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FlagEmbedding 推理 Embedder API 全解析：BaseEmbedder、M3Embedder、BaseLLMEmbedder 与 ICLLLMEmbedder 的架构、参数与实战
FlagEmbedding 推理 Embedder API 全解析BaseEmbedder、M3Embedder、BaseLLMEmbedder 与 ICLLLMEmbedder 的架构、参数与实战【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇技术指南聚焦 FlagEmbedding 的推理侧inferenceEmbedder API系统讲解仓库 API 文档docs/source/API/inference/embedder/embedder.rst所覆盖的四类嵌入模型封装类面向编码器架构的BaseEmbedder、面向 BGE-M3 多模态检索的M3Embedder、面向解码器 LLM 的BaseLLMEmbedder以及支持上下文学习In-Context Learning的ICLLLMEmbedder。读完本文你将掌握每个类的构造参数含义与默认值、encode_queries/encode_corpus/encode等核心方法的调用约定、底层 pooling 与多设备推理的实现原理并能直接照搬到自己的检索与 RAG 项目中。一、文档结构与四类 Embedder 的总览embedder.rst本身是一个 Sphinx toctree 索引页它挂载了四个子 API 页面分别对应四个推理类子文档对应类适用模型架构代表模型encoder_only/BaseEmbedder.rstFlagEmbedding.inference.embedder.encoder_only.base.BaseEmbedder编码器Encoder-onlyBERT 类BGE v1/v1.5 系列、e5、gte 等encoder_only/M3Embedder.rstFlagEmbedding.inference.embedder.encoder_only.m3.M3Embedder编码器多向量/稀疏/稠密混合BGE-M3decoder_only/BaseLLMEmbedder.rstFlagEmbedding.inference.embedder.decoder_only.base.BaseLLMEmbedder解码器Decoder-onlyLLMbge-reasoner、Qwen3-Embedding、SFR-Embedding 等decoder_only/ICLLLMEmbedder.rstFlagEmbedding.inference.embedder.decoder_only.icl.ICLLLMEmbedder解码器上下文学习BGE-EN-ICL在代码层面这四个类分别定义在 FlagEmbedding/inference/embedder/encoder_only/base.py、m3.py、decoder_only/base.py 与 decoder_only/icl.py并统一从FlagEmbedding/inference/embedder/__init__.py导出为FlagModel、BGEM3FlagModel、FlagLLMModel、FlagICLModel等用户友好的别名。四者都继承自抽象基类AbsEmbedder见 FlagEmbedding/abc/inference/AbsEmbedder.py因此共享一套查询/语料/通用编码接口约定差异集中在 pooling 方式与多模态输出上。二、共同架构抽象基类 AbsEmbedder 与统一编码流程所有 Embedder 的骨架由AbsEmbedder定义FlagEmbedding/abc/inference/AbsEmbedder.py其 docstring 明确说明扩展该类并实现encode_queries、encode_corpus、encode三个方法即可自定义 Embedder。2.1 统一的三入口设计encode_queries(queries, ...)编码查询。内部以self.query_max_length为默认长度上限并自动拼接检索指令query_instruction_for_retrieval见 AbsEmbedder.py 的encode_queries实现。encode_corpus(corpus, ...)编码语料/文档。以self.passage_max_length为默认长度上限并支持通过 kwargs 传入passage_instruction_for_retrieval/passage_instruction_format为语料附加独立的指令默认{}{}。encode(sentences, ...)通用编码入口最终依据设备数量决定走单设备路径encode_single_device还是多进程池路径encode_multi_process。三者均支持输入单个字符串str或字符串列表List[str]返回值可以是numpy.ndarray或torch.Tensor由convert_to_numpy控制默认True返回 numpy 数组。2.2 指令拼接机制get_detailed_instruct(instruction_format, instruction, sentence)AbsEmbedder.py 第 157-170 行按模板把指令与句子组合def get_detailed_instruct(instruction_format: str, instruction: str, sentence: str): if \\n in instruction_format: instruction_format instruction_format.replace(\\n, \n) return instruction_format.format(instruction, sentence)例如query_instruction_formatInstruct: {}\nQuery: {}会把检索指令 查询文本拼成Instruct: 指令\nQuery: 查询。注意源码会对字面量\n做一次显式替换因此既支持在 Python 字符串中写真实换行也支持写\n转义序列。2.3 设备自动探测与多进程并行get_target_devices(devices)AbsEmbedder.py 第 110-154 行是一套完整的设备解析逻辑devicesNone时按优先级自动探测CUDA全部可用卡cuda:0...N→ NPUnpu:0...N→ MUSAmusa:0...N→ MPSApple Silicon→ 兜底cpu传入str如cuda:0、int如0、字符串列表或整数列表均可当检测到多张卡且输入为批量列表时encode会通过start_multi_process_pool启动每卡一个进程的 worker 池配合encode_multi_process分块分发、_concatenate_results_from_multi_process合并结果对象析构时由__del__调用stop_self_pool清理进程与显存。2.4 通用后处理钩子_convert_to_numpy在 bf16 推理且非 CPU 设备上先将bfloat16张量升为float32再转 numpyNumPy 不支持 bfloat16_truncate_embeddings配合 Matryoshka 表示学习模型当truncate_dim不为None时截取前truncate_dim维例如把 4096 维向量截到 1024 维使用。三、BaseEmbedder编码器模型的通用推理封装3.1 构造参数速查BaseEmbedderencoder_only/base.py用于加载任意 HuggingFace 编码器模型AutoModel核心参数与默认值如下参数默认值说明model_name_or_path必填本地模型路径或 HuggingFace Hub 上的模型名normalize_embeddingsTrue是否对输出向量做 L2 归一化use_fp16True半精度推理加速轻微精度损失use_bf16False使用 bfloat16优先于 fp16query_instruction_for_retrievalNone检索任务查询指令文本query_instruction_format{}{}指令拼接模板devicesNone推理设备见上文设备探测逻辑pooling_methodcls池化方式cls或meantrust_remote_codeFalse是否信任远端模型自定义代码cache_dirNone模型缓存目录batch_size256推理批大小query_max_length512查询最大 token 长度passage_max_length512语料最大 token 长度convert_to_numpyTrue输出 numpy 数组而非张量truncate_dimNoneMatryoshka 截断维度构造时使用AutoTokenizer.from_pretrained与AutoModel.from_pretrained加载模型并按get_model_torch_dtypebf16 fp16 fp32设置精度。3.2 池化方法实现pooling(last_hidden_state, attention_mask)第 284-308 行支持两种方法cls直接取last_hidden_state[:, 0]即[CLS]token 的隐状态mean按 attention mask 对非 padding 位置的隐状态做加权平均s / d其中s是掩码加权和、d是有效 token 数其他值抛出NotImplementedError。3.3 单设备编码流水线encode_single_deviceencode_single_device第 174-282 行是理解整个库推理性能设计的关键流程如下单条字符串输入会先包成列表并在返回时还原input_was_string标记预分词先不带 padding 分词记录每条输入的真实长度按长度降序排序np.argsort将长度相近的样本分到同一 batch最大限度减少 padding 浪费batch size 自适应用试跑一个 batch的方式探测显存捕获RuntimeError或torch.cuda.OutOfMemoryError时把batch_size乘以3/4缩小重试正式推理forward 取last_hidden_state→pooling→_truncate_embeddings→ 按需 L2 归一化 → 按需转 numpy按length_sorted_idx的逆序还原样本顺序后返回。这套预排序 自适应 batch的设计在长尾长度的真实语料上能显著提升吞吐是仓库在大量推理场景中推荐的默认实现。四、M3EmbedderBGE-M3 的稠密 稀疏 多向量混合检索M3Embedderencoder_only/m3.py专为 BGE-M3 设计在BaseEmbedder基础上新增了**稀疏词权重lexical weights与ColBERT 多向量colbert vecs**两种输出覆盖稠密检索、稀疏检索、多向量重排三类能力。4.1 独有构造参数除BaseEmbedder的通用参数外还包含参数默认值说明colbert_dim-1ColBERT 线性投影维度-1表示使用模型 hidden_sizereturn_denseTrue是否返回稠密向量return_sparseFalse是否返回稀疏词权重字典return_colbert_vecsFalse是否返回 ColBERT 多向量模型加载走专门的EncoderOnlyEmbedderM3ModelForInference包装类来自FlagEmbedding.finetune.embedder.encoder_only.m3内部负责把 tokenizer、池化与归一化装配在一起。4.2 encode_* 方法的字典返回值encode_queries/encode_corpus/encode的返回类型统一为字典Dict[Literal[dense_vecs, lexical_weights, colbert_vecs], Union[np.ndarray, List[Dict[str, float]], List[np.ndarray]]]dense_vecs归一化后的稠密向量np.ndarraylexical_weights每个样本一个{token_id: weight}字典token_id 为字符串形式已剔除 cls/eos/pad/unk 等特殊 token且同 token 取最大权重见_process_token_weightscolbert_vecs去掉 padding 与[CLS]后的逐 token 向量列表。三个方法的默认长度/开关回退规则各不相同encode_queries用query_max_lengthencode_corpus与encode用passage_max_length若调用时未显式传return_dense/sparse/colbert_vecs则回退到构造时的对应开关。4.3 词级与向量级辅助方法convert_id_to_token(lexical_weights)把{token_id: weight}字典转换为{token: weight}方便直接阅读或对接 BM25 类检索器compute_lexical_matching_score(lw1, lw2)按共享 token 的权重乘积求和计算稀疏匹配分数支持单对单返回 float、批量对返回np.ndarray两种形态colbert_score(q_reps, p_reps)用torch.einsum(in,jn-ij)计算查询-文档 token 相似度矩阵取每行最大值MaxSim后求均值得到 ColBERT 风格的交互分数。4.4 混合打分compute_score 系列compute_score(sentence_pairs, batch_size, max_query_length, max_passage_length, weights_for_different_modes)第 488-538 行直接对(query, passage)对打分返回五档分数Dict[Literal[colbert, sparse, dense, sparsedense, colbertsparsedense], List[float]]单卡时直接走compute_score_single_device多卡时启动M3Embedder._compute_score_multi_process_worker进程池用compute_score_multi_process分块并汇总weights_for_different_modes是稠密、稀疏、ColBERT 三者的权重列表长度必须为 3默认[1.0, 1.0, 1.0]即等权融合sparsedense与colbertsparsedense分别按权重做加权平均。这在 hybrid 检索评测如仓库research/C_MTEB、evaluation下的多个 benchmark中是直接可复用的打分 API。五、BaseLLMEmbedder解码器 LLM 的嵌入封装5.1 与编码器版本的关键差异BaseLLMEmbedderdecoder_only/base.py面向 LLM 类嵌入模型与BaseEmbedder的差异集中在三点默认指令模板不同query_instruction_format默认值从{}{}变为Instruct: {}\nQuery: {}适配 E5、SFR、bge-reasoner 等指令式 LLM 嵌入模型池化方式强制为 last_token构造时校验kwargs.get(pooling_method, last_token)一旦传入非last_token立即抛ValueError(Pooling method must be last_token for LLM-based models.)池化函数不同使用模块级函数last_token_pool第 12-29 行——先判断是否为左 paddingattention_mask[:, -1].sum() batch 行数是则取最后一个位置last_hidden_states[:, -1]否则按每行有效 token 数定位最后一个真实 token 并取对应隐状态从而兼容paddingTrue的 batch 推理。5.2 编码流水线encode_single_device与BaseEmbedder的结构一致预分词 → 长度排序 → 自适应 batch → last_token 池化 → 归一化 → 输出并在参数注释中提示对于 bge-multilingual-gemma2 等模型可在 kwargs 中传pad_to_multiple_of8。由于 LLM 序列较长实际使用中建议配合batch_size与max_length的调优来控制显存占用。六、ICLLLMEmbedder带示例注入的上下文学习嵌入ICLLLMEmbedderdecoder_only/icl.py面向 BGE-EN-ICL 这类通过 few-shot 示例增强检索的模型把指令 示例 查询组装成模型特有的模板再编码使模型针对当前任务自适应。6.1 独有参数参数默认值说明query_instruction_formatinstruct{}\nquery{}查询指令模板构造时自动把\n字面量转为真实换行suffix\nresponse查询后追加的后缀 token 序列examples_for_taskNonefew-shot 示例列表元素为含instruct/query/response键的字典examples_instruction_formatinstruct{}\nquery{}\nresponse{}单个示例的组装模板6.2 示例管理与前缀组装set_examples(examples_for_taskNone)第 133-165 行把示例按examples_instruction_format展开后以\n\n连接末尾再补\n\n作为self.prefix未提供任何示例时prefix为空串get_detailed_example(instruction_format, instruction, query, response)第 167-182 行静态方法负责单条示例的模板拼接构造完成后立即调用self.set_examples()把构造参数中的examples_for_task固化为前缀。6.3 带前缀的查询编码encode_queries_single_device第 322-457 行是 ICL 模式的核心处理链条为用query_instruction_format拼接检索指令与查询文本将self.prefix与self.suffix分词后重新计算有效最大长度new_max_length (len(prefix_ids) len(suffix_ids) max_length 8) // 8 * 8 88 对齐兼顾部分模型对序列长度的对齐要求预分词阶段把每条文本重写为prefix 截断后的查询 suffix之后的长度排序、自适应 batch、last_token 池化、归一化与BaseLLMEmbedder一致。此外ICL 类为查询单独维护了一个query_pool与语料编码的pool分离并在encode_corpus前调用stop_self_query_pool释放查询侧的多进程资源避免两套进程池互相干扰。七、从 API 到自动装配模型映射与统一入口尽管embedder.rst只列出四个类但仓库在 FlagEmbedding/inference/embedder/model_mapping.py 中为它们建立了完整的模型名 → 类 池化方式 指令模板映射表EmbedderModelClass枚举了encoder-only-base、encoder-only-m3、decoder-only-base、decoder-only-icl、decoder-only-pseudo_moe五种类型BGE_MAPPING把bge-m3→BGEM3FlagModel(cls)、bge-en-icl→FlagICLModel(last_token, instruct{}\nquery{})、bge-large-en-v1.5等 →FlagModel(cls)、bge-reasoner-embed-qwen3-8b-0923→FlagLLMModel(Instruct: {}\nQuery: {})此外还有QWEN3_EMBEDDING_MAPPING、E5_MAPPING、GTE_MAPPING、SFR_MAPPING、LINQ_MAPPING、BCE_MAPPING最终合并为AUTO_EMBEDDER_MAPPING由support_model_list()列出全部支持模型名。这意味着在实际项目中多数情况下无需手动实例化上述四个类直接使用统一入口FlagAutoModelFlagEmbedding/inference/auto_embedder.py即可按模型名自动匹配正确的类、池化方式与指令模板需要精细控制时再回到这四个类手工配置。八、典型使用示例与工程建议以下示例演示如何直接使用四类 API均为仓库真实支持的调用形态仓库另附多份可运行的完整示例脚本见 examples/inference/embedder/encoder_only 与 examples/inference/embedder/decoder_onlyfrom FlagEmbedding import FlagModel, BGEM3FlagModel, FlagLLMModel, FlagICLModel # 1) 编码器模型BGE v1.5 系列等cls 池化 model FlagModel(bge-large-en-v1.5, query_instruction_for_retrievalRepresent this sentence for searching relevant passages:, use_fp16True) q_emb model.encode_queries([how to use FlagEmbedding?]) c_emb model.encode_corpus([FlagEmbedding is a library for retrieval., ...]) # 2) BGE-M3 混合输出稠密 稀疏 多向量 m3 BGEM3FlagModel(bge-m3, use_fp16True, return_denseTrue, return_sparseTrue, return_colbert_vecsTrue) out m3.encode_queries([query text]) dense, lexical, colbert out[dense_vecs], out[lexical_weights], out[colbert_vecs] # 词 id 转回 token、并直接算稀疏匹配分 lexical_tokens m3.convert_id_to_token(lexical) scores m3.compute_lexical_matching_score(lexical, lexical) # 或直接对 (query, passage) 混合打分 hybrid m3.compute_score([(q1, p1)], weights_for_different_modes[1., 1., 1.]) # 3) LLM 嵌入模型last_token 池化指令模板自动拼接 llm FlagLLMModel(bge-reasoner-embed-qwen3-8b-0923, query_max_length8192, batch_size16) q_emb llm.encode_queries([query text]) # 4) ICL 上下文学习注入 few-shot 示例 icl FlagICLModel(bge-en-icl, examples_for_task[ {instruct: Given a web search query, retrieve relevant passages..., query: example query, response: example passage} ]) q_emb icl.encode_queries([real query])工程使用建议显存优先LLM 类BaseLLMEmbedder/ICLLLMEmbedder建议调小batch_size并配合use_bf16True超大语料可先encode_corpus批量建索引再encode_queries在线检索多卡扩展传入devices[cuda:0, cuda:1]即可自动走多进程池并行注意每卡一个进程是推荐配置检索评估M3Embedder.compute_score可直接用于 hybrid 检索的分数融合验证仓库的 evaluation 与 research/C_MTEB 目录提供了 MSMARCO、BEIR、MIRACL、MLDR 等基准的完整评测配套回归验证仓库测试目录中的 tests/test_infer_embedder_basic.py 覆盖了 Embedder 的基础推理路径可作为自定义封装后的自检参考。九、小结FlagEmbedding 的推理 Embedder API 用一个抽象基类 四个具体类覆盖了当前主流的两代嵌入模型范式BaseEmbedder与M3Embedder服务于编码器架构单向量检索与稠密稀疏多向量混合检索BaseLLMEmbedder与ICLLLMEmbedder服务于解码器 LLM 架构指令式嵌入与上下文学习嵌入。理解它们的参数默认值、三入口编码约定、池化差异与多设备调度机制是高效使用 BGE 系列模型构建 RAG 与检索系统的基础也是阅读仓库评测与微调代码FlagEmbedding.abc.inference、FlagEmbedding.finetune.embedder的切入点。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考