模块

sentence_transformers.sparse_encoder.models 定义了不同的构建块，可用于从头开始创建 SparseEncoder 网络。有关更多详细信息，请参阅训练概览。请注意，来自 sentence_transformers.models 的模块也可用于稀疏模型，例如来自 SentenceTransformer > 模块的 sentence_transformers.models.Transformer

SPLADE 池化

class sentence_transformers.sparse_encoder.models.SpladePooling(pooling_strategy: Literal['max', 'sum'] = 'max', activation_function: Literal['relu', 'log1p_relu'] = 'relu', word_embedding_dimension: int | None = None, chunk_size: int | None = None)[source]

用于创建稀疏嵌入的 SPLADE 池化模块。

此模块实现了 SPLADE 池化机制，其功能为：

从掩码语言模型（MLM）获取 token logits。
使用激活函数后接 log1p（即 log(1 + activation(MLM_logits))）进行稀疏转换。
应用 max 或 sum 池化策略生成稀疏嵌入。

生成的嵌入是高度稀疏的，并捕获词汇信息，使其适用于高效的信息检索。

参数:

pooling_strategy (str) –
跨 token 维度的池化方法。可选：
- sum：求和池化（用于原始 SPLADE，详见 https://arxiv.org/pdf/2107.05720）。
- max：最大池化（用于 SPLADEv2 和后续模型，详见 https://arxiv.org/pdf/2109.10086 或 https://arxiv.org/pdf/2205.04733）。
activation_function (str) –
在 log1p 变换前应用的激活函数。可选：
- relu：ReLU 激活函数（所有 Splade 模型中的标准配置）。
- log1p_relu：log(1 + ReLU(x)) 变体，用于 Opensearch Splade 模型，详见 https://arxiv.org/pdf/2504.14839。
word_embedding_dimension (int, optional) – 输出嵌入的维度（如果需要）。
chunk_size (int, optional) – 沿序列长度维度的块大小（即，每个块的 token 数量）。如果为 None，则一次处理整个序列。使用较小的块可以减少内存使用，但可能会降低训练和推理速度。默认值为 None。

MLM Transformer

class sentence_transformers.sparse_encoder.models.MLMTransformer(model_name_or_path: str, max_seq_length: int | None = None, model_args: dict, Any] | None = None, tokenizer_args: dict, Any] | None = None, config_args: dict, Any] | None = None, cache_dir: str | None = None, do_lower_case: bool = False, tokenizer_name_or_path: str | None = None, backend: str = 'torch')[source]

MLMTransformer 适用于稀疏编码应用的掩码语言模型（MLM）。

此类扩展了 Transformer 类，专门用于具有 MLM 头（如 BERT、RoBERTa 等）的模型，并设计与 SpladePooling 结合使用，以创建 SPLADE 稀疏表示。

MLMTransformer 访问 MLM 预测头以获取每个 token 的词汇 logits，这些 logits 随后由 SpladePooling 用于创建稀疏词汇表示。

参数:

model_name_or_path – Hugging Face 模型名称（https://huggingface.co/models）
max_seq_length – 截断任何长于 max_seq_length 的输入
model_args – 传递给 Hugging Face MLMTransformers 模型的关键字参数
tokenizer_args – 传递给 Hugging Face MLMTransformers tokenizer 的关键字参数
config_args – 传递给 Hugging Face MLMTransformers config 的关键字参数
cache_dir – Hugging Face MLMTransformers 存储/加载模型的缓存目录
do_lower_case – 如果为 True，则将输入转换为小写（与模型是否区分大小写无关）
tokenizer_name_or_path – tokenizer 的名称或路径。如果为 None，则使用 model_name_or_path
backend – 用于模型推理的后端。目前该类仅支持 torch。

稀疏自编码器

class sentence_transformers.sparse_encoder.models.SparseAutoEncoder(input_dim: int, hidden_dim: int = 512, k: int = 8, k_aux: int = 512, normalize: bool = False, dead_threshold: int = 30)[source]

此模块实现了基于论文《Beyond Matryoshka: Revisiting Sparse Coding for Adaptive Representation》（https://arxiv.org/abs/2503.01776）的稀疏自编码器架构。

此模块通过以下方式将密集嵌入转换为稀疏表示：

应用多层前馈网络
应用 top-k 稀疏化以保留最大值
支持辅助损失以提高训练稳定性（通过 k_aux 参数）

参数:

input_dim – 输入嵌入的维度。
hidden_dim – 隐藏层的维度。默认值为 512。
k – 在最终稀疏表示中保留的前 k 个值的数量。默认值为 8。
k_aux – 用于辅助损失计算的要保留的前 k 个值的数量。默认值为 512。
normalize – 是否对输入嵌入应用层归一化。默认值为 False。
dead_threshold – 死神经元的阈值。激活值低于此阈值的非零神经元被视为死神经元。默认值为 30。

稀疏静态嵌入

class sentence_transformers.sparse_encoder.models.SparseStaticEmbedding(tokenizer: PreTrainedTokenizer, weight: torch.Tensor | None = None, frozen: bool = False)[source]

用于高效稀疏表示的 SparseStaticEmbedding 模块。

这个轻量级模块通过将输入 token 映射到静态权重（如 IDF (逆文档频率) 权重）来计算稀疏表示。它旨在根据输入中 token 的存在，将查询或文档编码为固定大小的嵌入。

一个常见的场景是使用此模块进行查询编码，并使用像 SPLADE (MLMTransformer + SpladePooling) 这样的更重模块进行文档编码。

参数:

tokenizer (PreTrainedTokenizer) – 用于将输入文本 token 化为输入 ID 的 PreTrainedTokenizer。
weight (torch.Tensor | None) – 词汇 token 的静态权重（例如，IDF 权重），形状应为 (vocab_size,)。如果为 None，则将权重初始化为全 1 向量。默认值为 None。
frozen (bool) – 权重是否应被冻结（不可训练）。默认值为 False。