模型架构SentenceTransformerSentenceTransformer类是模块组成的torch.nn.Sequential。常见形状是TransformerPooling 可选的Normalize/Dense但支持四种不同的架构家族正确的选择取决于任务。四个架构家族家族骨干池化用例编码器双向BERT、RoBERTa、DeBERTa、MPNet、ModernBERT、XLM-Rmean默认或cls短/中文本通用默认解码器因果 LLMQwen、Llama、Mistral、Gemmalasttoken长上下文、可指令微调、更高的质量上限静态嵌入StaticEmbedding模块不适用仅 CPU、10MB、极快多模态 / RouterVLM 骨干或组合编码器视情况而定文本 图像 / 音频 / 视频下面每个家族给出具体设置。编码器模型默认历史默认通常仍是文本嵌入的正确选择。fromsentence_transformersimportSentenceTransformer modelSentenceTransformer(microsoft/mpnet-base)# 自动构建Transformer(feature-extraction) - Pooling(mean)。当SentenceTransformer(checkpoint)以原始 HF 编码器调用时它会自动包装 transformer 并添加Pooling(..., pooling_modemean)。要自定义池化或添加模块fromsentence_transformersimportSentenceTransformerfromsentence_transformers.sentence_transformer.modulesimportNormalize,Pooling,Transformer transformerTransformer(answerdotai/ModernBERT-base)poolingPooling(transformer.get_embedding_dimension(),pooling_modecls)# 或 mean、lasttoken、...modelSentenceTransformer(modules[transformer,pooling,Normalize()])池化模式mean默认—— token 嵌入的平均值按注意力掩码遮蔽。最强的默认。cls——[CLS]token 的嵌入。如果基座经过 CLS 预训练则有效。max—— 跨 token 的逐元素最大值。罕见。mean_sqrt_len_tokens—— 按 √seq_len 缩放的均值。经验上对某些任务有帮助。weightedmean—— token 位置加权均值。作为非最后 token 的替代方案对解码器基座有用。lasttoken—— 最后 token 的嵌入。因果 LM 基座必需见下文解码器一节。不要在训练中途切换池化。只选一次。解码器 / 因果 LLM 模型在长上下文、指令遵循、多语言方面表现出色。内存消耗大——通常用 LoRA 训练而非全量微调。两条设置路径取决于模型是否已为嵌入适配# 路径 A已适配的嵌入检查点自带正确的模块fromsentence_transformersimportSentenceTransformer modelSentenceTransformer(Qwen/Qwen3-Embedding-0.6B)# 直接可用# 路径 B原始解码器 LLM手动构建流水线fromsentence_transformersimportSentenceTransformerfromsentence_transformers.sentence_transformer.modulesimportNormalize,Pooling,Transformer transformerTransformer(Qwen/Qwen2.5-0.5B,transformer_tasktext-generation,# 关键因果注意力非双向processor_kwargs{padding_side:left},# last-token 池化需要左填充)poolingPooling(transformer.get_embedding_dimension(),pooling_modelasttoken)modelSentenceTransformer(modules[transformer,pooling,Normalize()])在原始解码器上跳过transformer_tasktext-generation或pooling_modelasttoken会得到看起来合理、直到你跑基准测试才发现问题的嵌入。为什么用 last-token 池化因果注意力意味着只有最后一个 token 看到了完整序列。对因果模型做均值池化平均的是只见过前缀的嵌入——结果不能代表整个输入。训练解码器基座时学习率通常1e-4或更高不是编码器的2e-5。对 1B 参数的基座LoRA 几乎总是正确选择参见../scripts/train_sentence_transformer_with_lora_example.py其 docstring 涵盖何时使用、超参数、7B 的 QLoRA 和适配器共享。静态嵌入StaticEmbedding完全跳过 transformer——每个 token 通过查找表映射到预计算向量。无注意力、无上下文化。何时使用CPU 推理、无 GPU、浏览器 / 边缘 / 端侧部署。需要 10MB 模型大小。每个嵌入的延迟预算 1ms。拥有 100 万训练对上下文化被逐 token 优化取代这需要数据。何时不使用任务需要上下文理解多义词、句法、长程依赖。你只有 10 万训练对——模型学不到足够的东西。设置fromsentence_transformersimportSentenceTransformerfromsentence_transformers.sentence_transformer.modulesimportStaticEmbeddingfromtokenizersimportTokenizer tokenizerTokenizer.from_pretrained(google-bert/bert-base-uncased)static_embeddingStaticEmbedding(tokenizer,embedding_dim512)modelSentenceTransformer(modules[static_embedding])在大型对比数据集100 万 对上用MultipleNegativesRankingLoss训练。热启动 vs 随机初始化—— 当你有100 万训练样本时随机初始化胜过StaticEmbedding.from_model2vec(...)或.from_distillation(...)热启动。数据集较小时热启动有帮助。# 对于较小数据集10 万热启动static_embeddingStaticEmbedding.from_model2vec(minishlab/potion-base-8M)# 或static_embeddingStaticEmbedding.from_distillation(sentence-transformers/all-MiniLM-L6-v2,vocabularylist(tokenizer.get_vocab().keys()))可运行的端到端配方随机初始化 MNRL Matryoshka bf16 lr2e-1参见../scripts/train_sentence_transformer_static_embedding_example.py基准测试参见静态嵌入博客文章。通过 VLM 骨干实现多模态现代视觉-语言模型可以直接加载并产生联合的文本图像嵌入fromsentence_transformersimportSentenceTransformer modelSentenceTransformer(Qwen/Qwen3-VL-Embedding-2B,model_kwargs{attn_implementation:flash_attention_2},# 不要在这里设置 torch_dtype参见 training_args.mdprocessor_kwargs{min_pixels:28*28,max_pixels:600*600},)# 检查该模型支持哪些模态print(model.modalities)# [text, image, video, message]训练数据可以混合文本、PIL 图像、图像路径/URL、音频以及如{image: PIL, text: describe this}的混合模态字典。数据 collator 通过模型的preprocess方法处理预处理。安装多模态附加包pip install sentence-transformers[image]或[audio]、[video]。精度以 fp32 加载并给 TrainingArguments 传bf16True或fp16True——autocast 处理推理路径。不要在model_kwargs中设置torch_dtypebfloat16它会把 Adam 状态置于 bf16 并静默降低质量参见training_args.md。通过 Router 实现多模态不使用单个 VLM 骨干而是为每种模态组合独立的编码器fromsentence_transformersimportSentenceTransformerfromsentence_transformers.sentence_transformer.modulesimportDense,Pooling,Router,Transformer# 文本编码器text_encoderTransformer(sentence-transformers/all-MiniLM-L6-v2)text_poolingPooling(text_encoder.get_embedding_dimension(),pooling_modemean)# 投影文本以匹配图像编码器的维度text_projectionDense(text_encoder.get_embedding_dimension(),768)# 图像编码器SigLIP 直接输出池化嵌入image_encoderTransformer(google/siglip2-base-patch16-224)routerRouter(sub_modules{text:[text_encoder,text_pooling,text_projection],image:[image_encoder],},)modelSentenceTransformer(modules[router])警告基于 Router 的模型在初始化时嵌入空间不对齐——你必须训练来对齐它们。维度不同时使用Dense投影层。基于任务的路由查询与文档使用不同的编码器也通过route_mappings受支持参见Router的 docstring。陷阱解码器基座使用均值池化静默产生垃圾嵌入。始终使用lasttoken。Router 多模态不训练独立编码器的嵌入空间在初始化时不对齐。在训练对齐空间的损失之前不要指望有用的跨模态相似度。少于 10 万对的 StaticEmbedding模型学不到足够的东西。要么通过from_model2vec/from_distillation热启动要么使用常规编码器。消费级 GPU 上的大型 VLM 骨干组合 LoRA attn_implementationflash_attention_2。仅用 LoRA 时你还可以额外传torch_dtypebfloat16——bf16 基座权重是冻结的所以上面精度规则中关于 Adam 状态的问题不适用LoRA 适配器保持 fp32因此其优化器状态保持 fp32。不用 LoRA 时遵循精度规则保持权重 fp32依赖bf16Trueautocast。