Article

加速训练 Accelerate 速查文档

更新于：2026-07-20

第一部分：入门基础

第1章 Accelerate 简介与核心理念

1.1 什么是 Accelerate

名称	说明	用途	代码示例	注意事项
Hugging Face Accelerate	一个轻量级库，用于在 PyTorch 中无缝切换单 GPU、多 GPU、TPU 和混合精度训练，无需重写训练循环。	简化分布式训练流程，提升代码可移植性和可复用性。	无（概念性介绍）	不是模型训练框架，而是 PyTorch 训练流程的”增强层”。
核心设计目标	提供高层抽象，隐藏设备管理、分布式通信、混合精度等复杂细节。	让研究人员专注于模型逻辑而非工程细节。	无	用户仍需理解底层机制以进行调试和优化。
与 Transformers 集成	Accelerate 最初为 Hugging Face Transformers 库设计，可无缝配合使用。	支持快速部署 NLP 模型的分布式训练。	无	也可独立用于任意 PyTorch 模型。

1.2 Accelerate 解决的核心问题

名称	说明	用途	代码示例	注意事项
设备管理复杂性	手动调用 `.to(device)` 易出错，尤其在多设备环境下。	自动管理模型、数据、损失的设备放置。	无	Accelerate 通过 `Accelerator` 实例统一处理。
分布式训练配置繁琐	需手动初始化进程组、设置 `DistributedDataParallel`、处理 rank 分支。	封装 `torch.distributed` 复杂性，自动配置。	无	用户无需编写 `if rank == 0:` 等分支逻辑。
混合精度训练难统一	AMP（Automatic Mixed Precision）需手动管理 `GradScaler` 和 `autocast`。	自动启用 FP16/BF16，简化训练流程。	无	可通过配置文件或参数控制。
训练脚本可移植性差	同一代码在单卡、多卡、TPU 上需大量修改。	一套代码适配多种硬件环境。	无	仅需运行 `accelerate config` 一次生成配置。
模型保存与加载不一致	多卡下需调用 `module.state_dict()`，单卡则直接调用。	提供统一的 `save_state` 和 `load_state` 方法。	无	避免因设备差异导致的加载错误。

1.3 分布式训练的基本概念

概念名称	说明	注意事项
数据并行（Data Parallelism）	将输入数据分片到多个设备，每个设备保存完整模型副本，前向传播后同步梯度。	适用于模型较小但数据量大的场景；通信开销集中在梯度同步。
模型并行（Model Parallelism）	将模型不同层分配到不同设备，减少单设备显存压力。	适用于超大模型；需手动拆分模型，通信频繁。
张量并行（Tensor Parallelism）	将单个层的计算（如矩阵乘法）拆分到多个设备。	更细粒度的模型拆分，常用于 LLM；实现复杂。
混合精度训练（Mixed Precision）	使用 FP16（或 BF16）进行前向/反向传播，FP32 保存主梯度和参数更新。	可减少显存占用并加速训练；需梯度缩放防止下溢。
梯度累积（Gradient Accumulation）	多个 forward 后累积梯度，再执行一次 optimizer step，模拟大 batch size。	用于显存不足时增大有效 batch size；不增加显存峰值。
分布式数据加载（DistributedSampler）	每个进程加载数据的不同子集，避免重复。	必须配合 `DistributedDataParallel` 使用；需设置 `shuffle=True`。

1.4 Accelerate 的抽象层次与优势

抽象层次：

抽象层次	说明	优势	注意事项
应用层（用户代码）	用户编写标准 PyTorch 训练循环，调用 `accelerator.prepare()` 和 `accelerator.backward()`。	无需修改核心训练逻辑，迁移成本低。	仍需遵循 PyTorch 编程范式。
中间层（Accelerate）	封装 `torch.distributed`、`torch.cuda.amp`、`DistributedDataParallel` 等组件。	自动选择最优后端（NCCL, GLOO, XLA），统一接口。	行为受 `accelerate config` 控制。
底层（PyTorch / XLA）	实际执行分布式通信、混合精度计算、TPU 编译等。	兼容最新 PyTorch 功能，支持 TPU。	TPU 需 Google Cloud 环境和特殊配置。

优势说明：

优势	说明	影响	注意事项
代码简洁性	无需手动 `to(device)`、`DistributedDataParallel` 包装、`GradScaler` 管理。	减少样板代码，降低出错概率。	初学者仍需理解其背后机制。
可移植性	同一代码可在单卡、多卡、多机、TPU 上运行，仅需重新配置。	提升实验迭代效率，便于团队协作。	配置文件需根据环境调整。

第2章安装与环境配置

2.1 安装 Accelerate 库

操作名称	操作细节	注意事项
安装基础版本	`pip install accelerate`	适用于单机训练，包含 CPU/GPU 支持。
安装完整版本（推荐）	`pip install "accelerate[all]"`	包含 TPU、Deepspeed、safetensors 等额外依赖。
验证安装	`python -c "from accelerate import Accelerator; print('Success')"`	确保无导入错误。
安装特定版本	`pip install accelerate==0.27.0`	可指定版本以保证环境一致性。

2.2 初始化配置：accelerate config

步骤名称	操作细节	注意事项
运行配置向导	在终端执行 `accelerate config`	首次使用必须运行，生成 `~/.cache/huggingface/accelerate/default_config.yaml`。
选择训练类型	选项：multi-GPU, TPU, CPU, multi-CPU, mixed precision	根据当前硬件选择，错误选择可能导致运行失败。
设置GPU数量	输入可用 GPU 数量（如 4）	应 ≤ 实际 GPU 数量。
选择混合精度模式	选项：no, fp16, bf16	fp16 兼容性好；bf16 需硬件支持（如 A100、TPU）。
设置分布式后端	默认 nccl（NVIDIA GPU）；可选 gloo、mpi	多机训练需网络配置支持。
梯度累积步数	可在此设置默认累积步数，也可在代码中覆盖	仅作为默认值，不影响代码中动态设置。
配置保存路径	自动生成 YAML 配置文件，通常位于 `~/.cache/huggingface/accelerate/`	可通过 `ACCELERATE_CONFIG_FILE` 环境变量指定自定义路径。

2.3 配置文件详解（YAML 格式）

参数名称	说明	示例值	注意事项
`compute_environment`	计算环境类型	`LOCAL_MACHINE`	通常为本地机器。
`distributed_type`	分布式类型	`MULTI_GPU`	可选：CPU, GPU, TPU, MULTI_CPU, MULTI_GPU, NO。
`num_machines`	机器数量	`1`	多机训练时需设为 >1。
`num_processes`	总进程数	`4`	通常 = 单机 GPU 数 × 机器数。
`mixed_precision`	混合精度模式	`fp16`	可选：no, fp16, bf16。
`gpu_ids`	使用的 GPU ID	`all` 或 `0,1,2,3`	`all` 表示使用所有可用 GPU。
`use_cpu`	是否强制使用 CPU	`false`	调试时可启用。
`deepspeed_config`	DeepSpeed 配置路径	`null`	启用 DeepSpeed 时需指定 JSON 文件。
`fsdp_config`	FSDP 配置	`null`	用于全分片数据并行。
`megatron_lm_config`	Megatron-LM 配置	`null`	用于 Megatron 框架集成。

