Repository navigation
Releases
Patch release v5.22.2
Patch release v5.22.2
Some in between patch for security and distributed fixes. See the included commits π€
- [Distributed] Set device_id only for NCCL (#50281) by @michaelbenayoun and @3outeille
- Harden our Jinja sandboxing (#50431) by @Rocketknight1
Full Changelog: v5.22.1...v5.22.2
Patch release v5.22.1
v5.22.0: Mistral Large 4 (Le Chonk)
New Models
Mistral Large 4 (Le Chonk)
Mistral Large 4 is Mistral's largest and most capable model to date: a 1 trillion-parameter natively multimodal Mixture-of-Experts model with 49 billion active parameters per token (52 billion including embeddings and output layers), trained from scratch on 3,800 NVIDIA Grace Blackwell GPUs in Mistral's own datacenters in Europe.
Mistral Large 4 unifies instruction following, reasoning, coding, and agentic workflows in a single set of weights. While a generalist model, it shows especially good performance on workloads such as cybersecurity, finance, and law, and it surpasses frontier closed models on visual grounding. It is natively fluent in 160+ languages, including every official language of the European Union.
Key Features
Mistral Large 4 includes the following architectural choices:
- ~1T total / ~52B active parameters: granular Mixture-of-Experts with 128 routed experts (4 active per token) and 1 shared expert.
- 1M context length, for long-context workloads.
- Multimodal input: accepts text and image input, with text output. Pixtral-style vision encoder trained to handle variable image sizes and aspect ratios.
- Instruct and Reasoning functionalities with function calls, reasoning effort configurable per request.
Mistral Large 4 offers the following capabilities:
- Reasoning Mode: three reasoning efforts β
low,medium,high(default) β so the same model can answer a quick chat reply or work through a complex agentic run. - Vision: analyzes images, charts, technical drawings, and documents, with state-of-the-art visual grounding among open weights.
- Multilingual: natively fluent in 160+ languages, including all official languages of the European Union.
- System Prompt: strong adherence and support for system prompts.
- Agentic: native function calling, JSON output, and strict JSON schema enforcement.
- Cybersecurity: state of the art among open-weight models for security work, while refusing malicious requests.
- Large Context Window: supports a 1M context window.
The model is released under the Mistral Ecosystem Open-Weight License: a modified version of the MIT license, for both commercial and non-commercial use β operating a Model-as-a-Service business requires a separate commercial license with Mistral.
Recommended Settings
- Reasoning Effort:
'low'/'medium'/'high'β default is'high'.- Use
reasoning_effort="high"for complex prompts and agentic usage,'low'for fast chat replies and'medium'for day to day usage.
- Sampling: for all reasoning efforts, we recommend the following sampling parameters:
temperature=1.0top_p=0.95
- System Prompt: define a clear environment and use case, including guidance on how to effectively leverage tools in agentic systems.
- Tools: keep the set of tools well-defined and limit their number to the minimum required for the use case.
- Context: the checkpoint supports a 1M context window.
Breaking changes
- π¨ Separate EP logic into its own file (#49679) by @3outeille
Quantization
FP8 quantized models can now be used for adapter training (such as LoRA with PEFT). Backward passes were added to the dense and grouped FP8 matmuls, and is_trainable is now True. Backward also dequantizes experts in chunks and skips autograd at inference, which cuts peak memory in the MoE layer backward from about 28.9 GiB to 2.8 GiB at 8k tokens. Separately, the AMD CI image now install
- FP8 backward: chunked expert dequant, skip autograd.Function at inference (#50117) by @ArthurZucker in [#50117]
- Train adapters on top of FP8 weights (#50031) by @qgallouedec in [#50031]
- [AMD CI] Install onnxscript, bitsandbytes and peft in the AMD image (#50046) by @Abdennacer-Badaoui in [#50046]
Bugfixes and improvements
- Processor unnecessary warnings (#49812) by @zucchini-nlp in [#49812]
- Fix boolean padding in ClapFeatureExtractor (#23648) (#49960) by @rudy-07 in [#49960]
- [Fix] Count cropping of an uninitialized layer as a no-op (#50104) by @remi-or in [#50104]
- [loading] Allow
PermuteForRopeto act on single tensors while renaming (#50092) by @Cyrilvallez in [#50092] - Add Nemotron 3.5 Transcribe (#50084) by @eustlb in [#50084]
- [Nemotron3Diarization] add left context support (#49283) by @eustlb in [#49283]
- [Janus] Fix processor iterating a string prompt character by character (#50044) by @tarekziade in [#50044]
- fix(config): forward token kwarg to get_config_dict in PreTrainedConfig.from_pretrained (#50081) by @ydshieh in [#50081]
- Fix
rope_scalingsetter for configs that assign it during init (#50080) by @hmellor in [#50080] - [timesfm] Fix fp16 overflow on pad_val in _forward_transform (#50021) by @tarekziade in [#50021]
- Update dev version (#50068) by @albertvillanova in [#50068]
- Pin the shared Hub MIC fleet dataset (#49802) by @tarekziade in [#49802]
- [docs] NVIDIA/Intel/CPU (#49650) by @stevhliu in [#49650]
- Document how to handle non-persistent buffer initialization in custom models (#49880) by @Tialo in [#49880]
- Remove legacy benchmark/ and disable automatic benchmark runs (#50040) by @tarekziade in [#50040]
- Remove deprecation cycle for candidate generators (#50034) by @Cyrilvallez in [#50034]
- Fix test pil import leak (#49915) by @guarin in [#49915]
- fix: preserve NumPy integer label dtypes in default data collators (#49900) by @BlazeSR10hawk in [#49900]
- [ESMFold2] Don't build the MSA encoder for checkpoints without one (#49890) by @jimburtoft in [#49890]
- [minimax_m3_vl] Gate the integration tests on total accelerator memory (#50025) by @tarekziade in [#50025]
- Fix: Add kwargs in LFM2.5 conv layers (#50022) by @younesbelkada in [#50022]
- Forward code_revision to every pipeline loader (#49832) by @Rocketknight1 in [#49832]
- [moshi] Skip Moshiko integration tests whose checkpoint is gone (#50017) by @tarekziade in [#50017]
- Keep a capturing group's escapes when reversing a conversion pattern (#49772) by @IlyasMoutawwakil in [#49772]
- perf(ci): skip the lazy blob fetch in
git blameon a partial clone (#50007) by @nrenvo in [#50007] - fix(canary): set layerdrop=0.0 in test tester to prevent flaky test (#50012) by @ydshieh in [#50012]
- add a WA to Dockerfile for XPU (#50008) by @kaixuanliu in [#50008]
- pipelines: defer eager model imports in text_to_audio and token_classification (#50001) by @ydshieh in [#50001]
- [exporters] resolve @register_patch paths lazily to avoid eager model imports (#50000) by @ydshieh in [#50000]
- [Fix] Remove useless kwargs (#49966) by @remi-or in [#49966]
- Fix model's config attr naming (#49898) by @zucchini-nlp in [#49898]
Significant community contributions
The following contributors have made significant changes to the library over the last release:
- @tarekziade
- Fix
_init_weightsgaps in 7 audio models and enabletest_can_init_all_missing_weightsfor them (#49386) - Fix image backend equivalence tests for Pillow 13 (#50105)
- [Janus] Fix processor iterating a string prompt character by character (#50044)
- [timesfm] Fix fp16 overflow on pad_val in _forward_transform (#50021)
- Pin the shared Hub MIC fleet dataset (#49802)
- Remove legacy benchmark/ and disable automatic benchmark runs (#50040)
- [minimax_m3_vl] Gate the integration tests on total accelerator memory (#50025)
- [moshi] Skip Moshiko integration tests whose checkpoint is gone (#50017)
- Fix
- @eustlb
Patch release v5.21.1
Patch release v5.21.1
** Fix rope_scaling setter for configs that assign it during init (#50080 )
We broke remote code loading in vllm, this fixes it sorry everyone!
Release: v5.21.0
Release v5.21.0
New Model additions
MiniCPM-OCR
MiniCPM-OCR is a document-understanding model from OpenBMB's MiniCPM-V family. It keeps the MiniCPM-V 4.6 architecture, which pairs a SigLIP vision encoder and a window-attention merger with a Qwen3.5 language model. It is specialized for reading text-dense images such as scanned pages, screenshots, receipts and tables.
Links: Documentation | Paper
Flint
Flint is Recursive's mixture-of-experts language model. Compared to a standard SwiGLU MoE transformer such as Qwen3-MoE, it uses hybrid attention (sliding-window attention with rotary embeddings over the current token and the previous 512 tokens in most layers, and full attention without positional encoding in the remaining layers). It also has learned attention sinks, as in GPT-OSS, with per-head RMS-normalized queries and keys. Each sparse layer routes a token to 6 of 256 experts by sigmoid score and adds an ungated shared expert, and the first two layers are dense.
Links: Documentation
- Add Flint model support. (#49824) by @lovishmadaan in #49824
UltraVBert
UltraVBert extends ModernVBert by pairing the UltraBERT text encoder with a SigLIP vision encoder for visual document understanding and retrieval. Its image processor splits each page into 512-pixel tiles plus a global view. The connector merges each 4 x 4 block of vision patches into one token, so a tile becomes 64 image tokens, and RMS-normalizes them to the scale of UltraBERT's token embeddings. The max_image_tiles setting (27 by default) caps the number of tiles per page.
Links: Documentation
- Add UltraVBERT (#49685) by @athrael-soju in #49685
Gradium Phonon TTS
Gradium Phonon TTS is Gradium's family of on-device text-to-speech models, trained with the Pocket TTS recipe. A causal transformer reads a voice prompt and the text, then emits one continuous 32-dimensional audio latent per step at 12.5 Hz through a one-step flow head, and an end-of-speech head decides when the utterance ends. The latents are decoded to 24 kHz audio by a Pocket TTS audio tokenizer. Unlike Pocket TTS, voice conditioning uses 512-dimensional latents from a separate, unreleased speaker codec, so voices come as precomputed latents and cannot be cloned from a recording.
Links: Documentation
Pocket TTS
Pocket TTS is Kyutai's 100M-parameter text-to-speech model, built as a Continuous Audio Language Model that runs faster than real time on CPU. A causal transformer emits one continuous audio latent per frame (12.5 Hz) through a one-step flow head, and an end-of-speech head decides when to stop. A Mimi-based audio tokenizer encodes voice prompts and decodes the generated latents to 24 kHz audio. Two flow heads are released, Lagrangian self-distillation (default) and drifting, and voices can be cloned from a recording, passed as precomputed latents, or loaded from cached KV states.
Links: Documentation | [Paper](https://huggingface.co/papers/2509.06926 (the Continuous Audio Language Models paper, arXiv 2509.06926). It is the only paper the documentation links, and it describes the architecture family Pocket TTS belongs to. The docs do not cite a separate Pocket TTS technical report.) | [Blog Post](NONE. The documentation links no official blog post. It points only to the original code repository at https://github.com/kyutai-labs/pocket-tts.)
Pocket TTS Audio Tokenizer
The Pocket TTS audio tokenizer is the codec used by Pocket TTS. It has Mimi's architecture (SEANet convolutions plus a small causal transformer on each side), but its residual vector quantizer is replaced by a continuous 32-dimensional bottleneck, the VAE-GAN from Continuous Audio Language Models. It converts 24 kHz audio into latents at 12.5 Hz and decodes them back to audio. It serves as the audio_tokenizer of PocketTTSProcessor, encoding voice prompts and decoding generated latents, and its encoder and decoder can also be loaded on their own.
Links: Documentation | Paper
Breaking changes
Fixed Gemma4 processor imports (the Gemma4, Gemma4 unified and EmbeddingGemma2 processors) so from transformers import * no longer fails in environments that have PIL but not torch; no user action is needed.
- π¨ Fix gemma4 cross imports resulting in import failing without
torchbut withPIL(#49748) by @Sai-Suraj-27
Added an "fp8" backend to QuantizedCache, alongside quanto and hqq, that stores KV states in torch.float8_e4m3fn with a single scale per tensor; enable it with cache_implementation="quantized" and cache_config={"backend": "fp8"}.
- π¨Add an FP8 backend to
QuantizedCache(#48677) by @jiqing-feng
Tensor parallelism now has a dedicated embedding style, shards every model's input embeddings by default, and supports widths that aren't divisible by the TP size, so ColwiseParallel and RowwiseParallel now apply only to linear layers; custom TP plans that applied them to embeddings must switch to the new embedding style.
- π¨ TP: give embeddings their own style, shard input embeddings by default, and shard widths that don't divide by the TP size (#49570) by @IlyasMoutawwakil
Every MoE TP and EP plan now shards its experts, so models no longer keep all experts on every rank, and a new test_moe_parallel_plans_shard_experts test enforces this; custom or downstream MoE parallel plans must add expert sharding to pass it and to avoid wasted memory.
- π¨ MoE: shard the experts in every TP/EP plan, and test for it (#49206) by @IlyasMoutawwakil
Cache
This release improves cache handling across the library. Flash Attention now works with static caches, BLOOM no longer crashes with static cache or compiled generate, chunked prefill supports cache continuation, and the Qwen4-Exp indexer's position history stays aligned with its cached keys. Linear-attention caches also gain new getters (is_recording_past, get_recurrent_state, conv-state access) that stop exposing cache internals and prepare for paged-c
- [FA] Fix FA with static cache (#49998) by @Cyrilvallez in [#49998]
- [docs] CB cache behavior (#49025) by @stevhliu in [#49025]
- [CB] Reduce warmup time by not computing attention over full cache (#49853) by @remi-or in [#49853]
- Fix Qwen4-Exp indexer position cache lifecycle (#49840) by @taking-lying-flat in [#49840]
- [Cache] Linear attn cache: use new getters (#49375) by @remi-or in [#49375]
- [Cache] Get conv states (#49309) by @remi-or in [#49309]
- [Cache] Add get_recurrent_state (#49306) by @remi-or in [#49306]
- [Cache] Add is_recording_past (#49305) by @remi-or in [#49305]
- Fix BLOOM crash with static cache / compiled generate (#49481) by @kaixuanliu in [#49481]
- Allow Cache continuation for chunked prefill (#49662) by @Cyrilvallez in [#49662]
Vision
Vision image processors now composite PNG transparency onto white instead of exposing black pixels, and background_color is preserved correctly across the DeepSeek-VL and Janus processors. Model fixes cover SmolVLM's inputs_merger when image tokens aren't a multiple of the patch size, HunYuan-VL image assignment during batched beam search, and Ernie4.5-VL-MoE expert sharding under TP/EP. The DETR
- Composite transparency in shared RGB conversion and image processors (#49079) by @Nikhi00718 in [#49079]
- [Fetcher] Fix missing test deps for dynamically-resolved image processors (#49826) by @ydshieh in [#49826]
- fix(vision): Route the DETR conversion scripts through from_pretrained (#49830) by @harshaljanjani in [#49830]
- Fix background_color handling across DeepSeek-VL and Janus image processors (#49767) by @tritsystem in [#49767]
- Move the MI300 docker image to ROCm 10.1 and update test expectations (#49460) by @Abdennacer-Badaoui in [#49460]
- docs: fix 'allows to' grammar in Vision Encoder Decoder docs (#48730) by @mrchatam in [#48730]
- Fix SSH runner: add /opt/venv/bin to PATH for Python 3.11 images (#49759) by @ydshieh in [#49759]
- Fix SmolVLM inputs_merger when image tokens are not a multiple of patch_size (#49725) by @albertvillanova in [#49725]
- Ernie4.5-VL-MoE: shard the text and vision experts under TP and EP (#49462) by @IlyasMoutawwakil in [#49462]
- Fix HunYuan-VL image assignment during batched generation (#49557) by @Arnav66692 in [#49557]
Generation
This release fixes a range of generation bugs: BLOOM crashes with static cache or compiled generate, generate dropping the type of dict-like inputs such as ModelOutput, and incorrect image assignment or placeholder handling ...
Patch release v5.20.2
Patch release: v5.20.2
This patch notably solves an issue where some inputs could loose their original type inside prepare_inputs_for_generation in generate, leading to problems with multimodal models. It also fixes some other issues listed on the below commits.
It contains the following commits:
- Fix inputs dict casting in generate (#49731) by @Cyrilvallez
- Fix zero expert gradients in bfloat16 with expert parallelism and ep_size < fsdp_size (#49688) by @qgallouedec
- Declare the input modalities of the VLMs that report text only (#49677) by @qgallouedec
- Avoid a host-to-device copy in eager_mask (#49684) by @hmellor
Release v5.20.1
Release v5.20.1
Special surprise including the new model Beam from Reflection AI π₯³
Beam is a token-efficient, frontier-scale model focused on coding and agentic use cases. It is built for teams that want to run a powerful model on their own hardware, infrastructure, or cloud, and customize it to their specific needs.
Links: Documentation
- Fix small bug in auto mappings (#49664) by @yonigozlan in #49664
Some real patch fixes
We broke loading models on older torch versions π’ should be fixed now. But here is the full list of fixes
- Fix HunYuan-VL image assignment during batched generation (#49557) by @Arnav66692
- Fix DeepGEMM Mega MoE under expert parallelism(#49428) by @IlyasMoutawwakil
- Fix from_pretrained on torch 2.7: require torch>=2.8 for distributed checkpointing (#49652) by @naveecode
- Make DtensorShardOperation work on torch 2.6 and 2.7 (#49657) by @hazelxue
Full Changelog: v5.20.0...v5.20.1
Release v5.20.0
Release v5.20.0
New Model additions
Muse Spark Open
Muse Spark Open is a multimodal mixture-of-experts model from Meta that takes text, images, audio, and video as input and generates text. It has 816B total parameters (42B active per token) and a context window of up to 1,048,576 tokens shared across modalities. It is trained for agentic coding tasks such as multi-file editing, debugging, and tool use. Checkpoints are available in BF16 and NVFP4 formats.
Links: Documentation | Blog Post
Ling 3.0
Ling 3.0 Flash is a hybrid Mixture-of-Experts language model from InclusionAI. Its decoder groups five Kimi Delta Attention (KDA) layers with one Multi-head Latent Attention (MLA) layer. The MLA blocks use interleaved rotary embeddings and a head-wise output gate, and the feed-forward blocks combine routed and shared experts. It is natively supported in Transformers as BailingHybridForCausalLM, so it loads without trust_remote_code=True.
Links: Documentation
Kolibri1
Kolibri 1 is Aleph Alpha's mixture-of-experts reasoning model, focused on German and English. Each of its 50 layers routes every token to 6 of 384 experts using sigmoid routing, and adds one shared expert. Four sliding-window attention layers alternate with one full-attention layer, and RoPE is applied only in the sliding-window layers.
Links: Documentation
MiniCPM-V 4.7
MiniCPM-V is a series of efficient multimodal large language models developed by OpenBMB. Like MiniCPM-V 4.6, the MiniCPM-V 4.7 architecture pairs a SigLIP vision encoder that has a window-attention merger with a Qwen3.5 language model backbone, and supports both 4x and 16x visual downsampling modes.
The main addition over 4.6 is canvas M-RoPE: instead of numbering visual tokens along a single 1-D sequence, the model lays every image out on a 2-D canvas and assigns each visual token a (temporal, height, width) position, so slices of the same image keep their spatial relationship and video frames keep their temporal order.
- Fix more stuff (#48979) by @zucchini-nlp in #48979
UnlimitedOcr
UnlimitedOcr is a single 3B-parameter OCR model from Baidu with a standard 32,768-token context length. It builds on DeepSeek OCR and replaces all decoder attention layers with Reference Sliding Window Attention (R-SWA). This keeps the KV cache constant during decoding, so the model can transcribe dozens of pages in a single forward pass. It supports "gundam" mode (640x640 tiles with dynamic cropping) and "base" mode (a single 1024x1024 view), and it can output region detections with bounding boxes.
Links: Documentation | Paper
UltraBERT
UltraBERT is a family of bidirectional text encoders trained with a combination of masking ratios, pruning, and distillation for classification and retrieval tasks. The released encoders support sequences of up to 32,768 tokens. They use rotary position embeddings, RMSNorm, SwiGLU feed-forward layers, and alternating local and global attention (every third layer is global). Checkpoints include UltraBERT-150M and UltraBERT-380M for masked language modeling and fine-tuning, and UltraBERT-Embed-150M for text embeddings.
Links: Documentation | Paper
- Integrate the UltraBERT architecture (#49596) by @tomaarsen in #49596
MOSS-Transcribe-Diarize
MOSS-Transcribe-Diarize 0.9B is an end-to-end audio understanding model for long-form multi-speaker transcription, speaker diarization, and timestamps. It combines a Whisper-style encoder, a 4Γ frame merge step, a multi-modal projector, and a Qwen3 language model. It produces joint transcription and diarization in a single pass, with segments formatted as [start][S01]text[end]. It supports long-form audio through Whisper-window chunking in the processor, promptable transcription with hotword biasing, and 50+ languages.
Links: Documentation
Breaking changes
π¨ General breaking notice that inference with EP has regressions in speed; we are working on fixing this ASAP! π¨
Deprecated checks and methods have been removed from cache_utils.py (affecting models such as minimax_m3_vl and pi0), so any code still calling those deprecated cache methods must switch to the current cache API.
Accidental imports from other models were removed from several model files (e.g. embedding_gemma2, ijepa, lightglue), and the modular converter now avoids adding such cross-model imports. If you imported these names through those model modules, import them from their original modules instead.
The minimum kernels version is now 0.17.2, which allows use_fallback=KernelizeFallback.ALL so that a failed kernel load falls back to the original implementation instead of raising an error. Upgrade kernels to 0.17.2 or later.
A new SubConfigSpec centralizes the initialization of sub-configs, so default sub-configs are collected from dataclass fields instead of by instantiating the class, and this touches the configuration utilities and many model configs. Custom or existing nested configs may need to be updated to declare their sub-configs through this mechanism.
- π¨ SubConfigSpec for centralized init of subconfigs (#48282) by @zucchini-nlp
The LUKE and mLUKE tokenizers now treat entity special tokens such as <ent> as special tokens (not split, honored by skip_special_tokens, normalized) while keeping the same spacing as regular vocabulary tokens when decoding. Tokenization and decoding output involving these tokens may therefore differ from before, so check any code or saved outputs that depend on the old behavior.
Exporters
Transformers exporters now support quantization directly during export across Dynamo, ONNX, OpenVINO, and ExecuTorch. The new unified quantization API integrates PT2E, ONNX Runtime, and NNCF quantizers, enabling static and dynamic quantization as well as weight-only compression (INT8/INT4), with configurable calibration workflows. This makes it easier to export optimized models for efficient inference across different backends.
For more information see the docs: https://huggingface.co/docs/transformers/exporters_quantization
Parallelization
This release improves distributed training and inference. FSDP Γ TP model and optimizer checkpoints can now be saved and loaded across different parallel configurations, and expert-parallel dispatch, tensor-parallel plans, static-cache generate(), and the caching allocator's byte count were fixed. Tied LM heads in composite models now get their own TP plan entry, enable_expert_parallel applies the EP plan alone again, TPU loading uses the `tor
- FSDP x TP Saving / Loading, Optimizer (#49256) by @michaelbenayoun in [#49256]
- FSDP x TP Saving / Loading (#48802) by @michaelbenayoun in [#48802]
- Don't set a device per rank for gloo tensor-parallel tests (#49636) by @IlyasMoutawwakil in [#49636]
- fix(distributed): keep enable_expert_parallel as EP alone (#49633) by @dacorvo in [#49633]
- Fix a port allocation race in FSDP tests (#49455) by @icavan in [#49455]
- Expert-parallel dispatch hands the experts the received rows, not the all-to-all's pending result (#49421) by @IlyasMoutawwakil in [#49421]
- Fix static-cache generate() with host-side inputs and under TP (#49317) by @dacorvo in [#49317]
- Composite lm head tp plan (#49080) by @IlyasMoutawwakil in [#49080]
- Fix: use torch.accelerator device APIs so TP loading works again on TPU (#49502) by @tengomucho in [#49502]
- Count ep and fsdp in caching_allocator_warmup byte calculation (#49384) by @3outeille in [#49384]
- Do not wrap the model in FSDP for expert-parallel token dispatch (#49383) by @3outeille in [#49383]
Generation
This release fixes static-cache generate() bugs with host-side inputs and under tensor parallelism. It also speeds up Whisper generation on TPU by cutting device syncs and recompilation, and fixes Whisper batched timestamp decoding for tensor and NumPy inputs. Pipelines get a cleanup of generation-argument handling that removes spurious warnings.
...
Release v5.19.0
Release v5.19.0
New Model additions
EmbeddingGemma2
EmbeddingGemma 2 is a multimodal embedding model from Google built on the Gemma 4 architecture. It encodes text, images, audio, and video, individually or combined in one input, into a shared 768-dimensional vector space for cross-modal retrieval, semantic similarity, clustering, and classification. It uses Matryoshka Representation Learning, so embeddings can be truncated to 512, 256, or 128 dimensions. It also offers configurable visual and video token budgets, and unused vision or audio towers can be disabled at load time to save memory.
Links: Documentation
Breaking changes
All MoE models whose routers compute logits now return them when output_router_logits=True, following the Qwen3-MoE pattern (a router_logits recorder on the base model, MoeModelOutputWithPast from the backbone, and a MoE causal LM output from the head), so code that relied on the previous outputs or their absence should read the router logits from these output classes.
- π¨ Return router logits from every MoE model that computes them (#48920) by @qgallouedec
Owlv2ForObjectDetection.embed_image_query now selects the query box with the highest objectness score, as in the original OWLv2 notebook, instead of the OWL-ViT heuristic, so image-guided query embeddings and detections may differ from earlier releases.
- π¨ Select the OWLv2 image query by objectness (#49200) by @qgallouedec
The "paged|" prefix for SDPA and flash attention implementations is deprecated, so users should set the regular attention implementation (e.g. sdpa or flash_attention_2) for continuous batching instead of paged|sdpa or paged|flash_attention_2.
The regular flash and SDPA attention functions (flash_attention.py, sdpa_attention.py) now support continuous batching directly, and "paged|..." implementations for these are redirected to them, while eager still requires the "paged|eager" prefix.
In continuous batching, the cache update for the index-based and block-table paths is now fused into a single call, which slightly changes the cache update function's behavior and affects any custom code that calls the separate update paths.
Continuous batching internals changed in preparation for removing "paged": `max
Parallelization
Expert parallelism gains a token-dispatch implementation, selected via the new ep_dispatch_experts plan rule and now the default for Qwen3 MoE and Mellum, which removes the requirement that EP size equal TP size. The Trainer was also adapted to work with expert parallelism, and the docs now note that PEFT adapters support tensor parallelism. A CI-related fix for pipeline-parallel chart2table inference was also included.
- [
distributed]: adapt Trainer to work Expert Parallel (#48873) by @3outeille in [#48873] - [
distributed] Add expert-parallel token dispatch, default for Qwen3 MoE (#48865) by @3outeille in [#48865] - Fix pp chart2table inference (#49225) by @zucchini-nlp in [#49225]
- [docs] TP for PEFT adapters (#49060) by @stevhliu in [#49060]
Cache
This release fixes quantized cache handling: generate no longer mutates the user's cache_config, and QuantizedLayer.reorder_cache is repaired. It also adds per-layer cache configuration, so DynamicCache and StaticCache initialize each layer from its own config (sliding window, attention chunk size, conv states, and attention head counts) to better support heterogeneous models. Separately, the deprecation cycle on mask and cache
- Fix quantized cache (#48700) by @jiqing-feng in [#48700]
- [CI] check_bad_commit: use EFS cache to avoid Xet FUSE OOM (exit 137) (#49273) by @ydshieh in [#49273]
- Support per-layer cache configuration (#48178) by @eladsegal in [#48178]
- Remove deprecation cycle on mask and cache (#49231) by @Cyrilvallez in [#49231]
Bugfixes and improvements
- Revert "[CI] Temporarily disable AMD scheduled CI trigger" (#49271) (#49362) by @ydshieh in [#49362]
- ALM testx fIxing... (#49355) by @zucchini-nlp in [#49355]
- Fix DataCollatorForLanguageModeling ignoring seed=0 (#49349) by @akanyaani in [#49349]
- Fix explicit kernelization modes for evaluation models (#49339) by @DimensionSTP in [#49339]
- fix(cohere_compass): add video to input_modalities (#49320) (#49323) by @destopianpirate in [#49323]
- GPT-OSS: read the clamped SwiGLU's alpha and limit from the config (#49346) by @IlyasMoutawwakil in [#49346]
- [
distributed] Default MoEep_plansto token dispatch (#49160) by @3outeille in [#49160] - Move CI to Python 3.11, with the version set in
.python-version(#49311) by @tarekziade in [#49311] - Bump doc-builder main docs workflow pin (#49350) by @paulinebm in [#49350]
- [
distributed] decoupled tp_plan and ep_plan (#48859) by @3outeille in [#48859] - [
distributed] Add dense and expert device mesh (#48857) by @3outeille in [#48857] - Bump doc-builder workflow pin (#49342) by @paulinebm in [#49342]
- Allow registering new processing backends (#48984) by @zucchini-nlp in [#48984]
- Fix WatermarkDetector repeated-ngram counting (#49315) by @LE0-Lin in [#49315]
- Fix minicpm 4.6V video batching and CI (#49259) by @zucchini-nlp in [#49259]
- remove colwise_gather_output for lm_head for DeepseekV4 (#49314) by @3outeille in [#49314]
- Fix the
labelsdocstring of CLIPSegForImageSegmentation (#49001) by @qgallouedec in [#49001] - [CI] Temporarily disable AMD scheduled CI trigger (#49271) by @ydshieh in [#49271]
- Remove the unused pandas entry from setup.py deps (#49329) by @tarekziade in [#49329]
- Fix run_glue.py label ids becoming strings with pandas>=3 (#49326) by @tarekziade in [#49326]
- [Fix] Remove old test file with two ancient tests (#49280) by @remi-or in [#49280]
- Fix chunked prefill with multi-axis position ids (Qwen3-VL) (#49319) by @dacorvo in [#49319]
- Why override when you can fix in
Mixin(#49105) by @zucchini-nlp in [#49105] - Do RoPE with mul instead of matmul (#49265) by @Rocketknight1 in [#49265]
- Deprecated pipelines should redirect; removed pipelines should raise (#49308) by @LysandreJik in [#49308]
- Enable model test on upcoming
torch_tpubackend (#49207) by @tengomucho in [#49207] - Fix encoder repetition penalty source rows after batch expansion (#49262) by @gitedmond in [#49262]
- Preserve masked EOS scores in exponential decay length penalty (#49260) by @gitedmond in [#49260]
- [CI] Avoid fetching all artifacts when only specific ones are needed (#49282) by @ydshieh in [#49282]
- Revert "[CI] ssh-runner: add optional cache_type input to switch between bucket and EFS runners (#49159)" (#49270) by @ydshieh in [#49270]
- Add Trainer.loss_is_scaled_for_ga to declare whether compute_loss already scales for gradient accumulation (#49240) by @qgallouedec in [#49240]
- fix precomputed flash kwargs clashing (#47928) by @IlyasMoutawwakil in [#47928]
- Reapply modular examples (#49230) by @Cyrilvallez in [#49230]
- Remove some stuff that does not exist (#49232) by @Cyrilvallez in [#49232]
- Remove rotaries deprecation cycle (#49228) by @Cyrilvallez in [#49228]
- [
GTE] Add memory mixin (#49234) by @vasqu in [#49234] - [CB] Make CB more device agnostic and add support for XPU (#49156) by @remi-or in [#49156]
- correct final metrics due to resuming from checkpoint (#49208) by @SunMarc in [#49208]
- [ESM/Persimmon/NllbMoe/ESMFold] use safetensors repos to fix Xet FUSE SIGBUS/IOError on bucket CI runners (#49194) by @ydshieh in [#49194]
- Dev update (#49212) by @vasqu in [#49212]
Significant community contributions
The following contributors have made significant changes to the library over the last release:
- @vasqu
- @remi-or
- [Fix] Remove old test file with two ancient tests (#49280)
- [CB] Make CB more device agnostic and add support for XPU (#49156)
- π¨ Attention π¨ Deprecate "paged|" prefix for SDPA and flash (#49112)
- π¨ Attention π¨ Make regular attention support CB (#49101)
- π¨ [CB] π¨ Fuse update for index and block table path (#49088)
- [Refactor] Make some flash-attention utils more readable (#49071)
- π¨ [CB] π¨ Little fixes before removing "paged" (#49069)
Release 5.18.0
New Model additions
Nemotron 3 Diarization
Nemotron 3 Diarization is an open-weight streaming speaker diarization model designed to determine "who spoke when" in real-world audio. It supports both streaming and offline inference, handles up to eight speakers, and orders speaker outputs by each speaker's first arrival in the input audio.
The model uses the Arrival-Order Speaker Cache (AOSC) 1 and FIFO queue introduced for Streaming Sortformer 1, 2. A single checkpoint supports configurable latency profiles, from an 80 ms input buffer to a 30.4 s offline-style buffer, and configurable output frame resolution in multiples of 10 ms. With chunked inference, the maximum audio duration is not limited.
Links: Documentation
NemotronH Omni
NemotronH Omni is a multimodal reasoning model from NVIDIA that pairs the NemotronH hybrid
Mamba-Transformer language model with a RADIO vision encoder and an optional Parakeet-based sound encoder.
Image (and video) patches are projected through a RADIO tower and a pixel-shuffle MLP into the language model's
embedding space at the <image> / <video> context-token positions; audio clips are projected in the same way at
<audio> positions. The result is a single autoregressive model that reasons jointly over text, images, video and
sound.
Links: Documentation
- Add support for Nemotron Omni (#46509) by @meatybobby in #46509
HyperCLOVAX Vision V2
HyperCLOVAX Vision V2 is a multimodal vision-language model developed by NAVER. It combines the HyperClovaX language model backbone with a Qwen2.5-VL vision encoder. The model supports text, image, and video inputs and is capable of chain-of-thought reasoning via built-in thinking tokens (<think>...</think>).
Links: Documentation
GTE
GTE was proposed in mGTE: Generalized Long-Context Text Representation and Reranking Models for Multilingual Text Retrieval by Xin Zhang, Yanzhao Zhang, Dingkun Long, Wen Xie, Ziqi Dai, Jialong Tang, Huan Lin, Baosong Yang, Pengjun Xie, Fei Huang, Meishan Zhang, Wenjie Li and Min Zhang.
GTE is a BERT-style bidirectional encoder that replaces absolute position embeddings with RoPE, uses a gated MLP, and applies layer normalization after each residual connection. The same architecture backs Alibaba's gte-*-v1.5, gte-multilingual-* and gte-en-mlm-* checkpoints as well as Snowflake's snowflake-arctic-embed-m-v2.0.
Links: Documentation
- model: Add GTE to Transformers (#48416) by @harshaljanjani in #48416
Breaking changes
- π¨ [ROCm] gpt-oss: route FA3 to aiter-flash-attn, generate ROCm fixtures (#46837) by @Abdennacer-Badaoui
- π¨ Speed up detr image processing (#48066) by @guarin
- π¨ Remap indexers layer_type (#48974) by @Cyrilvallez
- π¨ [vLLM] Fix video token counting for Transformers backend video inputs (Part 1) (#48894) by @harshaljanjani
- π¨ π¨Bring some dinos to modern standards (#46266) by @molbap
- π¨ [
Kernels] Bump version (#48714) by @vasqu
Bugfixes and improvements
- fix incorrect hub tokenizer class (#48641) by @itazap
- [CI] Deduplicate Nvidia/AMD CI reply comments and add headers (#48655) by @ydshieh
- Update dev (#48654) by @vasqu
- [tests] Fix NougatModelIntegrationTest: pin artifact revision and update golden values (#48638) by @ydshieh
- [fix] Fix GlmOcr integration tests: wrong token IDs and image token decode bug (#48650) by @ydshieh
- [GLM 5.3 Flash] Preserve original names when saving text checkpoints (#48676) by @Dovis01
- Register activation kernel layers on XPU (#47858) by @jiqing-feng
- Mirror the registered pytree flatten when building automatic dynamic shapes (#48578) by @IlyasMoutawwakil
- Fix
AutoImageProcessorrequiring torchvision when only Pillow is installed (#48616) by @blipbyte - Assert cached decode matches recomputing without a cache (#48289) by @IlyasMoutawwakil
- [higgs_audio_v2] Fix: use config.num_codebooks in audio labels tensor (Simple Fix!) (#48560) by @b-re-w
- [
MoE] Fix eager EP (#48653) by @vasqu - [MusicgenMelody] Fix conditioning silently dropped at generation step 0 (#48679) by @ydshieh
- Fix deepspeed ci (#48640) by @SunMarc
- Synthetic test assets (#48589) by @tarekziade
- Skip the expert-parallel sentinel masking when expert parallelism is off (#48201) by @qgallouedec
- [Fix] yolos offload issue (#48688) by @molbap
- [serge] Fix 2 integration tests for model
minimaxfailing withoutput_mismatch(tensor values differ (2)) (#48515) by @sergereview[bot] - [serge] Fix 2 integration tests for model
mistralfailing withother(other (2)) (#48429) by @sergereview[bot] - Fix Qwen2.5-VL temporal RoPE for fractional video intervals (#48669) by @yeyeyeping
- Fix slow integration tests on XPU (#48611) by @jiqing-feng
- QA: Added a
MemoryCleanupMixinclass for tests (#48681) by @tarekziade - [serge] Fix 1 integration test for model
flex_olmofailing withother(other (1)) (#48668) by @sergereview[bot] - Fix D-FINE / RT-DETR main loss being computed over the denoising queries (#48528) by @stefan-it
- [CI] Replace hardcoded username allowlists with author_association check in workflow triggers (#48712) by @ydshieh
- Add flash_attention_4 in attn_implementation AutoModel docstring (#48684) by @3manifold
- Keep the expert-parallel sentinel slots out of the router gradient (#48689) by @qgallouedec
- [DeepseekV3] OOM cascade root-cause investigation (generator ref leak in conversion_mapping) (#48720) by @ydshieh
- Use huggingface_hub httpx export (#48685) by @Wauplin
- unifying device_mesh init to enable PP + TP inference (#48155) by @3outeille
- Enable FSDP2 + expert parallelism via a 2-D (fsdp, tp) device mesh (#48516) by @qgallouedec
- Switch daily CI to torch 2.14 β update expected outputs (#48750) by @ydshieh
- fix videomae load error (#48675) by @sywangyi
- Fix silently random-initializing
RTDetrModel/SEWDForCTCloads (wrongbase_model_prefix) (#48744) by @ - Fix Glm4vMoeIntegrationTest: offload_folder + MemoryCleanupMixin (#48776) by @ydshieh
- [InternVL] Normalize num_patches before np.cumsum (#48469) by @lorenzozanee
- Kernel api doc, part 2 (#46889) by @michaelbenayoun
- Fix hidden state selection on Gemma4 assistant's first prefill step (#48704) by @glistening
- Fix inkling embedding norm (#48786) by @Cyrilvallez
- Fix TextToAudioPipeline crash for tokenizer-only models (#48505) by @jiqing-feng
- Cast pixel values to the patch embedding dtype in DeepSeek-OCR-2 (#48632) by @jiqing-feng
- add kernel mapping entry for RMSNormGated, KDA, Conv1D on XPU (#48702) by @kaixuanliu
- Bump
peftversion requirement (#48716) by @shniubobo - [serge] Fix 12 integration tests for model
edgetamfailing withimport_or_config(other (12)) (#48322) by @sergereview[bot] - Restore legacy tensor-parallel initialization for compatibility (#48797) by @3outeille
- Fix kosmos flaky test (#48800) by @IlyasMoutawwakil
- Add integration tests for MuseGlimmerAssistantModel (#48796) by @ydshieh
- Fix
AutoModel.from_pretrainednot restoringmodules_to_saveweights (#48595) by @shniubobo - [docs] mrope and axial rope (#48717) by @stevhliu
- Fix decoder only path for older bert variants (#48785) by @Cyrilvallez
- [Fix] Clean-up ternaries in the DeepSeek family (#48447) by @remi-or
- [utils] Add MUSA support for Flash Attention 2 (#48612) by @XiaomingFun233
- [generate] Drop attention mask early without padding (#48814) by @Cyrilvallez
- Pin utf-8 in test_can_init_all_missing_weights source read (Windows non-UTF-8 locale fix) (#48819) by @dltsum
- Relax static-cache tolerance in test_generate_with_static_cache (1e-5 β 5e-5) (#48815) by @ydshieh
- Detect nested rope_parameters without relying on layer_types (#48798) by @hmellor
- Support for MoE in the GGUF integration (#48529) by @SunMarc
- [docs] gguf (#46357) by @stevhliu
- [apply_chat_template] pass sampling_rate to call (#48794) by @eustlb
- [CI] Add link checker (#48160) by @stevhliu
- Qwen3.8 GGUF (#48660) by @SunMarc
- docs: fix broken #combining-with-fsdp2 anchor in expert_parallelism.md (#48854) by @ydshieh
- [GPTNeoXJapanese] Fix RoPE ignoring partial_rotary_factor (#48652) by @blipbyte
- QA: deactivate rule 41 (#48852) by @tarekziade
- Fix
reseton the dynamic cache layers (#48809) by @jiqing-feng - [generate] Make all methods and logits processors agnostic to lm_head output size (#48846) by @Cyrilvallez
- Fix kosmos (#48853) by @Cyrilvallez
- Add test for causal only variant of some encoder-decoder models (#48760) by @nandan2003
- Fix ESMFold2 ligand iPLDDT weighting: mol_type non-polymer code is 3, not 4 (#48831) by @faustomilletari
- Fix flaky RfDetr test_sav...