企业官网建设流程全解析

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_KEY="sk-你的实际Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

如果你打算长期做编码类微调和 Agent 实验，可以顺带看一下 Coding Plan 的额度说明，它和按量计费的 Key 是分开管理的，适合高频调用场景。模型对话入口可以用来手动验证模型是否正常响应，接入文档则给出了不同语言 SDK 的调用示例，后面评估脚本会用到。

注意：Key 只显示一次，创建后立刻复制保存。如果泄露，到控制台吊销重建即可，不影响已有训练任务。

3. 可复制配置：训练、评估、预测三份 YAML

LLaMA-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.yaml

3.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表示对所有线性层挂 LoRA，Qwen2.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: 4

3.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: none

4. 启动训练与验证请求

4.1 执行训练

conda activate llama_factory export USE_MODELSCOPE_HUB=1 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.yaml

MMLU 评估结束后终端会打印各学科分数，形如：

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，需要时再改。