checkpoint路径填不对？教你快速定位训练结果
微调大模型时，最让人抓狂的不是显存爆了、不是训练崩了，而是——模型训完了，却找不到权重在哪。
你翻遍/root/output，看到一堆带时间戳的文件夹：v2-20250412-163245、v3-20250412-170822……点进去又是层层嵌套的checkpoint-50、checkpoint-100、checkpoint-150。
运行推理命令时，把路径一粘，报错：FileNotFoundError: Can't find adapter_config.json；再换一个，又提示ValueError: Expected state dict to contain 'base_model.model.embed_tokens.weight'。
别急——这不是你操作错了，也不是镜像有问题，而是LoRA微调产物的结构逻辑和传统全参微调完全不同，而绝大多数教程只告诉你“填对路径”，却没说清“为什么这个路径才对”。
本文不讲原理推导，不堆参数表格，就用最直白的方式，带你三步锁定正确checkpoint路径，并彻底理解背后的设计逻辑。哪怕你是第一次接触ms-swift、第一次跑LoRA，也能在2分钟内确认该用哪个文件夹、哪个子目录、哪一行命令。
1. 先搞懂：LoRA微调产物到底长什么样？
很多新手默认“微调完的模型=一个完整模型文件夹”，但LoRA不是这样工作的。它不修改原始模型权重，而是额外训练一组小规模适配器（adapter），推理时动态加载到基础模型上。因此，训练产物里没有.bin或.safetensors主模型文件，只有adapter相关的配置与权重。
在本镜像中，执行swift sft后，所有输出都落在/root/output下。我们先看一眼典型结构：
cd /root/output ls -l # 输出示例： # drwxr-xr-x 3 root root 4096 Apr 12 16:32 v2-20250412-163245 # drwxr-xr-x 3 root root 4096 Apr 12 17:08 v3-20250412-170822每个vX-xxxx文件夹是一个独立训练任务（对应一次sft命令）。进入任一任务目录：
cd v2-20250412-163245 ls -l # 输出示例： # drwxr-xr-x 3 root root 4096 Apr 12 16:32 checkpoint-50 # drwxr-xr-x 3 root root 4096 Apr 12 16:33 checkpoint-100 # -rw-r--r-- 1 root root 242 Apr 12 16:32 adapter_config.json # -rw-r--r-- 1 root root 128 Apr 12 16:32 README.md # -rw-r--r-- 1 root root 512 Apr 12 16:32 trainer_log.json注意这三点：
adapter_config.json是关键入口：它定义了LoRA的秩（rank）、alpha、目标模块等，是swift infer识别adapter的唯一依据；checkpoint-XX是真正的权重快照：每个checkpoint文件夹里都包含adapter_model.safetensors（或.bin）和adapter_config.json；- ❌根目录下的
adapter_config.json只是模板：它不带权重，不能直接用于推理。
所以，正确路径 =output/vX-xxx/checkpoint-XX（完整路径），而不是output/vX-xxx或output/vX-xxx/checkpoint-XX/adapter_model.safetensors。
一句话记住：
swift infer --adapters后面填的，必须是一个包含adapter_config.json和adapter_model.*的完整目录路径，且该目录里不能有其他同名文件干扰。
2. 三步法：快速定位唯一可用checkpoint
不用猜、不用试、不靠运气。按顺序执行以下三步，100%锁定你要的路径。
2.1 第一步：确认训练任务ID（vX-xxx）
打开训练日志，找第一行带Saving model checkpoint的记录：
tail -n 50 /root/output/v2-20250412-163245/trainer_log.json | grep "Saving model checkpoint" # 输出示例： # {"step": 50, "loss": 0.1234, "learning_rate": 1e-04, "epoch": 0.5, "timestamp": "2025-04-12T16:32:45", "message": "Saving model checkpoint to /root/output/v2-20250412-163245/checkpoint-50"}这里明确告诉你：最新保存的checkpoint是checkpoint-50，所属任务是v2-20250412-163245。
如果日志被覆盖，直接看文件夹修改时间：
ls -t /root/output | head -n 1 # 输出：v2-20250412-163245 → 这就是最新任务2.2 第二步：验证checkpoint是否完整（关键！）
很多同学卡在这一步：看到checkpoint-100就直接用，结果报错。因为checkpoint-100可能只保存了部分文件（比如训练中断后未写完）。
安全做法：检查该目录下是否存在两个核心文件：
ls -l /root/output/v2-20250412-163245/checkpoint-100/ # 必须同时存在： # -rw-r--r-- 1 root root 242 Apr 12 16:33 adapter_config.json # -rw-r--r-- 1 root root 1.2M Apr 12 16:33 adapter_model.safetensors如果只有adapter_config.json，没有adapter_model.*，说明该checkpoint写入失败，跳过；
如果文件大小为0（如0 bytes），也跳过；
只有两者都存在且非空，才是可使用的checkpoint。
2.3 第三步：一键生成可用推理命令
写个简单脚本，自动拼出完整命令（复制即用）：
# 替换为你的真实路径 TASK_DIR="v2-20250412-163245" CKPT_DIR="checkpoint-100" echo "CUDA_VISIBLE_DEVICES=0 \\" echo "swift infer \\" echo " --adapters /root/output/$TASK_DIR/$CKPT_DIR \\" echo " --stream true \\" echo " --temperature 0 \\" echo " --max_new_tokens 2048"执行后输出：
CUDA_VISIBLE_DEVICES=0 \ swift infer \ --adapters /root/output/v2-20250412-163245/checkpoint-100 \ --stream true \ --temperature 0 \ --max_new_tokens 2048粘贴进终端，回车——这次一定能跑通。
3. 常见填错路径的5种情况及修复方案
下面这些错误，90%的新手都踩过。对照自查，立刻解决。
3.1 错误1：填了output/vX-xxx（缺checkpoint子目录）
- 现象：报错
ValueError: Cannot find adapter_config.json in /root/output/v2-20250412-163245 - 原因：
vX-xxx目录下只有adapter_config.json模板，没有实际权重 - 修复：补上
/checkpoint-XX，例如/root/output/v2-20250412-163245/checkpoint-100
3.2 错误2：填了output/vX-xxx/checkpoint-XX/adapter_model.safetensors
- 现象：报错
OSError: adapter_config.json not found - 原因：
--adapters参数要求传目录，不是文件路径 - 修复：删掉文件名，只留目录：
/root/output/v2-20250412-163245/checkpoint-100
3.3 错误3：路径里有中文或空格（如我的微调结果）
- 现象：
bash: syntax error near unexpected token 'newline' - 原因：shell无法解析含空格路径，未加引号
- 修复：用单引号包裹路径：
--adapters '/root/output/我的微调结果/checkpoint-50'
（但本镜像默认路径无中文，此问题多见于自定义部署）
3.4 错误4：用了旧任务的checkpoint（如v1-xxx）
- 现象：模型回答仍是原始身份（“我是阿里云开发的…”）
- 原因：训练数据或参数不同，旧checkpoint未注入新身份
- 修复：确认
trainer_log.json里dataset字段是否为self_cognition.json，只用匹配任务的checkpoint
3.5 错误5：路径拼写错误（大小写、横线、数字错位）
- 现象：
No such file or directory - 原因：Linux严格区分大小写，
v2写成V2、checkpoint-100写成checkpoint_100均失败 - 修复：用
tab键自动补全路径，或先ls /root/output/确认真实名称
4. 进阶技巧：让路径管理不再混乱
训练多了，output里几十个文件夹，手动找太低效。这里给你三个实用技巧：
4.1 技巧1：训练时指定唯一任务名（推荐！）
下次运行sft，加--output_dir参数自定义路径名，避开时间戳：
swift sft \ --model Qwen2.5-7B-Instruct \ --train_type lora \ --dataset self_cognition.json \ --output_dir output/self_cognition_v1 \ # ← 关键！自定义清晰名称 ... # 其他参数不变训练完，路径直接是/root/output/self_cognition_v1/checkpoint-100，一目了然。
4.2 技巧2：用软链接固定最新checkpoint
每次训练完，自动创建latest软链接指向最新可用checkpoint：
# 训练结束后执行（替换为你的实际路径） ln -sf /root/output/v2-20250412-163245/checkpoint-100 /root/output/latest之后推理命令永远用：
swift infer --adapters /root/output/latest ...4.3 技巧3：写个检查脚本，一键诊断
保存为check_checkpoint.sh，放在/root下：
#!/bin/bash if [ ! -d "$1" ]; then echo "❌ 路径不存在: $1" exit 1 fi if [ ! -f "$1/adapter_config.json" ]; then echo "❌ 缺少 adapter_config.json" exit 1 fi if [ ! -f "$1/adapter_model.safetensors" ] && [ ! -f "$1/adapter_model.bin" ]; then echo "❌ 缺少 adapter_model.* 权重文件" exit 1 fi echo " 路径有效！可直接用于 swift infer"使用：
chmod +x check_checkpoint.sh ./check_checkpoint.sh /root/output/v2-20250412-163245/checkpoint-100 # 输出： 路径有效！可直接用于 swift infer5. 总结：路径问题的本质，是理解LoRA的加载机制
你填不对路径，根本原因不是手误，而是没意识到：
LoRA不是“替换模型”，而是“挂载插件”。--adapters不是指向一个模型，而是指向一个插件包——它必须同时包含描述（adapter_config.json）和功能（adapter_model.*），缺一不可。
所以，下次再遇到路径报错，别急着重训，按这三步走：
① 找最新任务目录（ls -t output | head -1）；
② 进入其checkpoint-XX，确认两个文件都在；
③ 用完整绝对路径填入--adapters。
10秒定位，零失败率。
现在，打开你的终端，cd到/root/output，敲下ls——那个让你纠结半天的checkpoint，其实一直安静地躺在那里，只等你用对的方式把它请出来。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
