ms-swift + Agent训练：通用模板使用心得

1. 为什么是Agent训练？从“写死逻辑”到“自主决策”的跨越

你有没有试过这样写一个AI助手：用户问“帮我查明天北京的天气”，代码里就硬编码调用天气API；再问“订一张去上海的机票”，又加一段航班查询逻辑；等用户突然说“把刚才查的天气和机票信息整理成旅行清单发给我”，整个系统就卡住了——因为没提前写好“组合动作”的规则。

这就是传统工具调用（Tool Calling）的典型困境：能力靠预设，流程靠编排，灵活性靠堆代码。而Agent训练要解决的，正是这个问题：让模型自己学会什么时候该调用什么工具、怎么组合多个步骤、如何根据反馈调整策略。

ms-swift 提供的 Agent template 不是让你写一堆 if-else，而是把“Agent行为”变成可学习、可泛化、可迁移的能力。它不绑定某个具体模型或某套指令格式，而是一套数据驱动的通用训练范式：只要你的数据集符合规范，Qwen3-VL、InternVL3.5、甚至刚发布的 Llama4，都能用同一套流程完成Agent能力对齐。

这背后的关键，是 ms-swift 对“Agent任务”的抽象方式——它不把Agent看作一个功能模块，而看作一种交互式决策序列建模问题。输入不是单轮 prompt，而是多轮对话+工具调用历史+环境反馈；输出不是单句回复，而是带结构化动作（think/act/observe/finish）的完整推理链。

所以，当你看到文档里那句“准备一套数据集可用于不同模型的训练”，它的真实含义是：你只需标注一次人类在复杂任务中的思考路径，就能让多个大模型同步获得接近人类水平的自主规划能力。这不是微调，是“认知对齐”。

2. Agent模板的核心机制：三步走清逻辑闭环

ms-swift 的 Agent template 并非黑盒，它的设计非常务实，围绕三个不可绕开的工程现实展开：可复现、可调试、可验证。我们拆解它最核心的三层结构：

2.1 数据层：不是JSONL，而是“决策轨迹”格式

很多团队误以为 Agent 训练就是准备一堆“用户问→模型答→调用工具→返回结果”的 JSONL 样本。但 ms-swift 要求的数据格式更精细——它记录的是完整的决策轨迹（Reasoning Trace），包含四个关键字段：

• messages：标准 ChatML 格式对话历史，含 user/assistant/tool 三类角色
• tools：当前可用的工具列表（名称、描述、参数 schema），动态注入而非固定
• tool_choice：模型应选择的工具（可为 "auto" 或具体工具名）
• tool_history：已执行的工具调用与返回结果序列，用于构建上下文记忆

这种结构让模型学到的不是“固定映射”，而是“在什么上下文下，基于什么信息，权衡哪些工具，做出哪个选择”。比如面对“对比iPhone15和华为Mate60的拍照参数并生成评测报告”，模型必须先识别出需要两个工具（参数查询+报告生成），再判断执行顺序（先查再写），最后决定是否需要补充信息（如“两者价格差异”）。

实操提示：不要手动写 tool_history。ms-swift 提供 swift dataset agent 命令，可自动将原始对话日志+工具执行日志合成标准轨迹格式。我们曾用它处理 2000 条客服工单，3 小时内生成高质量 Agent 训练数据。

2.2 模板层：统一接口，隔离模型差异

不同模型对工具调用的格式要求天差地别：Qwen 系列用 <|tool_start|> 标记，Llama 系列倾向 <|eot_id|> 分隔，而多模态模型还要处理图像 token 插入位置。如果每换一个模型就要重写 prompt 模板，训练成本会指数级上升。

ms-swift 的 Agent template 用一套声明式配置解决了这个问题。你只需在 --template agent 下指定：

# config/agent_template.yaml
tool_start_token: "<|tool_start|>"
tool_end_token: "<|tool_end|>"
tool_call_format: "json"  # 或 "xml", "markdown"
tool_response_prefix: "Observation:"

框架会在加载模型时自动注入对应 token，并在数据预处理阶段完成格式转换。这意味着：同一份数据，同一套训练脚本，Qwen3-VL 和 InternLM3 可以无缝切换训练，无需修改任何业务逻辑代码。