2.4 多GPU/TPU/混合精度环境准备

环境类型	操作细节	注意事项
多GPU环境	确保安装 NVIDIA 驱动和 CUDA，运行 `nvidia-smi` 验证 GPU 可见性。	推荐使用 nccl 后端；确保所有 GPU 型号一致。
TPU环境（Google Cloud）	安装 `torch_xla` 库，使用 TPU-VM 或 Colab TPU 运行。	需通过 xla 后端启动，不能使用标准 CUDA 流程。
混合精度支持	确认 GPU 支持 Tensor Cores（如 V100, A100, RTX 30xx+）。	bf16 需 Ampere 架构或更新；fp16 广泛支持。
多机SSH配置	配置无密码 SSH 登录，确保各节点时间同步。	`accelerate launch` 需通过 SSH 启动远程进程。
环境变量设置	可设置 `CUDA_VISIBLE_DEVICES` 限制 GPU 使用。	与 `accelerate config` 中的 `gpu_ids` 协同使用。

第3章快速上手：单机训练加速

3.1 使用 Accelerator 类包装训练流程

方法/属性	语法	用途	代码示例	注意事项
`Accelerator()`	`accelerator = Accelerator()`	初始化加速器，自动加载 `accelerate config` 配置。	`from accelerate import Accelerator` `accelerator = Accelerator()`	必须在所有模型、优化器创建前初始化。
`accelerator.prepare()`	`model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)`	包装模型、优化器、数据加载器，自动应用 DDP、AMP 等。	`model, optimizer, train_dataloader = accelerator.prepare(` `model, optimizer, train_dataloader` `)`	参数顺序需与返回值一致；支持任意数量参数。
`accelerator.backward(loss)`	`accelerator.backward(loss)`	替代 `loss.backward()`，兼容混合精度和分布式训练。	`loss = model(input_ids).loss` `accelerator.backward(loss)`	不要再调用 `loss.backward()`。
`accelerator.wait_for_everyone()`	`accelerator.wait_for_everyone()`	等待所有进程执行到此点，用于同步。	`if accelerator.is_main_process:` `print("Main process")` `accelerator.wait_for_everyone()`	用于主进程操作后同步。
`accelerator.end_training()`	`accelerator.end_training()`	清理资源，结束训练会话。	`accelerator.end_training()`	非必需，但在长任务中建议调用。

3.2 自动设备管理（device placement）

方法/属性	语法	用途	代码示例	注意事项
`accelerator.device`	`device = accelerator.device`	获取当前进程的设备（如 `cuda:0`, `cpu`）。	`model.to(accelerator.device)`	通常不需要，因 `prepare()` 已自动处理。
`accelerator.unwrap_model()`	`unwrapped_model = accelerator.unwrap_model(model)`	获取原始模型（去除 DDP 或 Accelerate 包装）。	`unwrapped_model.save_pretrained("output_dir")`	保存模型权重时需解包。
自动张量放置	所有输入数据无需 `.to(device)`	Accelerate 自动将数据移动到正确设备。	`for batch in dataloader:` `outputs = model(**batch) # batch 自动在正确设备`	数据加载器由 `prepare()` 包装后自动处理。
`is_main_process`	`if accelerator.is_main_process:`	判断当前是否为主进程，用于日志、保存等操作。	`if accelerator.is_main_process:` `print(f"Step {step}, Loss: {loss}")`	避免所有进程重复输出。
`local_process_index`	`index = accelerator.local_process_index`	获取本地进程索引（0~num_processes-1）。	`print(f"Process {index} running")`	调试时用于区分进程。

3.3 混合精度训练启用（AMP）

方法/属性	语法	用途	代码示例	注意事项
`prepare()` 自动启用	`model, optimizer, dataloader = accelerator.prepare(...)`	根据配置自动启用 FP16/BF16 和 GradScaler。	同 3.1 节示例	无需手动创建 GradScaler。
`accelerator.scaler`	`scaler = accelerator.scaler`	访问内部的 GradScaler 实例（如需手动控制）。	`if accelerator.use_fp16:` `scaler.scale(loss).backward()`	通常由 `accelerator.backward()` 内部处理。
`use_fp16` / `use_bf16`	`flag = accelerator.use_fp16`	查询是否启用了 FP16 或 BF16。	`if accelerator.use_fp16:` `print("Using FP16")`	可用于条件逻辑。
`autocast` 上下文	`with accelerator.autocast():`	手动控制混合精度作用域。	`with accelerator.autocast():` `outputs = model(inputs)`	在 `prepare()` 后调用；通常不需要。

3.4 模型、优化器、数据加载器的包装

组件	语法	用途	代码示例	注意事项
模型包装	`model = accelerator.prepare(model)`	自动包装为 DDP（多卡时）或保持原样（单卡），并移动到设备。	`model = accelerator.prepare(model)`	无需手动调用 `DistributedDataParallel`。
优化器包装	`optimizer = accelerator.prepare(optimizer)`	兼容混合精度训练，与 GradScaler 协同工作。	`optimizer = AdamW(model.parameters(), lr=5e-5)` `optimizer = accelerator.prepare(optimizer)`	必须在 `prepare()` 中与模型、dataloader 一起传入或单独准备。
数据加载器包装	`dataloader = accelerator.prepare(dataloader)`	自动插入 DistributedSampler（多卡时），处理批处理分片。	`train_dataloader = DataLoader(dataset, batch_size=8)` `train_dataloader = accelerator.prepare(train_dataloader)`	`shuffle` 参数在 DataLoader 中设置，DistributedSampler 会继承。
多组件联合包装	`model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)`	一行代码完成所有组件准备，推荐用法。	`model, optimizer, dl = accelerator.prepare(` `model, optimizer, train_dataloader` `)`	顺序需一致；支持 1~N 个组件。
包装后的行为	模型前向传播自动在正确设备	用户代码无需修改，保持简洁。	`outputs = model(input_ids) # 自动设备匹配`	输入数据也由 dataloader 自动放置。

第二部分：核心功能详解

第4章分布式训练基础

4.1 数据并行（Data Parallelism）原理

概念名称	说明	注意事项
数据并行（Data Parallelism）	将一个大 batch 拆分为多个子 batch，分发到多个设备（GPU），每个设备运行相同的模型副本进行前向和反向传播。	适用于模型可放入单卡显存但需更大 batch size 的场景。
模型复制	每个设备保存完整模型的副本。	显存占用为”单卡模型显存 × 设备数”，不适合超大模型。
前向传播	输入数据被 DistributedSampler 自动分片，各设备独立计算输出。	用户无需手动切分 batch。
梯度计算	各设备独立计算梯度。	梯度为局部梯度，需后续同步。
梯度同步（All-Reduce）	所有设备通过 All-Reduce 操作汇总梯度，确保每个设备拥有全局平均梯度。	accelerate 使用 `torch.distributed.all_reduce()` 实现，通常后端为 NCCL。
参数更新	各设备使用同步后的梯度更新模型参数，保持一致性。	所有设备参数始终一致，无需额外同步。

