|
| 1 | +<!--Copyright 2026 The HuggingFace Team. All rights reserved. |
| 2 | +
|
| 3 | +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with |
| 4 | +the License. You may obtain a copy of the License at |
| 5 | +
|
| 6 | +http://www.apache.org/licenses/LICENSE-2.0 |
| 7 | +
|
| 8 | +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on |
| 9 | +an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the |
| 10 | +specific language governing permissions and limitations under the License. |
| 11 | +
|
| 12 | +⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be |
| 13 | +rendered properly in your Markdown viewer. |
| 14 | +
|
| 15 | +--> |
| 16 | + |
| 17 | +# DistributedConfig |
| 18 | + |
| 19 | +[`DistributedConfig`] shards a model across GPUs directly through [`~PreTrainedModel.from_pretrained`]. It supports [FSDP2](./fsdp), [tensor parallelism](./tensor_parallelism), and [N-D parallelism](./perf_train_gpu_many). |
| 20 | + |
| 21 | +Pass a [`DistributedConfig`] to [`~PreTrainedModel.from_pretrained`] and Transformers builds the device mesh and shards the supported layers for you. |
| 22 | + |
| 23 | +The fields below control how the model is sharded. |
| 24 | + |
| 25 | +| field | description | |
| 26 | +|---|---| |
| 27 | +| `tp_size` | Number of devices for tensor parallelism. Defaults to 1 when only `fsdp_size` is set. | |
| 28 | +| `tp_plan` | Tensor parallel sharding plan. Leave as `None` to use the model's default plan. | |
| 29 | +| `fsdp_size` | Number of devices for FSDP2. Defaults to 1 when only `tp_size` is set. | |
| 30 | +| `fsdp_cpu_offload` | Offload parameters and gradients to CPU to save GPU memory. Defaults to `False`. | |
| 31 | +| `fsdp_mixed_precision` | Compute in `bfloat16` and reduce gradients in `float32`. Defaults to `False`. | |
| 32 | +| `enable_expert_parallel` | Shard mixture-of-experts layers across devices. See [Expert parallelism](./expert_parallelism). | |
| 33 | + |
| 34 | +The product of `tp_size` and `fsdp_size` must equal the number of devices you launch with. |
| 35 | + |
| 36 | +## FSDP2 |
| 37 | + |
| 38 | +[FSDP2](./fsdp) shards parameters, gradients, and optimizer states across GPUs. Set `fsdp_size` to the number of devices to shard across. |
| 39 | + |
| 40 | +```py |
| 41 | +import torch |
| 42 | +from transformers import AutoModelForCausalLM |
| 43 | +from transformers.distributed.configuration_utils import DistributedConfig |
| 44 | + |
| 45 | +distributed_config = DistributedConfig(fsdp_size=4) |
| 46 | + |
| 47 | +model = AutoModelForCausalLM.from_pretrained( |
| 48 | + "Qwen/Qwen3-0.6B", |
| 49 | + distributed_config=distributed_config, |
| 50 | +) |
| 51 | +``` |
| 52 | + |
| 53 | +Transformers wraps each layer according to the model's `base_model_fsdp_plan`. Check whether a model declares one before sharding. |
| 54 | + |
| 55 | +```py |
| 56 | +from transformers import AutoConfig |
| 57 | + |
| 58 | +config = AutoConfig.from_pretrained("Qwen/Qwen3-0.6B") |
| 59 | +print(config.base_model_fsdp_plan) |
| 60 | +``` |
| 61 | + |
| 62 | +The plan maps modules to a sharding strategy. `free_full_weight` reshards a module after the forward pass to save memory, and `keep_full_weight` keeps it gathered to avoid a second all-gather during the backward pass. |
| 63 | + |
| 64 | +```py |
| 65 | +{ |
| 66 | + "embed_tokens": "free_full_weight", |
| 67 | + "layers.*": "free_full_weight", |
| 68 | + "norm": "keep_full_weight", |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Set `fsdp_mixed_precision=True` to compute in `bfloat16` while reducing gradients in `float32`, and set `fsdp_cpu_offload=True` to move parameters and gradients to CPU when they aren't in use. |
| 73 | + |
| 74 | +```py |
| 75 | +distributed_config = DistributedConfig( |
| 76 | + fsdp_size=4, |
| 77 | + fsdp_mixed_precision=True, |
| 78 | + fsdp_cpu_offload=True, |
| 79 | +) |
| 80 | +``` |
| 81 | + |
| 82 | +## Tensor parallelism |
| 83 | + |
| 84 | +[Tensor parallelism](./tensor_parallelism) splits weight matrices across GPUs. Set `tp_size` to shard the model's supported layers. |
| 85 | + |
| 86 | +```py |
| 87 | +import torch |
| 88 | +from transformers import AutoModelForCausalLM |
| 89 | +from transformers.distributed.configuration_utils import DistributedConfig |
| 90 | + |
| 91 | +distributed_config = DistributedConfig(tp_size=4) |
| 92 | + |
| 93 | +model = AutoModelForCausalLM.from_pretrained( |
| 94 | + "Qwen/Qwen3-0.6B", |
| 95 | + distributed_config=distributed_config, |
| 96 | +) |
| 97 | +``` |
| 98 | + |
| 99 | +Transformers shards according to the model's `base_model_tp_plan`. Pass `tp_plan` to override the layout, for example `{"model.layers.*.self_attn.q_proj": "colwise"}`. |
| 100 | + |
| 101 | +## N-D parallelism |
| 102 | + |
| 103 | +Combine FSDP2 and tensor parallelism by setting both sizes. The example below runs on 4 GPUs, sharding each tensor-parallel group of 2 GPUs with FSDP2 across the remaining 2. |
| 104 | + |
| 105 | +```py |
| 106 | +import torch |
| 107 | +from transformers import AutoModelForCausalLM |
| 108 | +from transformers.distributed.configuration_utils import DistributedConfig |
| 109 | + |
| 110 | +distributed_config = DistributedConfig(tp_size=2, fsdp_size=2) |
| 111 | + |
| 112 | +model = AutoModelForCausalLM.from_pretrained( |
| 113 | + "Qwen/Qwen3-0.6B", |
| 114 | + dtype=torch.bfloat16, |
| 115 | + distributed_config=distributed_config, |
| 116 | +) |
| 117 | +``` |
| 118 | + |
| 119 | +## Launch |
| 120 | + |
| 121 | +Launch your script with [torchrun](https://pytorch.org/docs/stable/elastic/run.html) and set `--nproc-per-node` to the total number of devices, equal to `tp_size * fsdp_size`. |
| 122 | + |
| 123 | +```shell |
| 124 | +torchrun --nproc-per-node 4 train.py |
| 125 | +``` |
| 126 | + |
| 127 | +## Next steps |
| 128 | + |
| 129 | +- See [FSDP2](./fsdp) for sharded training. |
| 130 | +- See [Tensor parallelism](./tensor_parallelism) for more details on partitioning strategies and manual plans. |
| 131 | +- See [Expert parallelism](./expert_parallelism) for sharding mixture-of-experts models. |
| 132 | +- See [N-D parallelism](./perf_train_gpu_many) for combining parallelism strategies. |
| 133 | +- Read [The Ultra-Scale Playbook](https://huggingface.co/spaces/nanotron/ultrascale-playbook) for a deeper look at how these strategies work. |
0 commit comments