1. 从 WebUI 到命令行为什么微调 Qwen2.5-VL 要换一种姿势如果你已经用 LLaMA-Factory 的 WebUI 跑通过一次 Qwen2.5-VL 的 LoRA 微调大概率会有一个感受点选参数很直观但一旦要复现、要对比、要挂到远程服务器上批量跑鼠标就变成了效率瓶颈。命令行加 YAML 配置的组合解决的正是这个问题——一份.yaml文件把模型路径、数据集、LoRA 秩、学习率、评估策略全部固化下来提交到 Git 之后任何人 checkout 下来都能跑出同样的结果。这篇内容聚焦 LLaMA-Factory 命令行微调 Qwen2.5-VL 的完整链路从 YAML 配置骨架、llamafactory-cli train启动训练到 MMLU 基准评估和自定义数据集预测同时把模型调用与评估环节的 API 通道统一接到 TaoToken 上。适合已经装好 LLaMA-Factory、手头有 Qwen2.5-VL-3B-Instruct 权重、想从「能跑」进阶到「可复现、可对比、可自动化」的读者。下面所有配置和命令都可以直接复制修改我会把每个参数为什么这么写讲清楚也会把踩过的坑标出来。2. TaoToken 前置统一 Key 与 API 通道的准备在命令行流程里TaoToken 承担两个角色一是训练完成后做模型对话验证时用统一的 API Key 调用 Qwen2.5-VL 做效果抽查二是评估脚本里如果需要调用外部模型做对比或打分走同一个通道避免在多个平台之间切换 Key。先到官网注册并进入控制台在 API Keys 页面创建一个 Key。这个 Key 就是后续所有请求的凭证建议按项目命名比如llamafactory-qwen25vl方便后面排查是哪个任务在用。创建完成后你会拿到两样东西API 基础地址https://taotoken.net/api以及一串以sk-开头的 Key。把它写进环境变量不要硬编码在 YAML 或脚本里export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你打算长期做编码类微调和 Agent 实验可以顺带看一下 Coding Plan 的额度说明它和按量计费的 Key 是分开管理的适合高频调用场景。模型对话入口可以用来手动验证模型是否正常响应接入文档则给出了不同语言 SDK 的调用示例后面评估脚本会用到。注意Key 只显示一次创建后立刻复制保存。如果泄露到控制台吊销重建即可不影响已有训练任务。3. 可复制配置训练、评估、预测三份 YAMLLLaMA-Factory 在examples/下提供了大量模板正确做法是复制最接近的一份再改而不是从零写。针对 Qwen2.5-VL 的 LoRA SFT基础模板是examples/train_lora/qwen2.5vl_lora_sft.yaml。mkdir -p my_configs cp examples/train_lora/qwen2.5vl_lora_sft.yaml my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml3.1 训练配置骨架打开复制出来的文件改成下面这样。我按「模型 / 方法 / 数据 / 输出 / 训练 / 评估」六段组织方便你对照修改# my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml # model model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct image_max_pixels: 262144 video_max_pixels: 16384 trust_remote_code: true # method stage: sft do_train: true finetuning_type: lora lora_rank: 64 lora_alpha: 128 lora_dropout: 0.1 lora_target: all # dataset dataset: pokemon_multimodal dataset_dir: pokemon_sharegpt template: qwen2_vl cutoff_len: 4096 max_samples: 1000 overwrite_cache: true preprocessing_num_workers: 16 dataloader_num_workers: 4 # output output_dir: saves/qwen2.5vl-3b-lora-pokemon/sft-cli logging_steps: 10 save_steps: 500 plot_loss: true overwrite_output_dir: true save_only_model: false report_to: none # train per_device_train_batch_size: 2 gradient_accumulation_steps: 8 learning_rate: 2.0e-4 num_train_epochs: 3.0 lr_scheduler_type: cosine warmup_ratio: 0.1 bf16: true ddp_timeout: 180000000 resume_from_checkpoint: null # eval val_size: 0.1 per_device_eval_batch_size: 2 eval_strategy: steps eval_steps: 100几个关键点展开说。lora_target: all表示对所有线性层挂 LoRAQwen2.5-VL 的视觉编码器和语言解码器都会覆盖显存吃紧的话可以改成只挂语言层。template: qwen2_vl是必须的用错模板会导致图像 token 和文本 token 拼接错位训练 loss 会异常。cutoff_len: 4096对多模态数据要留意图像 patch 展开后占的 token 数不小如果数据集里图片分辨率高适当调大或调小image_max_pixels来控制。3.2 评估配置MMLU 评估用一份独立配置关键是adapter_name_or_path指向训练输出目录# my_configs/eval_mmlu.yaml model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct adapter_name_or_path: saves/qwen2.5vl-3b-lora-pokemon/sft-cli image_max_pixels: 262144 video_max_pixels: 16384 trust_remote_code: true finetuning_type: lora task: mmlu_test template: fewshot lang: en n_shot: 5 save_dir: saves/qwen2.5vl-3b-lora-pokemon/eval-mmlu batch_size: 43.3 预测配置自定义数据集预测用do_predict: true注意这里仍然走train子命令不是单独的 predict 命令# my_configs/predict_pokemon.yaml model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct adapter_name_or_path: saves/qwen2.5vl-3b-lora-pokemon/sft-cli image_max_pixels: 262144 video_max_pixels: 16384 trust_remote_code: true stage: sft do_predict: true finetuning_type: lora eval_dataset: pokemon_multimodal dataset_dir: pokemon_sharegpt template: qwen2_vl cutoff_len: 4096 max_samples: 100 overwrite_cache: true preprocessing_num_workers: 1 output_dir: saves/qwen2.5vl-3b-lora-pokemon/predict overwrite_output_dir: true per_device_eval_batch_size: 1 predict_with_generate: true report_to: none4. 启动训练与验证请求4.1 执行训练conda activate llama_factory export USE_MODELSCOPE_HUB1 llamafactory-cli train my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml启动后重点看三处日志。第一处是数据集加载确认pokemon_multimodal被正确识别样本数和你预期一致。第二处是 LoRA 注入信息会打印哪些模块被替换lora_target: all下应该能看到视觉和语言两侧的线性层。第三处是训练过程中的 loss 曲线logging_steps: 10意味着每 10 步打一次正常情况 loss 应该平滑下降如果剧烈震荡先检查学习率和 batch size。训练完成后saves/qwen2.5vl-3b-lora-pokemon/sft-cli下会有 adapter 权重和trainer_state.json后者记录了完整 loss 历史可以用plot_loss: true生成的图直接看。4.2 用 TaoToken 做模型对话验证训练完不要只看 loss要实际让模型回答几个问题。这里用 TaoToken 的 API 通道做一次快速验证确认模型服务正常、Key 有效curl -s ${TAOTOKEN_BASE_URL}/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: Qwen2.5-VL-3B-Instruct, messages: [ {role: user, content: 用一句话说明 LoRA 微调相比全量微调的优势} ], max_tokens: 128 }返回里choices[0].message.content就是模型输出。这一步的意义在于把「训练环境」和「推理环境」解耦——训练在本地或 GPU 服务器上跑验证走统一 API两边互不干扰。如果你更习惯图形界面模型对话页面可以直接粘贴 Key 做同样的验证。4.3 执行评估与预测llamafactory-cli eval my_configs/eval_mmlu.yaml llamafactory-cli train my_configs/predict_pokemon.yamlMMLU 评估结束后终端会打印各学科分数形如Average: 64.14 STEM: 60.47 Social Sciences: 74.85 Humanities: 56.62 Other: 68.32预测任务结束后saves/qwen2.5vl-3b-lora-pokemon/predict/all_results.json里是 ROUGE 和 BLEU 指标{ predict_bleu-4: 46.05964000000001, predict_rouge-1: 54.763231999999995, predict_rouge-2: 27.012867999999997, predict_rouge-l: 46.45837499999999, predict_runtime: 92.8343, predict_samples_per_second: 1.077 }predict_rouge-1在 50 以上说明生成内容和参考回答的词汇重叠度不错predict_bleu-4偏低是正常的多模态生成任务里 BLEU 对措辞变化很敏感重点看 ROUGE 系列。5. 本篇常见错排查报错一Template qwen2_vl not found。说明 LLaMA-Factory 版本偏旧Qwen2.5-VL 的模板是较新版本才加入的。升级到最新版即可或者检查template拼写注意是qwen2_vl不是qwen2.5_vl。报错二训练启动后 OOM。优先降per_device_train_batch_size到 1同时把gradient_accumulation_steps翻倍保持等效 batch。其次降image_max_pixels从 262144 降到 131072 能显著减少视觉 token 占用。lora_rank从 64 降到 32 也能省一部分显存。报错三评估时adapter_name_or_path找不到。确认路径是相对 LLaMA-Factory 根目录的且训练确实产出了adapter_model.safetensors。如果训练中途中断目录里可能只有 checkpoint 没有最终 adapter需要从checkpoint-xxx目录里取。报错四预测结果全是空或重复。检查predict_with_generate是否为 true以及template是否和训练时一致。模板不一致会导致模型看到的输入格式和训练时不同生成质量断崖式下降。报错五TaoToken 请求返回 401。检查环境变量是否在当前 shell 生效echo $TAOTOKEN_API_KEY确认非空。如果 Key 是在另一个终端创建的新终端需要重新 export或者写进~/.bashrc。6. 把命令行流程接进你的日常工作流走到这里你已经有了三份可复用的 YAML 和一套完整的训练、评估、预测命令。接下来最值得做的一件事是把它们串成一个 shell 脚本用参数控制不同的lora_rank和learning_rate跑一组对比实验。YAML 的好处就在这里——脚本里用sed替换几个字段或者用--lora_rank命令行覆盖就能批量启动结果目录按参数命名回头对比一目了然。评估环节如果要做更细的效果核对可以把预测输出和人工标注做逐条比对ROUGE 只是粗筛。需要调用外部模型做打分或对比时统一走 TaoToken 的 API 通道Key 和地址在环境变量里脚本里不用改。长期做编码类微调和 Agent 实验的话Coding Plan 的额度模型比按量计费更好预估成本接入文档里有完整的参数说明照着改model字段就能切换不同模型做对比。最后提醒一句resume_from_checkpoint在调试阶段很有用训练中断后不用从头再来把它设成具体的 checkpoint 路径即可续跑。这个字段平时是null需要时再改。