Chapter 11
常见错误
📌 commit b58b1bd从下载、训练到推理的高频问题
ms-swift 配置层多，错误类型也分散。本章按"下载 / 训练 / 推理 / 量化 / 部署"五类列。
11.1下载类
| 现象 | 处理 |
|---|
| 模型下载断网 | 重试；设 MODELSCOPE_CACHE 持久化避免重下 |
| HF 模型 timeout | 设 HF_ENDPOINT=https://hf-mirror.com |
| 魔搭模型不能匿名下 | 登录 modelscope login |
| 大模型下载磁盘满 | 大模型转 --model /path/to/local 本地路径 |
11.2训练类
| 现象 | 处理 |
|---|
| loss 不降 / 接近 ln(vocab) | 检查 template；EOS / pad 是否对 |
| OOM 第一步 | 开 --gradient_checkpointing true；降 micro_batch |
| OOM 在 eval | 降 --per_device_eval_batch_size |
| 多卡只用 1 张 | 没设 NPROC_PER_NODE |
| DeepSpeed ZeRO-3 + LoRA 报错 | 升级 peft >= 0.11、transformers >= 4.45 |
| save 时 OOM | distributed save 不应 OOM；--save_only_model true |
| 训完 adapter_model 0 字节 | save_steps 太小，第一次 save 时还没真训练 |
11.3多模态训练类
| 现象 | 处理 |
|---|
| image 找不到 | 用绝对路径，或设 --media_dir |
| OOM 视觉 LLM | 开 --freeze_vit true；降 --max_pixels |
| 视频抽帧很慢 | 装 decord；缩短视频或减少帧数 |
| VLM LoRA 不学视觉 | 检查 target_modules 是否覆盖 vision projector |
11.4推理类
| 现象 | 处理 |
|---|
| LoRA 加载后输出和训练时不一致 | infer 时 torch_dtype 跟训练保持一致；不要降到 fp16 |
| vLLM 不认识自定义模型 | vLLM 主分支可能不支持新模型；用 nightly |
| swift deploy 启动慢 | 正常，vLLM 编译 CUDA graph 需 30-60s |
| 多 adapter 同时部署 | vLLM 自家 multi-LoRA 支持；ms-swift 用 swift deploy --adapters a b c |
11.5量化类
| 现象 | 处理 |
|---|
| AWQ OOM | 降 quant_n_samples / quant_seqlen |
| GPTQ 慢 | 正常，AWQ 比 GPTQ 快 3-5× |
| 量化后乱码 | calibration 数据跟训练分布差太大；换更接近的 |
| 量化模型 vLLM 加载失败 | vLLM 量化插件版本不匹配；升 vllm |
11.6RLHF 专属
| 现象 | 处理 |
|---|
| DPO loss 不动 | lr 太大；DPO 用 5e-6 |
| GRPO advantage NaN | group reward std=0；提高 temperature |
| PPO reward 不升 | RM 不准；先评估 RM accuracy |
| online GRPO vLLM 慢 | 设 --vllm_gpu_memory_utilization 0.4 |
11.7调试技巧
# 开 verbose
export SWIFT_LOG_LEVEL=DEBUG
export NCCL_DEBUG=INFO
# 看完整 args
cat ./output/v0-xxx/args.json | jq .
# 用 0.5B 小模型先验证
swift sft --model Qwen/Qwen2.5-0.5B --dataset alpaca-zh#100 \
--train_type lora --num_train_epochs 1
11.8Sequence Parallel 启用 checklist
v4 的 SP（swift/sequence_parallel/）启用前必须满足的几个前置——少一条就 hang：
| 条件 | 修复 |
|---|
| 必须开 flash-attn 2 | --use_flash_attn true；eager / SDPA 与 SP 不兼容 |
sequence_parallel_size 整除 nproc | 调 SP 度或调 GPU 数；SP × DP = nproc |
| 启用 packing | --packing true，否则 SP 没意义 |
| 不可同时开 TP > 1（HF 路径） | Megatron 路径下另说，详见 ch09.8 五维并行 |
| 跨机用 zigzag_ring 而不是 ulysses | --sequence_parallel_mode zigzag_ring 省带宽 |
11.9多模态 packing 不兼容场景
2025-06 引入的多模态 packing 强大但不是万能。已知不兼容：
| 不兼容 | 替代 |
|---|
| 动态分辨率 VLM（InternVL3 / MiniCPM-V）+ packing | 关 packing；或固定 --max_pixels |
| 视频训练 + packing | 抽帧后视为图像批；否则关 packing |
| grounding 训练 + packing | bbox 坐标依赖单样本边界，packing 会破坏 |
| SP + 多模态 + packing 三连 | 实测有 hang 案例，先两两组合测 |
11.10Megatron HF 转换错误
9.6 提到 to_mcore 转换 OOM。其它常见转换坑：
| 现象 | 原因 | 修复 |
|---|
KeyError 找不到 linear_qkv.weight | Megatron 命名跟 HF 不一样 | mcore-bridge 升到 ≥ 1.3.0；某些自定义层需要 swift PR 加适配 |
| 转换后 forward 输出不一致 | RoPE / norm 实现微差 | 对比 swift export --to_hf 反向再训一步看 loss |
| LoRA Megatron 路径 target_modules 不匹配 | Megatron 层命名 linear_qkv / linear_proj，跟 HF 的 q_proj / v_proj 不同 | 用 --target_modules linear_qkv,linear_proj 或 all-linear |
| FP8 训练 grad scale 飘 | H100 / H200 才支持，A100 不行 | 关 --fp8；或换硬件 |
11.11v3 → v4 升级注意
本书基线 commit 上 v4 是默认。从 v3 升 v4 的常见坑：
| v3 路径 | v4 路径 |
|---|
from swift.llm import register_model | from swift.model import register_model |
from swift.llm import register_template | from swift.template import register_template |
from swift.llm import register_dataset | from swift.dataset import register_dataset |
from swift.llm.train.sft import SftPipeline | from swift.pipelines import SwiftSft / sft_main |
插件路径 --plugin_path my.py | --external_plugins my.py |
"我的 v3 代码升到 v4 import 全错" → grep swift.llm. 改成扁平 import 即可，99% 路径是直接迁移。CLI 字段名 v3 → v4 基本不变。
11.12这章你需要带走的
- 下载问题 90% 来自网络，用
HF_ENDPOINT 镜像或本地路径；
- 多卡未生效优先查
NPROC_PER_NODE；
- VLM OOM 首选
--freeze_vit true；
- 量化乱码看 calibration 数据是否对路；
- 0.5B 小模型 + 100 条数据是验证 pipeline 的快捷方式。