zk-data-agent/skills/model-training-lite/SKILL.md

name, name_zh, description, when_to_use, aliases, examples, allowed_tools

name	name_zh	description	when_to_use	aliases	examples	allowed_tools
model-training-lite	轻量模型训练	从 Codex、Claude Code 或其他 Agent 通过用户提供的 Jupyter 环境和数据版本发起一次模型训练，并可选发起评测和生成轻量结果摘要；不包含自动数据增强闭环。	当用户已经准备好训练数据，想让 Agent 使用 Jupyter/CloudML 基于某个数据分支或 commit 发起一次模型训练、训练后评测、汇总结果，或询问如何把模型训练流程沉淀成轻量 skill 时使用。	jupyter-model-training, sft-submit, 轻量训练, 模型训练提交	用这个 Jupyter 和 ai-planning 当前分支重新发起训练 数据已经提交到 autoresearch-v1，帮我提交一次 SFT 帮我把 Codex 通过 Jupyter 发起模型训练的流程跑起来 检查一下训练工作区和 CML 环境，然后提交训练任务	read_file, write_file, grep_search, glob_search, ask_user_question, python_exec, bash

轻量模型训练

本 skill 是人机协同的训练/评测执行器：人负责目标和边界裁决，AI 负责候选、统计、证据整理和确定性执行。

人提出目标问题
  -> AI 整理候选、统计分布、生成 review 表
  -> 人确认边界、保留样本、数据是否入库
  -> AI 提交训练、发起评测、汇总结果
  -> 人判断是否继续下一轮

训练评测执行链路：

Jupyter 授权环境
  -> 创建/复用远端 kernel
  -> 准备隔离训练工作区
  -> 同步训练脚本与数据版本
  -> 检查 CML / 数据 / zk_trainer
  -> 提交 SFT
  -> 可选：SFT 成功后提交 CML 评测
  -> 可选：读取 workflow metric_diff 生成轻量结果摘要
  -> 返回 JobID、workflow ID、产物路径、摘要路径

不要把它扩展成 model-iteration 那种完整“baseline -> 分析 -> 增强 -> 训练 -> 评测 -> 再分析”的自主循环。本 skill 可以辅助人完成每一步决策前的信息准备，但不自动裁决边界、不自动修改数据、不自动生成增强样本、不自动进入下一轮训练。

必要输入

开始前必须拿到：

• Jupyter 地址和授权方式：URL；密码、token、cookie/session，或使用本地默认配置。
• 数据版本：git repo + branch + commit，或 git repo + branch，或远端工作区中已存在的数据路径。
• 训练配方：如果是当前 ZK 中控 SFT，默认复用 skills/model-iteration/scripts/；如果不是，必须让用户提供训练脚本、模板或命令。

通常用户只需要显式给 Jupyter 地址 和 数据版本。当前项目的默认训练配方可从本仓库继承，不必每次追问。

组内默认 Jupyter 配置路径：

skills/model-training-lite/jupyter_defaults.json

这个文件随 skill 提交，组内默认可直接使用。脚本输出只显示认证是否已配置，不回显密码。

个人覆盖配置路径：

skills/model-training-lite/.local/jupyter_defaults.json

.local/ 已加入 gitignore。需要临时覆盖组内默认配置时，使用 .local/ 或环境变量，不要改共享配置。

配置格式可参考：

skills/model-training-lite/jupyter_defaults.example.json

脚本也支持环境变量：

MODEL_TRAINING_LITE_JUPYTER_URL
MODEL_TRAINING_LITE_JUPYTER_PASSWORD
MODEL_TRAINING_LITE_JUPYTER_TOKEN
MODEL_TRAINING_LITE_JUPYTER_COOKIE
MODEL_TRAINING_LITE_JUPYTER_AUTH_TYPE

配置优先级：

脚本输入 > 环境变量 > .local/jupyter_defaults.json > jupyter_defaults.json

可选但推荐确认：

• owner：远端输出目录使用的用户前缀，例如 wuyang6。
• run_name：本次训练工作区名，例如 manual_YYYYMMDD_zk_intent_xxx。
• 是否训练后立刻发起评测。默认只提交训练；用户要求“训练后评测/看效果/分析结果”时启用。
• model_old：评测工作流中的对照模型路径；未提供时使用默认线上基线。

默认 ZK SFT 配方

当前 ZK 中控 SFT 复用这些文件：

skills/model-iteration/scripts/
  prepare_and_train_sft.py
  resolve_run_ids.sh
  submit_sft.sh
  submit_cml_eval.sh
  sft_train_job.yaml.tpl
skills/model-iteration/assets/config.yaml

默认基模和训练模板见 references/zk_sft_defaults.md。只有用户明确要求或训练任务不是 ZK 中控 SFT 时，才修改这些默认值。

推荐流程

0. 人机协同边界

AI 应主动辅助人完成信息准备，但不能替人拍板：

阶段	AI 负责	人负责
目标定义	把问题拆成可评测口径，列出候选集合和风险	确认目标问题和主指标
数据准备	调用相关 skill 生成候选、统计、review 表	判断边界样本是否保留
数据构造	参考 product-data 生成训练/评测格式	确认数据是否入库
标签判断	参考 label-master 校验 tag / function / complex	确认争议规则
线上挖掘	参考 online-mining-v2 获取 rid/session/prompt/output	确认挖掘口径
批量打标	参考 model-labeling 请求线上模型，生成基线	确认宽口径和人工 override
训练评测	本 skill 提交 SFT、评测、轻量摘要	决定是否继续下一轮

