FlagEmbedding Reranker 全面指南从推理调用、微调训练到评估【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇技术指南以 FlagEmbedding 仓库中的 research/reranker/README.md 为核心系统讲解 BGE Reranker 系列模型bge-reranker-base / large的原理定位、双框架推理用法FlagEmbedding 与 HuggingFace Transformers、微调数据格式与三种训练方案并结合仓库源码分析底层实现。读完本文你将能够在检索增强RAG流程中独立部署 Reranker、构造高质量微调数据并完成端到端训练与评估。一、Reranker 是什么与 Embedding 模型的本质区别Reranker重排序模型与 Embedding向量检索模型在建模方式上有根本差异Embedding 模型将 query 和 passage 分别编码为稠密向量通过向量相似度如余弦相似度度量相关性。文档向量可离线构建索引适合大规模候选召回。Reranker 模型将query 与 passage 拼接作为整体输入直接输出一个相关性分数而不是向量。因此 Reranker 通常用于对召回阶段产出的 Top-N 候选文档进行精排是两阶段检索召回 精排中的第二阶段。原文档明确指出Reranker 基于交叉熵损失cross-entropy loss优化因此它输出的相关性分数不限定在某个固定区间内——分数本身没有绝对含义只有在同一批候选之间比较时才有意义分数越高表示越相关。这一点与常用 Sigmoid 归一化的向量相似度0~1形成鲜明对比。从仓库源码看这一设计体现在 FlagEmbedding/inference/reranker/encoder_only/base.py 中BaseReranker.compute_score_single_gpu直接取self.model(**inputs, return_dictTrue).logits.view(-1, ).float()作为分数即序列分类头的 logits。同时该类也提供了可选的normalize参数若置为True则会对 logits 施加 Sigmoid 归一化源码中的sigmoid(x) 1 / (1 exp(-x))方便将分数映射到 (0,1) 区间用于业务展示。二、快速开始用 FlagEmbedding 调用 Reranker2.1 安装pip install -U FlagEmbedding如需微调能力含训练依赖可安装带finetuneextra 的版本pip install -U FlagEmbedding[finetune]2.2 计算相关性分数from FlagEmbedding import FlagReranker reranker FlagReranker(BAAI/bge-reranker-large, use_fp16True) # Setting use_fp16 to True speeds up computation with a slight performance degradation score reranker.compute_score([query, passage]) print(score) scores reranker.compute_score([[what is panda?, hi], [what is panda?, The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.]]) print(scores)要点说明compute_score既支持单个 pair[query, passage]也支持pair 列表批量打分适合对一批候选文档重排。use_fp16True以半精度推理换取速度提升会带来轻微的精度损失对分数排序影响通常可忽略。返回的分数越高表示相关性越强。三、用 HuggingFace Transformers 直接调用如果你不想引入 FlagEmbedding 依赖也可以用原生 Transformers 复现同样的打分逻辑import torch from transformers import AutoModelForSequenceClassification, AutoTokenizer tokenizer AutoTokenizer.from_pretrained(BAAI/bge-reranker-large) model AutoModelForSequenceClassification.from_pretrained(BAAI/bge-reranker-large) model.eval() pairs [[what is panda?, hi], [what is panda?, The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.]] with torch.no_grad(): inputs tokenizer(pairs, paddingTrue, truncationTrue, return_tensorspt, max_length512) scores model(**inputs, return_dictTrue).logits.view(-1, ).float() print(scores)这段代码与 FlagEmbedding 内部实现的核心逻辑一致bge-reranker-large本身就是AutoModelForSequenceClassification兼容的 checkpoint输入为[query, passage]的 pair 列表取logits作为分数。四、深入源码FlagReranker 推理管线如何工作为了让读者对直接输出分数有更具体的感知这里结合源码拆解推理管线设备管理AbsReranker.get_target_devices见 FlagEmbedding/abc/inference/AbsReranker.py支持自动检测 CUDA / NPU / MUSA / MPS 设备传入devices[cuda:0]可手动指定。指令注入get_detailed_inputs会在启用query_instruction_for_rerank/passage_instruction_for_rerank时按query_instruction_format/passage_instruction_format默认{}{}拼接指令前缀。分长度 tokenizecompute_score_single_gpuencoder_only/base.py先分别对 queryquery_max_length未指定时默认为max_length * 3 // 4和 passagemax_length默认 512做截断 tokenize再通过prepare_for_model拼接为[CLS] query [SEP] passage形式。按长度排序减少 padding对所有 pair 按 token 长度降序排列后分批减少 padding 带来的计算浪费。自适应 batch 回退若前向发生 OOM / RuntimeErrorbatch_size 自动乘以 3/4 重试提升稳定性。结果还原按原始顺序还原分数np.argsort(length_sorted_idx)必要时 Sigmoid 归一化。另外仓库的 FlagEmbedding/inference/reranker/model_mapping.py 维护了自动路由映射FlagReranker对应encoder-only-base类FlagLLMReranker、LayerWiseFlagLLMReranker、LightWeightFlagLLMReranker分别对应 decoder-only 的 base、layerwise、lightweight 类。bge-reranker-v2-gemma 会自动路由到FlagLLMRerankerbge-reranker-v2-minicpm-layerwise 路由到LayerWiseFlagLLMReranker。从该映射还可以看到FlagReranker 同样支持加载jinaai/jina-reranker-v2-base-multilingual、Alibaba-NLP/gte-multilingual-reranker-base、maidalun1020/bce-reranker-base_v1等第三方序列分类式 Reranker。五、微调 Reranker数据格式与训练流程5.1 训练数据格式训练数据是JSON Lines每行一个 dict结构如下{query: str, pos: List[str], neg:List[str], pos_scores: List[int], neg_scores: List[int], prompt: str}字段含义query查询文本pos正例相关文档文本列表neg负例不相关文档文本列表pos_scores/neg_scores与 query 对应的分数列表仅在知识蒸馏knowledge distillation场景下需要否则可忽略prompt输入所用的指令前缀最终输入格式为query [sep] passage [sep] prompt。如果某个 query 没有负例可以从整个语料库中随机采样若干文档作为负例。仓库提供了可直接参考的真实样例 examples/finetune/reranker/example_data/normal/examples.jsonl标准格式与 examples/finetune/reranker/example_data/prompt_based/examples.jsonl含 prompt 的格式供 decoder-only 指令式模型使用。从样例可见每个 query 通常带 1 个 pos 和约 25 个 neg并附有由教师模型打出的pos_scores/neg_scores。5.2 硬负样本挖掘Hard Negatives硬负样本是提升句向量/排序质量广泛使用的技巧。使用仓库脚本 scripts/hn_mine.py 挖掘git clone https://github.com/FlagOpen/FlagEmbedding.git cd FlagEmbedding/scriptspython hn_mine.py \ --model_name_or_path BAAI/bge-base-en-v1.5 \ --input_file toy_finetune_data.jsonl \ --output_file toy_finetune_data_minedHN.jsonl \ --range_for_sampling 2-200 \ --negative_number 15 \ --use_gpu_for_searching参数含义input_file微调用 json 数据。脚本会为每个 query 检索 top-k 文档并从 top-k排除正例文档中随机采样负例output_file挖掘硬负样本后的 JSON 数据保存路径negative_number采样的负样本数量range_for_sampling负样本采样区间。例如2-100表示从 top2-top200 文档中采样negative_number个负例。调大区间可降低负样本难度例如设为60-300表示从 top60-300 中采样candidate_pool检索候选池默认为 None即从input_file中所有neg的并集里检索若传入该文件则改为从该候选池中检索use_gpu_for_searching是否使用 faiss-gpu 加速负例检索。5.3 教师分数知识蒸馏数据准备教师分数用于模型蒸馏。使用仓库脚本 scripts/add_reranker_score.py 为数据打上分数python add_reranker_score.py \ --input_file toy_finetune_data_minedHN.jsonl \ --output_file toy_finetune_data_score.jsonl \ --reranker_name_or_path BAAI/bge-reranker-v2-m3 \ --devices cuda:0 cuda:1 \ --cache_dir ./cache/model \ --reranker_query_max_length 512 \ --reranker_max_length 1024关键参数input_file/output_file含硬负样本的输入数据与带分数的输出数据路径reranker_name_or_path作为教师模型的 Reranker 名称或路径reranker_model_class教师模型类别可选[auto, encoder-only-base, decoder-only-base, decoder-only-layerwise, decoder-only-lightweight]默认auto自动识别devices推理设备支持多个值如cuda:0 cuda:1use_fp16/use_bf16是否用 fp16 / bf16 推理默认 Falsereranker_batch_size推理 batch size默认 3000reranker_query_max_length/reranker_max_lengthquery 与拼接输入的最大长度后者默认 512normalize是否归一化重排分数默认 Falseprompt、cutoff_layers、compress_ratio、compress_layers分别用于 prompt 输入、layerwise 输出层与 lightweight 压缩参数。5.4 三种微调方案仓库在 examples/finetune/reranker 下提供了完整可运行的脚本对应 bash 文件见 encoder_only/base.sh、decoder_only/base.sh、decoder_only/layerwise.sh。训练前的通用参数model_name_or_path初始化所用的模型 checkpointmodel_type微调类型[encoder, decoder]默认encodertrain_data一个或多个训练数据路径数据中必须包含query、pos、neg字段train_group_size每组训练的文档数默认 8query_max_len/passage_max_lenquery 与 passage 的最大长度默认 32 / 128max_len总最大长度默认 512knowledge_distillation当训练数据含pos_scores/neg_scores时设为True启用知识蒸馏损失query_instruction_for_rerank/query_instruction_formatquery 侧指令及其格式默认{}{}passage_instruction_for_rerank/passage_instruction_formatpassage 侧指令及格式sep_tokenLLM Reranker 中区分 query 与 passage 的分隔符默认\n。(1) 标准模型Encoder-only如 bge-reranker-base / v2-m3torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.reranker.encoder_only.base \ --model_name_or_path BAAI/bge-reranker-v2-m3 \ --cache_dir ./cache/model \ --train_data ./example_data/normal/examples.jsonl \ --cache_path ./cache/data \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ --knowledge_distillation False \ --output_dir ./test_encoder_only_base_bge-reranker-base \ --overwrite_output_dir \ --learning_rate 6e-5 \ --fp16 \ --num_train_epochs 2 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 1 \ --dataloader_drop_last True \ --warmup_ratio 0.1 \ --gradient_checkpointing \ --weight_decay 0.01 \ --deepspeed ../ds_stage0.json \ --logging_steps 1 \ --save_steps 1000(2) bge-reranker-v2-gemmaDecoder-only 标准微调 LoRAtorchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.reranker.decoder_only.base \ --model_name_or_path BAAI/bge-reranker-v2-gemma \ --use_lora True \ --lora_rank 32 \ --lora_alpha 64 \ --use_flash_attn True \ --target_modules q_proj k_proj v_proj o_proj \ --save_merged_lora_model True \ --model_type decoder \ --cache_dir ./cache/model \ --train_data ./example_data/prompt_based/examples.jsonl \ --cache_path ./cache/data \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ --knowledge_distillation False \ --query_instruction_for_rerank A: \ --query_instruction_format {}{} \ --passage_instruction_for_rerank B: \ --passage_instruction_format {}{} \ --output_dir ./test_decoder_only_base_bge-reranker-v2-minicpm-layerwise \ --overwrite_output_dir \ --learning_rate 2e-4 \ --bf16 \ --num_train_epochs 1 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 1 \ --dataloader_drop_last True \ --warmup_ratio 0.1 \ --gradient_checkpointing \ --weight_decay 0.01 \ --deepspeed ../ds_stage0.json \ --logging_steps 1 \ --save_steps 1000新增参数use_lora启用 LoRA 参数高效训练、lora_rank/lora_alpha/lora_dropoutLoRA 秩、alpha 与 dropout、target_modules/modules_to_save应用与保存的模块列表、use_flash_attnFlash Attention、save_merged_lora_model合并 LoRA 并保存完整模型。(3) bge-reranker-v2-layerwise-minicpmLayerwise 分层微调torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.reranker.decoder_only.layerwise \ --model_name_or_path BAAI/bge-reranker-v2-minicpm-layerwise \ --use_lora True \ --lora_rank 32 \ --lora_alpha 64 \ --use_flash_attn True \ --target_modules q_proj k_proj v_proj o_proj \ --save_merged_lora_model True \ --model_type decoder \ --model_type from_finetuned_model \ --start_layer 8 \ --head_multi True \ --head_type simple \ --trust_remote_code True \ --cache_dir ./cache/model \ --train_data ./example_data/prompt_based/examples.jsonl \ --cache_path ./cache/data \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ --knowledge_distillation False \ --query_instruction_for_rerank A: \ --query_instruction_format {}{} \ --passage_instruction_for_rerank B: \ --passage_instruction_format {}{} \ --output_dir ./test_decoder_only_base_bge-reranker-v2-minicpm-layerwise \ --overwrite_output_dir \ --learning_rate 2e-4 \ --bf16 \ --num_train_epochs 1 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 1 \ --dataloader_drop_last True \ --warmup_ratio 0.1 \ --gradient_checkpointing \ --weight_decay 0.01 \ --deepspeed ../ds_stage0.json \ --logging_steps 1 \ --save_steps 1000新增参数model_typelayerwise 语境下模型来源上下文取值[from_raw_model, from_finetuned_model]start_layer从第几层开始计算分数提前退出兼顾速度与精度head_multi是否使用多个分类头head_type分类头类型。六、模型训练数据与多语言定位原文档说明了 bge-reranker 系列以 bge-reranker-large 为代表的训练构成模型初始化自xlm-roberta-base中文数据来自 T2ranking、MMmarco、dulreader、Cmedqa-v2、nli-zh 等数据集的788,491个文本对英文数据来自 msmarco、nq、hotpotqa、NLI 等数据集的933,090个文本对其他语言来自 Mr.TyDi 的97,458个文本对含阿拉伯语、孟加拉语、英语、芬兰语、印尼语、日语、韩语、俄语、斯瓦希里语、泰卢固语、泰语。为增强跨语言检索能力作者还基于 MMmarco 构造了两个跨语言检索数据集采样100,000 个英文 query 检索中文 passage以及100,000 个中文 query 检索英文 passage。该数据集已发布为Shitao/bge-reranker-data。需要明确的能力边界该模型目前主要支持中文和英文对其他低资源语言可能出现性能下降使用前应结合实际语言分布评估。七、评估在 C-MTEB 基准上的表现可以使用仓库提供的 C-MTEB 评估脚本见 research/C_MTEB对 Reranker 进行评测评测说明详见 research/C_MTEB/README.md 中的 Evaluate Reranker 一节。以下是原文档给出的 Reranker 在多个多语言重排任务上的评测结果T2Reranking、T2RerankingZh2En*、T2RerankingEn2Zh*、MmarcoReranking、CMedQAv1、CMedQAv2指标为 nDCG10 一类重排指标其中带 * 的两项为跨语言检索任务ModelT2RerankingT2RerankingZh2En*T2RerankingEn2Zh*MmarcoRerankingCMedQAv1CMedQAv2Avgtext2vec-base-multilingual64.6662.9462.5114.3748.4648.650.26multilingual-e5-small65.6260.9456.4129.9167.2666.5457.78multilingual-e5-large64.5561.6154.2828.667.4267.9257.4multilingual-e5-base64.2162.1354.6829.566.2366.9857.29m3e-base66.0362.7456.0717.5177.0576.7659.36m3e-large66.1362.7256.116.4677.7678.2759.57bge-base-zh-v1.566.4963.2557.0229.7480.4784.8863.64bge-large-zh-v1.565.7463.3957.0328.7483.4585.4463.97bge-reranker-base67.2863.9560.4535.4681.2684.165.42bge-reranker-large67.6064.0461.4537.1782.1484.1966.10从结果可以看到bge-reranker 系列在各任务上均高于同期的通用多语言向量/排序模型其中bge-reranker-large平均分最高66.10。需要说明的是这些数字来自原文档的评测报告反映其发布时的基准结果实际效果请以你自己在目标数据上的评估为准。八、Acknowledgement 与引用原文档致谢部分说明部分代码基于 Reranker 项目开发该链接为外部项目地址仅作背景说明。在仓库内你还可以通过 examples/finetune/reranker 下的可运行脚本、FlagEmbedding/inference/reranker 的推理实现以及 FlagEmbedding/finetune/reranker 的微调代码进一步深入。如果你在自己的工作中使用了本仓库成果原文档建议按如下 BibTeX 引用misc{bge_embedding, title{C-Pack: Packaged Resources To Advance General Chinese Embedding}, author{Shitao Xiao and Zheng Liu and Peitian Zhang and Niklas Muennighoff}, year{2023}, eprint{2309.07597}, archivePrefix{arXiv}, primaryClass{cs.CL} }总结Reranker 的落地建议两阶段检索架构用 Embedding 模型如 bge-base-zh-v1.5召回 Top-50~200再用 Reranker 精排取 Top-10 送入下游 LLM可在几乎不增加首轮召回成本的前提下显著提升最终检索精度。分数使用规范Reranker 分数不受区间约束只用于同一 query 下候选之间的相对排序如需展示为 0~1 置信度可开启normalizeTrueSigmoid。微调数据质量优先优先使用硬负样本挖掘scripts/hn_mine.py构造训练集若有大模型教师可通过 scripts/add_reranker_score.py 生成教师分数并开启知识蒸馏。按资源选方案中小规模场景选择 encoder-only 标准微调bge-reranker-base/v2-m3追求更强能力可微调 decoder-only 的 gemma 版本需要权衡速度与精度时可选择 layerwise 方案并通过start_layer控制提前退出层。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考