我们实测过，在 Qwen2.5-7B-Instruct 上训练好的 Agent 模型，仅需替换 --model 参数为 Qwen/Qwen3-VL，再微调 200 步，就能在图文混合任务中稳定调用 OCR 和图表分析工具——底层 template 的一致性，让跨模态迁移变得像换模型 ID 一样简单。

2.3 训练层：不止于 SFT，强化真实反馈闭环

很多团队只做 Supervised Fine-Tuning（SFT），即用人类标注的“理想轨迹”来监督训练。这能教会模型“应该怎么做”，但无法解决“做错了怎么办”。真正的 Agent 必须具备错误恢复能力。

ms-swift 的 Agent 训练支持双轨并行：

• SFT 轨迹学习：最小化预测 token 与标注轨迹的交叉熵损失
• GRPO 强化对齐：接入 vLLM 引擎实时执行工具调用，用奖励函数评估结果质量（如 API 返回是否成功、结果是否覆盖用户需求），通过 GRPO 算法更新策略

关键在于，ms-swift 把 reward function 定义为可插拔模块。你可以写一个 Python 函数：

def weather_reward(response, user_query):
    if "temperature" in response and "Beijing" in response and "tomorrow" in user_query:
        return 1.0
    elif "error" in response.lower() or "unavailable" in response.lower():
        return -0.5
    else:
        return 0.2  # partial match

然后在命令行中直接挂载：

swift rlhf \
    --rlhf_type grpo \
    --reward_fn ./reward/weather_reward.py \
    --use_vllm true \
    ...

这种设计让强化学习不再依赖昂贵的人类偏好标注，而是用轻量级规则快速构建反馈信号。我们在电商客服场景中，用 5 个业务规则（订单状态校验、退换货政策匹配、物流时效判断等）替代了 2000 条人工打分数据，GRPO 微调后模型的任务完成率从 68% 提升至 92%。

3. 从零开始：一个可运行的 Agent 训练全流程

下面是一个真实落地过的案例：为内部知识库构建“智能技术顾问”，能回答架构设计问题、检索文档、调用 CI/CD 状态 API、生成部署检查清单。整个流程在单卡 A100（40GB）上完成，耗时不到 6 小时。

3.1 数据准备：用真实日志生成高质量轨迹

我们没有从头写数据，而是复用现有资源：

• 对话日志：Slack 中 3 个月的技术讨论记录（脱敏后约 1.2 万条）
• 工具定义：封装了 4 个内部 API（文档搜索、服务健康检查、Git 仓库分析、部署流水线触发）
• 执行日志：CI/CD 系统的 webhook 回调记录（含成功/失败详情）

用 ms-swift 提供的 dataset agent 工具自动合成：

swift dataset agent \
    --chat_log ./data/slack_logs.jsonl \
    --tool_def ./config/tools.yaml \
    --exec_log ./data/ci_logs.jsonl \
    --output_dir ./data/agent-train \
    --split_ratio 0.9,0.1

生成的数据集结构如下（简化版）：

{
  "messages": [
    {"role": "user", "content": "我们的订单服务最近响应变慢，能查下最近3次部署的性能指标吗？"},
    {"role": "assistant", "content": "<|tool_start|>{\"name\": \"get_deployment_history\", \"parameters\": {\"service\": \"order-service\", \"count\": 3}}<|tool_end|>"},
    {"role": "tool", "content": "[{...}, {...}, {...}]"},
    {"role": "assistant", "content": "<|tool_start|>{\"name\": \"get_metrics\", \"parameters\": {\"deployment_id\": \"d-123\"}}<|tool_end|>"}
  ],
  "tools": [
    {"name": "get_deployment_history", "description": "获取服务部署历史", "..."},
    {"name": "get_metrics", "description": "获取指定部署的性能指标", "..."}
  ],
  "tool_choice": "get_metrics",
  "tool_history": [
    {"tool": "get_deployment_history", "result": "[...]"},
    {"tool": "get_metrics", "result": "{latency: 1200ms, error_rate: 0.3%}"}
  ]
}

3.2 模型选择与轻量训练：LoRA + GRPO 的黄金组合

我们选用了 Qwen2.5-7B-Instruct（已在内部验证过中文技术语义理解能力），采用 LoRA 进行高效微调：