4.2 启动多进程训练：accelerate launch

方法/命令	语法	用途	代码示例	注意事项
`accelerate launch`	`accelerate launch train.py`	启动多进程训练脚本，自动根据配置创建多个进程。	`accelerate launch --num_processes=4 train.py`	必须使用此命令启动分布式训练，不能直接 `python train.py`。
指定进程数	`--num_processes=N`	覆盖配置文件中的进程数。	`accelerate launch --num_processes=8 train.py`	应 ≤ 可用 GPU 数量。
CPU 模式运行	`--use_cpu`	强制在 CPU 上运行（用于调试）。	`accelerate launch --use_cpu train.py`	性能极低，仅用于验证逻辑。
混合精度设置	`--mixed_precision=fp16`	临时启用 FP16，覆盖配置文件。	`accelerate launch --mixed_precision=bf16 train.py`	支持 no, fp16, bf16。
多机启动	`--num_machines=N --machine_rank=0 --main_process_ip=IP --main_process_port=PORT`	启动跨多台机器的训练。	`accelerate launch --num_machines=2 --machine_rank=0 ...`	需配置 SSH 免密登录和网络连通性。
查看帮助	`accelerate launch --help`	显示所有可用参数。	`accelerate launch --help`	推荐首次使用前查看。

4.3 进程组初始化与 rank 管理

属性/方法	语法	用途	代码示例	注意事项
`local_rank`	`accelerator.local_rank`	获取当前进程在本地机器上的 rank（0~num_processes_per_machine-1）。	`print(f"Local rank: {accelerator.local_rank}")`	通常用于设置 `CUDA_VISIBLE_DEVICES`。
`process_index`	`accelerator.process_index`	全局进程索引（0~num_processes*num_machines-1）。	`if accelerator.process_index == 0: print("Global main")`	在多机训练中区分全局主进程。
`is_main_process`	`accelerator.is_main_process`	判断是否为主进程（通常是 local_rank == 0）。	`if accelerator.is_main_process:` `save_model()`	仅主进程执行日志、保存等操作。
`is_local_main_process`	`accelerator.is_local_main_process`	判断是否为本地主进程（local_rank == 0）。	`if accelerator.is_local_main_process:` `log_to_wandb()`	多机训练中每台机器可独立记录日志。
`num_processes`	`accelerator.num_processes`	获取总进程数。	`print(f"Total processes: {accelerator.num_processes}")`	用于计算有效 batch size（batch_size × num_processes）。
`dataloader_config`	`DistributedDataLoaderConfig(...)`	配置分布式数据加载器行为。	不常用，由 `prepare()` 内部处理。	一般无需手动设置。

4.4 梯度同步与模型参数一致性

机制	说明	注意事项
DistributedDataParallel (DDP)	Accelerate 在多卡时自动将模型包装为 DDP，实现梯度同步。	包装由 `accelerator.prepare(model)` 完成，用户无感知。
梯度 All-Reduce	反向传播后，各设备梯度通过 All-Reduce 汇总并取平均。	通信开销随设备数增加而上升，是主要性能瓶颈之一。
参数一致性	由于所有设备使用相同梯度更新，参数始终保持一致。	无需在每步后同步模型。
`no_sync()` 上下文	在梯度累积时禁用梯度同步，减少通信开销。	仅在累积步数内有效，最后一步必须同步。

no_sync 示例：

with accelerator.no_sync(model):
    for i, batch in enumerate(dataloader):
        if (i + 1) % grad_accum_steps != 0:
            with accelerator.no_sync(model):
                loss = model(batch).loss
                accelerator.backward(loss)

第5章混合精度训练

5.1 FP16 与 BF16 精度介绍

精度类型	位宽	范围与精度	硬件支持	注意事项
FP16（Float16）	16 位	范围小，易发生下溢（underflow）或溢出（overflow）。	广泛支持（Pascal 架构及以上）。	需梯度缩放（GradScaler）防止下溢。
BF16（Bfloat16）	16 位	指数位与 FP32 相同，动态范围大，不易溢出。	需 Ampere（A100）或更新 GPU，或 TPU。	不需要梯度缩放也能稳定训练。
FP32（Float32）	32 位	高精度，标准精度。	所有设备支持。	显存占用高，速度慢。
混合精度策略	计算使用 FP16/BF16，参数更新使用 FP32 主副本。	减少显存占用 30%~50%，加速训练。	Accelerate 自动管理主副本。

5.2 使用 prepare() 自动启用混合精度

方法	语法	用途	代码示例	注意事项
`accelerator.prepare()`	`model, optim, dl = accelerator.prepare(model, optim, dl)`	根据 `accelerate config` 自动启用混合精度。	`accelerator = Accelerator(mixed_precision="fp16")` `model = accelerator.prepare(model)`	配置文件或初始化时设置 `mixed_precision`。
初始化时指定	`Accelerator(mixed_precision="fp16")`	覆盖配置文件设置。	`accelerator = Accelerator(mixed_precision="bf16")`	优先级高于配置文件。
检查是否启用	`accelerator.mixed_precision != "no"`	判断是否启用了混合精度。	`if accelerator.mixed_precision == "fp16":` `print("FP16 enabled")`	可用于条件逻辑。

5.3 混合精度上下文管理（autocast）

方法	语法	用途	代码示例	注意事项
`accelerator.autocast()`	`with accelerator.autocast():` `outputs = model(inputs)`	手动控制混合精度作用域。	`with accelerator.autocast():` `loss = model(batch).loss`	通常不需要，因 forward 已自动处理。
禁用自动混合精度	`with accelerator.autocast(enabled=False):` `outputs = model(inputs)`	在特定计算中禁用混合精度。	用于数值不稳定的操作（如 LayerNorm）。	少数情况需要。
返回值类型	FP16/BF16 张量	输出为低精度张量。	不影响损失计算，因 loss 通常 `.float()` 后计算。	梯度仍通过 GradScaler 正确处理。

5.4 梯度缩放（Gradient Scaling）机制

方法/属性	语法	用途	代码示例	注意事项
`accelerator.scaler`	`scaler = accelerator.scaler`	访问内部 GradScaler 实例。	`if accelerator.use_fp16:` `print(scaler.get_scale())`	仅在 FP16 启用时非 None。
`scaler.scale(loss)`	`scaled_loss = scaler.scale(loss)`	缩放损失值，防止梯度下溢。	`scaled_loss = scaler.scale(loss)` `accelerator.backward(scaled_loss)`	通常由 `accelerator.backward()` 内部处理。
`scaler.step(optimizer)`	`scaler.step(optimizer)`	更新参数并处理缩放。	`scaler.step(optimizer)`	由 `accelerator.step(optimizer)` 封装。
`scaler.update()`	`scaler.update()`	更新缩放因子（自动增减）。	`scaler.update()`	每步 optimizer step 后调用。
自动管理	`accelerator.backward()` 和 `optimizer.step()`	Accelerate 自动处理梯度缩放全流程。	`accelerator.backward(loss)` `optimizer.step()` `optimizer.zero_grad()`	用户无需手动调用 scaler 方法。

