SFT 完全指南：从数据构造到 Agent 微调，用 TaoToken 统一 Key 打通 LLaMA-Factory 训练链路

1. 为什么 SFT 训练链路总在 Key 上翻车SFTSupervised Fine-Tuning监督微调是把预训练模型从会说话变成会干活的关键一步。但真正跑过 LLaMA-Factory 的人都知道训练本身不难难的是训练完之后那一段——你要验证模型有没有学会工具调用要拿它去跑 Agent 任务要对比微调前后的行为差异。这时候你会发现数据构造阶段用的一个 Key、训练脚本里写死的另一个 Key、推理验证时又换一个 Key三套配置互相打架改一处忘一处最后连自己都搞不清哪次请求走的是哪个通道。我试过最离谱的一次数据合成脚本里用的是 A 平台的 KeyLLaMA-Factory 的config.toml里写的是 B 平台的 endpoint推理验证时又临时 export 了 C 平台的变量。结果模型明明微调得不错Agent 调用却一直报 401排查了两个小时才发现是环境变量没继承到子进程。这种问题不是技术难点纯粹是配置割裂带来的隐性成本。这篇要解决的就是这件事用 TaoToken 的统一 Key 把数据构造 → LLaMA-Factory 训练 → Agent 推理验证整条链路串起来只维护一份凭证只改一个地方。适合正在做 Agent 微调、被多套 Key 折腾过的同学也适合刚接触 LLaMA-Factory、想一次把链路跑通的新手。下面会给可复制的config.toml骨架、数据构造脚本、训练配置和验证动作每一步都能直接跟做。2. TaoToken 统一 Key 的前置准备TaoToken 在这里扮演的角色是统一入口它提供一个兼容 OpenAI 接口规范的 endpoint你的数据合成脚本、LLaMA-Factory 的推理后端、Agent 验证脚本全部指向同一个 base_url 和同一个 API Key。这样你不需要在三个地方分别配置三家平台的凭证也不需要担心某个平台的模型突然下线导致链路断掉。具体要准备的东西只有三样第一一个 TaoToken 账号和对应的 API Key。登录官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进控制台创建 Key。建议给这个 Key 起个明确的名字比如sft-agent-pipeline方便后面区分。第二确认你要用的模型名。TaoToken 的模型列表在文档里有数据合成阶段通常用能力强的模型比如 Claude 系列或 GPT 系列训练阶段 LLaMA-Factory 本身不消耗 Key它是本地训练但推理验证阶段要用同一个 Key 去调模型。第三把 base_url 记牢https://taotoken.net/api。注意这个地址不带任何查询参数是纯粹的 API 入口。所有 OpenAI SDK 兼容的调用都指向它。注意不要把官网地址和 API 地址搞混。官网是给人看的API 是给代码调的。写进config.toml和脚本里的必须是https://taotoken.net/api。环境变量建议这样设一次设好后面所有脚本都读它export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你在 Windows 上用 PowerShell$env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设完之后用echo $TAOTOKEN_API_KEY确认一下避免设了个空值自己还不知道。3. 可复制的配置从数据构造到 LLaMA-Factory3.1 数据构造脚本统一 Key 调用Agent SFT 的数据核心是多轮对话 工具调用轨迹。下面这个脚本用 TaoToken 统一 Key 合成轨迹数据输出成 LLaMA-Factory 能直接吃的 sharegpt 格式。import os import json from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) SYSTEM_PROMPT 你是一个可以使用工具的 AI Agent。 可用工具 - web_search(query): 搜索网络信息 - calculator(expr): 计算数学表达式 调用工具时输出格式为 {tool: 工具名, args: {参数字典}} 等待工具返回结果后再决定下一步或给出最终答案。 def synthesize_trajectory(task: str, model: str claude-sonnet-4-6) - dict: 用统一 Key 合成一条 Agent 轨迹数据 messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: task}, ] resp client.chat.completions.create( modelmodel, messagesmessages, temperature0.7, ) assistant_reply resp.choices[0].message.content messages.append({role: assistant, content: assistant_reply}) return {messages: messages} tasks [ 帮我查一下北京今天的天气然后告诉我气温换算成华氏度是多少, 读取 sales.csv 的总销售额并搜索行业平均水平做对比, ] dataset [] for t in tasks: dataset.append(synthesize_trajectory(t)) with open(agent_sft_data.jsonl, w, encodingutf-8) as f: for item in dataset: f.write(json.dumps(item, ensure_asciiFalse) \n) print(f生成 {len(dataset)} 条轨迹数据)这里的关键点是base_url和api_key都从环境变量读脚本本身不写死任何凭证。你换 Key 只需要改环境变量脚本一行不用动。3.2 数据注册到 LLaMA-Factory把生成的agent_sft_data.jsonl放到 LLaMA-Factory 的data/目录下然后在data/dataset_info.json里加一段{ agent_sft: { file_name: agent_sft_data.jsonl, formatting: sharegpt, columns: { messages: messages }, tags: { role_tag: role, content_tag: content, user_tag: user, assistant_tag: assistant, system_tag: system } } }formatting必须是sharegpt因为我们的数据是 messages 数组格式。tags里把角色标签映射清楚LLaMA-Factory 才知道哪段是 system、哪段是 assistant。3.3 config.toml 骨架LLaMA-Factory 新版支持config.toml比 yaml 更清晰。下面这份可以直接复制改模型路径和数据集名就行[model] model_name_or_path Qwen/Qwen3-7B-Instruct trust_remote_code true [finetuning] stage sft do_train true finetuning_type lora lora_rank 16 lora_alpha 32 lora_dropout 0.05 lora_target q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj [data] dataset agent_sft template qwen cutoff_len 4096 max_samples 10000 overwrite_cache true [training] per_device_train_batch_size 2 gradient_accumulation_steps 4 learning_rate 5.0e-5 num_train_epochs 3 lr_scheduler_type cosine warmup_ratio 0.05 bf16 true logging_steps 10 save_steps 200 save_total_limit 3 output_dir ./output/agent-qwen3-sft [inference] # 推理验证阶段走 TaoToken 统一 Key # 这里不写 Key由环境变量注入启动训练llamafactory-cli train config.toml多卡的话在[training]里加一行deepspeed examples/deepspeed/ds_z3_config.json然后同样用llamafactory-cli train config.toml启动。注意learning_rate对 Agent SFT 建议比普通指令微调低一点。工具调用格式的学习对学习率很敏感5e-5 是个稳妥起点如果 loss 震荡就降到 2e-5。4. 验证请求微调前后 Agent 调用对比训练跑完之后最关键的验证动作是用同一个 TaoToken Key分别调微调前的基座模型和微调后的模型看 Agent 行为有没有变化。4.1 微调前基线import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) test_task 帮我查一下北京今天的天气然后换算成华氏度 resp client.chat.completions.create( modelQwen/Qwen3-7B-Instruct, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: test_task}, ], ) print(微调前输出) print(resp.choices[0].message.content)微调前的模型大概率会直接编一段天气描述或者输出一段自然语言而不是工具调用 JSON。这就是我们要对比的基线。4.2 微调后验证LLaMA-Factory 训练完的 LoRA 权重需要合并或加载。合并后用 vLLM 或 LLaMA-Factory 自带的推理接口起一个本地服务然后把 Agent 验证脚本的 base_url 指向本地服务llamafactory-cli export config.toml导出合并后的模型然后用 vLLM 起服务python -m vllm.entrypoints.openai.api_server \ --model ./output/agent-qwen3-sft/merged \ --port 8000验证脚本改成指向本地client OpenAI( api_keydummy, # 本地服务不需要真 Key base_urlhttp://localhost:8000/v1, ) resp client.chat.completions.create( model./output/agent-qwen3-sft/merged, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: test_task}, ], ) print(微调后输出) print(resp.choices[0].message.content)理想情况下微调后的模型应该输出类似{tool: web_search, args: {query: 北京今天天气}}而不是一段自然语言。如果它还是输出自然语言说明训练数据里工具调用格式的样本不够或者 loss mask 没设对。4.3 成功结果的判断标准一次成功的 Agent SFT验证时应该看到三个信号模型主动输出工具调用 JSON、JSON 格式合法可解析、多步任务能按顺序调用多个工具。如果只满足第一个说明格式学会了但逻辑没学会需要补多步轨迹数据。5. 本篇常见错排查5.1 401 报错Key 没继承到子进程最常见的问题。你在 shell 里 export 了TAOTOKEN_API_KEY但 LLaMA-Factory 或 vLLM 是通过 subprocess 启动的环境变量没传进去。解决方法是启动命令前显式带上TAOTOKEN_API_KEY$TAOTOKEN_API_KEY llamafactory-cli train config.toml或者在 Python 脚本里用os.environ读取后显式传给 client不要依赖 shell 继承。5.2 对话模板用错导致乱输出LLaMA-Factory 的template字段必须和模型匹配。Qwen3 用qwenLlama-3 用llama3用错了模型会输出一堆特殊 token 或者直接乱码。检查方法训练日志里会打印实际用的 template对一下模型名。5.3 Loss Mask 没设对如果训练时 loss 一直降但推理效果差很可能是 loss mask 没把 user 和 system 部分屏蔽掉。LLaMA-Factory 默认会按 template 自动 mask但如果你用的是自定义数据格式需要确认train_on_inputs设为false。在config.toml的[data]段加train_on_inputs false5.4 工具调用 JSON 格式错误Agent 数据里如果混入了格式错误的 JSON模型会学到错误的格式。训练前跑一遍校验import json def validate(path): bad 0 with open(path, encodingutf-8) as f: for i, line in enumerate(f): item json.loads(line) for msg in item[messages]: if msg[role] assistant and msg.get(content, ).strip().startswith({): try: json.loads(msg[content]) except json.JSONDecodeError: print(f第 {i} 行格式错误) bad 1 print(f共 {bad} 条格式错误) validate(agent_sft_data.jsonl)5.5 数据分布不均导致通用能力丢失如果 SFT 数据全是工具调用模型微调后会变得只会调工具普通对话能力下降。建议在训练集里混入 20% 左右的通用对话数据保持基础能力。这个比例不是死的根据你的业务场景调。6. 把 Key 收口到一处链路才跑得顺整条链路跑下来你会发现真正省事的地方在于数据构造脚本、LLaMA-Factory 推理验证、Agent 调用测试全部读同一个TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL。换模型、换 Key、换环境只改环境变量代码和配置一行不动。如果你还在排障阶段建议先去控制台确认 Key 状态和额度https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后对照接入文档检查 base_url 有没有写错https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。验证模型输出是否正常可以直接在模型对话页面试几条https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果你打算长期跑 Agent 微调和编码任务Coding Plan 会比按量计费更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个实操建议训练前先用 100 条数据跑一个 epoch 的冒烟测试确认 loss 正常下降、验证输出格式正确再上全量数据。这一步能帮你省下大量返工时间。