Accelerate 命令行完全指南从 accelerate config 到 accelerate launch 的分布式训练实战手册【免费下载链接】accelerate 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项目地址: https://gitcode.com/gh_mirrors/ac/accelerate导读 Accelerate 的核心交互入口是它提供的一套命令行工具CLI。本文以 docs/source/package_reference/cli.md 为骨架系统梳理accelerate config、accelerate launch、accelerate env、accelerate estimate-memory、accelerate tpu-config、accelerate test等全部命令的用途、参数语义与典型用法并结合仓库源码CLI 入口、launch 实现、配置数据类剖析其底层工作方式。读完本文你将能够独立完成「机器初始化配置 → 编写可分布式运行脚本 → 以多 GPU / DeepSpeed / FSDP / TPU 等方式启动 → 诊断环境 → 评估显存」的完整工作流。一、命令行体系总览所有 Accelerate 命令都注册在统一的入口脚本 accelerate_cli.py 中。从源码看main()使用CustomArgumentParser构建了名为Accelerate CLI tool的顶层解析器并注册了 8 个子命令get_config_parser(subparserssubparsers) # config / config default / config update estimate_command_parser(subparserssubparsers) # estimate-memory env_command_parser(subparserssubparsers) # env launch_command_parser(subparserssubparsers) # launch merge_command_parser(subparserssubparsers) # merge tpu_command_parser(subparserssubparsers) # tpu-config test_command_parser(subparserssubparsers) # test to_fsdp2_command_parser(subparserssubparsers) # to-fsdp2因此每个命令都有两种等价调用方式accelerate command与accelerate-command如accelerate config与accelerate-config部分命令还支持python -m accelerate.commands.module形式。若直接输入accelerate不带子命令解析器会打印帮助信息并退出。命令别名 / 等价写法职责accelerate configaccelerate-config交互式生成配置文件default_config.yamlaccelerate config defaultaccelerate-config default用少量参数快速生成默认配置accelerate config updateaccelerate-config update将旧配置升级为最新格式accelerate envaccelerate-env/python -m accelerate.commands.env列出运行环境与配置内容accelerate launchaccelerate-launch/python -m accelerate.commands.launch以正确的分布式参数启动训练脚本accelerate estimate-memoryaccelerate-estimate-memory/python -m accelerate.commands.estimate估算模型推理 / 训练所需显存accelerate tpu-config—在 TPU pod 上批量执行命令与安装配置accelerate testaccelerate-test验证 Accelerate 安装与配置是否正确二、accelerate config初始化你的训练系统命令accelerate config或accelerate-configaccelerate config会启动一系列交互式问答prompt根据你的回答创建并保存一份default_config.yaml配置文件。官方文档强调该命令应在每台机器上最先执行因为后续accelerate launch会从这份配置中读取默认启动参数。配置文件默认存储位置从 config_args.py 的源码可以看到精确的路径推导逻辑hf_cache_home os.path.expanduser( os.environ.get(HF_HOME, os.path.join(os.environ.get(XDG_CACHE_HOME, ~/.cache), huggingface)) ) cache_dir os.path.join(hf_cache_home, accelerate) default_yaml_config_file os.path.join(cache_dir, default_config.yaml)即优先取环境变量HF_HOME若未设置则取XDG_CACHE_HOME仍未设置则用~/.cache下的huggingface目录最后拼接accelerate/default_config.yaml。源码中还做了向后兼容处理旧版本曾使用 JSON 格式若 YAML 文件不存在而 JSON 文件存在则默认读取 JSON 版本。可选参数--config_file CONFIG_FILEstr— 指定配置文件存储路径。缺省时使用上述默认缓存路径下的default_config.yaml。-h、--helpbool— 显示帮助信息并退出。从源码看配置的解析与校验配置文件的读写由 config_args.py 中的BaseConfig、ClusterConfig本地 / 集群环境与SageMakerConfigSageMaker 环境三个 dataclass 负责。load_config_from_file会先读取文件头部的compute_environment字段判断环境类型再选择对应的配置类进行反序列化process_config则为缺失字段补齐默认值例如未指定distributed_type时直接抛出ValueError必须显式声明分布式类型NO分布式时num_processes默认为1旧的fp16布尔字段会自动迁移为mixed_precision: fp16旧的dynamo_backend字段会被迁移为dynamo_config字典文件中出现未知键时会报错提示升级accelerate版本。这正是accelerate config update存在的意义Accelerate 的配置 schema 会随版本演进旧配置文件通过 update 命令即可无损迁移到最新格式保持原有配置项仅补齐新增的默认字段。子命令 1accelerate config default命令accelerate config default或accelerate-config default以最少参数快速生成默认配置文件适合脚本化初始化的场景。在 config/init.py 中default与update均注册为config的子命令。可选参数--config_file CONFIG_FILEstr— 配置文件存储路径默认同上。-h、--helpbool— 显示帮助并退出。--mixed_precision {no,fp16,bf16}str— 是否启用混合精度训练。可选no不启用、fp16、bf16bfloat16。注意BF16 训练仅支持 NVIDIA Ampere 架构 GPU 且要求 PyTorch 1.10 或更高版本这是硬件与框架层面的硬性约束仓库源码中通过is_bf16_available()等工具函数进行能力探测。子命令 2accelerate config update命令accelerate config update或accelerate-config update将已有配置文件升级为当前版本的最新默认格式同时保留旧配置内容。唯一的可选参数为--config_file指定待升级的配置文件路径缺省用默认缓存路径与-h/--help。升级过程复用 config_args.py 中的process_config逻辑自动补齐缺失字段并完成旧字段迁移。三、accelerate env一键导出完整环境诊断信息命令accelerate env或accelerate-env或python -m accelerate.commands.envaccelerate env会打印当前机器上所有与 Accelerate 相关的运行环境信息以及已加载的配置文件内容。官方建议在向项目仓库提交 issue 时应先运行本命令并附上输出因为它几乎覆盖了定位分布式问题所需的全部信息。从 env.py 的源码实现可以看到它收集的信息包括torch.__version__PyTorch 版本torch.cuda.is_available()CUDA 是否可用各类加速硬件的可用性探测XPU、MLU、SDAA、MUSA、NPU、Neuron、MPS根据探测结果确定当前使用的加速器类型CUDA / XPU / MLU / SDAA / MUSA / NPU 等以及--config_file指定的或默认的Accelerate 配置文件内容。可选参数--config_file CONFIG_FILEstr— 指定要展示的配置文件路径缺省为默认缓存路径下的default_config.yaml。-h、--helpbool— 显示帮助并退出。典型用法在运行任何分布式训练之前执行accelerate env确认 PyTorch 版本、CUDA 可用性、加速器类型与配置文件一致可避免大量「环境不匹配」类问题。四、accelerate launch分布式启动的核心命令命令accelerate launch或accelerate-launch或python -m accelerate.commands.launchaccelerate launch负责以正确的分布式参数在集群上启动训练脚本是整套 CLI 中参数最丰富、使用最频繁的命令。Usageaccelerate launch [arguments] {training_script} --{training_script-argument-1} --{training_script-argument-2} ...位置参数{training_script}— 需要并行启动的脚本完整路径--{training_script-argument-*}— 传给训练脚本自身的参数原样透传。基础可选参数参数类型说明-h,--helpbool显示帮助并退出--config_file CONFIG_FILEstr指定为 launch 提供默认值的配置文件-m,--modulebool让每个进程把启动脚本当作 Python 模块执行等价于python -m语义--no_pythonbool不在脚本前拼接python直接执行脚本本身适用于非 Python 脚本--debugbool失败时打印torch.distributed的完整堆栈信息-q,--quietbool静默子进程错误仅显示相关 traceback仅适用于 DeepSpeed 与单进程配置其余参数通常通过accelerate config写入配置文件accelerate launch从--config_file或默认配置读取这些默认值所有参数也都可以在命令行手动覆盖。一个值得注意的源码细节动态参数组launch.py 中定义了一个CustomHelpFormatter它会在--help时根据命令行实际传入的启动模式如--use_deepspeed、--use_fsdp、--multi_gpu、--tpu等动态隐藏与本平台无关的参数组只展示当前模式相关的参数极大降低了--help的信息噪音。硬件选择参数Hardware Selection参数类型说明--cpubool强制在 CPU 上训练--multi_gpubool启动多 GPU 分布式训练--tpubool启动 TPU 训练资源选择参数Resource Selection参数类型说明--mixed_precision {no,fp16,bf16,fp8}str混合精度策略。fp16/bf16BF16 需 Ampere GPU 且 PyTorch≥1.10fp8为 8 位浮点训练需配合下方 FP8 参数指定后端--num_processes NUM_PROCESSESint并行启动的进程总数--num_machines NUM_MACHINESint参与训练的总机器数--num_cpu_threads_per_process NUM_CPU_THREADS_PER_PROCESSint每个进程占用的 CPU 线程数可调优以获得最佳性能--enable_cpu_affinitybool是否启用 CPU 亲和性与负载均衡当前仅支持 NVIDIA 硬件此外launch还支持--dynamo_backend、--dynamo_mode、--dynamo_use_fullgraph、--dynamo_use_dynamic、--dynamo_use_regional_compilation等 torch.compile / Dynamo 相关参数见 launch.py便于直接通过 CLI 开启编译优化。训练范式选择参数Training Paradigm参数类型说明--use_deepspeedbool使用 DeepSpeed 训练--use_fsdpbool使用 FullyShardedDataParallelFSDP训练--use_megatron_lmbool使用 Megatron-LM 训练--use_parallelism_configbool使用 N 维并行配置源码 launch.py 中新增配合并行度配置文件使用多 GPU 分布式参数Distributed GPU以下参数仅在传入--multi_gpu或通过accelerate config配置了多 GPU 训练时生效参数类型说明--gpu_idsstr本机用于训练的 GPU id逗号分隔列表--same_networkbool多机训练的所有机器是否位于同一局域网--machine_rankint当前启动脚本所在机器的 rank--main_process_ipstrrank 0 机器的 IP 地址--main_process_portint与 rank 0 机器通信的端口-t,--teestr将标准流同时写入日志文件并输出到控制台--log_dirstr使用 torchrun /torch.distributed.run启动器时的日志基础目录与--tee配合将标准流重定向到日志文件--rolestr为 worker 定义的用户角色默认default--rdzv_backendstrrendezvous 方式如static默认或c10d--rdzv_confstr附加 rendezvous 配置格式key1value1,key2value2,...--max_restartsintworker 组在失败前的最大重启次数默认0--monitor_intervalint监控 worker 状态的间隔秒数从源码看多 GPU 模式最终走multi_gpu_launcher()launch.py它借助torch.distributed.runtorchrun完成进程拉起并会针对 RTX 4000 系列等不支持 P2P/IB 加速的硬件自动设置NCCL_P2P_DISABLE1与NCCL_IB_DISABLE1以避免通信异常。TPU 参数以下参数仅在传入--tpu或配置了 TPU 训练时生效参数类型说明--tpu_clusterbool是否使用 GCP TPU pod 训练--tpu_use_sudobool在每个 pod 中执行 TPU 训练脚本时是否使用sudo--vmstr单个 Compute VM 实例名列表未提供时假定使用实例组TPU pod 场景--envstr要在 Compute VM 实例上设置的环境变量列表TPU pod 场景--main_training_functionstr脚本中要执行的主函数名仅 TPU 训练--downcast_bf16boolTPU 上使用 bf16 时float 与 double 张量是否都转为 bfloat16否则 double 张量保持 float32从 launch.py 的tpu_launcher()看TPU 启动依赖torch_xla.distributed.xla_multiprocessingxmp通过 import 训练脚本模块并调用指定的main_training_function来运行若脚本中没有该函数会直接报错提示通过--main_training_function指定。DeepSpeed 参数以下参数仅在传入--use_deepspeed或通过配置启用了 DeepSpeed 时生效。源码中这些参数均标注了「未指定时的默认值」下文一并列出参数类型默认值说明--deepspeed_config_filestr—DeepSpeed 配置文件路径--zero_stageint2DeepSpeed ZeRO 优化阶段--offload_optimizer_devicestrnone优化器状态卸载位置none/cpu/nvme--offload_param_devicestrnone参数卸载位置none/cpu/nvme--offload_optimizer_nvme_pathstrnone优化器状态卸载到的 NVMe 路径--gradient_accumulation_stepsint1训练脚本中使用的梯度累积步数--gradient_clippingfloat1.0训练脚本中使用的梯度裁剪值--zero3_init_flagstrtrue是否启用deepspeed.zero.Init构建超大模型仅 ZeRO Stage-3 适用--zero3_save_16bit_modelstrfalseZeRO Stage-3 下是否保存 16 位模型权重--deepspeed_hostfilestr—多节点计算的 DeepSpeed hostfile--deepspeed_exclusion_filterstr—多节点时的排除过滤器字符串--deepspeed_inclusion_filterstr—多节点时的包含过滤器字符串--deepspeed_multinode_launcherstrpdsh多节点启动器如pdsh、standard、openmpi、mvapich、mpich、slurm、nosshnossh需 DeepSpeed ≥ 0.14.5--deepspeed_moe_layer_cls_namesstr—要包装的 Transformer MoE 层类名大小写敏感逗号分隔如MixtralSparseMoeBlock、Qwen2MoeSparseMoeBlock、JetMoEAttention,JetMoEBlockDeepSpeed 模式下走deepspeed_launcher()launch.py它要求本机已安装 DeepSpeed否则提示pip3 install deepspeed单节点时同样通过torch.distributed.run拉起进程多节点时则直接以子进程方式执行 DeepSpeed 启动命令并将必要的环境变量写入DEEPSPEED_ENVIRONMENT_NAME文件。仓库中提供了现成的 DeepSpeed 配置模板可参考examples/deepspeed_config_templatesZeRO Stage 1/2/3 及 offload 变体与 examples/config_yaml_templates/deepspeed.yaml。FSDP 参数以下参数仅在传入--use_fsdp或配置了 FSDP 时生效参数类型默认值说明--fsdp_offload_paramsstrfalse是否将参数与梯度卸载到 CPUtrue/false--fsdp_min_num_paramsint1e8FSDP Default Auto Wrapping 的最小参数数量阈值--fsdp_sharding_strategyint/strFULL_SHARDFSDP 分片策略--fsdp_auto_wrap_policystr—FSDP 自动包装策略--fsdp_transformer_layer_cls_to_wrapstr—要包装的 Transformer 层类名大小写敏感如BertLayer、GPTJBlock、T5Block--fsdp_backward_prefetch_policystr—FSDP 反向预取策略--fsdp_state_dict_typestr—FSDP state dict 类型--fsdp_forward_prefetchstr—是否启用前向预取--fsdp_use_orig_paramsstr—为True时允许 FSDP 单元内混用非均匀requires_grad--fsdp_cpu_ram_efficient_loadingstr—为true时仅第一个进程加载预训练权重其余进程使用空权重使用本项时--fsdp_sync_module_states必须为True--fsdp_sync_module_statesstr—为true时每个单独包装的 FSDP 单元从 rank 0 广播模块参数--fsdp_activation_checkpointingbool—前向过程中是否释放中间激活、仅保留 checkpoint 占位符此外源码launch.py还提供--fsdp_version {1,2}FSDP1 与 FSDP2 选择默认1与--fsdp_reshard_after_forward等进阶参数。仓库中的 examples/config_yaml_templates/fsdp.yaml 提供了完整可用的 FSDP 配置模板。Megatron-LM 参数以下参数仅在传入--use_megatron_lm或配置了 Megatron-LM 时生效参数说明--megatron_lm_tp_degreeMegatron-LM 的张量并行TP度--megatron_lm_pp_degreeMegatron-LM 的流水线并行PP度--megatron_lm_num_micro_batchesPP 度大于 1 时的微批次数量--megatron_lm_sequence_parallelismTP 度大于 1 时是否启用序列并行true/false--megatron_lm_recompute_activations是否启用选择性激活重计算true/false--megatron_lm_use_distributed_optimizer是否使用分布式优化器在数据并行 rank 间分片优化器状态与梯度true/false--megatron_lm_gradient_clipping基于全局 L2 范数的梯度裁剪值0表示禁用仓库中的 examples/by_feature/megatron_lm_gpt_pretraining.py 演示了 Megatron-LM 与 Accelerate 的集成用法。FP8 参数以下参数用于 FP8 训练参数类型说明--fp8_backendstr选择 FP8 训练后端teTransformer Engine或msampMS-AMP--fp8_use_autocast_during_evalbool评估阶段是否使用 FP8 autocast仅--fp8_backendte时有效通常不传此参数可获得更好的指标--fp8_marginint梯度缩放使用的 margin仅te后端--fp8_intervalint缩放因子重计算的间隔仅te后端--fp8_formatstrFP8 recipe 使用的格式仅te后端--fp8_amax_history_lenint缩放因子计算使用的历史长度仅te后端--fp8_amax_compute_algostr缩放因子计算算法仅te后端--fp8_override_linear_precisionTuple[bool, bool, bool]是否以更高精度执行fprop、dgrad、wgradGEMM--fp8_opt_levelstrMS-AMP 使用的 8 位集合通信级别仅msamp后端仓库中的 examples/config_yaml_templates/fp8.yaml 提供了 FP8 配置模板benchmarks/fp8 目录下则分别给出了torchao、transformer_engine、ms_amp三个后端的完整对比基准实现。AWS SageMaker 参数以下参数仅在 SageMaker 环境训练时使用参数类型说明--aws_access_key_idstr用于启动 SageMaker 训练任务的 AWS_ACCESS_KEY_ID--aws_secret_access_keystr用于启动 SageMaker 训练任务的 AWS_SECRET_ACCESS_KEYlaunch 的启动器分发逻辑从 launch.py 的launch_command()可以看出整个启动流程的决策树if args.use_deepspeed and not args.cpu: deepspeed_launcher(args) elif args.use_fsdp and not args.cpu: multi_gpu_launcher(args) elif args.use_megatron_lm and not args.cpu: multi_gpu_launcher(args) elif args.multi_gpu and not args.cpu: multi_gpu_launcher(args) elif args.tpu and not args.cpu: tpu_pod_launcher(args) if args.tpu_use_cluster else tpu_launcher(args) elif defaults is not None and defaults.compute_environment ComputeEnvironment.AMAZON_SAGEMAKER: sagemaker_launcher(defaults, args) else: simple_launcher(args)也就是说DeepSpeed、FSDP、Megatron-LM、普通多 GPU、TPU、SageMaker、单进程simple各有独立的启动路径CPU 模式会优先兜底到simple_launcher。启动前还会调用_validate_launch_command对命令行参数与配置文件进行一致性校验。五、accelerate estimate-memory估算模型显存占用命令accelerate estimate-memory或accelerate-estimate-memory或python -m accelerate.commands.estimate该命令估算托管在 Hugging Face Hub 上的模型加载推理所需的显存总量并附带训练态估算。前置条件需要安装huggingface_hub若估算transformers/timm模型还需对应安装这两个库。官方提示进行推理时建议在估算结果基础上额外预留约 ≤20% 的整体分配量可参考 transformer 参数计数经验公式更精细的自动估算能力正在规划中。Usageaccelerate estimate-memory {MODEL_NAME} --library_name {LIBRARY_NAME} --dtypes {dtype_1} {dtype_2} ...参数说明参数类型说明MODEL_NAMEstr必填Hugging Face Hub 上的模型名称--library_name {timm,transformers}str模型所属集成库仅当 Hub 上未存储该信息时需要显式指定--dtypes {float32,float16,int8,int4} [...]str列表要估算的 dtype可同时传多个默认四者都算--trust_remote_codebool是否允许执行 Hub 上自定义模型文件中的代码仅在信任且已阅读过代码的仓库上使用底层原理从 estimate.py 的源码可以看到其估算思路通过huggingface_hub.model_info校验模型仓库是否存在、是否 gated随后借助accelerate.init_empty_weights()在meta device上创建一个全精度空模型不实际加载权重再根据 dtype 与参数量计算内存占用。这也解释了为什么它能快速估算超大模型——整个过程不消耗真实显存/内存。transformers模型通过AutoConfig/AutoModel构建并优先选择auto_map中指定的AutoModelFor*构造函数timm模型则通过timm.create_model(..., pretrainedFalse)创建。仓库中还有配套的 Web 演示逻辑与 examples/by_feature/memory.py 示例。六、accelerate tpu-config批量配置 TPU pod命令accelerate tpu-config用于在 TPU pod 集群上批量执行命令与安装配置便于统一初始化多台 TPU 虚拟机。Usageaccelerate tpu-config [arguments]参数说明Config Arguments可通过accelerate config配置的项参数类型说明--config_filestrAccelerate 配置文件路径--tpu_namestr要使用的 TPU 名称未指定时使用配置文件中的 TPU--tpu_zonestrTPU 所在 zone未指定时使用配置文件中的 zoneTPU Arguments在 TPU 内部执行的选项参数类型说明--command_filestr包含 pod 启动时要执行命令的文件路径--commandstr要在 pod 上执行的单条命令可重复传入多次--install_acceleratebool是否在 pod 上安装 accelerate默认False--accelerate_versionstr要安装的 accelerate 版本未指定时使用最新 PyPI 版本传dev表示从源码安装开发版--debugbool仅打印将要执行的命令而不实际执行-h,--helpbool显示帮助并退出对应的 CLI 解析与执行逻辑见 tpu.py。七、accelerate test验证安装与配置是否就绪命令accelerate test或accelerate-test运行accelerate/test_utils/scripts/test_script.py验证 Accelerate 是否正确安装并能在当前系统上正常运行。若全部通过会输出Test is a success! You are ready for your distributed training!。Usageaccelerate test [arguments]可选参数--config_file CONFIG_FILEstr— 测试时使用的配置文件路径缺省为默认缓存路径下的default_config.yaml。-h、--helpbool— 显示帮助并退出。从 test.py 的实现看test命令本质上是用accelerate-launch以测试脚本为训练脚本再跑一次完整启动流程cmd [accelerate-launch] test_args result execute_subprocess_async(cmd)因此它验证的不只是安装本身而是整套「配置 → 启动 → 多进程协作」链路是否通畅。测试脚本位于 src/accelerate/test_utils/scripts/test_script.py仓库的测试套件如 tests/test_cli.py中还有大量围绕 CLI 参数解析与启动行为的回归测试tests/test_configs 目录保存了多个历史版本的配置文件用于验证config update的向后兼容能力。八、实战串联一个完整的配置-启动工作流综合以上命令一次典型的 Accelerate 分布式训练之旅如下初始化配置首次在机器上执行accelerate config按提示选择硬件单机多卡 / 多机多卡 / TPU / CPU 等、是否使用 DeepSpeed / FSDP、混合精度策略生成default_config.yaml。也可以直接套用仓库现成模板单机多卡可参考 examples/config_yaml_templates/multi_gpu.yaml多节点可参考 examples/config_yaml_templates/multi_node.yaml并通过--config_file指定。验证环境accelerate env估算显存上线前评估模型是否放得下accelerate estimate-memory gpt2 --library_name transformers --dtypes float16 int8启动训练以 DeepSpeed ZeRO Stage-2 为例accelerate launch --use_deepspeed --zero_stage 2 \ --gradient_accumulation_steps 8 \ --mixed_precision bf16 \ examples/by_feature/nlp_example.py --max_train_steps 1000验证安装换新机器 / 升级版本后accelerate test结语Accelerate 的 CLI 设计遵循「配置文件驱动 命令行可覆盖」的原则accelerate config负责把繁琐的分布式参数沉淀为机器级配置accelerate launch依据配置选择最合适的启动器torchrun / DeepSpeed / xla / SageMaker并透传参数accelerate env与accelerate test则分别承担诊断与自检职责。结合仓库源码accelerate_cli.py、launch.py、config_args.py阅读本文你可以对每个参数的作用范围与底层行为有更精确的把握从而在几乎任何设备与分布式配置下稳定地启动 PyTorch 训练任务。【免费下载链接】accelerate 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项目地址: https://gitcode.com/gh_mirrors/ac/accelerate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考