第6章模型与数据的设备管理

6.1 `accelerator.prepare()` 方法详解

参数	语法	用途	代码示例	注意事项
`models`	`prepare(model)`	包装模型（DDP、设备放置）。	`model = accelerator.prepare(model)`	单个模型可直接传入。
`optimizers`	`prepare(optimizer)`	包装优化器（兼容 AMP）。	`optimizer = accelerator.prepare(optimizer)`	必须与模型一起或单独准备。
`dataloaders`	`prepare(dataloader)`	包装 DataLoader（插入 DistributedSampler）。	`dl = accelerator.prepare(dl)`	`shuffle` 在原始 DataLoader 中设置。
`lr_schedulers`	`prepare(scheduler)`	包装学习率调度器。	`scheduler = accelerator.prepare(scheduler)`	通常与 optimizer 一起准备。
多参数联合	`prepare(model, optim, dl, sched)`	一次性准备多个组件。	`model, optim, dl = accelerator.prepare(m, o, d)`	推荐写法，简洁高效。
`device_placement`	`prepare(..., device_placement=True)`	是否自动设备放置（默认 True）。	可设为 False 用于自定义放置。	一般保持默认。

6.2 模型、优化器、Dataloader 的统一包装

组件	包装前	包装后行为	注意事项
模型	`nn.Module`	多卡时为 `DistributedDataParallel`，自动放置到 `accelerator.device`。	无需手动 `to(device)` 或 DDP。
优化器	`torch.optim.Optimizer`	与 GradScaler 集成，支持混合精度更新。	必须在模型之后创建并包装。
DataLoader	`torch.utils.data.DataLoader`	插入 DistributedSampler，自动分片数据。	原始 DataLoader 的 `batch_size` 为每卡 batch size。
学习率调度器	`torch.optim.lr_scheduler`	正常调用 `step()`，不受分布式影响。	通常每个 step 或 epoch 调用一次。
包装顺序	模型 → 优化器 → DataLoader → Scheduler	依赖关系需正确。	错误顺序可能导致设备不匹配。

6.3 设备无关的张量操作（`accelerator.device`）

方法/属性	语法	用途	代码示例	注意事项
`accelerator.device`	`device = accelerator.device`	获取当前进程的设备。	`tensor = tensor.to(accelerator.device)`	少数情况需要（如创建新张量）。
设备判断	`if tensor.device == accelerator.device`	检查张量是否在正确设备。	通常由 `prepare()` 保证。
创建新张量	`torch.zeros(10).to(accelerator.device)`	确保新张量在正确设备。	`loss = torch.tensor(0.0).to(accelerator.device)`	避免跨设备操作错误。
跨设备操作	避免 `tensor1 + tensor2` 在不同设备	防止 RuntimeError。	所有张量应由 dataloader 或模型输出自动放置。	Accelerate 减少此类问题。

6.4 数据并行下的数据分片与批处理

概念	说明	注意事项
DistributedSampler	Accelerate 自动为每个 DataLoader 插入该采样器。	确保每个进程加载不同数据子集。
数据分片	一个 epoch 的数据被均匀分给所有进程。	每个进程看到 1/N 的数据（N=进程数）。
批处理	每个进程处理自己的 batch，大小为原始 batch_size。	有效 batch size = batch_size × num_processes。
`drop_last`	sampler 设置 `drop_last=True` 可丢弃不完整 batch。	避免最后 batch 大小不一。
随机打乱（shuffle）	`shuffle=True` 在 DataLoader 中设置，DistributedSampler 会处理。	每个 epoch 打乱方式不同。

第7章训练循环中的关键方法

7.1 梯度累积（`accumulate()`）

方法	语法	用途	代码示例	注意事项
导入	`from accelerate.utils import accumulate`	导入累积上下文。	`from accelerate.utils import accumulate`
`accumulate()` 上下文	`with accumulate(model):`	在累积步数内自动处理 `no_sync`。	`for step, batch in enumerate(dataloader):` `with accumulate(model):` `loss = model(batch).loss` `accelerator.backward(loss)` `optimizer.step()` `optimizer.zero_grad()`	简化梯度累积逻辑，推荐使用。

7.2 梯度裁剪（`clip_grad_norm_` / `clip_grad_value_`）

方法	语法	用途	代码示例	注意事项
`accelerator.clip_grad_norm_`	`accelerator.clip_grad_norm_(model.parameters(), 1.0)`	按范数裁剪梯度。	`accelerator.clip_grad_norm_(model.parameters(), max_norm=1.0)`	替代 `torch.nn.utils.clip_grad_norm_`。
`accelerator.clip_grad_value_`	`accelerator.clip_grad_value_(model.parameters(), 0.1)`	按值裁剪梯度。	`accelerator.clip_grad_value_(model.parameters(), clip_value=0.1)`	较少用，按范数更常见。
调用时机	必须在 `backward` 后、`optimizer.step()` 前调用。		`accelerator.backward(loss)` `accelerator.clip_grad_norm_(model.parameters(), 1.0)` `optimizer.step()`	顺序不能错。

7.3 模型保存与加载（`save_state` / `load_state`）

方法	语法	用途	代码示例	注意事项
`accelerator.save_state()`	`accelerator.save_state("checkpoint_dir")`	保存模型、优化器、随机状态等完整状态。	`accelerator.save_state("ckpt/step_1000")`	主进程保存即可。
`accelerator.load_state()`	`accelerator.load_state("checkpoint_dir")`	从检查点恢复完整训练状态。	`accelerator.load_state("ckpt/step_1000")`	必须在 `prepare` 后调用。
`accelerator.save()`	`accelerator.save(model.state_dict(), "model.bin")`	保存模型权重（需先 `unwrap_model`）。	`unwrapped_model = accelerator.unwrap_model(model)` `accelerator.save(unwrapped_model.state_dict(), "model.pt")`	用于模型部署。

7.4 检查点管理与恢复训练

步骤	操作细节	注意事项
保存检查点	调用 `save_state()` 保存完整状态。	包括模型、优化器、scaler、随机数生成器状态。
恢复训练	在 `prepare` 后调用 `load_state()`。	确保模型、优化器已 `prepare`。
恢复后继续训练	从上次 step/epoch 继续。	训练循环需记录当前 step。
版本兼容性	Accelerate 版本应一致。	不同版本可能导致加载失败。
路径管理	使用唯一目录保存不同检查点。	避免覆盖。

第8章日志与性能监控

8.1 集成日志记录（`accelerator.log`）

方法	语法	用途	代码示例	注意事项
`accelerator.log()`	`accelerator.log({"loss": loss, "step": step}, step=step)`	记录标量日志，仅主进程执行。	`accelerator.log({"loss": loss.item()}, step=step)`	自动集成到 TensorBoard、WandB 等。
支持平台	TensorBoard, Weights & Biases, CometML, MLflow	自动检测并集成。	需安装对应库（如 wandb）。	配置文件可设置跟踪器。

