需先按 PyTorch 官方指引自行安装 PyTorch,仓库在 Python 3.11+ 和 PyTorch 2.6.0+ 上测试;FP8 混合精度需额外安装 Transformer Engine 或 torchao;DeepSpeed、FSDP、Megatron-LM 支持在 README 中标注为实验性。
accelerate
huggingfaceApache-2.0活跃维护只需几行代码就能把 PyTorch 模型跑在任意设备或分布式配置上,自动处理混合精度(含 fp8)和 FSDP、DeepSpeed 配置,省去手写分布式训练样板代码的麻烦。
🚀 A simple way to launch, train, and use PyTorch models on almost any device and distributed configuration, automatic mixed precision (including fp8), and easy-to-configure FSDP and DeepSpeed support
pip install accelerateREADME 未说明具体显存要求;支持纯 CPU、单机或多机多 CPU、单 GPU、单机或多机多 GPU 以及 TPU。
不改训练循环就能把原生 PyTorch 脚本跑在单卡、多卡、TPU 和混合精度上的轻量封装库
只需几行代码就能把 PyTorch 模型跑在任意设备或分布式配置上,自动处理混合精度(含 fp8)和 FSDP、DeepSpeed 配置,省去手写分布式训练样板代码的麻烦。
核心能力
- 用 Accelerator 和 prepare 包装模型、优化器、数据加载器
- 用 accelerator.backward 替换 loss.backward 以支持混合精度
- 提供 accelerate config 交互式生成环境配置
- 用 accelerate launch 统一启动多卡、TPU、MPI 任务
- 支持 fp8、fp16、bf16 混合精度与 FSDP、DeepSpeed
容易踩的坑
- v1.15.0v1.15.0: FSDP2 activation memory, dtensor improvements最新正式版2026-09-09 · 2026-09-09 13:30 UTC
v1.15.0: FSDP2 activation memory, dtensor improvements
FSDP2
A large batch of FSDP2 work this release: two fixes that cut activation memory at long sequence lengths, tied-embedding support on torch >= 2.13, and a round of checkpointing correctness and scale fixes.
Activation checkpointing was wrapping each child of the matched layer (
self_attn,mlp, the norms) instead of the layer itself, so every inter-child activation stayed saved for backward. It now wraps the layer.There's also a new FSDP2-only
activation_checkpointing_offload, which moves the remaining per-layer checkpoint inputs to pinned CPU memory. Gradients are exactly those of plain activation checkpointing:# fsdp2.yaml fsdp_config: fsdp_version: 2 fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP fsdp_activation_checkpointing: true fsdp_activation_checkpointing_offload: trueaccelerate launch --config_file fsdp2.yaml train.py- FSDP2 activation checkpointing: wrap the matched transformer layer itself, not each of its children by @qgallouedec in #4172
- Add FSDP2
activation_checkpointing_offload: offload checkpointed layer inputs to pinned CPU memory by @qgallouedec in #4175 - Fix FSDP2 tied-embedding models on torch >= 2.13: put the output embedding in the same fully_shard group by @qgallouedec in #4171
- Fix FSDP2/PEFT/
FULL_STATE_DICTdropping every rank's adapter shard except rank 0 by @AmineDiro in #4206 - FSDP2: per-rank torch.save/load for SHARDED_STATE_DICT to fix 2800+ NPU checkpoint timeout by @gygdh-001 in #4105
- Fix FSDP sharded checkpoint path resolution by @HaomingSong in #4119
- Raise a clear error when FSDP is enabled on a mesh with no shard dimension by @qgallouedec in #4180
DTensor
Two fixes for DTensor-sharded models, which you hit with FSDP2, tensor parallelism, or any N-D parallelism setup: gradient clipping no longer fails on the
foreachop when plain tensors and DTensors are mixed, andprepare_modelleaves an already-sharded model where it is:- Clip grad norm support for dtensors by @michaelbenayoun in #4219
- prepare_model: don't move DTensor-sharded models to the device by @qgallouedec in #4181
Offloading & Quantization
An entire model can now be dispatched to disk, including tied weights — useful for tools like
llm-compressorthat compress large models on machines that can't hold them:- [Offloading] Support full disk offloading by @kylesayrs in #4083
- Fix disk offload crash on FP8 tensors by @shoemoney in #4151
Trackers
Custom trackers can be registered by name and then selected from
log_with=like any built-in one:from accelerate import Accelerator from accelerate.tracking import register_tracker_class register_tracker_class(MyTracker) # MyTracker.name == "my_tracker" accelerator = Accelerator(log_with="my_tracker")- Add register_tracker_class to register custom trackers by name by @javierdejesusda in #4060
- Fix MLFLOW_NESTED_RUN never being able to turn nesting off by @yupengtang in #4223
Device support
Neuron gains a torch dynamo backend (so
--torch-compileworks with the Transformers Trainer) and MPS is now reported and handled properly byaccelerate envandfind_executable_batch_size.- Add
neuronbackend for torch dynamo by @michaelbenayoun in #4097 - Add the neuron device branch in state by @michaelbenayoun in #4218
- Report MPS as the accelerator in
accelerate envby @xquantize in #4158 - Fix accelerate env never reading the MPS chip name by @yupengtang in #4221
- Treat MPS out-of-memory errors as OOM in find_executable_batch_size by @caiotheodoro in #4227
- Fix memory accounting for integrated CUDA devices by @harshitakrishna18 in #4187
- Ensure device-agnostic in docs by @kaixuanliu in #4163
CLI
- Handle missing accelerate executable in env command by @tandede in #4168
- Fix accelerate launch --cpu never setting the KMP variables by @yupe
- v1.14.0v1.14.0: AMD ROCm support, FSDP2 hardening2026-06-11 · 2026-06-11 13:58 UTC
查看更新说明
FSDP2 Improvements
This release brings a large batch of FSDP2 fixes and quality-of-life improvements: correct dtype handling on load, sharding of embeddings/norms, QLoRA crash prevention, and a more robust auto-wrap policy.
- Fsdp2 fully_shard embedding and norm by @SunMarc in #4015
- Fix fsdp2 load full state dict dtype mismatch by @SunMarc in #4021
- Fix region compilation fsdpv2 by @SunMarc in #4022
- [FSDP2] Cast model to uniform dtype before fully_shard to fix mixed-dtype AssertionError by @roycho96 in #3985
- [FSDP2] Auto-exclude non-floating frozen Params4bit from fully_shard to prevent QLoRA crash by @roycho96 in #3987
- fix(FSDP2): auto-wrap policy ignoring _no_split_modules fallback by @JohnGiorgi in #3999
- fix: use key-based matching in fsdp2_load_full_state_dict by @roycho96 in #3982
- fix: add missing model_has_params4bit guard to fsdp2_load_full_state_dict call by @roycho96 in #3981
- Fix to-fsdp2: drop REMOVED / NOT_YET_IMPLEMENTED FSDP1 keys instead of leaking them by @lollinng in #4065
- Prevent double-wrapping models in prepare_model() by @joshuaswanson in #3977
AMD ROCm support
Accelerate now works end-to-end on AMD ROCm devices. Thanks @Abdennacer-Badaoui!
- Make accelerate work end-to-end on AMD ROCm by @Abdennacer-Badaoui in #4025
Neuron
Further Neuron improvements to reduce recompilation and cover missing device cases.
- Add padded allgather and broadcast for Neuron devices to reduce recompilation by @czkkkkkk in #4000
- fix: add missing neuron device case by @michaelbenayoun in #4042
Quantization & Offloading
We improved offloading support for quantized models, including Torchao, int8, and tied-weight handling.
- Torchao offload by @SunMarc in #3973
- Fix int8 offload hook detachment statistics restoration by @jiqing-feng in #4044
- Fix keep_in_fp32_modules not working for tied weights in load_and_quantize_model by @jiqing-feng in #4043
- Fix dtype_byte_size for FP8 fnuz / e8m0fnu dtypes by @lollinng in #4063
Data Loading
- Feat: Support dynamic batch size in BatchSamplerShard with even_batches by @yuxinyuan in #3969
- Fix iterable dataset sharding condition when n_shards == num_processes by @SunMarc in #3958
- Fix implicit padding in split_between_processes when apply_padding=False and num_samples < num_processes by @3manifold in #4052
Minor fixes
- [DeepSpeed] allow kernels flash-attn in SP by @kashif in #3959
- Fix: Conditionally import torch.distributed.algorithms.join in accelerator.py by @0xDELUXA in #3962
- Fix is_hf_initialized attribute by @SunMarc in #3976
- feat(utils): add max reduction type by @imstevenpmwork in #4027
- fix(state): make MLU backend part of the _prepare_backend elif chain by @Anai-Guo in #4057
- fix notebook launcher cuda init by @SunMarc in #4059
- pytorch-triton-xpu rename to triton-xpu by @sywangyi in #4007
- Relax numerical tolerance for XPU in test_big_modeling by @YangKai0616 in #4001
- Fix gloo backend error in test_load_checkpoint_and_dispatch_with_broadcast on XPU by @kaixuanliu in #4056
- Raise ValueError instead of a bare string in ParallelismConfig.get_device_mesh by @lollinng in #4064
- tests: Gracefully handle missing set_device for mps by @booxter in #4028
- test: add regression test for no_split_module_classes accepting set type by @UFO0506 in #4048
- Fix all tests by @SunMarc in #4072
- docs: add aggregate profiler memory example by @aryanputta in #4054
- DOC: document missing parameters in load_accelerator_state, find_executable_batch_size, and send_to_device by @kratos0718 in #4051
- docs: Fix docstring of fsdp2_prepare_auto_wrap_policy by @slocoro in #4037
- Fix DistributedType documentation by @3manifold in #3980
- Fix grammar, spelling, and consistency issues across docs and examples by @cihandemir in #3961
- docs: fix typos in docstrings, comments, and user docs by @mokashang in #4040
- chor
- v1.13.0v1.13.0: Neuron support, IPEX removal, and distributed training fixes2026-03-04 · 2026-03-04 20:15 UTC
查看更新说明
AWS Neuron support
We now have support for AWS Neuron (Trainium/Inferentia) devices. Thanks @michaelbenayoun for adding this.
- Neuron integration by @michaelbenayoun in https://github.com/huggingface/accelerate/pull/3935
XPU Improvements
We've removed IPEX dependency and improved device-agnostic code for XPU.
- using spawn instead of fork for XPU device by @kaixuanliu in https://github.com/huggingface/accelerate/pull/3884
- Remove ipex by @yao-matrix in https://github.com/huggingface/accelerate/pull/3883
- enhance new codes to XPU, and make them be device agnostic by @yao-matrix in https://github.com/huggingface/accelerate/pull/3890
- Fix KMP_AFFINITY incorrectly set for non-CPU training by @hexfaker in https://github.com/huggingface/accelerate/pull/3912
FSDP2 Improvements
We've added a bunch of important fixes for FSDP2 users: upcasting only grad-requiring params, better tied embedding errors, DCP optimizer loading, bf16 optimizer step crash fix, and torch < 2.7.0 compatibility.
- Upcast FSDP2 parameters only if requires_grad by @ojh31 in https://github.com/huggingface/accelerate/pull/3848
- Fix FSDP2 tied embedding errors with targeted ValueError guidance by @amanzoni1 in https://github.com/huggingface/accelerate/pull/3878
- bug: fsdp cannot load optimizer state using dcp by @flymin in https://github.com/huggingface/accelerate/pull/3904
- fix crash in optimizer.step when fsdp2 is enabled and model is bfloat16 by @sywangyi in https://github.com/huggingface/accelerate/pull/3905
- Fix FSDP2 crash with ignored_params on torch < 2.7.0 by @Mr-Neutr0n in https://github.com/huggingface/accelerate/pull/3924
DeepSpeed Sequence Parallelism
We've added several fixes to the DeepSpeed + Sequence Parallelism integration introduced in v1.12.0, including evaluation support during SP training and proper process group handling.
- [SP] fix loss computation example by @kashif in https://github.com/huggingface/accelerate/pull/3858
- [SP and CP] error out if both CP and SP enabled by @kashif in https://github.com/huggingface/accelerate/pull/3862
- DeepSpeed has its own process group by @kashif in https://github.com/huggingface/accelerate/pull/3916
- [Deepspeed] skip device mesh creation when deepspeed and sp_size >1 by @kashif in https://github.com/huggingface/accelerate/pull/3914
- Enable evaluation during deepspeed Sequence Parallel by @jp1924 in https://github.com/huggingface/accelerate/pull/3917
FP8
We've enhanced FP8 training. Thanks @shimizust for fixing torchao support.
- Fix FP8 torchao default config with padding and FSDP2 all-gather support by @shimizust in https://github.com/huggingface/accelerate/pull/3831
- Fix execution with Transformer Engine by @ksivaman in https://github.com/huggingface/accelerate/pull/3852
- add MS-AMP deprecation warnings by @neha222222 in https://github.com/huggingface/accelerate/pull/3857
Performance
Accelerate now imports faster by deferring heavy dependencies, and torch.compile hooks are disabled lazily.
- Faster import by @SunMarc in https://github.com/huggingface/accelerate/pull/3953
- lazy compile disable by @SunMarc in https://github.com/huggingface/accelerate/pull/3947
- Disable hook compile by @SunMarc in https://github.com/huggingface/accelerate/pull/3888
Minor fixes
- Allow non-Tensor values in a batch with dispatch_batches=True by @tomaarsen in https://github.com/huggingface/accelerate/pull/3850
- fix module and optimizer parameter mismatch before prepare_tp_ by @naomili0924 in https://github.com/huggingface/accelerate/pull/3845
- Fix KeyError in extract_model_from_parallel for partial torch.compile by @amanzoni1 in https://github.com/huggingface/accelerate/pull/3881
- Fix hf_device_map device index comparison in prepare_model by @rezaqorbani in https://github.com/huggingface/accelerate/pull/3895
- Fix StatefulDataLoader KeyError with num_workers > 0 by @veeceey in https://github.com/huggingface/accelerate/pull
- v1.12.0v1.12.0: Deepspeed Ulysses/ALST2025-11-21 · 2025-11-21 12:47 UTC
查看更新说明
Deepspeed Ulysses/ALST integration
Deepspeed Ulysses/ALST is an efficient way of training on long sequences by employing sequence parallelism and attention head parallelism. You can learn more about this technology in this paper https://arxiv.org/abs/2506.13996 or this deepspeed tutorial https://www.deepspeed.ai/tutorials/ulysses-alst-sequence-parallelism/.
To enable Deepspeed Ulysses, you first need to create
ParallelismConfigand settingsprelated args:parallelism_config = ParallelismConfig( sp_backend="deepspeed", sp_size=2, sp_handler=DeepSpeedSequenceParallelConfig(...), )Then, you need to make sure to compute the correct loss as described on our docs
... losses_per_rank = torch.distributed.nn.functional.all_gather(loss, group=sp_group) good_tokens = (shift_labels != -100).view(-1).sum() good_tokens_per_rank = torch.distributed.nn.functional.all_gather(good_tokens, group=sp_group) total_loss = sum( losses_per_rank[rank] * good_tokens_per_rank[rank] for rank in range(sp_world_size) if good_tokens_per_rank[rank] > 0 ) total_good_tokens = sum(good_tokens_per_rank) loss = total_loss / max(total_good_tokens, 1)Thanks @S1ro1 for starting this work and for @stas00 for finishing this work. Also thanks @kashif for adding docs and reviewing/testing this PR !
This feature will also be available in HF Trainer thanks for this PR from @stas00: https://github.com/huggingface/transformers/pull/41832
Minor changes
- Remove warning for
cpu_ram_efficient_loadingby @SunMarc in https://github.com/huggingface/accelerate/pull/3816 - update typo in bnb quantisation 4bit flag docstring by @hbraith in https://github.com/huggingface/accelerate/pull/3828
- ArXiv -> HF Papers by @qgallouedec in https://github.com/huggingface/accelerate/pull/3834
- Fix typo in broadcast_object_list docstring by @wsntxxn in https://github.com/huggingface/accelerate/pull/3823
- [Bug] Update torch.optim.Optimizer parameter states after tensor parallelism by @naomili0924 in https://github.com/huggingface/accelerate/pull/3835
- use self hosted runner by @SunMarc in https://github.com/huggingface/accelerate/pull/3841
- device type helper by @kashif in https://github.com/huggingface/accelerate/pull/3843
New Contributors
- @hbraith made their first contribution in https://github.com/huggingface/accelerate/pull/3828
- @wsntxxn made their first contribution in https://github.com/huggingface/accelerate/pull/3823
- @naomili0924 made their first contribution in https://github.com/huggingface/accelerate/pull/3835
Full Changelog: https://github.com/huggingface/accelerate/compare/v1.11.0...v1.12.0
- Remove warning for
- v1.11.0v1.11.0: TE MXFP8, FP16/BF16 with MPS, Python 3.10 2025-10-20 · 2025-10-20 16:08 UTC
查看更新说明
TE MXFP8 support
We've added support for MXFP8 in our TransformerEngine integration. To use that, you need to set
use_mxfp8_block_scalinginfp8_config. See nvidia docs [here]. (https://docs.nvidia.com/deeplearning/transformer-engine/user-guide/examples/fp8_primer.html#MXFP8-and-block-scaling)- Add support for TE MXFP8 recipe in accelerate by @pstjohn in https://github.com/huggingface/accelerate/pull/3688
FP16/BF16 Training for MPS devices
BF16 and FP16 support for MPS devices is finally here. You can now pass
mixed_precision = "fp16" or "bf16"when training on a mac (fp16requires torch 2.8 andbf16requires torch 2.6)- Add bf16/fp16 support for amp with mps device by @SunMarc in https://github.com/huggingface/accelerate/pull/3373
FSDP updates
The following PRs add respectively support to
ignored_paramsandno_sync()for FSDPv2:- feat: add ignored_params support for fsdp2 by @kmehant in https://github.com/huggingface/accelerate/pull/3731
- fix: model.set_requires_gradient_sync(False) should be called to turn off gradient synchronization in FSDP2 by @EquationWalker in https://github.com/huggingface/accelerate/pull/3762
Mixed precision can now be passed as a dtype string from accelerate cli flag or
fsdp_configin accelerate config file:- feat: allow mixed precision policy as dtype by @kmehant in https://github.com/huggingface/accelerate/pull/3751
Nd-parallel updates
Some minor updates concerning nd-parallelism.
- Context Parallelism docs typos fixed by @sergiopaniego in https://github.com/huggingface/accelerate/pull/3761
- Feat: add to_json by @S1ro1 in https://github.com/huggingface/accelerate/pull/3743
- make torch_native_parallelism examples device agnostic by @yao-matrix in https://github.com/huggingface/accelerate/pull/3759
- [ND Parallel] Update examples, cleanup by @S1ro1 in https://github.com/huggingface/accelerate/pull/3737
Bump to Python 3.10
We've dropped support for python 3.9 as it reached EOL in October.
- Bump to python3.10 + update linter by @SunMarc in https://github.com/huggingface/accelerate/pull/3809
Lots of minor fixes:
- fix: CPU RAM efficient loading for nd or HSDP parallelisms by @kmehant in https://github.com/huggingface/accelerate/pull/3740
- xpu INT64 all_gather issue fixed in 2.9 by @yao-matrix in https://github.com/huggingface/accelerate/pull/3756
- Specify device_ids in torch.distributed.barrier for PartialState by @qgallouedec in https://github.com/huggingface/accelerate/pull/3744
- fix: specify device for process_tensor in example usage by @qgallouedec in https://github.com/huggingface/accelerate/pull/3755
- Lower complexity of get_balanced_memory by adding a set by @SamuelBarryCS in https://github.com/huggingface/accelerate/pull/3776
- Fix (skip) cuda cache flush when origin device is
cpuand offloaded tometaby @Qubitium in https://github.com/huggingface/accelerate/pull/3796 - Fix convert LayerNorm without bias to fp8 by @mjun0812 in https://github.com/huggingface/accelerate/pull/3725
- Add optional typing by @cyyever in https://github.com/huggingface/accelerate/pull/3769
- refactor: Use
within Accelerator.autocast()instead of__enter__()and__exit__()for more elegant style. by @EquationWalker in https://github.com/huggingface/accelerate/pull/3767 - switch XPU ccl backend to torch-builtin xccl in test_zero3_integration by @yao-matrix in https://github.com/huggingface/accelerate/pull/3773
- fix FSDP2 test case failure on XPU by @yao-matrix in https://github.com/huggingface/accelerate/pull/3771
- Fix tests by @SunMarc in https://github.com/huggingface/accelerate/pull/3722
- Protect import for device_mesh by @SunMarc in https://github.com/huggingface/accelerate/pull/3742
- Fix
SWANLAB_MODEby @SunMarc in https://github.com/huggingface/accelerate/pull/3808 - Fix tracking swanlab by @SunMarc in https://github.com/huggingface/accelerate/pull/3810
- refactor: nit change for
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
Easy to integrate
🤗 Accelerate was created for PyTorch users who like to write the training loop of PyTorch models but are reluctant to write and maintain the boilerplate code needed to use multi-GPUs/TPU/fp16.
🤗 Accelerate abstracts exactly and only the boilerplate code related to multi-GPUs/TPU/fp16 and leaves the rest of your code unchanged.
Here is an example:
import torch
import torch.nn.functional as F
from datasets import load_dataset
+ from accelerate import Accelerator
+ accelerator = Accelerator()
- device = 'cpu'
+ device = accelerator.device
model = torch.nn.Transformer().to(device)
optimizer = torch.optim.Adam(model.parameters())
dataset = load_dataset('my_dataset')
data = torch.utils.data.DataLoader(dataset, shuffle=True)
+ model, optimizer, data = accelerator.prepare(model, optimizer, data)
model.train()
for epoch in range(10):
for source, targets in data:
source = source.to(device)
targets = targets.to(device)
optimizer.zero_grad()
output = model(source)
loss = F.cross_entropy(output, targets)
- loss.backward()
+ accelerator.backward(loss)
optimizer.step()
As you can see in this example, by adding 5-lines to any standard PyTorch training script you can now run on any kind of single or distributed node setting (single CPU, single GPU, multi-GPUs and TPUs) as well as with or without mixed precision (fp8, fp16, bf16).
In particular, the same code can then be run without modification on your local machine for debugging or your training environment.
🤗 Accelerate even handles the device placement for you (which requires a few more changes to your code, but is safer in general), so you can even simplify your training loop further:
import torch
import torch.nn.functional as F
from datasets import load_dataset
+ from accelerate import Accelerator
- device = 'cpu'
+ accelerator = Accelerator()
- model = torch.nn.Transformer().to(device)
+ model = torch.nn.Transformer()
optimizer = torch.optim.Adam(model.parameters())
dataset = load_dataset('my_dataset')
data = torch.utils.data.DataLoader(dataset, shuffle=True)
+ model, optimizer, data = accelerator.prepare(model, optimizer, data)
model.train()
for epoch in range(10):
for source, targets in data:
- source = source.to(device)
- targets = targets.to(device)
optimizer.zero_grad()
output = model(source)
loss = F.cross_entropy(output, targets)
- loss.backward()
+ accelerator.backward(loss)
optimizer.step()
Want to learn more? Check out the documentation or have a look at our examples.
Launching script
🤗 Accelerate also provides an optional CLI tool that allows you to quickly configure and test your training environment before launching the scripts. No need to remember how to use torch.distributed.run or to write a specific launcher for TPU training!
On your machine(s) just run:
accelerate config
and answer the questions asked. This will generate a config file that will be used automatically to properly set the default options when doing
accelerate launch my_script.py --args_to_my_script
For instance, here is how you would run the GLUE example on the MRPC task (from the root of the repo):
accelerate launch examples/nlp_example.py
This CLI tool is optional, and you can still use python my_script.py or python -m torchrun my_script.py at your convenience.
You can also directly pass in the arguments you would to torchrun as arguments to accelerate launch if you wish to not run accelerate config.
For example, here is how to launch on two GPUs:
accelerate launch --multi_gpu --num_processes 2 examples/nlp_example.py
To learn more, check the CLI documentation available here.
Or view the configuration zoo here
Launching multi-CPU run using MPI
🤗 Here is another way to launch multi-CPU run using MPI. You can learn how to install Open MPI on this page. You can use Intel MPI or MVAPICH as well. Once you have MPI setup on your cluster, just run:
accelerate config
Answer the questions that are asked, selecting to run using multi-CPU, and answer "yes" when asked if you want accelerate to launch mpirun.
Then, use accelerate launch with your script like:
accelerate launch examples/nlp_example.py
Alternatively, you can use mpirun directly, without using the CLI like:
mpirun -np 2 python examples/nlp_example.py
Launching training using DeepSpeed
🤗 Accelerate supports training on single/multiple GPUs using DeepSpeed. To use it, you don't need to change anything in your training code; you can set everything using just accelerate config. However, if you desire to tweak your DeepSpeed related args from your Python script, we provide you the DeepSpeedPlugin.
from accelerate import Accelerator, DeepSpeedPlugin
# deepspeed needs to know your gradient accumulation steps beforehand, so don't forget to pass it
# Remember you still need to do gradient accumulation by yourself, just like you would have done without deepspeed
deepspeed_plugin = DeepSpeedPlugin(zero_stage=2, gradient_accumulation_steps=2)
accelerator = Accelerator(mixed_precision='fp16', deepspeed_plugin=deepspeed_plugin)
# How to save your 🤗 Transformer?
accelerator.wait_for_everyone()
unwrapped_model = accelerator.unwrap_model(model)
unwrapped_model.save_pretrained(save_dir, save_function=accelerator.save, state_dict=accelerator.get_state_dict(model))
Note: DeepSpeed support is experimental for now. In case you get into some problem, please open an issue.
Launching your training from a notebook
🤗 Accelerate also provides a notebook_launcher function you can use in a notebook to launch a distributed training. This is especially useful for Colab or Kaggle notebooks with a TPU backend. Just define your training loop in a training_function then in your last cell, add:
from accelerate import notebook_launcher
notebook_launcher(training_function)
An example can be found in this notebook.
Why should I use 🤗 Accelerate?
You should use 🤗 Accelerate when you want to easily run your training scripts in a distributed environment without having to renounce full control over your training loop. This is not a high-level framework above PyTorch, just a thin wrapper so you don't have to learn a new library. In fact, the whole API of 🤗 Accelerate is in one class, the Accelerator object.
Why shouldn't I use 🤗 Accelerate?
You shouldn't use 🤗 Accelerate if you don't want to write a training loop yourself. There are plenty of high-level libraries above PyTorch that will offer you that, 🤗 Accelerate is not one of them.
Frameworks using 🤗 Accelerate
If you like the simplicity of 🤗 Accelerate but would prefer a higher-level abstraction around its capabilities, some frameworks and libraries that are built on top of 🤗 Accelerate are listed below:
- Amphion is a toolkit for Audio, Music, and Speech Generation. Its purpose is to support reproducible research and help junior researchers and engineers get started in the field of audio, music, and speech generation research and development.
- Animus is a minimalistic framework to run machine learning experiments. Animus highlights common "breakpoints" in ML experiments and provides a unified interface for them within IExperiment.
- Catalyst is a PyTorch framework for Deep Learning Research and Development. It focuses on reproducibility, rapid experimentation, and codebase reuse so you can create something new rather than write yet another train loop. Catalyst provides a Runner to connect all parts of the experiment: hardware backend, data transformations, model training, and inference logic.
- fastai is a PyTorch framework for Deep Learning that simplifies training fast and accurate neural nets using modern best practices. fastai provides a Learner to handle the training, fine-tuning, and inference of deep learning algorithms.
- Finetuner is a service that enables models to create higher-quality embeddings for semantic search, visual similarity search, cross-modal text<->image search, recommendation systems, clustering, duplication detection, anomaly detection, or other uses.
- InvokeAI is a creative engine for Stable Diffusion models, offering industry-leading WebUI, terminal usage support, and serves as the foundation for many commercial products.
- Kornia is a differentiable library that allows classical computer vision to be integrated into deep learning models. Kornia provides a Trainer with the specific purpose to train and fine-tune the supported deep learning algorithms within the library.
- Open Assistant is a chat-based assistant that understands tasks, can interact with their party systems, and retrieve information dynamically to do so.
- pytorch-accelerated is a lightweight training library, with a streamlined feature set centered around a general-purpose Trainer, that places a huge emphasis on simplicity and transparency; enabling users to understand exactly what is going on under the hood, but without having to write and maintain the boilerplate themselves!
- Stable Diffusion web UI is an open-source browser-based easy-to-use interface based on the Gradio library for Stable Diffusion.
- torchkeras is a simple tool for training pytorch model just in a keras style, a dynamic and beautiful plot is provided in notebook to monitor your loss or metric.
- transformers as a tool for helping train state-of-the-art machine learning models in PyTorch, Tensorflow, and JAX. (Accelerate is the backend for the PyTorch side).
Installation
This repository is tested on Python 3.11+ and PyTorch 2.6.0+
You should install 🤗 Accelerate in a virtual environment. If you're unfamiliar with Python virtual environments, check out the user guide.
First, create a virtual environment with the version of Python you're going to use and activate it.
Then, you will need to install PyTorch: refer to the official installation page regarding the specific install command for your platform. Then 🤗 Accelerate can be installed using pip as follows:
pip install accelerate
Supported integrations
- CPU only
- multi-CPU on one node (machine)
- multi-CPU on several nodes (machines)
- single GPU
- multi-GPU on one node (machine)
- multi-GPU on several nodes (machines)
- TPU
- FP16/BFloat16 mixed precision
- FP8 mixed precision with Transformer Engine or torchao
- DeepSpeed support (Experimental)
- PyTorch Fully Sharded Data Parallel (FSDP) support (Experimental)
- Megatron-LM support (Experimental)
Citing 🤗 Accelerate
If you use 🤗 Accelerate in your publication, please cite it by using the following BibTeX entry.
@Misc{accelerate,
title = {Accelerate: Training and inference at scale made simple, efficient and adaptable.},
author = {Sylvain Gugger and Lysandre Debut and Thomas Wolf and Philipp Schmid and Zachary Mueller and Sourab Mangrulkar and Marc Sun and Benjamin Bossan},
howpublished = {\url{https://github.com/huggingface/accelerate}},
year = {2022}
}