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

# 训练任务

> 在 Osmosis platform 上提交、监控和管理训练任务

训练任务会使用 base model，并通过强化学习进行改进。您提供 rollout、grader、训练配置和数据集；平台负责配置 GPU、从已同步的 workspace repository 拉取代码、执行训练循环，并自动保存 checkpoints。

## 概念

### Training Configuration 与 Training Run

**Training Configuration** 是配方，定义要使用的模型、数据集、AgentWorkflow 和超参数。**Training Run** 是该配置的一次执行。您可以从同一配置提交多个训练任务，以实验不同设置。

### 训练行为

每次提交都会为 TOML config 中指定的 rollout、dataset、model 和超参数创建一个 managed training job。如果要运行另一个实验，请更新 `total_epochs`、sampling settings 或 checkpoint cadence 等字段后再次提交 config。

## 提交训练任务

使用 CLI 和 TOML 配置文件提交训练任务：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis train submit configs/training/default.toml
```

<Warning>
  Git Sync 是您 rollout 代码的 source of truth。CLI 会读取您传入的本地 TOML config 值，但 rollout 代码来自已同步的 workspace repository。提交代码修改前，请先 commit、push 并等待同步完成；需要特定已同步版本时，请设置 `commit_sha`。
</Warning>

### 关键配置字段

```toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[experiment]
rollout = "my-rollout"                  # rollouts/ 下的 rollout 目录名
entrypoint = "main.py"                  # entrypoint 文件名
model_path = "Qwen/Qwen3.6-35B-A3B"     # Hugging Face model path
dataset = "my-dataset"                  # 数据集名称
# commit_sha = "abc123..."              # 可选：固定到特定已同步 commit

[training]
lr = 1e-6                               # 学习率
total_epochs = 1                        # Training epochs
n_samples_per_prompt = 8                # 每个 prompt 生成的样本数
rollout_batch_size = 32                 # rollout batch size
agent_workflow_timeout_s = 450          # 每行 agent rollout 超时
grader_timeout_s = 150                  # 每行 grader 超时

[sampling]
rollout_temperature = 1.0               # rollout 采样温度
rollout_top_p = 1.0                     # rollout top-p 采样

[checkpoints]
checkpoint_save_freq = 20               # 每 N step 保存 checkpoint
```

<Info>
  完整 TOML 参考和所有字段请参见 [Config Files](/zh/cli/config-files)。
</Info>

## 状态生命周期

每个训练任务都会经历一系列状态：

| Status       | Description                           |
| ------------ | ------------------------------------- |
| **pending**  | 任务已排队，正在等待 GPU 资源。                    |
| **running**  | 训练正在进行，指标和 checkpoints 正在生成。          |
| **finished** | 训练成功完成，最终 checkpoint 和指标可用。           |
| **failed**   | 训练执行过程中出错。查看日志了解详情。                   |
| **stopped**  | 用户通过 CLI 或 dashboard 手动停止训练。          |
| **killed**   | 训练在平台 cleanup 或 stop handling 期间被终止。  |
| **crashed**  | 训练进程意外终止（e.g. OOM, hardware failure）。 |
| **unknown**  | 平台无法确定当前训练状态。                         |

内部生命周期阶段为：**init** → **provision** → **setup** → **train** → **finalize** → **complete**（或 **error** / **cleanup**）。

<Note>
  `failed` 或 `crashed` 状态的任务，在失败前保存的 checkpoint 仍可能可用。
</Note>

## 监控

您可以通过 CLI 或平台 dashboard 跟踪训练进度。

### CLI 命令

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
# 显示任务详情、checkpoints 和指标
osmosis train info my-run

# 将指标保存到指定 JSON 文件
osmosis train info my-run --output results/my-run.json
```

在运行过程中，`train info` 会显示进度（`current_step` / `total_steps`）和最新的 reward。`train list` 也会展示相同字段，便于一览所有 run。

### Platform Dashboard

[platform.osmosis.ai](https://platform.osmosis.ai) Web dashboard 提供：

* **Run list** —— 按 status、dataset、base model 和 rollout 搜索和筛选训练任务。
* **Overview metrics** —— 在可用时查看 Duration、Reward、Improvement、Samples、Training Reward、Validation Reward、Model Entropy、Response Length、Total Length 和 Truncation Ratio。
* **Checkpoints** —— 查看已保存 checkpoints 及其 step、reward、deployment status 和 Hugging Face upload status。
* **Outputs** —— 在可用时查看 output artifacts。

完整 dashboard 指标列表请参见 [Monitoring](/zh/platform/monitoring)。

## LoRA Checkpoints

训练过程中，LoRA checkpoints 会按配置中的 `checkpoint_save_freq` 间隔保存。Checkpoints 捕获特定训练 step 的 adapter weights。

您可以：

* **按 reward 分数比较 checkpoints**，找出表现最佳的 step
* **从 dashboard 导出 checkpoints**
* **将 checkpoints 上传到 Hugging Face**
* **用 `osmosis model deploy` 部署 LoRA models** 进行 inference

## 管理训练任务

### 停止任务

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis train stop my-run
```

这会请求平台优雅停止训练进程。如果停止成功完成，任务会进入 `stopped` 状态。

## 下一步

<CardGroup cols={2}>
  <Card title="Datasets" icon="database" href="/zh/platform/datasets">
    上传训练用数据集。
  </Card>

  <Card title="Models" icon="cube" href="/zh/platform/models">
    管理 base models，并部署已训练 LoRA models。
  </Card>
</CardGroup>