8.2 使用 Progress Bar 显示训练进度

方法	语法	用途	代码示例	注意事项
`accelerator.get_tracker()`	`tracker = accelerator.get_tracker("tensorboard")`	获取底层跟踪器实例。	不常用。
tqdm 集成	`from tqdm.auto import tqdm`	使用自动 tqdm 显示进度。	`progress_bar = tqdm(range(total_steps), disable=not accelerator.is_main_process)`	仅主进程显示进度条。
更新进度条	`progress_bar.update(1)`	每步更新一次。	`progress_bar.set_postfix(loss=loss.item())`	提升用户体验。

8.3 性能指标收集（throughput, memory usage）

指标	收集方法	注意事项
吞吐量（Throughput）	记录每秒处理的样本数：`samples_per_second = batch_size * num_processes / time_per_step`	反映训练效率。
显存使用	`torch.cuda.memory_allocated()`	仅 GPU 有效；多卡需在各卡收集。
训练速度（Steps/sec）	记录每秒完成的训练步数。	可通过日志跟踪。
`accelerator.print()`	仅主进程打印性能信息。

第三部分：高级功能与实战应用

第9章多机多卡训练（Multi-Node Training）

9.1 多节点训练架构概述

概念名称	说明	注意事项
多节点训练（Multi-Node Training）	将训练任务分布到多台物理机器（节点），每台机器拥有多个 GPU，协同完成大规模模型训练。	用于训练超大规模模型（如 LLM），突破单机显存和计算限制。
节点（Node）	一台独立的服务器，通常配备 4 或 8 块 GPU。	节点间通过高速网络（如 InfiniBand）连接。
进程（Process）	每个 GPU 对应一个训练进程，运行模型副本或分片。	总进程数 = 节点数 × 每节点 GPU 数。
主节点（Main Node）	节点 rank 为 0 的机器，负责初始化进程组、保存模型等协调任务。	IP 地址需通过 `--main_process_ip` 指定。
分布式通信	节点间通过 TCP/IP 或 RDMA 进行梯度同步（All-Reduce）、参数广播等操作。	通信带宽是性能瓶颈之一，建议使用 100Gbps+ 网络。
数据并行 + 跨节点	采用跨节点数据并行，各节点处理不同数据分片，梯度在所有节点间同步。	Accelerate 自动处理跨节点通信，用户无感知。

9.2 配置 SSH 与分布式启动参数

步骤名称	操作细节	注意事项
配置 SSH 免密登录	在主节点上生成密钥对，并将公钥复制到所有工作节点的 `~/.ssh/authorized_keys`。	使用 `ssh-keygen` 和 `ssh-copy-id` 命令完成。
验证 SSH 连通性	在主节点执行 `ssh user@node2` 确保无需密码即可登录。	所有节点需开放 SSH 端口（默认 22）。
安装依赖一致	所有节点安装相同版本的 Python、PyTorch、Accelerate 等库。	建议使用容器（如 Docker）或 conda 环境保证一致性。
启动命令参数	使用 `accelerate launch` 并指定多节点参数。	`accelerate launch --num_machines=2 --machine_rank=0 --main_process_ip="192.168.1.10" --main_process_port=29500 --num_processes=8 train.py`
`main_process_ip`	主节点的 IP 地址，其他节点通过此 IP 加入训练。	必须为可路由 IP，不能是 localhost 或 127.0.0.1。
`main_process_port`	主节点监听的端口，用于进程组初始化。	端口需在所有节点上开放（如通过防火墙）。
`num_processes`	每台机器的进程数（即 GPU 数）。	所有机器应具有相同 GPU 数量。

9.3 跨节点通信与同步机制

机制	说明	注意事项
`torch.distributed` 初始化	所有进程调用 `dist.init_process_group(backend="nccl", init_method="env://")` 加入同一组。	Accelerate 自动处理，用户无需手动调用。
NCCL 后端	NVIDIA 的集合通信库，支持跨节点 GPU 间高效通信。	需要 InfiniBand 或 RoCE 网络以获得高性能。
梯度 All-Reduce	使用 `all_reduce` 操作在所有节点的所有 GPU 上同步梯度。	通信量大，建议使用 Ring-AllReduce 算法。
参数广播	初始时主节点将模型参数广播到所有其他节点。	确保所有节点模型初始化一致。
`accelerator.wait_for_everyone()`	阻塞所有进程，直到所有节点都执行到该点。	用于检查点保存、日志输出前的同步。
通信优化	使用混合精度、梯度累积减少通信频率。	也可结合 FSDP 或 DeepSpeed 进一步优化。

9.4 容错与重启支持

机制	说明	注意事项
检查点保存	定期调用 `accelerator.save_state()` 保存完整训练状态。	保存路径需为所有节点可访问的共享存储（如 NFS）。
从检查点恢复	重启训练时调用 `accelerator.load_state(checkpoint_dir)`。	确保模型、优化器已 `prepare`，且配置一致。
进程失败处理	若某节点宕机，整个训练任务中断，需手动重启。	Accelerate 本身不支持自动故障转移。
重启命令	使用与初次启动相同的 `accelerate launch` 命令，但加载检查点。	建议在脚本中添加 `--resume_from_checkpoint` 参数逻辑。
状态一致性	恢复后所有进程必须加载相同检查点，保持状态一致。	共享文件系统是关键。
日志记录	记录训练 step、loss 等信息，便于定位恢复点。	可结合 WandB、TensorBoard 等工具。

第10章 TPU 训练支持

10.1 TPU 环境配置（Google Cloud）

步骤名称	操作细节	注意事项
创建 TPU-VM	使用 Google Cloud Console 或 `gcloud` 命令创建 TPU-VM 实例。	选择 TPU 类型（v2-8, v3-8, v4-8 等）。
安装依赖	在 TPU-VM 上安装 `torch_xla` 和 `accelerate`。	`pip install torch==xla torchvision==xla -f https://storage.googleapis.com/jax-releases/jax_releases.html` `pip install accelerate[all]`
验证 TPU 可见性	运行 `python -c "import torch_xla.core.xla_model as xm; print(xm.get_xla_supported_devices())"`	应输出 `['TPU:0', 'TPU:1', ...]`。
设置环境变量	通常无需设置，`torch_xla` 自动检测 TPU。	可设置 `XRT_TPU_CONFIG="localservice;0;localhost:51011"` 调试。
使用 Colab TPU	在 Google Colab 中选择 TPU 运行时，自动配置环境。	需运行 `!pip install accelerate`。

10.2 使用 xla 后端进行训练

