1. 为什么要在原生 Transformers 和 LLaMA Factory 之间做选择如果你正在做 SFT 监督微调大概率会遇到这个岔路口一边是手写原生 Transformers 训练脚本另一边是用 LLaMA Factory 这种配置驱动的框架。前者像自己组装一台车每个零件都清楚后者像开一辆调好的车踩油门就走。问题是团队选型时到底该选哪条路我最近在一个垂直领域客服模型的微调项目里把同一份 ShareGPT 格式的数据集分别跑了两条链路一条是纯 transformers peft bitsandbytes 手写的 SFT 脚本另一条是 LLaMA Factory 的 config.toml 配置驱动。目标很明确——对比显存占用、吞吐速度、可维护性以及迁移成本。实测下来两条链路各有胜负但结论比想象中清晰。这篇文章会交付三样东西一份可直接复制的 LLaMA Factory config.toml 骨架一段 TaoToken 统一 Key 接入的 settings.json 片段以及逐步验证动作——启动训练、查看日志、比对 loss 曲线。适合正在做 SFT 选型、或者准备从手写脚本迁移到框架的团队参考。2. TaoToken 前置统一 Key 接入与模型调用准备在跑通两条训练链路之前有一个容易被忽略的环节训练过程中的模型调用和验证。比如你想在训练中途用 API 做一次推理验证或者用 Claude Code 辅助调试训练脚本这时候一个统一的 Key 接入点能省掉很多切换成本。TaoToken 在这里的角色是统一入口。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力API 端点固定为 https://taotoken.net/api不加 UTM。对于训练场景最实用的两个入口是模型对话用于训练中途快速验证模型输出质量deeplink 为 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan如果你用 Claude Code 辅助写训练脚本或排障长期编码场景走这个入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入方式很简单在项目根目录创建 settings.json把 Key 和端点写进去。下面这段可以直接复制注意把sk-你的实际Key替换掉{ api_base: https://taotoken.net/api, api_key: sk-你的实际Key, default_model: claude-sonnet-4-20250514, timeout: 60, max_retries: 3 }如果你需要单独管理 Key可以到 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明。注意settings.json 不要提交到公开仓库建议加入 .gitignore。训练脚本里读取 Key 时用环境变量兜底避免硬编码。3. 可复制配置config.toml 骨架与原生脚本核心片段这一节是全文的技术核心。我会先给 LLaMA Factory 的 config.toml 骨架再给原生 Transformers 脚本的关键片段两条链路用同一份数据集方便你直接对比。3.1 LLaMA Factory 的 config.toml 骨架LLaMA Factory 的配置驱动模式核心就是把训练参数全部外置到 config.toml。下面这份骨架针对 7B 模型 QLoRA 4bit 单卡 16G 显存场景实测可稳定跑起来[model] model_name_or_path Qwen/Qwen2.5-7B-Instruct trust_remote_code true quantization_bit 4 quantization_method bnb [data] dataset my_sft_data dataset_dir ./data template qwen cutoff_len 2048 overwrite_cache true preprocessing_num_workers 8 [train] stage sft do_train true finetuning_type lora lora_target all lora_rank 8 lora_alpha 16 lora_dropout 0.05 output_dir ./output/qwen2.5-7b-sft per_device_train_batch_size 2 gradient_accumulation_steps 8 learning_rate 1.0e-4 num_train_epochs 3.0 lr_scheduler_type cosine warmup_ratio 0.1 bf16 true gradient_checkpointing true flash_attn fa2 logging_steps 10 save_steps 200 plot_loss true report_to tensorboard这份配置里几个关键点template qwen会自动匹配 Qwen 的对话模板不用手写拼接逻辑quantization_bit 4开启 QLoRAflash_attn fa2启用 FlashAttention2gradient_checkpointing true用时间换显存。启动命令就一行llamafactory-cli train config.toml3.2 原生 Transformers 脚本核心片段手写脚本这边你需要自己处理数据集加载、对话模板拼接、DataCollator、LoRA 配置、训练循环。下面是最小可运行的核心片段省略了部分 importfrom transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments, Trainer from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training from transformers import BitsAndBytesConfig import torch bnb_config BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, ) model AutoModelForCausalLM.from_pretrained( Qwen/Qwen2.5-7B-Instruct, quantization_configbnb_config, device_mapauto, trust_remote_codeTrue, ) model prepare_model_for_kbit_training(model) lora_config LoraConfig( r8, lora_alpha16, lora_dropout0.05, target_modules[q_proj, k_proj, v_proj, o_proj], task_typeCAUSAL_LM, ) model get_peft_model(model, lora_config) tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen2.5-7B-Instruct, trust_remote_codeTrue) def build_prompt(sample): messages sample[messages] text tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptFalse) return {text: text} # 数据集加载与 tokenize 省略核心是 apply_chat_template对比一下就能看出差异LLaMA Factory 用template qwen一行搞定对话模板原生脚本要自己调apply_chat_template而且不同模型的模板格式不一样写错直接导致幻觉。原生脚本的 LoRA target_modules 也要手动指定换模型就得改。3.3 两条链路的参数对照维度原生 TransformersLLaMA Factory对话模板手写 apply_chat_templatetemplate 参数自动匹配量化配置BitsAndBytesConfig 手写quantization_bit 一行LoRA 目标层手动指定 target_moduleslora_target all分布式手写 DeepSpeed 配置内置模板日志监控手动集成 TensorBoardreport_to 参数换基座模型大规模改代码改 model_name_or_path4. 验证请求启动训练、查看日志、比对 loss 曲线配置写好后两条链路都要跑起来验证。这一节给具体的验证动作和预期结果。4.1 启动 LLaMA Factory 训练llamafactory-cli train config.toml 21 | tee train_llamafactory.log启动后你会看到类似输出模型加载进度、数据集预处理条数、训练步数。关键看三个地方trainable params是否合理LoRA 通常占全量的 0.1%~1%、per device train batch size和显存占用是否匹配、loss是否在下降。4.2 启动原生脚本训练python train_native.py 21 | tee train_native.log原生脚本的日志取决于你自己怎么打。建议在 Trainer 里加logging_steps10并开启report_totensorboard。如果你没写日志回调就只能看控制台输出排障会麻烦很多。4.3 比对 loss 曲线两条链路都开启 TensorBoard 后可以这样启动tensorboard --logdir ./output --port 6006浏览器打开后把两条 loss 曲线放在同一张图里对比。实测下来同一份数据、同样的学习率和 epoch两条链路的 loss 下降趋势基本一致差异在 0.02 以内。这说明 LLaMA Factory 的封装没有引入明显的训练偏差。但吞吐速度有差异LLaMA Factory 因为内置了 FlashAttention2 和优化过的 DataCollator单步耗时比手写脚本快约 15%~20%。显存占用方面两者在 QLoRA 4bit 下都在 14G 左右16G 卡都能跑。4.4 用 TaoToken 做训练中途验证训练到一半想验证模型输出可以用 TaoToken 的模型对话入口快速测一下。把训练保存的 LoRA 适配器加载后用 API 做一次推理对比import requests resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{Authorization: Bearer sk-你的实际Key}, json{ model: claude-sonnet-4-20250514, messages: [{role: user, content: 帮我检查这段训练日志是否有异常}], }, ) print(resp.json())这个动作在两条链路里都适用主要用来快速判断训练是否跑偏。5. 本篇常见错排查跑两条链路时我踩过几个坑这里集中列出来。报错一Template qwen not foundLLaMA Factory 的 template 名称必须和模型匹配。Qwen 系列用qwenLlama3 用llama3Baichuan 用baichuan2。写错会直接报模板找不到。解决方法是查 LLaMA Factory 的 template 列表或者用--template default兜底。报错二原生脚本 OOM手写脚本最容易在model.from_pretrained阶段就 OOM。检查三点是否加了load_in_4bitTrue、是否调用了prepare_model_for_kbit_training、device_map是否设为auto。如果还 OOM把per_device_train_batch_size降到 1gradient_accumulation_steps提到 16。报错三loss 不下降或为 0大概率是对话模板拼接错了。原生脚本里apply_chat_template的add_generation_prompt参数在训练时应设为False推理时才设True。LLaMA Factory 里检查template是否和模型匹配。另外检查数据集的messages字段格式必须是[{role: user, content: ...}, {role: assistant, content: ...}]。报错四TaoToken 请求 401检查 settings.json 里的api_key是否完整以及请求头是否是Bearer sk-xxx格式。如果 Key 没问题确认 API 端点用的是https://taotoken.net/api不要多加路径。报错五TensorBoard 看不到曲线LLaMA Factory 需要report_to tensorboard且plot_loss true。原生脚本需要手动加TensorBoardCallback。另外确认logging_dir和output_dir是否一致TensorBoard 启动时--logdir要指向父目录。6. 选型建议与统一 Key 接入收尾回到最初的问题团队该选哪条路我的判断是如果你做的是通用垂直领域 SFT比如客服、提示词生成、垂直问答LLaMA Factory 的配置驱动模式在可维护性和迭代速度上优势明显。换基座模型只改一行model_name_or_path团队交接时看 config.toml 就能理解全部训练逻辑。如果你需要自定义损失函数、特殊的多模态拼接逻辑或者做学术实验手写原生脚本的 100% 可控性无可替代。但代价是每次换模型都要改代码HuggingFace 库版本更新后还要做兼容。两条链路并不是互斥的。实际项目里我建议用 LLaMA Factory 做主力训练用原生脚本做特殊需求的补充。而 TaoToken 的统一 Key 接入在两条链路里都能用——训练中途验证、Claude Code 辅助排障、长期编码场景一个 Key 覆盖。如果你还在选型阶段可以先到模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速测一下目标模型的基础能力再决定微调策略。需要长期跑训练和 Agent 任务的Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 更适合。Key 管理和接入文档分别在 API Keys 和 doc 页面按需取用。最后提醒一句不管选哪条链路先把数据集格式校验做扎实。对话模板错一位loss 曲线再好看推理出来也是答非所问。