●Change8

Migrating to Transformers 4.54.1

Version 4.54.1 introduces 5 breaking changes. This guide details how to update your code.

Released: 7/29/2025

5
Breaking Changes
5
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

Cache.max_cache_lenmodeling_utils.pyGPT2MambaModernBERTCachesmodel._tp_sizedevice-mesh

Breaking Changes

●Issue #1

The maximum value for Cache.max_cache_len in Hybrid models has been corrected, which might affect configurations relying on the previous, incorrect maximum.

✓Solution

Review your configuration for Hybrid models and ensure that the desired max_cache_len is still valid within the newly corrected bounds. No code change is strictly required unless your previous setting was invalid or hitting the old limit.

●Issue #2

A regression affecting model versioning in modeling_utils.py has been fixed, which might cause issues if your custom models relied on the previous incorrect version handling.

✓Solution

If you are using custom models or specific version checks, verify that they behave as expected. No direct code change is usually needed unless you were explicitly relying on the buggy version behavior.

●Issue #3

Fixes related to cache inheritance and layer device placement in Caches have been implemented, potentially altering how caches are initialized or moved across devices.

✓Solution

If you manually manage device placement for caches or rely on specific cache inheritance patterns, test your initialization logic thoroughly. Ensure device placement calls are robust.

●Issue #4

The handling of n-dim device-mesh during TP trainer saving has been corrected, which could break custom saving routines that relied on the previous behavior.

✓Solution

If you use custom logic for saving trainers with Tensor Parallelism (TP), ensure that the trainer saving process completes successfully and verify saved checkpoints.

●Issue #5

The missing model._tp_size attribute following an 'ep refactor' (likely related to pipeline parallelism or expert parallelism) has been restored.

✓Solution

If your code accessed model._tp_size directly, this attribute should now be present. If you were patching around its absence, remove those patches.

Migration Steps

  1. 1
    1. Update your library to version 4.54.1 or later.
  2. 2
    2. Review any configurations related to Hybrid models and the 'Cache.max_cache_len' parameter to ensure they are within the corrected limits.
  3. 3
    3. If you are using custom models or specific version checks, test model loading and initialization to confirm the fix in modeling_utils.py did not introduce regressions for your use case.
  4. 4
    4. Thoroughly test any code paths involving distributed training, especially those dealing with Tensor Parallelism (TP) saving routines, to confirm device-mesh and trainer saving integrity.
  5. 5
    5. If you previously encountered issues with cache inheritance or device placement on caches, re-test those specific scenarios.

Release Summary

A maintenance patch release focused on fixing regressions in cache inheritance, device placement, and distributed training (TP/device-mesh) across various model architectures like ModernBERT, GPT2, and Mamba.

Need More Details?

View the full release notes and all changes for Transformers 4.54.1.

View Full Changelog