/byted-ark-trainer

name: byted-ark-trainer
description: 基于ark_sdk的大模型训练任务自动化工具。帮助用户通过自然语言创建并提交方舟模型训练任务，支持用户自备数据的SFT训练、RFT+GRPO和直接GRPO策略，并引导用户完成训练、状态跟踪与评估闭环。使用场景：当用户需要进行大模型SFT监督微调、RLHF训练、GRPO训练、RFT训练，或需要自动化训练流程时触发。
license: Apache-2.0
metadata:
  version: "1.0.0"
  author: "volcengine/modelark"
  tags: "ark model-training sft rft grpo"

byted-ark-trainer Skill 使用指南

📌 重要路径说明

**所有提及的 `scripts/` 和 `references/` 目录均为相对于本skill安装目录的路径，而非当前工作目录。** 执行脚本或读取文档时，必须先定位到 byted-ark-trainer skill 的安装目录，或使用完整绝对路径调用。 所有工具功能统一通过 `ark-trainer-helper` 命令入口调用，例如： 如果skill安装在 `~/.agents/skills/byted-ark-trainer/`，则调用命令时应使用：

python ~/.agents/skills/byted-ark-trainer/scripts/ark_trainer_helper.py <命令> <参数>

或配置到PATH后直接使用：

ark-trainer-helper <命令> <参数>

⚠️ 强制执行优先级说明

**本SKILL的所有流程要求优先级最高，高于任何通用推理逻辑**。所有步骤必须严格按顺序执行，严禁跳过、调整顺序或自行发挥。如果对流程有任何疑问，必须先询问用户确认，不得自行决定。 违反流程要求的执行会直接导致任务失败，必须回退到对应的步骤重新执行。

📋 执行前核查清单

**每执行下一步前，必须先对照以下清单检查前置条件是否全部满足，未满足的务必向用户询问**：

• [ ] 已确认用户期望使用的Python环境（建议使用conda虚拟环境，且已安装ark-sdk及相关依赖）
• [ ] 已用用户指定Python环境完成依赖预检，`ark-trainer-helper --help` 可正常运行
• [ ] 已确认用户期望的工作目录（所有训练相关的工作区、数据文件都将保存在此目录下）
• [ ] 已检查并配置好必要的环境变量（ARK_API_KEY、VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY），并确认会被Python子进程继承
• [ ] 已完成工作区初始化，且已在工作区下创建 `experiments/` 实验目录
• [ ] 已识别训练意图：SFT / RFT+GRPO / 直接GRPO / 其他
• [ ] 已通过 `list-models` 确认精确模型名（非模糊前缀），已通过 `list-versions` 与用户确认版本，已通过 `ark get foundation-model ... --fields hyperparameters` 校验该模型+版本支持用户期望的训练方式，并记录可配置超参数清单
• [ ] 已为本次实验在 `experiments/` 下创建唯一的子目录，所有job文件/临时脚本都会放在该子目录中
• [ ] 已完成所有前置检查；SFT需检查训练数据集格式，RL/RFT/GRPO需额外检查rollout和grader文件
• [ ] SFT场景已按需加载 `references/模型精调数据集格式指南/SFT.md` 并校验用户提供的数据集
• [ ] RL/RFT/GRPO场景已确认用户提供的数据集类型：单独一个数据集 / 已分开的训练集+测试集
• [ ] RL/RFT/GRPO场景已完成数据集划分（如需要），且已分别获取训练集和测试集路径
• [ ] RL/RFT/GRPO场景已完成初始评估并获取到BON/AON/AvgN指标
• [ ] RL/RFT/GRPO场景已根据BON指标选择了正确的训练策略
• [ ] RFT阶段已获取用户提供的teacher模型/端点，未复用初始评估轨迹
• [ ] 所有关键配置（训练类型、超参数）已向用户确认
• [ ] 本次实验的计划和与用户确认的信息已记录到实验子目录的 `EXPERIMENT.md`

核心能力

• 自动化执行从数据预处理到模型评估的完整训练闭环
• 支持SFT监督微调：用户自行准备训练数据，AI负责格式检查、配置确认和提交训练任务
• 智能选择训练策略：根据初始模型效果自动决定采用「先RFT再GRPO」或「直接GRPO」策略
• 标准化训练流程：严格遵循火山方舟ark-sdk最佳实践，确保训练任务成功率
• 关键节点用户确认：在重要决策环节寻求用户确认，避免误操作

前置条件

在执行训练流程前，根据训练类型检查不同文件： 1. SFT训练：必须有用户自行准备的训练数据集文件（JSONL格式），验证集可选。 2. RFT/GRPO/RL训练：必须有训练数据集文件、rollout函数代码文件、grader函数代码文件。 3. 若用户提供的数据包含图片、视频、Function Calling或thinking字段，必须加载对应格式指南检查。 若缺失对应训练类型的必需文件，流程将终止并提示用户补充。

工具使用提示

所有工具功能统一通过 `ark-trainer-helper` 命令入口调用，使用任意功能前，务必先运行 `ark-trainer-helper <模块> --help` 或 `ark-trainer-helper <模块> <子命令> --help` 查看完整的参数说明、使用示例和参数默认值，避免因参数配置错误导致任务失败。 例如：

