UltraBERT-380M

UltraBERT-380M

预测英文文本中被遮盖的词，并提供一个上下文长度 32K 的预训练编码器，可微调用于分类或检索。这是 dmis-lab 的填空模型，适合机器学习工程师和研究人员。

由 dmis-lab 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：UltraBERT-380M 是 dmis-lab 的英文双向编码器，作为填空（fill mask）模型发布，配合 transformers 库使用。它原生支持最长 32K token 的输入。作者说，它在分类和检索两方面同时拿到最高分，而同等规模的早期编码器只在其中一项领先。

适合谁：适合为分类或搜索微调编码器的机器学习工程师，以及比较各种编码器的研究人员。模型权重采用 Apache 2.0 许可证。

Industry | Who uses it | How they use it | Example
搜索 | 检索工程师 | 用均值池化和对比损失微调，做稠密检索 | 用自己的段落对训练一个检索器
语言技术 | 分类团队 | 在带标签的文本上加分类头进行微调 | 加一个二分类头来给短消息分类
研究 | 编码器研究人员 | 测试编码器在长输入上的表现 | 在不同的长上下文长度下做类似口令检索的测试

如果你想要能写文字的模型，可以跳过它，因为这个模型负责填补被遮盖的词并对文本编码。

用在哪里：

• 装有 transformers 5.20 或更新版本的 Python，UltraBERT 在其中原生受支持
• 更早的 5.x 版 transformers，需要传入 trust_remote_code=True
• 一台 CUDA 设备，模型卡的示例就是把模型加载到它上面
• 装有 Python 的 Windows、macOS 或 Linux，用来下载

Use case | Who | What they get back
填补被遮盖的词 | 开发者 | 模型给这个空位打分最高的词
分类 | 机器学习工程师 | 一个能把文本分到各标签的微调模型
稠密检索 | 搜索团队 | 一个基于均值池化的微调检索器

如何设置：

• 在 Windows、macOS 或 Linux 上装好 Python
• huggingface_hub 软件包
• transformers 5.20 或更新版本，或者更早的 5.x 版并传入 trust_remote_code=True
• 为 F32 权重留出约 1.7 GB 磁盘空间

1. 如果还没有 Python，先安装。
2. 用下面第一条命令安装 huggingface_hub 软件包。
3. 用第二条命令下载模型文件。
4. 安装支持 UltraBERT 的 transformers 版本，见上面的列表。
5. 处理长输入时推荐使用 FlashAttention 2，SDPA 或 eager 注意力也可以。

pip install -U huggingface_hub
hf download dmis-lab/UltraBERT-380M

如何使用：模型卡的第一个示例会加载分词器和掩码语言模型，构造一个含有掩码 token 的句子，并打印模型为这个空位选出的词。

import torch
from transformers import AutoModelForMaskedLM, AutoTokenizer

model_id = "dmis-lab/UltraBERT-380M"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForMaskedLM.from_pretrained(
    model_id,
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",  # or "sdpa"
    device_map="cuda",
)

text = f"The capital of France is {tokenizer.mask_token}."
inputs = tokenizer(text, return_tensors="pt").to(model.device)
with torch.no_grad():
    logits = model(**inputs).logits

mask_index = (inputs.input_ids == tokenizer.mask_token_id).nonzero()[0, 1]
print(tokenizer.decode(logits[0, mask_index].argmax()))

做微调时，同一个检查点可以加载到常用的任务类里。

from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    "dmis-lab/UltraBERT-380M", num_labels=2
)

作者建议从论文里的设置开始。他们还提醒，学习率应设得远低于常见的编码器取值，有时要低十倍。在 MNLI 上，他们为这个模型报告的最佳学习率是 8e-6，稠密检索则是 3e-5。

Tool | What it does
AutoTokenizer | 把文本转成 token，并提供掩码 token
AutoModelForMaskedLM | 加载模型来预测被遮盖的词
AutoModelForSequenceClassification | 加载带分类头的模型，用于微调

示例：你写下句子 "The capital of France is"，后面接上掩码 token，然后运行模型卡的第一段代码。它会打印出模型给这个空位评分最高的那个词。

新手与专家：填空（fill mask）是指模型猜测句子中被隐藏的词。一个好的起步是运行模型卡的第一段代码，看看它为空位打印出什么。

从底层看，每个预训练批次里，有的序列隐藏了 5% 的 token，有的隐藏了 50%，每个比例各由一个独立的输出头负责。根据模型卡，轻度隐藏有利于分类，重度隐藏有利于检索，而分开的头避免两者互相干扰。训练先在 2K token 上进行，之后上下文扩展到 32K。380M 这个规模来自对一个 1.3B 编码器的宽度剪枝，并由那个教师模型做蒸馏。

在 2K token 上预训练
用两个头分别遮盖 5% 和 50%
剪枝 1.3B 编码器并蒸馏
把上下文扩展到 32K
为分类或检索做微调

注意事项：

• License: Apache 2.0
• Cost to run: 未提及
• Data it reaches: 下载时从 Hugging Face 获取文件，来源没有提到其他内容
• 名称写的是 380M，而 Hugging Face 的记录是 430M 参数
• 权重 F32 约 1.7 GB，按 4-bit 估计约 215 MB
• 模型卡里的检索分数来自在数据子集上微调每个编码器，所以它们体现的是潜力，而不是成品的嵌入模型

Hugging Face 上的数据（2026年11月13日）

• 任务：fill mask
• 框架：transformers
• 参数量：430M
• Weights: about 1.7 GB in F32; about 215 MB at 4-bit (estimate)
• Formats: Safetensors
• 最近 30 天下载：15,830
• 点赞：82
• 许可证：apache-2.0
• 语言：en
• Quantized versions: 3
• Fine-tunes: 28
• 标签：transformers, safetensors, ultrabert, fill-mask, encoder, masked-language-modeling, long-context

链接

• 模型：https://huggingface.co/dmis-lab/UltraBERT-380M
• 文件：https://huggingface.co/dmis-lab/UltraBERT-380M/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download dmis-lab/UltraBERT-380M

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。