方法/属性	语法	用途	代码示例	注意事项
`distributed_type=TPU`	在 `accelerate config` 中选择 TPU。	启用 XLA 后端。	`accelerate config` 时选择 TPU	配置文件生成 `tpu=True`。
`Accelerator()`	`accelerator = Accelerator()`	自动检测 TPU 并初始化 XLA 设备。	`accelerator = Accelerator()`	无需修改代码。
`accelerator.device`	`device = accelerator.device`	获取 TPU 设备（如 `xla:0`）。	`model.to(accelerator.device)`	`prepare()` 已自动处理。
xla 后端训练	使用 `accelerate launch` 启动。	`accelerate launch --use_tpu=true train.py`	必须使用 `--use_tpu=true`。
编译与执行	XLA 在后台自动编译计算图并执行。	用户代码保持不变。	无需手动 `xm.mark_step()`，Accelerate 自动处理。
数据加载	使用 `pl.MpDeviceLoader` 包装 DataLoader。	由 `accelerator.prepare(dataloader)` 自动完成。	无需手动包装。

10.3 TPU 上的混合精度与性能优化

方法/配置	说明	注意事项
BF16 支持	TPU 原生支持 BF16，无需额外配置。	在 `accelerate config` 中选择 `mixed_precision=bf16`。
自动混合精度	`accelerator.prepare()` 自动启用 BF16 计算。	输出可能为 BF16，但损失通常转为 FP32。
性能优化建议	使用大 batch size，充分利用 TPU 高吞吐。	TPU 擅长高并行计算，小 batch 效率低。
避免频繁主机交互	减少 `print`、`item()` 等操作，防止性能下降。	在主进程中集中日志输出。
使用 `accelerator.gather()`	跨 TPU 核心收集张量。	用于计算全局指标（如准确率）。
检查内存使用	使用 `xm.get_memory_info(accelerator.device)`	监控 TPU 内存占用，避免 OOM。

第11章自定义训练策略与扩展

11.1 自定义 Dispatching 策略

概念	说明	注意事项
Dispatching 策略	Accelerate 内部决定如何分发模型、数据、优化器到设备。	默认策略适用于大多数场景。
自定义分发	目前 Accelerate 不直接暴露 dispatching API。	高级用法需结合 FSDP、DeepSpeed 等。
手动控制	通过 `prepare(..., device_placement=False)` 禁用自动放置，自行管理设备。	`model = model.to("cuda:0")` `accelerator.prepare(model, device_placement=False)`

11.2 手动控制进程行为（`on_main_process` 等装饰器）

装饰器/属性	语法	用途	代码示例	注意事项
`@accelerator.on_main_process`	`@accelerator.on_main_process`	仅在主进程执行函数。	`@accelerator.on_main_process` `def save_model():` `model.save_pretrained("output")`	用于保存、日志等操作。
`is_main_process`	`if accelerator.is_main_process:`	条件判断主进程。	`if accelerator.is_main_process:` `print("Training complete")`	更灵活，适用于简单逻辑。
`is_local_main_process`	`if accelerator.is_local_main_process:`	仅在本地主进程执行（多机时每节点一个）。	用于每节点独立日志记录。
`wait_for_everyone()`	`accelerator.wait_for_everyone()`	同步所有进程。	保存检查点前调用，确保所有进程完成前向传播。	避免 race condition。

11.3 与 PyTorch Lightning / DeepSpeed 的对比与集成

框架	对比说明	集成方式	注意事项
PyTorch Lightning	更高层次的训练框架，内置训练循环、回调、日志等。	Accelerate 更轻量，可嵌入现有训练循环。	可结合使用：在 Lightning 的 `training_step` 中使用 Accelerate 进行低层控制。
DeepSpeed	提供 ZeRO 优化、模型并行、CPU 卸载等高级功能。	Accelerate 可通过 `deepspeed_config_file` 集成 DeepSpeed。	`accelerate config` 时选择 “DeepSpeed” 选项，生成 JSON 配置文件。
FSDP (Fully Sharded Data Parallel)	PyTorch 原生的分片数据并行，减少显存占用。	Accelerate 支持 FSDP，通过配置启用。	在 `accelerate config` 中选择 FSDP 选项。
选择建议	Accelerate 适合需要灵活性和轻量集成的场景；Lightning 适合标准化训练；DeepSpeed/FSDP 适合超大模型。		根据模型规模和硬件选择。

第12章实战项目：从单卡到多机训练迁移

12.1 单卡训练代码重构

步骤	操作细节	注意事项
移除设备管理	删除所有 `.to(device)`、`cuda()` 调用。	由 Accelerate 自动处理。
标准化训练循环	确保使用标准 PyTorch 训练模式（`model.train()`、`optimizer.step()`）。	避免硬编码 batch size、epoch 等。
参数化配置	将学习率、batch size 等设为变量或从命令行读取。	便于不同环境调整。
日志输出控制	使用 `accelerator.is_main_process` 包裹 `print`。	避免多进程重复输出。

12.2 添加 Accelerator 包装

步骤	操作细节	代码示例	注意事项
导入 Accelerator	`from accelerate import Accelerator`
初始化 Accelerator	`accelerator = Accelerator()`		必须在模型创建前初始化。
包装组件	`model, optimizer, train_dataloader = accelerator.prepare(model, optimizer, train_dataloader)`		保持顺序一致。
替换 backward	使用 `accelerator.backward(loss)` 替代 `loss.backward()`。	`accelerator.backward(loss)`
添加同步点	在保存、日志前调用 `accelerator.wait_for_everyone()`。	`accelerator.wait_for_everyone()`	确保状态一致。

12.3 配置分布式训练脚本

步骤	操作细节	注意事项
运行 `accelerate config`	根据目标环境（多机、TPU）配置。	生成 `default_config.yaml`。
使用 `accelerate launch`	启动脚本。	`accelerate launch train.py`
多机参数设置	按 9.2 节配置 SSH 和启动参数。	确保网络和权限正确。
检查点路径	使用共享存储路径（如 NFS、GCS）。	所有节点可读写。
日志集成	启用 WandB/TensorBoard，配置自动记录。	在配置文件中设置跟踪器。

12.4 部署与性能调优

优化项	操作细节	注意事项
混合精度	启用 FP16/BF16 减少显存并加速。	监控 loss 是否稳定。
梯度累积	显存不足时使用，增大有效 batch size。	有效 batch size = batch_size × grad_accum_steps × num_processes。
学习率调整	按有效 batch size 线性缩放学习率。	`lr = base_lr * (effective_batch_size / 256)`
监控吞吐量	记录 steps/sec、samples/sec。	评估训练效率。
分析瓶颈	使用 PyTorch Profiler 或 XLA Profiler（TPU）。	找出计算或通信瓶颈。
模型并行	超大模型可结合 FSDP 或 DeepSpeed。	Accelerate 支持这些后端。

第四部分：附录与工具

附录A：Accelerate CLI 命令详解

