> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 提交训练作业

> sf submit 全流程：资源声明、超参覆盖、数据引用、镜像与观测

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf submit my-grpo --profile h200:8
```

本地校验、打包上传、服务端准入（catalog / 配额 / 预检）、排队、投放。下面是这条路上的开关。

## 资源：--profile

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf submit my-exp --profile h200          # 注册表默认形状
sf submit my-exp --profile h200:4        # 4 张卡
sf submit my-exp --profile h200:16       # 2 满节点
sf submit my-exp --profile train=h200:8 --profile rollout=h100:2   # 异构多池
```

`--profile` 是唯一资源入口，语义见[资源模型](/zh-Hans/concepts/resources)。

## 超参：--set

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf submit my-exp -s policy.optimizer.kwargs.lr=1e-6 -s grpo.kl_coef=0.05
```

可重复；按方法声明本地校验类型与区间，拼错立即报错。只影响本次提交，不改实验文件。

## 模型与数据

<Tabs>
  <Tab title="NeMo-RL">
    模型与数据在 config 里声明（基底 + 模型片段），提交时通常不需要额外参数。
  </Tab>

  <Tab title="verl / TRL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf submit my-verl \
      --model Qwen/Qwen3.5-9B \
      --train-data data/train.parquet \
      --validation-data data/val.parquet
    ```

    `--model`（HF id 或路径）与 `--train-data` / `--validation-data` 必填。
  </Tab>

  <Tab title="平台数据集">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf submit my-verl \
      --train-dataset alice/gsm8k-zh@v2 \
      --train-data train.parquet          # 数据集内的相对文件名
    ```

    引用平台数据集（`<owner>/<name>[@version]`）时，作业启动自动拉到共享缓存并注入 `<NAME>_DATA_DIR`；`--train-data` 写数据集内相对路径。推荐写在 config 的 `data.train.dataset`，CLI 参数仅作临时覆盖。详见[数据集](/zh-Hans/guides/datasets)。
  </Tab>
</Tabs>

## 项目名

控制台按 `starforge.yaml` 的 `name` 聚合本项目下的所有 run，提交时自动带上，不必再写 `--project`。

## 单次作业覆盖镜像

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf submit my-custom --profile h200:8 \
  --image myregistry.io/train:v1
```

一等框架和 custom 都能用 `--image`；custom 必须显式给。解析顺序：`--image` → Console 框架默认 → runtime registry → catalog。tag 能用，生产建议 digest。仓库要在服务端 allowlist 里。

日志跟 stdout 走。控制台曲线要在训练里调 `starforge.report`。当前 catalog 的 custom 默认是外部观测，那种提交还要带 `--observability-url`。完整写法：[自定义训练](/zh-Hans/guides/custom-training)。Docker 和白名单：[自定义镜像](/zh-Hans/guides/custom-images)。

## 溯源与豁免

| 参数                 | 语义                                                   |
| ------------------ | ---------------------------------------------------- |
| `--allow-dirty`    | 工作区有未提交改动时仍提交（默认拒绝，保证可追溯到确切 commit）。未跟踪文件会列出警告       |
| `--no-validate`    | 跳过提交前校验                                              |
| `--upgrade-recipe` | 提交前把实验锁升级到当前 catalog（配 `--framework-version` 可同时切版本） |

<Warning>
  打包器有敏感文件黑名单（`.env`、`*.pem`、`id_rsa*` 等），命中会**拒绝打包**——密钥不应进入作业包，平台侧有专门的密钥注入通道。
</Warning>

## 训练后自动动作：--then

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf submit my-exp --then export --then eval
```

训练成功后自动执行导出 / 评测，详见[流水线](/zh-Hans/guides/pipelines)。

## 提交之后

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf job ls                 # 作业列表
sf job logs               # 跟随最近作业日志（-n 0 看全量历史）
sf job status <JOB_ID>    # 状态详情
sf job stop <JOB_ID>      # 停止
sf job pause <JOB_ID>     # 暂停（保留 checkpoint）
sf job resume <JOB_ID>    # 从最近 checkpoint 续训
sf job retry <JOB_ID>     # 失败/中断的作业重新排队（同 run id，从最近 checkpoint 继续）
```

服务端受理时可能拒绝的常见原因（都会给出明确报错）：catalog 握手失败（锁过期）、配额不足（进队列等待不算失败）、镜像 registry 不在 allowlist、HF gated 模型未授权、批大小校验不过。排查见[故障排查](/zh-Hans/troubleshooting)。