人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载本文是 sentence-transformers 仓库中MultiVectorEncoder多向量编码器又称 ColBERT / 晚期交互模型的 API 级使用指南。它以 model.md 为骨架结合 model.py 的源码实现讲解如何加载多向量模型、用encode_query/encode_document生成逐 token 向量、用similarity/similarity_pairwise进行 MaxSim 打分以及如何使用模型卡数据类MultiVectorEncoderModelCardData。读完本文你将掌握多向量检索的完整调用链并能直接上手语义检索、视觉文档检索ColPali 风格等实战场景。MultiVectorEncoder一句话理解它是什么MultiVectorEncoder是 sentence-transformers 中用于加载或创建多向量 / 晚期交互late-interactionColBERT 风格嵌入模型的类定义于 sentence_transformers/multi_vector_encoder/model.py。它与传统的SentenceTransformer有本质区别SentenceTransformer对每个输入只产生一个向量句子级嵌入MultiVectorEncoder对每个输入产生一个向量序列即每个 token 一个向量查询与文档之间的打分使用MaxSim 晚期交互算子对每个查询 token取它与所有文档 token 相似度的最大值再对所有查询 token 求和。这一设计保留了单向量模型丢弃的token 级匹配信息通常能带来更强的检索效果代价是更大的索引占用每个文档都存储为一串 token 向量而非单个向量。同时它是视觉文档检索ColPali 风格的事实标准文本查询可以直接匹配页面图像完全跳过 OCR相关说明见 docs/multi_vector_encoder/usage/usage.rst。核心构造参数MultiVectorEncoder.__init__的核心参数如下完整签名见 model.py参数类型 / 取值默认值说明model_name_or_pathstrNone磁盘路径则从本地加载否则尝试下载预训练多向量模型再失败则尝试用该名称从 Hugging Face Hub 构造模型moduleslist[nn.Module]None按顺序串行调用的 torch 模块列表可用于从零搭建自定义多向量模型devicecuda/cpu/mps/npuNone计算设备为None时自动检测可用 GPUpromptsdict[str, str]None标准 prompts 字典由 encode 方法前置到输入。ColBERT 风格模型需提供{query: [Q] , document: [D] }或模型自身的前缀 tokendefault_prompt_namestrNone默认使用的 prompt 名称未设置则不应用任何 promptcache_folderstrNone模型存储路径也可通过环境变量SENTENCE_TRANSFORMERS_HOME设置trust_remote_codeboolFalse是否允许加载 Hub 上自带建模代码的自定义模型revisionstrNone指定的模型版本local_files_onlyboolFalse是否仅使用本地文件tokenbool/strNoneHugging Face 认证 tokenmodel_kwargsdictNone透传给底层 Transformers 模型的关键字参数processor_kwargsdictNone透传给 HF processor / tokenizer 的关键字参数config_kwargsdictNone透传给 HF config 的关键字参数model_card_dataMultiVectorEncoderModelCardDataNone模型卡数据对象backendtorch/onnx/openvinotorch推理后端similarity_fn_namemaxsim/meanmaxsimmaxsim相似度函数名注意query_length、document_length、query_expansion、skiplist_words等长度 / 扩展 / 掩码旋钮并不直接挂在模型上而是位于底层模块Transformer与MultiVectorMask上并在保存时写入 checkpoint 配置见 model.py。默认模块流水线从测试 tests/multi_vector_encoder/test_model.py 可以看到一个从裸 HF backbone 构建的MultiVectorEncoder默认由 4 个模块组成Transformerbackbone产出上下文化 token 嵌入Densetoken 级投影将隐藏维度投影到多向量维度默认输出 128 维biasFalse、activation_functionnn.Identity()、module_input_nametoken_embeddingsMultiVectorMask计算打分掩码见下节Normalizetoken 级 L2 归一化module_input_nametoken_embeddings。默认情况下query_expansionNone经典 ColBERT 技巧属于显式配方选择而非默认行为skiplist_words[]空掩码列表。你可以在构造时传入modules...自定义投影如不同的输出维度。编码encode、encode_query 与 encode_document为什么检索要用不对称的 query / document 拆分多向量检索中查询与文档的预处理策略刻意不同这正是encode_query与encode_document存在的意义见 model.pyencode_query若未显式指定 prompt自动使用模型 prompts 字典中的query项设置taskquery从而插入查询前缀 token、使用query_length作为最大序列长度并在开启query_expansion时将输入扩展到指定长度encode_document自动使用document/passage/corpus中第一个可用的 prompt设置taskdocument插入文档前缀 token、使用document_length并应用文档侧 skiplist如标点符号将其从输出中剔除。文档侧的task与掩码行为由MultiVectorMask模块实现见 sentence_transformers/multi_vector_encoder/modules/multi_vector_mask.py真实 tokentokenizer 的attention_mask参与打分taskquery且开启查询扩展时扩展位置也参与打分——这是 ColBERT 的核心技巧即使 Transformer 的注意力没有看到扩展 token它们也贡献 MaxSim对skiplist_tasks默认仅document无 task 的输入视为 document中的 token 应用 skiplist 剔除非 query 任务且设置了keep_only_token_ids时额外限制为这些 token ID典型场景是 ColPali 风格的图像 patch token可让文档索引体积减半。encode 的完整参数encode是底层通用方法encode_query/encode_document都委托给它model.py。核心参数参数默认值说明inputs必填字符串、字符串列表或多模态输入dict、图像、数组prompt_name/promptNone使用的 promptprompt字符串优先于prompt_namebatch_size32前向传播批大小必须为正整数show_progress_barNone自动是否显示进度条output_valuetoken_embeddingstoken_embeddings默认返回按打分掩码切片的逐 token 嵌入None返回原始逐输入模块输出字典含token_embeddings、attention_mask及自定义模块写入的额外键不做归一化与转换convert_to_numpyFalse为True时返回numpy.ndarray列表并逐批移到 CPU多进程编码pool或 device 列表总是返回 CPU 结果deviceNone单个设备、设备列表多进程编码或None使用模型当前设备normalize_embeddingsFalse返回前对每个 token 向量做 L2 归一化流水线中已有 token 级Normalize时无操作poolNone通过start_multi_process_pool创建的多进程池chunk_sizeNone多进程编码的块大小token_poolingNone按次调用的 token 池化应用于tasks中匹配的 task默认仅 document若模型流水线已内置池化则会叠加taskNonequery或document决定前缀 / 长度 / 掩码策略两个值得注意的行为均有源码与报错支撑由于多向量嵌入长度可变无法堆叠encode没有convert_to_tensor参数——传了会直接报错提示改用convert_to_numpyTruemodel.py默认返回值为每个输入一个 2D 张量形状(num_tokens_i, embedding_dim)传入单个字符串时外层列表会被解包直接返回裸 2D 张量。快速上手示例from sentence_transformers import MultiVectorEncoder # 1. 加载预训练多向量模型 model MultiVectorEncoder(lightonai/LateOn) queries [What is the capital of France?] documents [ Paris is the capital of France., Berlin is the capital of Germany., ] # 2. 编码查询与文档注意不对称的 encode_query / encode_document 拆分 query_embeddings model.encode_query(queries) document_embeddings model.encode_document(documents) # 每个元素是形状为 (num_tokens_i, embedding_dim) 的 2D 张量长度随输入变化 print(query_embeddings[0].shape) # torch.Size([10, 128]) # 3. 用 MaxSim 打分 scores model.similarity(query_embeddings, document_embeddings) print(scores) # tensor([[9.1129, 8.8769]], devicecuda:0)打分similarity 与 similarity_pairwisemodel.similarity返回全对all-pairsMaxSim 分数矩阵model.similarity_pairwise返回配对分数向量model.pyscores model.similarity(query_embeddings, document_embeddings) print(scores.shape) # torch.Size([1, 2])1 个查询对 2 个文档 pairwise model.similarity_pairwise([query_embeddings[0], query_embeddings[0]], document_embeddings) print(pairwise.shape) # torch.Size([2])两者都遵循模型的similarity_fn_namemaxsim默认sum_i max_j (a_i . b_j)即对每个查询 token 取与任意文档 token 的最大相似度再求和meanmaxsimMaxSim 除以查询的真实 token 数分数落在逐 token 相似度区间归一化嵌入约为[-1, 1]与查询长度无关。若模型用长度归一化打分训练应设为meanmaxsim以保持训练 / 评估一致。similarity_fn_name是惰性初始化的属性model.py首次访问时若未显式设置则取maxsim。setter 会校验取值只接受maxsim与meanmaxsim传xtr会明确报错——XTR 是训练期打分其全局 top-k 依赖 batch 构成不适用于模型级相似度传cosine/dot等单向量相似度也会被拒绝因为它们无法作用于长度参差的逐 token 嵌入。底层 MaxSim 实现打分的底层实现位于 sentence_transformers/util/similarity.py 的maxsim/maxsim_pairwise/mean_maxsim/mean_maxsim_pairwise函数。源码揭示了几个关键的工程细节打分在文档所在设备上进行文档是大头查询便宜可搬移可通过device参数指定打分设备长文本按chunk_elements元素预算分块打分默认 1 亿元素预算约 400 MBbf16 / fp16 减半防止中间张量撑爆显存被掩码的文档 token 用dtype 最小值填充参与 max 而不是乘 0避免 padding token 因负相似度而赢得max与 PyLate 的乘 0 方案相比更严谨见 similarity.py查询 token 的求和始终在 float32 中累积——MaxSim 分数量级可达 O(查询 token 数)bf16 网格太粗会淹没相近分数完全无有效 token 的文档会得到约_EMPTY_DOCUMENT_SCORE的哨兵分数排在所有真实文档之下。多模态输入与视觉文档检索部分多向量模型支持文本之外的输入最典型的是用于视觉文档检索的页面图像。可使用model.modalities与model.supports()检查模态支持示例见 docs/multi_vector_encoder/usage/usage.rstfrom sentence_transformers import MultiVectorEncoder model MultiVectorEncoder(vidore/colqwen2.5-v0.2) # 列出所有支持的模态 print(model.modalities) # [text, image] # 检查特定模态 print(model.supports(image)) # True print(model.supports(audio)) # False图像文档以 URL、本地路径或 PIL 图像传入编码方式与文本完全一致随后用 MaxSim 计算跨模态分数from sentence_transformers import MultiVectorEncoder # 1. 加载同时支持文本与图像的模型 model MultiVectorEncoder(vidore/colqwen2.5-v0.2) queries [ What is the variable represented on the y-axis of the graph?, Total outlay is maximum in which year?, ] # 2. 图像文档以 URL、本地路径或 PIL 图像传入 images [ https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/doc1.jpg, https://huggingface.co/datasets/sentence-transformers/example-documents/resolve/main/doc2.jpg, ] # 3. 图像文档与文本文档编码方式相同 query_embeddings model.encode_query(queries) document_embeddings model.encode_document(images) # 4. 计算跨模态 MaxSim 分数 scores model.similarity(query_embeddings, document_embeddings) print(scores)相关实战脚本可参考 examples/multi_vector_encoder/applications/README.mdsemantic_search.py一次性编码语料后用 MaxSim 检索retrieve_rerank.py用双编码器先召回再用多向量模型精排heatmap.py与text_similarity_map.py利用 MaxSim 分数可追溯到具体 token / 图像 patch 的特性做可解释性可视化token_pooling.py用HierarchicalTokenPooling压缩文档索引。前缀 token 与 prompts多向量模型的前缀 token 以模型的query与documentprompts 存储可以直接检查每个方法前置了什么from sentence_transformers import MultiVectorEncoder model MultiVectorEncoder(lightonai/mLateOn) print(model.prompts) # {query: [Q] , document: [D] }不同 checkpoint 的前缀不同原版 ColBERT 格式的模型复用保留词表项例如answerdotai/answerai-colbert-small-v1的 prompts 为{query: [unused0] , document: [unused1] }。而 PyLate v3 与 Stanford-NLP ColBERT 等旧格式 checkpoint 中保存的query_prefix/document_prefix或artifact.metadata中的query_token_id/doc_token_id会在加载时自动提升为 prompts并通过_register_prefix_tokensmodel.py注册为特殊 token——否则像[unused0]这样的保留 token 以文本前置会被切碎成[[, unused, ##0, ]]与训练时的 token 插入行为不一致。模型加载五种来源透明兼容MultiVectorEncoder可以从以下来源透明加载自动检测格式对应_get_model_type与_load_default_modules的多条加载路径见 model.pyfrom sentence_transformers import MultiVectorEncoder # 1. 本库原生格式用本库训练的多向量模型PyLate 也基于同一 schemacheckpoint 可无差别加载 model MultiVectorEncoder(lightonai/LateOn) model MultiVectorEncoder(lightonai/mLateOn) model MultiVectorEncoder(LiquidAI/LFM2-ColBERT-350M) # 2. 部分原生 checkpoint 自带自定义架构代码需要 trust_remote_code model MultiVectorEncoder(perplexity-ai/pplx-embed-v1-late-0.6b, trust_remote_codeTrue) # 3. Stanford-NLP ColBERT 格式通过 HF_ColBERT 架构标记自动检测 # 内联投影权重与特殊 token 从 artifact.metadata 读取 model MultiVectorEncoder(colbert-ir/colbertv2.0) model MultiVectorEncoder(answerdotai/answerai-colbert-small-v1) # 4. transformers 原生晚期交互检索器*ForRetrieval 架构如 ColPali / ColQwen2 / # ColModernVBert自动检测投影与归一化在模型内部完成查询与图像文档由 processor 格式化 model MultiVectorEncoder(vidore/colqwen2-v1.0-hf) # 5. 裸 Transformer自动追加随机初始化的投影层需要训练后才能使用 model MultiVectorEncoder(answerdotai/ModernBERT-base)各路径的关键行为原生格式读取config_sentence_transformers.json的模块配置其中model_type ColBERT的 PyLate v3 保存会被归一化为MultiVectorEncoder并按标准配置加载Stanford-NLP ColBERTconfig.json中architectures [HF_ColBERT]触发专用路径——从仓库根的linear.weight读取内联投影权重、从artifact.metadata恢复特殊 token / 长度 / 扩展配置并默认以string.punctuation预置 skiplist与原始mask_punctuation默认行为一致旧格式的query_expansion平面字段do_query_expansion、attend_to_expansion_tokens等会被翻译成新的 dict 形态query_length落入扩展配置回退到 ColBERT 规范默认值 32*ForRetrieval架构如 ColPali / ColQwen2投影、L2 归一化、padding 置零都在模型内部完成processor 已内置查询前缀与视觉 prompt因此只追加MultiVectorMask无需 Dense / Normalize裸 Transformer追加随机初始化的 token 级投影输出 128 维并提示需要训练才有用可通过modules...自定义。从SentenceTransformercheckpoint 转换_load_converted_modules时句子级Pooling与句子级Normalize会被移除若存在句子级Dense头则重定向到 token 级保留学习到的投影权重否则追加随机投影转换后的模型相似度函数自动设为maxsimmodel.py。MultiVectorEncoderModelCardData模型卡元数据MultiVectorEncoderModelCardData是用于生成模型卡的 dataclass定义于 sentence_transformers/multi_vector_encoder/model_card.py继承自BaseModelCardData。核心字段字段示例说明languageen或[en, de, nl]模型语言licenseapache-2.0/mit/cc-by-nc-sa-4.0模型许可证model_nameMultiVectorEncoder based on answerdotai/ModernBERT-base模型的展示名model_idtomaarsen/mve-modernbert-base-ms-marco推送到 Hub 时的模型 IDtrain_datasets/eval_datasets[{name: MS MARCO, id: microsoft/ms_marco}]训练 / 评估数据集task_namesemantic search with late interaction任务人类可读名称注册模型时若未设置自动取该值tags[sentence-transformers, multi-vector, colbert, late-interaction]模型标签local_files_onlyTrue/False是否不访问 Hub 查询数据集与基础模型信息generate_widget_examplesTrue/False是否从评估 / 训练数据集生成 widget 示例模型注册register_model时自动设置pipeline_tagfeature-extraction并将ir_model置为True——晚期交互总是检索任务base 会按位置从第一个数据集列取查询、第二个列取文档生成 widget 示例。get_model_specific_metadata会写入output_dimensionality逐 token 向量维度与人类化的similarity_fn_nameMaxSim/MeanMaxSim并当query_expansion为fixed策略时把query_length覆盖为扩展长度固定扩展把每个查询钉在自己的长度上。run_usage_snippet会真实运行一次检索并生成用法片段第一个示例作为查询、其余作为文档输出逐 token 形状与相似度矩阵generate_usage_snippet生成可直接复制的代码块。模型卡模板位于 model_card_template.md。安装codecarbon后模型卡可自动记录碳排放信息。实战要点与进阶阅读检索一定用不对称 APIencode_query/encode_document会自动处理前缀 token[Q]/[D]、最大长度与文档侧 skiplist只有需要显式覆盖task时才直接用encodeGPU 上保持张量而非 numpy默认convert_to_numpyFalse时嵌入留在设备上similarity打分无需搬运在加速器上收益数倍语料过大放不进显存时再开convert_to_numpyTrue推理加速PyTorch 后端可组合 fp16 / bf16、Flash Attentionattn_implementationflash_attention_2配合model[0].unpad_inputs控制输入去 padding、model.compile(dynamicTrue)也可切 ONNX / OpenVINO 后端详见 docs/multi_vector_encoder/usage/efficiency.rst。注意非 attend 查询扩展模型如 Stanford 系 checkpoint加载时拒绝 Flash Attention需用sdpa索引与精排多向量索引与模型无关索引存储encode_document的输出可将本库MultiVectorEncoder与外部晚期交互索引如 PyLate 的 PLAID配合使用也可在 examples/multi_vector_encoder 中查看语义检索、召回 精排、可解释性与索引压缩的完整脚本训练训练多向量模型可参考 examples/multi_vector_encoder/training 下的对比损失contrastive、缓存对比cached contrastive、蒸馏KD与 LoRA 示例对应的CachedMultiVectorMultipleNegativesRankingLoss支持按mini_batch_num_tokens打包以减少训练内存。进一步阅读多向量模型的输入格式说明见 docs/input_formats.rst自定义多向量模型指南见 docs/multi_vector_encoder/usage/custom_models.rst损失函数总览见 docs/multi_vector_encoder/loss_overview.md。赞分享人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载相关推荐sentence-transformers MultiVectorEncoder 使用指南MaxSim 多向量编码、视觉文档检索与模型加载实战sentence transformers MultiVectorEncoder 使用指南MaxSim 多向量编码、视觉文档检索与模型加载实战 本文以 doc人工智能NLPEmbedding微调sentence-transformers 多向量编码器评估指南MultiVectorEncoder 的 MaxSim 评测体系与 NanoBEIR 实战sentence transformers 多向量编码器评估指南MultiVectorEncoder 的 MaxSim 评测体系与 NanoBEIR 实战 导人工智能NLPEmbedding微调基于 CocoIndex 与 ColPali 多向量检索的图像搜索Qdrant MaxSim 延迟交互式匹配实战基于 CocoIndex 与 ColPali 多向量检索的图像搜索Qdrant MaxSim 延迟交互式匹配实战 本文以 CocoIndex 仓库中的 ima人工智能大模型RAGAI AgentAgent 记忆数据工程流处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