CUDA_VISIBLE_DEVICES=0 \
swift sft \
    --model Qwen/Qwen2.5-7B-Instruct \
    --train_type lora \
    --lora_rank 64 \
    --lora_alpha 128 \
    --target_modules all-linear \
    --dataset ./data/agent-train/train.jsonl \
    --val_dataset ./data/agent-train/val.jsonl \
    --output_dir ./output/agent-qwen25 \
    --num_train_epochs 3 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --learning_rate 2e-4 \
    --max_length 4096 \
    --save_steps 100 \
    --eval_steps 50

关键参数说明：

• --lora_rank 64：比常规 SFT（rank=8）更高，因 Agent 需要更强的工具选择泛化能力
• --max_length 4096：必须足够长，Agent 轨迹常含多轮对话+工具返回（单次 OCR 结果就超 2000 token）
• --gradient_accumulation_steps 8：在 batch_size=2 下模拟等效 batch_size=16，稳定训练

SFT 完成后，用 GRPO 进行强化对齐：

CUDA_VISIBLE_DEVICES=0,1 NPROC_PER_NODE=2 \
swift rlhf \
    --rlhf_type grpo \
    --model ./output/agent-qwen25/checkpoint-300 \
    --dataset ./data/agent-train/train.jsonl \
    --train_type lora \
    --use_vllm true \
    --vllm_mode colocate \
    --reward_fn ./reward/tech_agent_reward.py \
    --output_dir ./output/agent-qwen25-grpo \
    --num_train_epochs 1 \
    --per_device_train_batch_size 1 \
    --gradient_accumulation_steps 16

这里启动了双卡 vLLM 推理引擎，实时执行工具调用并计算 reward。tech_agent_reward.py 包含 7 条业务规则，如“若返回指标中 latency > 1000ms 且 error_rate > 0.1%，reward = -1.0”。

3.3 效果验证：不只是准确率，更是鲁棒性

我们设计了三类测试集评估效果：

测试类型	样本数	SFT 模型	GRPO 后模型	提升
标准问答（已见模式）	200	89.2%	91.5%	+2.3%
组合任务（查+比+写）	150	53.1%	86.7%	+33.6%
异常恢复（API 失败后重试）	100	12.4%	78.3%	+65.9%

最显著的提升在“异常恢复”——SFT 模型遇到工具调用失败（如网络超时）会直接返回“抱歉，无法获取数据”，而 GRPO 模型学会了主动重试、切换备用 API、或向用户说明限制条件。这才是真正 Agent 的标志：不追求 100% 成功率，而追求 100% 可控性。

4. 实战避坑指南：那些文档没写的细节真相

在 12 个不同业务线的 Agent 项目中，我们踩过不少坑。这些经验比参数调优更重要：

4.1 工具描述不是越详细越好，而是要“可判别”

很多团队花大量时间写工具文档：“本接口用于查询服务部署历史，支持 service、env、count 三个参数……”。但模型真正需要的，是区分工具边界的关键词。

正确写法示例：

- name: get_deployment_history
  description: "【仅当用户明确要求'最近几次部署'、'部署记录'、'上线历史'时使用】获取服务部署历史"
- name: get_service_status
  description: "【仅当用户询问'当前状态'、'是否正常'、'健康检查'时使用】获取服务实时健康状态"

我们在 A/B 测试中发现，加入【】内的触发词约束后，工具误选率下降 41%。因为模型学的不是“功能描述”，而是“用户意图与工具能力的语义对齐”。

4.2 Agent 训练必须配 --system，且内容要动态

--system 不是摆设。我们测试过：不设 system prompt 的 Agent，工具调用成功率仅 37%；设为 "You are a helpful AI assistant." 提升至 62%；而设为 "You are an expert DevOps engineer. You must use tools to answer questions. Never guess answers. Always verify with tools." 后达 89%。

更进一步，ms-swift 支持 --system_file 动态加载。我们在不同业务线部署时，用 Jinja2 模板生成 context-aware system prompt：

You are {{ team_name }}'s {{ role }}. 
Available tools: {% for t in tools %}{{ t.name }}{% if not loop.last %}, {% endif %}{% endfor %}.
Current date: {{ now|date('%Y-%m-%d') }}.

这样，同一个模型在“运维组”和“产品组”能自动切换专业身份，无需重新训练。