命令	语法	用途	示例	注意事项
`accelerate config`	`accelerate config`	交互式生成分布式训练配置文件。	`accelerate config`	首次使用必运行，生成 `~/.cache/huggingface/accelerate/default_config.yaml`。
`accelerate launch`	`accelerate launch [args] script.py`	启动分布式训练脚本。	`accelerate launch train.py`	必须使用此命令，不能直接 `python train.py`。
`--config_file`	`accelerate launch --config_file=my_config.yaml script.py`	指定自定义配置文件。	用于多环境切换（开发/生产）。
`--num_processes`	`accelerate launch --num_processes=4 script.py`	覆盖配置中的进程数。	临时调试用。	应 ≤ 可用 GPU 数。
`--mixed_precision`	`accelerate launch --mixed_precision=fp16 script.py`	覆盖混合精度设置。	支持 no, fp16, bf16。	TPU 仅支持 bf16。
`--use_cpu`	`accelerate launch --use_cpu script.py`	强制在 CPU 上运行（调试）。	`python -m debugpy --listen 5678 --wait-for-client train.py`	用于逻辑验证，性能极低。
`--use_tpu`	`accelerate launch --use_tpu=true script.py`	在 TPU 上启动训练。	需已配置 TPU-VM。	仅 Google Cloud 支持。
`--num_machines`	`accelerate launch --num_machines=2 ...`	指定机器数量（多机训练）。	结合 `--machine_rank`, `--main_process_ip` 使用。	所有机器需安装相同环境。
`--machine_rank`	`accelerate launch --machine_rank=0 ...`	指定当前机器的 rank（0~num_machines-1）。	每台机器设置不同值。
`--main_process_ip`	`accelerate launch --main_process_ip="192.168.1.10" ...`	指定主节点 IP 地址。	必须为可路由 IP。
`--main_process_port`	`accelerate launch --main_process_port=29500 ...`	指定主节点通信端口。	确保端口未被占用且防火墙开放。
`accelerate env`	`accelerate env`	打印当前环境信息（PyTorch、CUDA、Accelerate 版本等）。	`accelerate env`	用于问题排查和提交 issue 时提供信息。
`accelerate test`	`accelerate test`	运行内部测试（开发者使用）。	不推荐用户调用。

附录B：常见错误与调试技巧

错误信息	原因	解决方案	调试技巧
`RuntimeError: Expected all tensors to be on the same device`	张量位于不同设备（如 CPU 和 GPU）。	使用 `tensor.to(accelerator.device)` 统一设备。	打印 `tensor.device` 检查位置。
`CUDA out of memory`	显存不足。	1. 减小 `batch_size` 2. 启用 `gradient_accumulation_steps` 3. 使用 `fp16/bf16` 4. 启用 FSDP 或 DeepSpeed	使用 `nvidia-smi` 监控显存。
`Connection refused` / `Address already in use`	多机训练时主节点 IP/端口错误或被占用。	检查 `--main_process_ip` 和 `--main_process_port` 是否正确，更换端口。	使用 `netstat -an \| grep 29500` 检查端口占用。
`SSH connection failed`	SSH 免密登录未配置或网络不通。	配置 `ssh-keygen` 和 `ssh-copy-id`，测试 `ssh user@node2`。	确保 sshd 服务运行且防火墙开放。
`ValueError: Invalid device`	设备名错误（如 `cuda:0` 不存在）。	检查 GPU 是否可见（`nvidia-smi`），确认 `CUDA_VISIBLE_DEVICES` 设置。	使用 `torch.cuda.is_available()` 验证。
`accelerator.backward()` fails with scale error	FP16 梯度缩放失败（loss 为 NaN/inf）。	1. 检查数据是否包含 NaN 2. 降低学习率 3. 使用 `clip_grad_norm_`	在 `backward` 前打印 loss 值。
`DistributedDataParallel not set up`	未使用 `accelerate launch` 启动。	必须使用 `accelerate launch` 命令。	检查启动方式。
`File not found on load_state`	检查点路径错误或文件不存在。	确认路径为共享存储，所有节点可访问。	使用绝对路径，检查 NFS 挂载。
`TPU not found`	TPU-VM 未正确配置或 `torch_xla` 未安装。	运行 `import torch_xla.core.xla_model as xm; print(xm.get_xla_supported_devices())` 验证。	重新安装匹配版本的 `torch_xla`。
多进程重复日志输出	未使用 `accelerator.is_main_process` 控制输出。	将 `print`、`logging` 等包装在 `if accelerator.is_main_process:` 中。	使用 `accelerator.print()`（自动处理）。

附录C：配置文件参数完整说明

配置文件路径： ~/.cache/huggingface/accelerate/default_config.yaml

参数	类型	可选值	说明	示例
`compute_environment`	str	`LOCAL_MACHINE`, `AWS_EC2`, `GOOGLE_CLOUD`	计算环境类型。	`LOCAL_MACHINE`
`distributed_type`	str	`NO`, `MULTI_GPU`, `MULTI_CPU`, `TPU`, `DEEPSPEED`, `FSDP`	分布式训练类型。	`MULTI_GPU`
`num_processes`	int	正整数	总进程数（GPU 或 TPU 核心数）。	`8`
`machine_rank`	int	0 ~ num_machines-1	当前机器的 rank（多机时使用）。	`0`
`num_machines`	int	正整数	总机器数（多机训练）。	`2`
`main_process_ip`	str	IP 地址	主节点 IP 地址（多机时使用）。	`"192.168.1.10"`
`main_process_port`	int	1024 ~ 65535	主节点通信端口。	`29500`
`main_training_function`	str	函数名	主训练函数名（用于 launch 调用）。	`"main"`
`fp16`	bool	true, false	⚠️ 已弃用，使用 `mixed_precision`。	`false`
`bf16`	bool	true, false	⚠️ 已弃用，使用 `mixed_precision`。	`false`
`mixed_precision`	str	`no`, `fp16`, `bf16`	混合精度模式。	`fp16`
`tpu_num_cores`	int	1, 8	TPU 核心数（v2/v3-8, v4-8）。	`8`
`tpu_use_cluster`	bool	true, false	是否使用 TPU 集群。	`false`
`tpu_use_sudo`	bool	true, false	TPU 安装是否使用 sudo。	`false`
`deepspeed_config_file`	str	文件路径	DeepSpeed 配置文件路径。	`"ds_config.json"`
`deepspeed_zero_stage`	int	0, 1, 2, 3	ZeRO 优化阶段（0=禁用，3=最大分片）。	`2`
`deepspeed_offload_optimizer`	bool	true, false	是否将优化器状态卸载到 CPU。	`true`
`deepspeed_offload_param`	bool	true, false	是否将模型参数卸载到 CPU。	`true`
`deepspeed_gradient_accumulation_steps`	int	正整数	DeepSpeed 内部梯度累积步数。	`1`
`fsdp_config`	dict	-	FSDP 配置字典。	`{ "fsdp_min_num_params": 1e8, "fsdp_sharding_strategy": "FULL_SHARD" }`
`gradient_accumulation_steps`	int	正整数	梯度累积步数。	`4`
`use_cpu`	bool	true, false	强制使用 CPU。	`false`
`debug`	bool	true, false	启用调试模式。	`false`

注意： fp16 和 bf16 已弃用，请使用 mixed_precision。

附录D：API 参考速查表

