> ## 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 CLI 使用的 TOML 配置文件

Osmosis CLI 使用 TOML 文件运行 evaluation runs 和训练任务。Configs 必须位于 workspace directory 内：

| Config type | Required location         | Command                |
| ----------- | ------------------------- | ---------------------- |
| Eval        | `configs/eval/*.toml`     | `osmosis eval submit`  |
| Training    | `configs/training/*.toml` | `osmosis train submit` |

<Note>
  必需字段会以 un-commented 形式显示。可选字段在 template 文件中会被注释掉，可省略以使用平台默认值。
</Note>

***

## Eval Config

由 [`osmosis eval submit`](/zh/cli/command-reference#eval-submit) 使用，用于提交一次 evaluation run。平台会克隆由 `origin` remote 标识的 workspace repository，并在服务端针对 platform dataset 运行 rollout。

```toml configs/eval/my-rollout.toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[experiment]
rollout = "my-rollout"                         # Rollout directory under rollouts/
entrypoint = "main.py"                         # Entrypoint relative to rollout dir
model_path = "openai/gpt-5-mini"               # LiteLLM-style model name for the evaluation policy
dataset = "my-platform-dataset"                # Platform dataset name from `osmosis dataset list`
# commit_sha = "abc123..."                     # Pin code to a specific commit

[evaluation]
# Optional. Omit values to use platform defaults.
# limit = 200                                  # First N rows; omit for random 10% sample
# n = 1                                        # Evaluation attempts per row
# batch_size = 1                               # Rows evaluated per batch
# pass_threshold = 1.0                         # Minimum passing score
# agent_workflow_timeout_s = 450               # Agent workflow timeout per row
# grader_timeout_s = 150                       # Grader timeout per row

# [env]
# LOG_LEVEL = "INFO"                           # Non-secret literal env var

[secrets]
# Eval config 必填。默认 OpenAI eval 模型需要此 secret。
# 仅在 evaluation 不需要任何 secret refs 时使用 required = []。
required = ["OPENAI_API_KEY"]
```

### `[experiment]`

| Field        | Type  | Required | Description                                               |
| ------------ | ----- | -------- | --------------------------------------------------------- |
| `rollout`    | `str` | Yes      | `rollouts/` 下的 rollout 目录名                                |
| `entrypoint` | `str` | Yes      | 相对 rollout 目录的 Python entrypoint                          |
| `model_path` | `str` | Yes      | evaluation policy 的 LiteLLM 风格模型名（例如 `openai/gpt-5-mini`） |
| `dataset`    | `str` | Yes      | 来自 `osmosis dataset list` 的 platform dataset 名称           |
| `commit_sha` | `str` | No       | 固定到指定 commit。默认使用默认分支上最新已同步的 commit。                      |

### `[evaluation]`

所有字段均为可选。省略字段表示使用平台默认值。

| Field                      | Type    | Description                                   |
| -------------------------- | ------- | --------------------------------------------- |
| `limit`                    | `int`   | 评估的行数（前 `N` 行）。省略时，平台会对 dataset 随机抽取 10% 的样本。 |
| `n`                        | `int`   | 每行 evaluation 的尝试次数（取 > 1 用于 pass\@n metrics） |
| `batch_size`               | `int`   | 每个 batch 评估的行数                                |
| `pass_threshold`           | `float` | 样本计为通过所需达到或超过的分数                              |
| `agent_workflow_timeout_s` | `float` | 每行 `AgentWorkflow.run()` 的 timeout            |
| `grader_timeout_s`         | `float` | 每行 `Grader.grade()` 的 timeout                 |

### `[env]` 和 `[secrets]`（eval）

evaluation run container 的可选 `[env]` 变量与必填 `[secrets]` 表。Eval config 必须包含 `[secrets]`——仅在 evaluation 不需要任何 secret refs 时才写 `required = []`。完整规则见下方的 [`[env]` 和 `[secrets]`](#env-and-secrets)。

***

## Training Config

由 [`osmosis train submit`](/zh/cli/command-reference#train-submit) 使用，用于提交训练任务。

```toml configs/training/my-rollout.toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[experiment]
rollout = "my-rollout"                         # Rollout directory under rollouts/
entrypoint = "main.py"                         # Entrypoint file name
model_path = "Qwen/Qwen3.6-35B-A3B"            # Supported base model
dataset = "my-dataset"                         # Platform dataset name
# commit_sha = "abc123..."                     # Pin code to a commit

[training]
# lr = 1e-6                                    # Learning rate
# total_epochs = 1                             # Training epochs
# n_samples_per_prompt = 8                     # Rollout samples per prompt
# rollout_batch_size = 32                      # Rollout batch size
# max_prompt_length = 8192                     # Max prompt tokens
# max_response_length = 8192                   # Max response tokens
# agent_workflow_timeout_s = 450               # Agent timeout per row
# grader_timeout_s = 150                       # Grader timeout per row

[sampling]
# rollout_temperature = 1.0                    # Sampling temperature
# rollout_top_p = 1.0                          # Top-p sampling

[checkpoints]
# eval_interval = 10                           # Evaluate every N rollouts
# checkpoint_save_freq = 20                    # Save checkpoint every N rollouts

# [advanced]
# Backend-specific fields. Use only when instructed by Osmosis support.

# [env]
# LOG_LEVEL = "INFO"                           # Non-secret literal env var

# [secrets]
# required = ["OPENAI_API_KEY"]                # 训练可选；若包含 [secrets]，必须有 `required`
```

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

### `[experiment]`

| Field        | Type  | Required | Description                               |
| ------------ | ----- | -------- | ----------------------------------------- |
| `rollout`    | `str` | Yes      | `rollouts/` 下的 rollout 目录名                |
| `entrypoint` | `str` | Yes      | Python entrypoint 文件名，通常为 `main.py`       |
| `model_path` | `str` | Yes      | 受支持 base model path                       |
| `dataset`    | `str` | Yes      | 来自 `osmosis dataset list` 的数据集名称          |
| `commit_sha` | `str` | No       | 从 workspace repository 获取的 Git commit SHA |

### `[training]`

| Field                      | Type    | Default          | Description                     |
| -------------------------- | ------- | ---------------- | ------------------------------- |
| `lr`                       | `float` | platform default | 学习率                             |
| `total_epochs`             | `int`   | platform default | Training epochs                 |
| `n_samples_per_prompt`     | `int`   | platform default | 每个 prompt 生成的 rollout samples 数 |
| `rollout_batch_size`       | `int`   | platform default | 每个 rollout batch 处理的 prompts 数  |
| `max_prompt_length`        | `int`   | platform default | 最大 prompt tokens                |
| `max_response_length`      | `int`   | platform default | 最大 response tokens              |
| `agent_workflow_timeout_s` | number  | platform default | 每行 agent rollout timeout        |
| `grader_timeout_s`         | number  | platform default | 每行 grader timeout               |

### `[sampling]`

| Field                 | Type   | Default          | Description                      |
| --------------------- | ------ | ---------------- | -------------------------------- |
| `rollout_temperature` | number | platform default | rollout 期间的 sampling temperature |
| `rollout_top_p`       | number | platform default | Top-p sampling threshold         |

### `[checkpoints]`

| Field                  | Type  | Default          | Description                              |
| ---------------------- | ----- | ---------------- | ---------------------------------------- |
| `eval_interval`        | `int` | platform default | 每 N 个 rollout steps 评估一次                 |
| `checkpoint_save_freq` | `int` | platform default | 每 N 个 rollout steps 保存一个 LoRA checkpoint |

### `[advanced]`

可选 backend-specific fields。CLI 会保留该 section 中的未知 keys，并由平台在服务端验证。

<a id="env-and-secrets" />

### `[env]` 和 `[secrets]`

使用这些 sections 向 training run 或 evaluation run 期间的 rollout container 注入环境变量。同一套结构同时适用于 training 和 evaluation configs。

| Section              | Values                         | Use for        |
| -------------------- | ------------------------------ | -------------- |
| `[env]`              | 存在 config 文件中的 literal strings | 非 secret 配置    |
| `[secrets].required` | 平台 `environment_secret` 记录名列表  | API keys 和私有凭证 |

```toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[env]
LOG_LEVEL = "INFO"

[secrets]
required = ["OPENAI_API_KEY", "DATABASE_URL"]
```

规则：

* `[env]` keys 必须匹配 `^[A-Z_][A-Z0-9_]*$`；`[secrets].required` 名称必须匹配 `^[A-Z][A-Z0-9_]*$`。
* 同一个名称不能同时出现在 `[env]` 和 `[secrets].required` 中。
* `[env]` 中以 `_OSMOSIS_` 开头的名称由平台保留，不能使用。
* `[secrets].required` 只保存记录名——平台会在服务端将每个名称解析为加密的值，并以同名环境变量注入。Secret 值不会出现在 config 文件、API payload 或 CLI 输出中。
* Eval config 必须包含 `[secrets]`。仅在 evaluation 不需要任何 secret refs 时使用 `required = []`。
* Training config 可以省略 `[secrets]`。但只要包含该 table，就必须定义 `required`。

<Note>
  Secrets 有 scope。**Workspace** secret 在 workspace 内共享；**Personal** secret 只属于您本人，且会在运行时覆盖同名的 workspace secret。提交引用 secrets 的 run 之前，先用 [`osmosis secret set`](/zh/cli/command-reference#secret) 注册它们。
</Note>

<Tip>
  从只填写 `[experiment]`（以及 eval config 的 `[secrets]`）开始，让平台使用训练默认值。仅在需要调优训练任务时添加可选字段。
</Tip>