byted-ark-trainer

Files (25)

• LICENSE
• SKILL.md
• RL guide.md · references/
• ark-sdk guide.md · references/
• README.md · references/templates/
• job_grpo_lora.py · references/templates/
• job_grpo_lora.yaml · references/templates/
• job_sft_lora.py · references/templates/
• job_sft_lora.yaml · references/templates/
• CPT.md · references/模型精调数据集格式指南/
• DPO.md · references/模型精调数据集格式指南/
• Function Calling 样本要求.md · references/模型精调数据集格式指南/
• RL.md · references/模型精调数据集格式指南/
• SFT.md · references/模型精调数据集格式指南/
• 图片文件要求.md · references/模型精调数据集格式指南/
• 多轮reasoning_content的样本文件拆分.md · references/模型精调数据集格式指南/
• 对视频内容进行抽帧处理.md · references/模型精调数据集格式指南/
• 数据集Thinking字段处理工具.md · references/模型精调数据集格式指南/
• 视频文件要求.md · references/模型精调数据集格式指南/
• ark_trainer_helper.py · scripts/
• __init__.py · scripts/modules/
• endpoint.py · scripts/modules/
• job.py · scripts/modules/
• model.py · scripts/modules/
• train.py · scripts/modules/

SKILL.md (first lines)

# byted-ark-trainer Skill 使用指南

## 📌 重要路径说明
**所有提及的 `scripts/` 和 `references/` 目录均为相对于本skill安装目录的路径，而非当前工作目录。**
执行脚本或读取文档时，必须先定位到 byted-ark-trainer skill 的安装目录，或使用完整绝对路径调用。
所有工具功能统一通过 `ark-trainer-helper` 命令入口调用，例如：
如果skill安装在 `~/.agents/skills/byted-ark-trainer/`，则调用命令时应使用：
```bash
python ~/.agents/skills/byted-ark-trainer/scripts/ark_trainer_helper.py <命令> <参数>
```
或配置到PATH后直接使用：
```bash
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. **基础模型查询**：
   - 查询基础模型列表（支持名称模糊查询和训练类型筛选）：
     ```bash
     # 查询所有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)`
   - 查询模型支持的训练超参数：
     ```bash
     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 前，先执行：
  ```bash
  <用户指定python> <skill目录>/scripts/ark_trainer_helper.py --help

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples