发布 v5.20.0 版本

新增车型

Muse Spark Open

Muse Spark Open 是 Meta 推出的一个多模态混合专家模型，它以文本、图像、音频和视频作为输入并生成文本。它拥有 816B 总参数（每个 token 激活 42B），并在各模态之间共享最高 1,048,576 个 token 的上下文窗口。它针对多文件编辑、调试和工具使用等智能体编码任务进行了训练。检查点提供 BF16 和 NVFP4 两种格式。

链接： 文档 | 博客文章 * 添加 Muse Spark Open (#49644)，作者 @guarin，位于 #49644

Ling 3.0

Ling 3.0 Flash 是来自 InclusionAI 的混合专家（Mixture-of-Experts）语言模型。其解码器将五个 Kimi Delta Attention（KDA）层与一个 Multi-head Latent Attention（MLA）层组合在一起。MLA 模块使用交错旋转位置编码和逐头输出门控，前馈模块则结合了路由专家和共享专家。Transformers 已原生支持该模型，用法如下 BailingHybridForCausalLM，因此加载时无需 trust_remote_code=True.

链接： 文档 * [模型] 添加对 Ling 3.0 Flash 的原生支持 (#49446)，由 @icavan 提交于 #49446

Kolibri1

Kolibri 1 是 Aleph Alpha 的混合专家推理模型，专注于德语和英语。它的 50 层中的每一层都使用 sigmoid 路由将每个 token 路由到 384 个专家中的 6 个，并增加一个共享专家。四个滑动窗口注意力层与一个全注意力层交替出现，且 RoPE 仅应用于滑动窗口层。

链接： 文档 * 添加 Kolibri 1 (#49463) 由 @lucamotz 提交于 #49463

MiniCPM-V 4.7

MiniCPM-V 是由 OpenBMB开发的一系列高效多模态大语言模型。与 MiniCPM-V 4.6 一样，MiniCPM-V 4.7 架构将带有窗口注意力合并器的 SigLIP 视觉编码器与 Qwen3.5 语言模型骨干配对，并支持 4x 和 16x 视觉下采样模式。

相对于 4.6 的主要新增是 canvas M-RoPE：模型不是沿单一 1-D 序列为视觉 token 编号，而是将每张图像布局在 2-D 画布上，并为每个视觉 token 分配一个 (temporal, height, width) 位置，因此同一图像的各部分保持其空间关系，视频帧也保持其时间顺序。

• 修复更多内容 (#48979) 由 @zucchini-nlp 提交于 #48979

UnlimitedOcr

UnlimitedOcr 是百度推出的单一 3B 参数 OCR 模型，具有标准的 32,768 token 上下文长度。它基于 DeepSeek OCR 构建，并将所有解码器注意力层替换为 Reference Sliding Window Attention（R-SWA）。这使得解码期间的 KV 缓存保持恒定，因此该模型可以在单次前向传播中转录数十页内容。它支持 "gundam" 模式（640x640 图块加动态裁剪）和 "base" 模式（单一 1024x1024 视图），并且可以输出带有边界框的区域检测结果。

链接： 文档 | 论文 * 由 @guarin 在 中添加 Unlimited OCR (#46836) #46836

UltraBERT

UltraBERT 是一系列双向文本编码器，通过结合多种掩码比例、剪枝和蒸馏进行训练，用于分类和检索任务。发布的编码器支持长达 32,768 个 token 的序列。它们使用旋转位置嵌入、RMSNorm、SwiGLU 前馈层，以及局部与全局注意力交替的结构（每第三层为全局注意力）。检查点包括用于掩码语言建模和微调的 UltraBERT-150M 和 UltraBERT-380M，以及用于文本嵌入的 UltraBERT-Embed-150M。

链接： 文档 | 论文 * 由 @tomaarsen 集成 UltraBERT 架构（#49596），见 #49596

MOSS-Transcribe-Diarize

MOSS-Transcribe-Diarize 0.9B 是一个端到端音频理解模型，用于长篇多说话人转录、说话人分离和时间戳标注。它结合了 Whisper 风格的编码器、一个 4× 帧合并步骤、一个多模态投影器和一个 Qwen3 语言模型。它在单次处理中同时生成转录和说话人分离，片段格式为 [start][S01]text[end]。它通过处理器中的 Whisper 窗口分块支持长篇音频、支持带热词偏置的可提示转录，以及 50 多种语言。

链接： 文档 * 由 @itazap 添加 MOSS-Transcribe-Diarize 模型（#48386），见 #48386

破坏性变更

🚨 一般性破坏通知：使用 EP 的推理在速度上出现回归；我们正在尽快修复！🚨

已弃用的检查和方法已从 cache_utils.py 中移除（影响 minimax_m3_vl 和 pi0 等模型），因此任何仍在调用这些已弃用缓存方法的代码都必须切换到当前的缓存 API。 * 🚨 由 @guarin 移除已弃用的缓存工具方法（#49605）

从多个模型文件（例如 embedding_gemma2、ijepa、lightglue）中移除了来自其他模型的意外导入，模块化转换器现在也避免添加此类跨模型导入。如果你通过这些模型模块导入了这些名称，请改为从它们的原始模块导入。 * 🚨 由 @guarin 移除来自其他模型的导入（#49473）

最低 kernels 版本现在为 0.17.2，这使得 use_fallback=KernelizeFallback.ALL 内核加载失败时会回退到原始实现而不是抛出错误。请将 kernels 升级到 0.17.2 或更高版本。 * 🚨 由 @SunMarc 将最低内核版本提升至 0.17.2 以获得更好的回退（#49235）

新增的 SubConfigSpec 集中化了子配置的初始化，因此默认子配置是从 dataclass 字段收集的，而不是通过实例化类获得，这涉及配置工具和许多模型配置。自定义或现有的嵌套配置可能需要更新，以通过此机制声明其子配置。 * :rotating_light: 由 @zucchini-nlp 实现用于集中初始化子配置的 SubConfigSpec（#48282）

LUKE 和 mLUKE 分词器现在将诸如 <ent> 的实体特殊 token 视为特殊 token（不拆分、被 skip_special_tokens识别、进行规范化），同时在解码时保持与普通词表 token 相同的空格处理。因此，涉及这些 token 的分词和解码输出可能与之前不同，请检查任何依赖旧行为的代码或已保存的输出。 * 🚨🚨🚨 由 @itazap 修复 luke（#48408）

导出器

Transformers 导出器现在支持在导出过程中直接进行量化，涵盖 Dynamo、ONNX、OpenVINO 和 ExecuTorch。新的统一量化 API 集成了 PT2E、ONNX Runtime 和 NNCF 量化器，支持静态和动态量化以及仅权重量化压缩（INT8/INT4），并提供可配置的校准流程。这使得导出优化模型以在不同后端上实现高效推理变得更加容易。

更多信息请参阅文档：https://huggingface.co/docs/transformers/exporters_quantization

并行化

此版本改进了分布式训练和推理。FSDP × TP 模型和优化器检查点现在可以在不同的并行配置之间保存和加载，并且修复了专家并行分发、张量并行计划、静态缓存 generate()以及缓存分配器的字节数。复合模型中的共享 LM 头现在拥有自己的 TP 计划条目， enable_expert_parallel 再次单独应用 EP 计划，TPU 加载使用 `tor

• FSDP x TP 保存/加载、优化器（#49256），由 @michaelbenayoun 提交于 [#49256]
• FSDP x TP 保存/加载（#48802），由 @michaelbenayoun 提交于 [#48802]
• 不要为 gloo 张量并行测试在每个 rank 上设置设备（#49636），由 @IlyasMoutawwakil 提交于 [#49636]
• fix(distributed)：将 enable_expert_parallel 保留为单独的 EP（#49633），由 @dacorvo 提交于 [#49633]
• 修复 FSDP 测试中的端口分配竞争问题（#49455），由 @icavan 提交于 [#49455]
• Expert-parallel dispatch 将接收到的行交给专家，而不是 all-to-all 的待处理结果（#49421），由 @IlyasMoutawwakil 提交于 [#49421]
• 修复在使用主机端输入及 TP 下的 static-cache generate()（#49317），由 @dacorvo 提交于 [#49317]
• Composite lm head tp plan（#49080），由 @IlyasMoutawwakil 提交于 [#49080]
• 修复：使用 torch.accelerator 设备 API，使 TP 加载在 TPU 上重新可用（#49502），由 @tengomucho 提交于 [#49502]
• 在 caching_allocator_warmup 字节计算中计入 ep 和 fsdp（#49384），由 @3outeille 提交于 [#49384]
• 在 expert-parallel token dispatch 时不将模型包装进 FSDP（#49383），由 @3outeille 提交于 [#49383]

生成

此版本修复了静态缓存 generate() 在主机端输入和张量并行下的 bug。它还通过减少设备同步和重新编译来加速 TPU 上的 Whisper 生成，并修复了针对张量和 NumPy 输入的 Whisper 批量时间戳解码。Pipelines 对生成参数处理进行了清理，消除了虚假警告。

• 添加自动生成 Intel CPU Docker 镜像的任务 (#49560)，由 @regisss 提交于 [#49560]
• 图像解码迁移到 torchcodec (#47963)，由 @zucchini-nlp 提交于 [#47963]
• 针对 TPU 优化 Whisper 生成并减少设备同步 (#49426)，由 @tengomucho 提交于 [#49426]
• 清理 pipelines 中的生成逻辑 (#49269)，由 @Rocketknight1 提交于 [#49269]
• 修复针对张量的 Whisper 批量时间戳解码 (#49419)，由 @Kingofbooks 提交于 [#49419]

视觉

视觉处理在多个地方进行了更新。图像解码现在使用 torchcodec，Molmo2 的图像和视频 kwargs 遵循库的标准约定，并且 Pixtral Flash Attention 在轴向 RoPE 重构之后不再检测到错误的图像边界——该问题曾导致 CUDA 非法内存访问错误和错误输出。此外还包含多项 CI 和 Docker 变更：GPU 镜像迁移到 Python 3.11，numpy/pyarrow 冲突

• 修复 XPU Docker 镜像中的 numpy/pyarrow 冲突 (#49582)，由 @jiqing-feng 提交于 [#49582]
• CI: 将 GPU 镜像迁移到 python 3.11 (#49352)，由 @tarekziade 提交于 [#49352]
• 更新 molmo2 处理图像/视频的 kwargs (#49563)，由 @guarin 提交于 [#49563]
• 修复轴向 RoPE 重构后 Pixtral Flash Attention 的图像边界问题 (#49373)，由 @oliverholworthy 提交于 [#49373]

内核

此版本改进了跨硬件的内核支持。 flash_attention_2 在 ROCm 上未安装 flash-attn 时回退到 AITER 内核，T5 风格的模型获得了连续的 SDPA 位置偏置掩码，从而再次使用融合内核。Hub 旋转位置编码内核现在仅限于 CUDA 推理使用，因为其反向传播会产生不正确的梯度。用于 Strix Halo 和

• 在 ROCm 上为 flash_attention_2 回退到 AITER 内核 (#49608)，由 @Abdennacer-Badaoui 提交于 [#49608]
• 使 SDPA position_bias 掩码连续，以便 T5 风格的模型使用融合内核 (#49517)，由 @IvenHsu01 提交于 [#49517]
• Hub 旋转位置编码内核仅用于 CUDA 推理 (#49439)，由 @qgallouedec 提交于 [#49439]
• [Atlas Inference] 为 Strix Halo Gated DeltaNet hub 内核启用 torch.compile (#49453)，由 @AzeezIsh 提交于 [#49453]
• [Atlas Inference] 修复 GB10 Gated DeltaNet hub 内核以兼容 transformers 5.17+ 并启用 torch.compile (#49452)，由 @AzeezIsh 提交于 [#49452]

缓存

此版本修复了多个与缓存相关的 bug：静态缓存 generate() 现在能正确处理主机端嵌套输入和张量并行，卸载缓存的预取不再与卸载复制发生竞态，且 Phi3 LongRoPE 在上下文边界处的缓存重建现在能接收到完整前缀。此版本还在 MiMo-V2-Flash 的滑动窗口中计入查询 token，并修正了量化缓存 (hqq/quanto) 文档示

• 修复卸载缓存预取与卸载复制之间的竞态问题 (#49363)，由 @qgallouedec 提交于 [#49363]
• docs: 更新量化缓存 hqq/quanto 示例和文档 (#47212)，由 @DavidJohnQuinlan 提交于 [#47212]
• [MiMo-V2-Flash] 在滑动窗口中计入查询 token (#49170)，由 @guapisolo 提交于 [#49170]
• 修复 Phi3 LongRoPE 在上下文边界处的缓存重建 (#49361)，由 @LE0-Lin 提交于 [#49361]

Bug 修复与改进

• [docs] 硬件文档模板 (#49575)，由 @stevhliu 提交于 [#49575]
• 为 PR CI 集成添加 MIC 合约锁定文件 (#49631)，由 @ydshieh 提交于 [#49631]
• 在 ROCm 上使用 aiter-rope 版本 3 (#49595)，由 @Abdennacer-Badaoui 提交于 [#49595]
• 从文档中移除缺失的方法 (#49637)，由 @guarin 提交于 [#49637]
• 将 torch.mm(..., out_dtype=...) 转换为 ONNX (#49635)，由 @IlyasMoutawwakil 提交于 [#49635]
• [docs] 硬件部分 (#49541)，由 @michaelbenayoun 提交于 [#49541]
• 当 torch 回退会丢弃打包序列边界时抛出异常（#49474），作者 @qgallouedec，链接 [#49474]
• Fa packed sequence decode（#49610），作者 @SunMarc，链接 [#49610]
• 修复嵌套 set_attn_implementation（#49138），作者 @eustlb，链接 [#49138]
• feat: 为 Mellum2/2.1 添加 MTP 支持（#49531），作者 @shadeMe，链接 [#49531]
• 将 onnx 导出器测试扩展到非 CUDA 设备（#49627），作者 @kaixuanliu，链接 [#49627]
• 文档化视频处理器后端（#49470），作者 @DimensionSTP，链接 [#49470]
• 使正弦位置嵌入可被编译（#49482），作者 @jiqing-feng，链接 [#49482]
• 从模型自身参数保存加载时已分片模型的 PEFT 适配器（#49500），作者 @qgallouedec，链接 [#49500]
• fix: 将 MTP 层类型传递给按层类型的旋转位置嵌入（#49468），作者 @shadeMe，链接 [#49468]
• 将 LFM2 添加到 GGUF 加载路径（#49400），作者 @francip，链接 [#49400]
• 添加 MtpModel 供拥有草稿循环的框架使用的辅助函数（#49544），作者 @hmellor，链接 [#49544]
• 使用 .python-version 中指定的 Python 版本构建文档（#49603），作者 @tarekziade，链接 [#49603]
• 为 AXK1 使用 mlp_layer_types，使 MoE 层布局遵循 moe_layer_freq（#49518），作者 @hmellor，链接 [#49518]
• 将 Nvidia 和 AMD 的 run-slow CI 评论合并为一条（#49598），作者 @ydshieh，链接 [#49598]
• 修复不稳定的 streamer 超时测试（#49583），作者 @tarekziade，链接 [#49583]
• 修复与 TPU 相关的测试问题（#49568），作者 @tengomucho，链接 [#49568]
• fix(distributed): 将 TPU rank 绑定到设备索引 0，而非 LOCAL_RANK（#49543），作者 @tengomucho，链接 [#49543]
• 在所有地方使用 transformers 初始化（#49573），作者 @guarin，链接 [#49573]
• [docs] 评估期间上下文并行（#48663），作者 @stevhliu，链接 [#48663]
• 移除 examples（#49357），作者 @SunMarc，链接 [#49357]
• 在 parse_response 中接受整数工具参数的整数值浮点数（#49547），作者 @yonigozlan，链接 [#49547]
• 更新 Intel CPU Dockerfile（#49408），作者 @jiqing-feng，链接 [#49408]
• 添加缺失的视频处理器自动文档字符串（#49569），作者 @guarin，链接 [#49569]
• 添加聊天输入清洗（#47386），作者 @Rocketknight1，链接 [#47386]
• 修复 create_chunked_causal_mask() 崩溃的问题，涉及 block_sequence_ids （#49457），作者 @kaixuanliu，链接 [#49457]
• 修复 SinglePositionMultiTokenCandidateGenerator 签名（#49413），作者 @jiqing-feng，链接 [#49413]
• Minicpm 4.7 更新集成测试（#49565），作者 @zucchini-nlp，链接 [#49565]
• 不再将 HunYuan 的 DynamicNTKAlpha RoPE 视为动态（#49445），作者 @jiqing-feng，链接 [#49445]
• 修复 Gemma3nVision2TextModelTest::test_model_parallelism 的分片测试（#49562），作者 @tarekziade，链接 [#49562]
• 修复 torch.compile 下 SuperPoint forward 中的 UnboundLocalError (#49409)，作者 @kaixuanliu，见 [#49409]
• 在 AutoVideoProcessor 中保留已解析的远程后端引用 (#49511)，作者 @DimensionSTP，见 [#49511]
• 修复 PR slow CI 建议：在 venv 中安装 transformers (#49558)，作者 @tarekziade，见 [#49558]
• 修复 PR 中 CI 缓慢的建议：安装 transformers，在脚本出错时失败 (#49549)，由 @ArthurZucker 在 [#49549] 中提交
• 移除已弃用的 data helpers (#49360)，由 @SunMarc 在 [#49360] 中提交
• 针对有意冻结的参数修复 test_all_params_have_gradient (#49264)，由 @thillai-c 在 [#49264] 中提交
• 针对 molmo2 测试的 Flex attn 修复 (#49530)，由 @molbap 在 [#49530] 中提交
• 修复 bridgetower 交叉注意力掩码形状错误 (#49447)，由 @kaixuanliu 在 [#49447] 中提交
• 当 Hub 的 tokenizer_class 为 GemmaTokenizer 时使用 Siglip2Tokenizer (#49245)，由 @jayzuccarelli 在 [#49245] 中提交
• 修复 WatermarkDetector 中混合 BOS 前缀验证问题 (#49496)，由 @dangruiyuan 在 [#49496] 中提交
• 弃用未使用的 get_uniform_frame_indices (#49464)，由 @archiep867-sys 在 [#49464] 中提交
• [测试] 针对 TPU 上测试套件失败的一些修复 (#49425)，由 @tengomucho 在 [#49425] 中提交
• torch 2.6 清理工作的第二阶段 (#49396)，由 @Rocketknight1 在 [#49396] 中提交
• 为 current_accelerator() 的检查添加保护并提升 Torch 版本 (#49395)，由 @Rocketknight1 在 [#49395] 中提交
• 在 PR 描述中使用一个静态的 Transformers CI 徽章 (#49471)，由 @tarekziade 在 [#49471] 中提交
• 修复：将配置类中每个已声明的字段都视为默认值，修复 #49456 (#49466)，由 @tarekziade 在 [#49466] 中提交
• 保持 AutoVideoProcessor 类查找的惰性 (#49458)，由 @DimensionSTP 在 [#49458] 中提交
• 添加 Molmo2 (#43451)，由 @SangbumChoi 在 [#43451] 中提交
• CI 递归获取多模态模型 (#49389)，由 @zucchini-nlp 在 [#49389] 中提交
• 对所有子配置进行递归处理 (#49461)，由 @zucchini-nlp 在 [#49461] 中提交
• Aria、Ernie4.5-VL-MoE、Gemma4、Inkling、MiniMax-M3-VL、Qwen3.5-MoE：在 VLM/ALM 测试器上运行模型测试 (#49404)，由 @IlyasMoutawwakil 在 [#49404] 中提交
• 修复 CI slack 报告：在 model_results.json 中呈现崩溃/缺失的模型任务 (#49427)，由 @ydshieh 在 [#49427] 中提交
• [Qwen3VLMoe] 更新 test_small_model_integration_test_expand 中的预期文本 (#49301)，由 @ydshieh 在 [#49301] 中提交
• 修复文档中的 backend 属性以及 MistralCommonBackend 中的默认 backend (#49149)，由 @samyuktahegde 在 [#49149] 中提交
• 更多 RoPE 简化及 TF32 修复 (#49328)，由 @Rocketknight1 在 [#49328] 中提交
• 完成 PR #49228：从 rope 中移除未使用的 device=None init 涉及 11 个模型家族 (#49285)，由 @ydshieh 在 [#49285] 中提交
• 回退 "[CI] 暂时禁用 AMD 定时 CI 触发器" (#49433)，由 @ydshieh 在 [#49433] 中提交
• 修复 QuantizedCache 在多 token 更新时的残留刷新问题 (#49418)，由 @LE0-Lin 在 [#49418] 中提交
• 修复 compile 下 _ignore_causal_mask_sdpa 中依赖数据的分支 (#49354)，由 @dacorvo 在 [#49354] 中提交
• 修复当存在 dense_intermediate_size 时 Inkling 的 moe_intermediate_size (#49416)，由 @Talhax55z 在 [#49416] 中提交
• 修复 DebertaV2ForMaskedLM 非旧式加载的问题 (#49152)，由 @kaixuanliu 在 [#49152] 中提交
• 此 PR 修复了 Gemma3n 在缺失权重需要以 fp16 加载时的问题…… (#49147)，由 @sywangyi 在 [#49147] 中提交
• PR CI：为可复用工作流授予 actions: read 权限 (#49417)，由 @tarekziade 在 [#49417] 中提交
• [Bugfix] [Modeling] 修复 DSV4 norm (#47486)，由 @kylesayrs 提交于 [#47486]
• [docs] 更新 Spaces (#49242)，由 @stevhliu 提交于 [#49242]
• 由 @itazap 在 [#49211] 中修复 spm 转换器中空预编译 charsmap 的处理（#49211）
• [CI] 暂时禁用 AMD 定时 CI 触发器（#49394），由 @ydshieh 在 [#49394] 中提交
• [tests] 修复 Speech2TextFeatureExtractionWithoutTorchaudioTest 中不稳定的 CMVN 测试（#49374），由 @ydshieh 在 [#49374] 中提交
• 让 token 分发以运行 ep_size != tp_size （#49368），由 @qgallouedec 在 [#49368] 中提交
• [tests] 跳过 BitForImageClassification 的 onnx.exactness（ORT fp32 漂移）（#49366），由 @ydshieh 在 [#49366] 中提交

重要的社区贡献

以下贡献者在上一个发布周期以来对该库做出了重要改动：

• @itazap
  • 添加 MOSS-Transcribe-Diarize 模型（#48386）
  • 修复 spm 转换器中空预编译 charsmap 的处理（#49211）
  • 🚨🚨🚨 luke fixe（#48408）
• @ydshieh
  • 为 PR CI 集成添加 MIC contract lock 文件（#49631）
  • 将 Nvidia+AMD run-slow CI 评论合并为一条（#49598）
  • 修复 CI slack 报告：在 model_results.json 中呈现崩溃/缺失的模型任务（#49427）
  • [Qwen3VLMoe] 更新 test_small_model_integration_test_expand 中的预期文本（#49301）
  • 完成 PR #49228：从 11 个模型家族的 rope init 在11个模型系列中（#49285）
  • 回退 "[CI] 暂时禁用 AMD 定时 CI 触发器"（#49433）
  • [CI] 暂时禁用 AMD 定时 CI 触发器（#49394）
  • [tests] 修复 Speech2TextFeatureExtractionWithoutTorchaudioTest 中不稳定的 CMVN 测试（#49374）
  • [Docker] 升级到 torch 2.14/CUDA 13.0 并优化从源码构建 FA2（#49381）
  • [tests] 跳过 BitForImageClassification 的 onnx.exactness（ORT fp32 漂移）（#49366）
• @icavan
  • 修复 FSDP 测试中的端口分配竞争问题（#49455）
  • [Model] 添加原生 Ling 3.0 Flash 支持（#49446）
• @tarekziade
  • 使用 .python-version 中指定的 Python 版本构建文档（#49603）
  • 修复不稳定的 streamer 超时测试（#49583）
  • CI：将 GPU 镜像迁移到 python 3.11（#49352）
  • 修复 Gemma3nVision2TextModelTest::test_model_parallelism split (#49562)
  • 修复 PR slow CI 建议：在 venv 中安装 transformers (#49558)
  • 在 PR 描述中使用一个静态 Transformers CI 徽章 (#49471)
  • fix: 将配置类的所有已声明字段视为默认值，修复 #49456 (#49466)
  • PR CI: 为可复用工作流授予 actions: read 权限 (#49417)
• @lucamotz
  • 添加 Kolibri 1 (#49463)
• @SangbumChoi
  • 添加 Molmo2 (#43451)
• @maxiaolong03
  • [Model] 添加 PP-DocLayoutV4 模型支持 (#48387)