submit-volc-training-task

Imported from CXP-2024/tutorial (skills/submit-volc-training-task/SKILL.md). Install upstream with npx skills add CXP-2024/tutorial --skill submit-volc-training-task. Copyright stays with the author.

火山训练任务提交与通知

先区分正式训练与提交测试

• 用户要求正式训练：读取当前工作区的 AGENTS.md 和任务配置，按下节选择来源并替换训练命令。
• 用户要求提交 test/smoke 验证队列：使用自动退出的最小资源诊断任务，检查工作区/环境/输出挂载与 CUDA；不默认启动训练、不加载大型 checkpoint、不复用来源的长期运行命令。用户已指定队列时以该队列为准。来源只用于核实镜像、资源规格和挂载，优先同队列的可用模板；用户未指定且查询无法确定时再询问。
• test 提交同样需要真实认证、挂载核验、唯一任务名与提交后查询；不将只读查询成功说成创建权限已验证。test 不自动停止/删除 xx 或其他任务，也不启动长期补位服务。
• 正式训练的 finetune.sh / exp_name / edp.card 校验不适用于纯 shell/Python test；使用维护工具的 preflight --workload command --entrypoint-file ...，精确核验已审核入口，保留一次提交和恢复保护。

当前 GalaxeaFM worktree

在 GalaxeaFM worktree 中提交时，先读 worktree 与短任务约定。核心规则：

• git rev-parse --show-toplevel 确定实际代码根；不能复制模板中的其他用户代码目录。
• 从 git rev-parse --path-format=absolute --git-common-dir 找到主仓及环境初始化脚本；初始化可能改变 cwd、PYTHONPATH 或 CUDA_VISIBLE_DEVICES，必须恢复当前 worktree，并保留平台分配的 GPU 可见范围。
• 显式设置当前 worktree 的 src、根目录以及所需实验脚本路径。共享 worktree 中未提交、未跟踪、被忽略的文件不会自动被 Git/TOS 代码上传携带；采用已授权共享挂载时核验实际文件存在。
• 训练通过 bash scripts/run/finetune.sh <task> 启动，不传具体 GPU 数字；不从模板盲继承 batch/LR/epochs 来覆盖本任务 YAML。
• 输出、日志和提交记录位于该实验 workspace 内；已有结果不覆盖，已有本地评估不因队列测试被停止。

正式训练来源与参数

• 用户指定来源或明确要求沿用默认时直接使用；否则需要复制平台配置而无法从上下文确定来源时，合并询问来源及缺少的新任务信息。历史来源 t-20260903151751-wwnh8（北京、motor_0826_4view_rtc8_s2x_t1x_arclean）仅是候选模板，不是所有 worktree 的默认训练配方。
• 替换实际 Entrypoint 中的 Hydra task、exp_name、edp.card，以及与当前 worktree 不同的代码/环境入口；不只修改平台任务名。
• 用户给出 YAML 时去掉 configs/task/ 和 .yaml 得到 Hydra task；默认路径末段为 exp_name 与 edp.card。用户明确指定各值时优先采用。
• 学习率、batch、梯度累积、epoch、checkpoint 从此次有效配置和用户约束确定。只保留已经确认需要的模板 overrides；对照实验另核对 global batch 与实际更新数，不能仅按卡数缩放学习率。
• 提交前展示来源、worktree、队列、GPU 资源、入口关键改动和独立输出位置。遵守 AGENTS.md 对新训练 YAML 的真实短训练验收要求；纯提交/环境 smoke 不伪装成完成了训练验收。

提交与复制

• 使用本机实际支持的 CLI 入口，先核对对应子命令的 --help；顶层帮助不能算子命令可用，必要时检查同安装目录的 mlp。认证测试只读查询用户指定的任务，查询成功不等于已验证创建权限。用户已要求后续训练时，可在数据处理中提前完成这些检查。
• 优先使用已有凭据。不得把 AK/SK、token 写入 skill、任务产物、通知或代码仓库，也不得打印凭据。临时配置需限制权限并在 finally 中恢复实际改动的配置；不要整体覆盖 .volc，其中可能有只读的托管 token。持续监控需要持续可用的认证，不能删除唯一凭据后声称监控仍可工作。
• 记录实际认证来源及环境优先级，不记录凭据值。没有受支持的身份查询证据时，调用者为未知；不能把本机用户名、开发机所有者或来源任务创建者当作 API 调用者。
• 用户已要求复制并重新提交时，沿用该授权。仅问“能否提交”或测试认证，不等于要求创建训练任务。
• 用 volc ml_task export --task <source_id> --config 在独立产物目录导出配置。检查镜像、启动命令、队列、worker 数、每 worker GPU 数、挂载、环境变量、重试设置及运行时限。导出配置可能遗漏优先级等字段，结合原任务详情核对，不能默认为完整快照。
• 提交前将真实代码、数据、模型、输出及缓存路径映射到所需挂载和读写模式。移除无用挂载或缩小范围时保存差异；代码只读前检查环境初始化和缓存写入，核实 CLI 字段实际映射到 API。本机可读或开发机已挂载不证明新任务的挂载授权。最小必要访问仍被 ACL 明确拒绝时停止提交，报告具体权限对象与已知认证来源，等待真实权限或认证修复，不自行授权或绕过 ACL。
• 平台任务名优先使用用户指定名称，否则基于新 exp_name 加可辨识的复制后缀；原样重跑时基于原名称加后缀。平台任务名后缀不自动加到 exp_name 或 edp.card。保留用户要求沿用的训练参数。检查输出路径是否会覆盖原结果。共享挂载中的代码与数据使用提交时的当前内容，复制平台配置不保证复现原任务的历史代码。
• 用 volc ml_task submit --conf <yaml> --task_name <name> --output json 提交，必要时显式补齐原优先级等字段。得到 ID 后立即只读查询验证。超时或响应不明确时，先查找此次唯一任务名，避免重复提交；不要自动重试训练或改用更多资源。
• 使用 维护工具 的 inspect-source、preflight、submit、recover 完成早期只读检查、离线预检、持久一次提交及恢复查询。它提交已审核配置，不替代前述来源和三个字段的精确替换，也不替代数据验收。已有用户授权直接记录沿用，不重复询问是否提交。
• 提交失败要保留退出码、脱敏错误码和短原因，不能只吞成“CLI 非零退出”；必要目录和访问模式应保留，凭据与配置全文不得进入日志。非零或未返回 ID 不证明未创建，先按完整状态集合分页精确查名；具体问题修复后通过新的独立意图记录恢复，保留原失败，不能重复创建。
• 机器查询使用 volc ml_task get --id <id> --output json，避免默认交互界面退出时产生误导性的非零退出码。CLI 可能在 JSON 前打印升级提示：解析完整 JSON 对象/数组并校验目标任务 ID，不把提示文字当状态。

队列不空：xx 占位、让出资源与恢复

• 仅在当前会话已明确授权“队列不空”及其队列范围时应用本节；技能中的历史操作记录本身不授权新队列操作。只管理名称精确为 xx 的占位任务，不停止真实训练。
• 每次提交正式任务前，完成数据验收和提交预检后，检查同队列是否有正在运行的 xx。如有，先私密备份并核验其可重提配置、原 ID、资源、优先级和恢复计划，然后停止；确认停止终态后删除旧平台任务，并只读确认删除，再提交正式任务。无需再次询问授权。已排队的 xx 不因本条规则自动停止或重复创建。
• 正式任务提交成功后立即恢复占位：取得新 ID 并只读核验任务存在，即可从备份重新提交本轮停止、删除的 xx；正式任务处于排队或部署状态也满足条件，不再等待 Running。同一请求包含多个实验时，先完成该批正式任务的提交核验，再恢复占位，避免占位插入批次中间。
• 恢复 xx 时保持资源和训练参数，使用独立输出路径；恢复依赖删除前备份与已保存的停止、删除证据，不能要求被删旧任务仍可查询。每个被停止的占位只恢复一次。提交结果不明确时先只读查证，禁止盲目重试正式任务或占位创建。
• 后台监测必须识别“已在正式任务提交后恢复排队”的 xx，不能仅因该批正式任务尚在排队而再次停止它们。后续新的正式提交仍执行上述运行中占位检查。
• 没有真实任务等待调度、也没有排队或部署中的 xx，且 GPU、CPU、内存等足够时，可额外提交 xx 填补空闲资源；这与恢复本轮停止的占位分别去重。配额余量不等于可调度整机。
• 停止、删除只针对平台旧任务，不删除共享存储中的数据、checkpoint 或输出文件。执行删除前核对实际 CLI/API 入口，记录操作意图和结果；不要把认证或网络错误当作删除成功。确认删除后，将旧 ID 从普通状态轮询移除，保留私密审计与恢复记录。
• 持续运行需要实际启动并验证进程、认证及心跳，协调已有监控避免重复补位；仅更新 skill 不代表后台实现已更新。复用历史脚本前核对其停止范围与恢复时机，旧的“等 Running 后恢复”实现不符合当前规则。
• “队列不空”不放宽数据验收：需等待数据生产的正式实验，必须在完整验收后提交。没有外部通知通道时只记录本地状态，不声称已推送手机通知。

通知事件

提交后跟踪状态，默认向当前 Codex 对话通知；用户指定飞书等渠道时，确认接收目标并使用已授权、可用的发送工具。没有发送渠道时不得声称已发外部通知。通知内容保持简短：任务名、ID、控制台链接、观察时间和以下事件信息。

状态名以当前 CLI/API 实际返回为准；以上名称不是穷举。取消/停止单独通知为“已取消/已停止”，不能当成功完成或训练失败。未知状态保留原值并继续核实。认证错误、网络故障和 JSON 解析错误是监控异常，不是任务失败。提交本身被拒绝则通知“提交失败”，不要编造新任务 ID。

监控与去重

• 每个新任务保存不含密钥的监控记录：region、task_id、task_name、source_id（如有）、通知渠道与目标、last_status、last_checked_at、已确认发送的事件及时间、连续查询失败数。恢复监控时读取记录，按 task_id + 事件去重；发送成功后才标记已发送。发送失败保留待发送事件，重试前检查渠道回执（如可用）。
• 默认每 60 秒查询一次，遵守当前工具允许的等待时长；状态不变不重复发送。失败、成功或取消终态通知送达后结束监控。若首次观察已是终态，只通知实际观察到的终态，不补造“已运行”事件。
• 失败时只读查询日志与诊断；不自动重提、不取消其他任务。连续 3 次查询失败时通知一次“监控异常”，保留最后已知状态；后续逐渐延长查询间隔，上限 5 分钟。恢复后继续状态通知。
• 当前对话内轮询不具备跨会话持续运行保证。若需会话结束后通知，必须实际配置可持续运行的监控进程/调度器、可用认证和通知渠道，并验证其存活与发送结果；仅更新本 skill 不代表监控服务已经启动。若当前环境做不到，明确说明监控尚未启用和缺少的条件。
• 不把终态通知作为训练成功验收：平台成功仅证明任务退出成功，需要指标验收时另按用户要求读取指标。

控制台链接按实际 region 构造，例如北京： https://console.volcengine.com/ml-platform/region:ml-platform+cn-beijing/customTask/detail?Id=<task_id>&tabState=TaskInfo