需要全自动假设驱动迭代时，使用 model-iteration，不要把本 skill 临时扩展成自动闭环。

1. 先生成提交计划

优先执行 portable script：

python skills/model-training-lite/scripts/render_sft_submission_plan.py --input input.json

输入示例：

{
  "jupyter_url": "https://.../lab?",
  "data_repo": "git@git.n.xiaomi.com:ai-service/ai-planning.git",
  "data_branch": "autoresearch-v1",
  "data_commit": "b92be709",
  "owner": "wuyang6",
  "run_name": "manual_20260528_zk_intent_clean_train",
  "recipe": "zk_sft",
  "run_eval": true,
  "model_old": "/mnt/wangsenhao/verl_zk/qwen4b_cispo_wokl_add_bvt_2/global_step_5/actor/huggingface"
}

脚本只生成计划和命令草案，不连接 Jupyter，不提交训练。

如果只提供 data_branch 不提供 data_commit，脚本会生成 git reset --hard origin/<branch>，并在结果中写 warning。正式训练报告里必须记录实际 git rev-parse HEAD，避免后续无法复现。

2. 连接 Jupyter

如果已经有 session/cookie，可直接调用 Jupyter REST API：

• GET /api/kernels 检查登录态。
• POST /api/kernels 创建 kernel；POST 需要 X-XSRFToken。
• websocket 连接 /api/kernels/<kernel_id>/channels 执行 Python/Bash。

如果没有登录态，用用户提供的密码/token 登录；不要把密码写入仓库、日志或最终报告。

3. 准备远端工作区

远端路径默认：

/mnt/wangsenhao/autoresearch-zk-users/<owner>/<run_name>

工作区内必须有：

scripts/
assets/
results/
output/
ai-planning/
zk_trainer/

把默认 ZK SFT 配方里的 scripts/ 和 config.yaml 同步到远端工作区。再 clone 或更新数据仓库，并 checkout 到用户指定 commit。

除 model-iteration 默认脚本外，还要同步本 skill 的轻量分析脚本：

skills/model-training-lite/scripts/summarize_eval_result.py

4. 提交前检查

提交训练前必须输出：

• ai-planning 当前 commit。
• 训练 JSONL 文件数量和总行数。
• 关键增量文件行数。
• 目标评测集行数，如果用户指定了评测集。
• source ~/.cloudml-cli/.profile 后 cml config show 可用。
• zk_trainer 已存在或 clone 成功。

如果 cml 不在 PATH，先检查 ~/.cloudml-cli/.profile。不要因为 which cml 为空就直接判定不可用。

5. 提交 SFT

ZK SFT 提交命令：

source ~/.cloudml-cli/.profile
export AUTORESEARCH_CHAT_ROOT=<remote_workspace>
export AUTORESEARCH_ROOT="$AUTORESEARCH_CHAT_ROOT"
cd "$AUTORESEARCH_CHAT_ROOT"
eval "$(./scripts/resolve_run_ids.sh)"
./scripts/submit_sft.sh "$SFT_RUNDIC"

注意：resolve_run_ids.sh 只输出 SFT_RUNDIC 和 EVAL_RUNDIC，不要读取不存在的 RUNDIC。

6. 成功判定

提交成功后必须回报：

• CloudML JobID。
• CloudML 链接。
• SFT_RUNDIC 和 EVAL_RUNDIC。
• 远端训练工作区。
• 成功标记路径：<remote_workspace>/sft_output/_SUCCESS。
• 查看状态命令：cml custom_train describe <JOB_ID>。

再查一次 cml custom_train describe <JOB_ID>，确认状态不是提交后立即失败。

7. 可选：训练后提交评测

只有用户要求“训练后评测/看效果/分析结果”时执行。

训练成功标记存在后：

source ~/.cloudml-cli/.profile
export AUTORESEARCH_CHAT_ROOT=<remote_workspace>
export AUTORESEARCH_ROOT="$AUTORESEARCH_CHAT_ROOT"
cd "$AUTORESEARCH_CHAT_ROOT"
eval "$(./scripts/resolve_run_ids.sh)"
./scripts/submit_cml_eval.sh "$EVAL_RUNDIC" "$AUTORESEARCH_CHAT_ROOT/sft_output" "<model_old>"

提交后必须回报：

• EVAL_RUNDIC
• CloudML workflow 提交输出
• 评测产物目录：/mnt/xiaoai-zk-model-train-tj5/workflow5/workflow<EVAL_RUNDIC>/
• 评测完成标记：metric_diff/lark_template.json

8. 可选：轻量结果摘要

评测产物落盘后执行：

python "$AUTORESEARCH_CHAT_ROOT/scripts/summarize_eval_result.py" \
  --workflow-root /mnt/xiaoai-zk-model-train-tj5/workflow5 \
  --run-dic "$EVAL_RUNDIC" \
  --output "$AUTORESEARCH_CHAT_ROOT/results/eval_summary_${EVAL_RUNDIC}.md"

摘要脚本只做轻量汇总：

• 从 metric_diff/lark_template.json 尽力抽取指标。
• 从 metric_diff/specific_comparison.csv 汇总错误分布和错误样例。
• 不做数据增强建议，不做训练集修改，不替代 model-iteration 的深度归因。

边界

• 不自动修改训练数据。
• 不自动做深度错误归因；只允许生成轻量指标/错误分布摘要。
• 不自动生成增强样本。
• 不默认串接评测；训练成功后是否评测由用户或后续明确指令决定。
• 不把 Jupyter 密码、CloudML key、cookie 写进产物或最终回复。