训练中断怎么办？ms-swift断点续训机制使用说明-开发者社区

训练中断怎么办？ms-swift断点续训机制使用说明

在大模型微调实践中，训练过程动辄持续数小时甚至数天，却常因显存溢出、网络波动、集群调度抢占、意外断电或人为误操作而突然中止。此时若从头开始重训，不仅浪费大量计算资源和时间成本，更可能因随机种子、数据加载顺序等不可复现因素导致结果偏差。如何让训练“断而不断”，成为工程落地的关键能力。

ms-swift 框架原生内置的断点续训（Checkpoint Resumption）机制，正是为此而生——它不是简单的权重保存，而是一套覆盖训练状态、优化器参数、学习率调度、数据迭代位置、随机数生成器状态的全量快照系统。无论你使用 LoRA 微调 7B 模型，还是用 Megatron 并行训练 70B 多模态大模型，只要训练中途暂停，下次启动时就能精准回到中断前的毫秒级状态，继续推进。

本文不讲抽象原理，只聚焦一个目标：让你在 15 分钟内真正掌握 ms-swift 断点续训的完整操作链路——从配置要点、中断恢复、常见陷阱到生产级避坑建议，全部基于真实命令行与日志反馈，拒绝空泛描述。

1. 断点续训的核心前提：理解 checkpoint 的构成

在 ms-swift 中，“能续训”不等于“有 checkpoint 文件夹”。很多用户误以为只要--save_steps设置了，生成了checkpoint-xxx目录，就一定能恢复训练。这是最大的认知误区。

真正的断点续训依赖三类关键状态文件，缺一不可：

模型权重文件（pytorch_model.bin或model.safetensors）
存储当前模型参数，LoRA 权重单独保存在adapter_model.bin中。
训练状态字典（trainer_state.json）
包含当前 step 数、global_step、epoch、loss 曲线历史、learning_rate 调度器当前值等——这是续训能否对齐进度的核心依据。
优化器与调度器状态（optimizer.pt、scheduler.pt）
保存 AdamW 等优化器的state_dict，包括每个参数的exp_avg和exp_avg_sq，直接影响梯度更新方向。

正确做法：ms-swift 默认在每次--save_steps时，自动同步写入以上三类文件。但前提是你的--output_dir具有可写权限，且磁盘空间充足（尤其optimizer.pt在 7B 模型上可达 2–3GB）。

❌ 常见错误：手动删除checkpoint-xxx下的optimizer.pt或scheduler.pt；使用--save_only_model true参数；将output_dir挂载为只读 NFS；磁盘满导致写入失败（日志中会出现OSError: No space left on device）。

验证 checkpoint 是否完整，只需执行：

ls -lh output/checkpoint-100/ # 应看到至少以下文件（LoRA 训练为例）： # adapter_model.bin # LoRA 权重 # pytorch_model.bin # 基座模型（若启用 full finetune 则为完整权重） # trainer_state.json # 关键！必须存在 # optimizer.pt # 关键！必须存在 # scheduler.pt # 关键！必须存在 # config.json # 模型配置 # args.json # 启动参数快照（用于 infer/export 自动复用）

若缺失trainer_state.json或optimizer.pt，该 checkpoint无法用于续训，仅可用于推理或导出。

2. 两种续训方式：命令行直连 vs 配置文件接管

ms-swift 提供两种主流续训路径，适用不同场景。不要混用，否则会引发状态冲突。

2.1 方式一：命令行参数直连（推荐新手 & 单卡调试）

这是最直观的方式：完全复用原始训练命令，仅替换--output_dir为 checkpoint 路径，并添加--resume_from_checkpoint标志。

假设你最初运行的是：

CUDA_VISIBLE_DEVICES=0 swift sft \ --model Qwen/Qwen2.5-7B-Instruct \ --train_type lora \ --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \ --output_dir output \ --num_train_epochs 3 \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 16 \ --save_steps 50 \ --learning_rate 1e-4 \ --lora_rank 8

训练至checkpoint-120时中断。要从中断点继续，请执行：

CUDA_VISIBLE_DEVICES=0 swift sft \ --model Qwen/Qwen2.5-7B-Instruct \ --train_type lora \ --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \ --output_dir output/checkpoint-120 \ # 关键：指向 checkpoint 目录本身 --num_train_epochs 3 \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 16 \ --save_steps 50 \ --learning_rate 1e-4 \ --lora_rank 8 \ --resume_from_checkpoint true # 必须显式声明

为什么--output_dir要设为checkpoint-120而非output？
因为 ms-swift 的续训逻辑是：以--output_dir为根目录，自动查找其中的trainer_state.json并加载其记录的global_step和epoch。若仍设为output，框架会新建checkpoint-121，而非从120继续。

小技巧：--resume_from_checkpoint true可简写为-r true，但首次使用建议写全称避免歧义。

2.2 方式二：配置文件接管（推荐多机 & 生产环境）

当训练涉及 DeepSpeed、FSDP 或 Megatron 多机并行时，命令行参数易出错。此时应使用args.json配置文件接管。

ms-swift 在每个 checkpoint 目录下自动生成args.json，完整记录本次训练的所有参数（包括--deepspeed zero2等分布式配置）。续训时只需指定该文件路径：

CUDA_VISIBLE_DEVICES=0,1,2,3 NPROC_PER_NODE=4 \ swift sft \ --config_file output/checkpoint-120/args.json \ # 加载完整配置 --resume_from_checkpoint true

优势：
100% 还原原始环境，避免参数遗漏（如--deepspeed,--fsdp,--megatron等）；
支持跨机器续训（只要 checkpoint 文件完整，新机器无需重新下载模型）；
args.json中的output_dir字段会被自动忽略，框架仍以你传入的--config_file所在目录为工作根路径。

注意：若修改过args.json内容（如调整learning_rate），需确保逻辑自洽。例如，若原训练已进行 2 个 epoch，你将num_train_epochs改为 1，则框架会报错终止。

3. 数据加载一致性：为什么 resume 后 loss 突然飙升？

这是续训中最令人困惑的现象：明明trainer_state.json显示global_step=120，恢复后前几个 step 的 loss 却比中断前高 30%。根本原因在于数据迭代器（DataLoader）未同步重置。

ms-swift 默认使用IterableDataset流式加载（尤其--streaming true时），其内部状态（如当前 shard、sample index）不保存在trainer_state.json中。因此，单纯恢复训练状态，数据加载会从头开始，导致样本重复或错位。

正确解法：启用--dataloader_drop_last false+--seed 42（固定随机种子），并确保--dataset参数完全一致。对于流式数据集，ms-swift 会在trainer_state.json中额外记录data_load_state字段（v1.10+ 版本），包含：

"data_load_state": { "shard_idx": 3, "sample_offset": 1247, "epoch": 1 }

只要该字段存在且非空，续训时数据加载器将自动跳转至对应位置。

❌ 错误操作：

使用--shuffle true但未设--seed→ 每次重启数据顺序不同；
更改--dataset路径或采样比例（如#500改为#1000）→ 数据集结构变化；
在--streaming true下手动删除cache_dir→ shard 索引丢失。

验证数据是否对齐：查看日志中Resuming from checkpoint后的首条Step X / Y输出，对比中断前最后一条Step 120 / 1000的loss值。若差异 < 5%，则数据加载正常；若 > 20%，请检查上述配置。

4. 分布式训练续训：DeepSpeed / FSDP / Megatron 的特殊处理

单卡续训逻辑清晰，但多机多卡场景下，各节点的 checkpoint 必须严格一致，否则会导致梯度同步失败。

4.1 DeepSpeed ZeRO 续训（最常用）

DeepSpeed 的 checkpoint 是分片存储的：主节点（rank 0）保存zero_pp_rank_0/...，其他节点保存各自分片。ms-swift 已封装此逻辑，你只需确保：

所有节点挂载同一共享存储（如 NFS、Lustre），且output_dir路径完全一致；
启动命令中--deepspeed参数与原始训练完全相同（如--deepspeed zero2）；
--resume_from_checkpoint true由所有节点统一传入。

验证方法：在任意节点执行

ls -d output/checkpoint-120/zero_pp_rank_*/ # 应看到 rank_0, rank_1, ... 目录 cat output/checkpoint-120/zero_pp_rank_0/trainer_state.json | jq '.global_step' # 所有 rank 的值必须相同

4.2 FSDP 续训

FSDP 要求--fsdp参数（如--fsdp full_shard）与原始训练严格一致。ms-swift 会自动从checkpoint-120中加载pytorch_model_fsdp_0.bin等分片文件。关键点：