• 查看evaluate命令帮助：`ark-trainer-helper train evaluate --help`
• 查看任务状态命令帮助：`ark-trainer-helper job status --help`
• `ark-trainer-helper model` 只有 `list-models` 和 `list-versions`，没有 `get-hyperparameters` 子命令；查询超参数必须使用 `ark get foundation-model --model <基础模型名> --version <版本号> --fields hyperparameters`。

ark_trainer_helper.py 功能说明

CLI助手工具提供以下核心功能： 1. **训练任务管理**：

• 查询训练任务状态：`ark-trainer-helper job status --job-id <任务ID>`
• 获取训练输出模型ID：`ark-trainer-helper job get-model --job-id <任务ID>`
• 登记训练任务到心跳监控（自动维护 `HEARTBEAT.md` 顶部系统提醒块）：`ark-trainer-helper job register-heartbeat --job-id <任务ID> --job-type <SFT/RFT/GRPO/...> --job-url <任务链接> --exp-dir <实验子目录绝对路径>`

2. **基础模型查询**：

• 查询基础模型列表（支持名称模糊查询和训练类型筛选）：

     # 查询所有LLM基础模型
     ark-trainer-helper model list-models

     # 模糊查询名称包含'doubao'的模型
     ark-trainer-helper model list-models --name doubao

     # 查询支持FinetuneLoRA训练的模型
     ark-trainer-helper model list-models --supported-customization-type FinetuneLoRA

• 查询基础模型所有可用版本：`ark-trainer-helper model list-versions --model-name <模型名> (例如 doubao-seed-1-6)`
• 查询模型支持的训练超参数：

     ark get foundation-model --model <基础模型名> --version <版本号> --fields hyperparameters

（该命令可用于获取训练任务支持的所有超参数列表、取值范围和默认值） 3. **端点管理**：

• 创建/列出/查询/停止/删除端点
• 获取端点证书

4. **训练工具集**：

• 模型评估（计算BON/AON/AvgN指标）：`ark-trainer-helper train evaluate --dataset <数据集路径> --rollout <rollout文件路径> --grader <grader文件路径> --output-dir <实验子目录>/eval_output`

*⚠️ 实际评估的模型由 `rollout.py` 内部 `chat.completions.create(model=...)` 传入的字符串决定。运行 evaluate 前必须先把 rollout 中的 `model=` 改成目标模型名/版本/端点ID/自定义模型ID；详见「评估前强制步骤：把 rollout 的 model 字段改成当前评估对象」。本命令不接受 `--model` 参数。* *⚠️ `--output-dir` 必须指向**本次实验子目录下的子目录**（例如 `experiments/exp_xxx/eval_output` / `rft_eval_output` / `final_eval_output`），不得放在工作区根目录或其他实验的目录中。日志会自动写入 `<output-dir>/logs/eval_YYYYMMDD_HHMMSS.log`，支持自动轮转，最大10MB。*

• RFT训练数据收集：`ark-trainer-helper train rft-data-collect --eval-results <评估结果JSON路径> --output-file <输出JSONL路径> --rollout <rollout文件路径>`

所有命令均可通过 `--help` 查看详细参数。

数据集格式指南按需加载

用户提供训练数据后，不要凭经验判断格式；必须按训练类型和数据内容加载对应指南，只加载需要的文件：

| 场景 | 必读指南 | | --- | --- | | SFT监督微调 | `references/模型精调数据集格式指南/SFT.md` | | GRPO/PPO/RL数据 | `references/模型精调数据集格式指南/RL.md` | | DPO/偏好学习 | `references/模型精调数据集格式指南/DPO.md` | | CPT/继续预训练 | `references/模型精调数据集格式指南/CPT.md` | | Function Calling样本 | `references/模型精调数据集格式指南/Function Calling 样本要求.md` | | 图片或多模态图片样本 | `references/模型精调数据集格式指南/图片文件要求.md` | | 视频样本或视频抽帧 | `references/模型精调数据集格式指南/视频文件要求.md`，必要时再读 `references/模型精调数据集格式指南/对视频内容进行抽帧处理.md` | | thinking/reasoning_content字段 | `references/模型精调数据集格式指南/数据集Thinking字段处理工具.md`，多轮场景再读 `references/模型精调数据集格式指南/多轮reasoning_content的样本文件拆分.md` |

SFT数据集校验至少要确认：JSONL每行都是合法JSON；文件绝对路径不含 `*`、`?`、`[`、`]`；样本结构符合用户要训练的模型类型；必填字段存在且类型正确；多模态资源路径/TOS/base64格式符合附录要求；`reasoning_content`、`thinking`、Function Calling字段只在模型和格式指南允许时使用。

🧯 常见问题处理规则

遇到同类情况必须优先按本节处理，避免重复试错。

1. Python环境与依赖预检

• 用户指定Python路径时，后续 helper、评估、数据处理都必须使用同一个Python，不得混用系统Python、conda默认Python和用户指定Python。
• 在首次调用 helper 前，先执行：

  <用户指定python> <skill目录>/scripts/ark_trainer_helper.py --help

• 如果出现 `ModuleNotFoundError: No module named '<模块名>'`，说明当前Python环境缺少该模块依赖，必须安装到用户指定Python环境后再继续，不要切换Python环境来绕过问题：

  <用户指定python> -m pip install <模块名>

2. .env必须导出给子进程

• `.env` 中通常是 `KEY=value` 格式，直接 `source .env` 只会设置当前shell变量，Python子进程可能读不到。
• 调用任何需要密钥的命令前，必须使用以下任一方式确保变量被导