类/方法	语法	用途	示例	注意事项
`Accelerator`	`Accelerator(mixed_precision="fp16", gradient_accumulation_steps=4)`	初始化加速器，加载配置。	`accelerator = Accelerator()`	必须在模型创建前初始化。
`prepare()`	`model, optim, dl = accelerator.prepare(model, optim, dl)`	包装模型、优化器、数据加载器，启用分布式、混合精度等。	`model, optimizer, dataloader = accelerator.prepare(model, optimizer, dataloader)`	顺序：模型 → 优化器 → 数据加载器。
`backward()`	`accelerator.backward(loss)`	兼容混合精度的反向传播（自动处理梯度缩放）。	`accelerator.backward(loss)`	替代 `loss.backward()`。
`clip_grad_norm_()`	`accelerator.clip_grad_norm_(model.parameters(), 1.0)`	梯度范数裁剪。	`accelerator.clip_grad_norm_(model.parameters(), max_norm=1.0)`	在 `backward` 后，`step` 前调用。
`clip_grad_value_()`	`accelerator.clip_grad_value_(model.parameters(), 0.1)`	梯度值裁剪。	`accelerator.clip_grad_value_(model.parameters(), clip_value=0.1)`	较少使用。
`gather()`	`gathered_tensor = accelerator.gather(tensor)`	跨进程收集张量（用于计算全局指标）。	`losses = accelerator.gather(losses)`	返回张量在主进程上拼接。
`reduce()`	`reduced = accelerator.reduce(tensor, reduction="sum")`	跨进程归约操作（sum, mean 等）。	`total_loss = accelerator.reduce(loss, "mean")`	用于聚合统计量。
`print()`	`accelerator.print("Hello")`	仅在主进程打印。	`accelerator.print(f"Step {step}")`	替代 `print()` 避免重复输出。
`log()`	`accelerator.log({"loss": loss}, step=step)`	记录日志到 TensorBoard、WandB 等。	`accelerator.log({"loss": loss.item()}, step=step)`	自动判断跟踪器类型。
`save_state()`	`accelerator.save_state("ckpt/step_1000")`	保存完整训练状态（模型、优化器、scaler 等）。	`accelerator.save_state(checkpoint_dir)`	主进程保存。
`load_state()`	`accelerator.load_state("ckpt/step_1000")`	从检查点恢复完整训练状态。	`accelerator.load_state(checkpoint_dir)`	必须在 `prepare` 后调用。
`save()`	`accelerator.save(model.state_dict(), "model.pt")`	保存模型权重（需先 `unwrap_model`）。	`unwrapped_model = accelerator.unwrap_model(model)` `accelerator.save(unwrapped_model.state_dict(), "model.pt")`	用于模型部署。
`unwrap_model()`	`model = accelerator.unwrap_model(model_wrapped)`	移除 DistributedDataParallel 等包装。	`model = accelerator.unwrap_model(model)`	用于保存或推理。
`wait_for_everyone()`	`accelerator.wait_for_everyone()`	阻塞所有进程，直到全部到达该点。	`accelerator.wait_for_everyone()`	用于同步保存、日志等。
`autocast()`	`with accelerator.autocast():` `outputs = model(inputs)`	手动控制混合精度上下文。	通常不需要，forward 已自动处理。
`no_sync()`	`with accelerator.no_sync(model):` `loss = model(batch).loss`	在梯度累积时禁用梯度同步。	用于实现高效 accumulate。
`is_main_process`	`if accelerator.is_main_process:`	判断是否为主进程。	用于保存、日志等。
`device`	`device = accelerator.device`	获取当前设备。	`model.to(accelerator.device)`	`prepare()` 已自动处理。

加速训练 Accelerate 速查文档

第一部分：入门基础

第1章 Accelerate 简介与核心理念

1.1 什么是 Accelerate

1.2 Accelerate 解决的核心问题

1.3 分布式训练的基本概念

1.4 Accelerate 的抽象层次与优势

第2章 安装与环境配置

2.1 安装 Accelerate 库

2.2 初始化配置：accelerate config

2.3 配置文件详解（YAML 格式）

2.4 多GPU/TPU/混合精度环境准备

第3章 快速上手：单机训练加速

3.1 使用 Accelerator 类包装训练流程

3.2 自动设备管理（device placement）

3.3 混合精度训练启用（AMP）

3.4 模型、优化器、数据加载器的包装

第二部分：核心功能详解

第4章 分布式训练基础

4.1 数据并行（Data Parallelism）原理

4.2 启动多进程训练：accelerate launch

4.3 进程组初始化与 rank 管理

4.4 梯度同步与模型参数一致性

第5章 混合精度训练

5.1 FP16 与 BF16 精度介绍

5.2 使用 prepare() 自动启用混合精度

5.3 混合精度上下文管理（autocast）

5.4 梯度缩放（Gradient Scaling）机制

第6章 模型与数据的设备管理

6.1 accelerator.prepare() 方法详解

6.2 模型、优化器、Dataloader 的统一包装

6.3 设备无关的张量操作（accelerator.device）

6.4 数据并行下的数据分片与批处理

第7章 训练循环中的关键方法

7.1 梯度累积（accumulate()）

7.2 梯度裁剪（clip_grad_norm_ / clip_grad_value_）

7.3 模型保存与加载（save_state / load_state）

7.4 检查点管理与恢复训练

第8章 日志与性能监控

8.1 集成日志记录（accelerator.log）

8.2 使用 Progress Bar 显示训练进度

8.3 性能指标收集（throughput, memory usage）

第三部分：高级功能与实战应用

第9章 多机多卡训练（Multi-Node Training）

9.1 多节点训练架构概述

9.2 配置 SSH 与分布式启动参数

9.3 跨节点通信与同步机制

9.4 容错与重启支持

第10章 TPU 训练支持

10.1 TPU 环境配置（Google Cloud）

10.2 使用 xla 后端进行训练

10.3 TPU 上的混合精度与性能优化

第11章 自定义训练策略与扩展

11.1 自定义 Dispatching 策略

11.2 手动控制进程行为（on_main_process 等装饰器）

11.3 与 PyTorch Lightning / DeepSpeed 的对比与集成

第12章 实战项目：从单卡到多机训练迁移

12.1 单卡训练代码重构

12.2 添加 Accelerator 包装

12.3 配置分布式训练脚本

12.4 部署与性能调优

第四部分：附录与工具

附录A：Accelerate CLI 命令详解

附录B：常见错误与调试技巧

附录C：配置文件参数完整说明

附录D：API 参考速查表

第2章安装与环境配置

第3章快速上手：单机训练加速

第4章分布式训练基础

第5章混合精度训练

第6章模型与数据的设备管理

6.1 `accelerator.prepare()` 方法详解

6.3 设备无关的张量操作（`accelerator.device`）

第7章训练循环中的关键方法

7.1 梯度累积（`accumulate()`）

7.2 梯度裁剪（`clip_grad_norm_` / `clip_grad_value_`）

7.3 模型保存与加载（`save_state` / `load_state`）

第8章日志与性能监控

8.1 集成日志记录（`accelerator.log`）

第9章多机多卡训练（Multi-Node Training）

第11章自定义训练策略与扩展

11.2 手动控制进程行为（`on_main_process` 等装饰器）

第12章实战项目：从单卡到多机训练迁移