不要手动合并分片（--fsdp_use_orig_params false时，分片不可直接加载）；
若使用--fsdp_offload_params true，需确保offload_dir路径可访问。

4.3 Megatron-SWIFT 续训

Megatron 的 checkpoint 结构与 PyTorch 原生不同，包含mp_rank_00/、tp_rank_00/等目录。ms-swift 通过megatron sft命令自动识别：

NPROC_PER_NODE=2 CUDA_VISIBLE_DEVICES=0,1 megatron sft \ --config_file output/checkpoint-120/args.json \ --resume_from_checkpoint true

重要限制：Megatron 续训不支持跨 TP/PP 组合变更。例如，原始训练用--tensor-model-parallel-size 2，续训时不能改为4，否则会报KeyError: 'module.language_model.embedding.word_embeddings.weight'。

5. 实战排障：5 个高频问题与一键修复方案

问题现象	根本原因	修复命令/操作
`ValueError: Cannot resume from checkpoint: trainer_state.json not found`	checkpoint 目录不完整，或`--output_dir`指向父目录而非 checkpoint 本身	`ls -l output/checkpoint-120/trainer_state.json`→ 若不存在，换用更早的 checkpoint；若存在，检查`--output_dir`是否写错
`RuntimeError: Expected all tensors to be on the same device`	模型权重与优化器状态设备不匹配（如权重在 cuda:0，optimizer 在 cpu）	删除`output/checkpoint-120/optimizer.pt`，重新运行原命令（框架会重建 optimizer）；或升级 ms-swift 至 v1.12+（自动设备对齐）
`OSError: [Errno 17] File exists: 'output/checkpoint-121'`	`--output_dir`设为`output`而非`checkpoint-120`，框架尝试新建 checkpoint	修改命令，将`--output_dir`明确设为`output/checkpoint-120`
`Loss spikes at step 121, then slowly recovers`	数据加载未同步，样本重复或错位	添加`--seed 42 --dataloader_drop_last false`，并确认`args.json`中`data_load_state`字段存在且有效
`Loading checkpoint failed: size mismatch for ...`	模型结构变更（如修改`--lora_rank`或`--target_modules`）	不可续训！必须从头训练。修改参数后，旧 checkpoint 的权重维度与新模型不兼容

终极保底方案：若多次尝试失败，可利用 ms-swift 的--load_args false+--adapters推理能力，先验证 checkpoint 是否能成功加载并生成合理输出：
swift infer --adapters output/checkpoint-120 --max_new_tokens 32 # 若能输出通顺文本，说明权重完好，问题必在训练配置

6. 生产环境最佳实践：让续训真正可靠

在企业级训练平台中，断点续训不是“能用就行”，而是“必须零故障”。以下是经过千卡级集群验证的硬性规范：

6.1 checkpoint 策略配置（写入训练脚本）

# 推荐组合（平衡可靠性与磁盘占用） --save_steps 100 \ --save_total_limit 3 \ # 只保留最近 3 个 checkpoint，防磁盘爆满 --save_on_each_node false \ # 多机时仅主节点保存，避免重复写入 --overwrite_output_dir false \ # 防止误覆盖已有 checkpoint --logging_steps 10 \ # 日志频率高于 save_steps，便于定位中断点

6.2 磁盘健康监控（运维必备）

在训练脚本前加入磁盘空间检查：

#!/bin/bash DISK_FREE=$(df /path/to/output | awk 'NR==2 {print $4}') if [ "$DISK_FREE" -lt 10000000 ]; then # 小于 10GB echo "ERROR: Disk space low! $(df -h /path/to/output)" exit 1 fi # 后续执行 swift sft ...

6.3 自动化续训脚本（示例）

#!/bin/bash # resume.sh：自动检测最新可用 checkpoint 并续训 OUTPUT_DIR="output" LATEST_CKPT=$(ls -t ${OUTPUT_DIR}/checkpoint-* 2>/dev/null | head -n1) if [ -z "$LATEST_CKPT" ]; then echo "No checkpoint found. Starting fresh training..." exec swift sft "$@" else echo "Resuming from $LATEST_CKPT" exec swift sft --resume_from_checkpoint true --output_dir "$LATEST_CKPT" "$@" fi

运行方式：bash resume.sh [original_args...]