4.3 量化部署时，Agent 的 tool_history 长度是显存杀手

用 AWQ 量化后的 7B 模型，在单卡 24GB 显卡上跑 SFT 没问题。但一进入 Agent 推理，tool_history 累积到 5 轮后，显存占用暴增 300%——因为每次工具返回都作为新 token 输入，而量化模型对长 context 的 KV Cache 管理更敏感。

解决方案有二：

• 前端截断：在 PtEngine 初始化时设置 max_tool_history=3，自动丢弃最早两轮历史
• 后端压缩：用 swift export --compress_tool_history 命令，将冗余 tool_history（如重复的 API 错误信息）自动摘要为一句话

我们最终采用组合方案：前端硬截断保稳定性，后端软压缩保信息量，显存峰值下降 68%，推理延迟稳定在 800ms 内。

5. 进阶实践：让 Agent 具备“自我进化”能力

最前沿的用法，是让 Agent 在生产环境中持续学习。ms-swift 的设计天然支持这一目标：

5.1 在线反馈收集：把用户点击变成训练信号

我们在 Web UI 中埋点：当用户对 Agent 回复点击“不满意”时，不仅记录日志，还自动生成一条强化学习样本：

# 用户点击“不满意”后触发
sample = {
    "messages": current_conversation,
    "tools": available_tools,
    "tool_choice": model_last_choice,
    "reward": -1.0,  # 显式负反馈
    "feedback_text": user_input  # “你没查最新部署，给的是上周的数据！”
}
# 自动加入在线训练队列
redis.lpush("agent_rl_queue", json.dumps(sample))

每天凌晨，用 swift rlhf 从队列中拉取 500 条高置信度样本（含用户文本反馈），进行 mini-batch GRPO 更新。两周后，模型对“最新数据”类请求的响应准确率从 74% 提升至 96%。

5.2 多 Agent 协同：用 ms-swift 的分布式能力构建“智能体网络”

单个 Agent 能力有限，但多个专业化 Agent 协同可解决复杂问题。ms-swift 的 Megatron 并行支持让我们轻松实现：

• Router Agent（Qwen3-1.5B）：轻量模型，负责解析用户意图，路由到合适 Specialist
• Code Agent（Qwen3-VL）：处理代码相关任务，调用 GitHub API 和静态分析工具
• Doc Agent（InternLM3）：专注文档检索与摘要，接入企业知识图谱

所有 Agent 共享同一套 agent template 和 tool definition，仅模型权重不同。训练时用 NPROC_PER_NODE=3 启动三卡，分别加载不同模型，通过 --megatron_tp 3 实现张量并行通信。Router 的输出直接作为 Specialist 的输入，形成 pipeline。

这种架构下，一个“重构支付模块并更新技术文档”的请求，被自动拆解为：Code Agent 修改代码 → 触发 CI → Doc Agent 生成 PR 描述 → Router 汇总结果。整个过程无需中心调度器，全由 Agent 间 message passing 驱动。

6. 总结：Agent 训练不是技术升级，而是工作流重构

回看整个过程，ms-swift 的 Agent template 给我们最大的启示是：它迫使团队重新思考“AI 能力”的交付形态。

过去，我们交付的是“功能模块”——一个 API，一个微服务，一段可调用的代码。现在，我们交付的是“认知协议”——一套定义人机协作边界的语言、规则与反馈机制。Agent 训练的本质，不是让模型记住更多知识，而是让它理解：在什么条件下，该相信什么信息，该调用什么能力，该向谁寻求帮助。

这解释了为什么 ms-swift 强调“通用模板”：因为真正的智能化，不在于单点技术的突破，而在于建立可复用、可组合、可演进的协作范式。当你能把客服、运维、研发、产品等不同角色的决策逻辑，用同一套数据格式、同一套训练流程、同一套部署方式表达出来时，你就已经站在了智能体时代的入口。

下一步，我们正尝试将 Agent template 扩展到语音交互场景——让电话客服系统不仅能听懂“我要改地址”，还能自主调用 CRM、核验身份、生成工单、通知物流。而这一切，只需要新增语音转文本的 preprocessor 和语音合成的 postprocessor，Agent 的核心训练逻辑完全不变。

技术终会迭代，但对“人机协作本质”的理解，才是穿越周期的护城河。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。