> ## 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.

# 术语表

> CLI、JobSpec、控制台实际在用的名字

报错信息里出现的就是这些词。随便换成近义词（run 当 job、image 当 recipe）会让你点到错页。

## 仓库与控制台

| 词            | 含义                                                                                             |
| ------------ | ---------------------------------------------------------------------------------------------- |
| **Lab / 仓库** | `sf init` 建出来的目录。标记文件是 `starforge.yaml`。`sf` 从当前目录往上找，和 git 一样。                                |
| **项目**       | `starforge.yaml` 里的 `name`。控制台把这个 lab 交出去的作业归到 `@<用户>/<name>`。名字按用户唯一，不是全局唯一。                  |
| **实验**       | `experiments/<name>/` 下的目录。里面有 `config.yaml`、`recipe.lock.json`，自定义作业还有 `train.sh`。建实验不会占 GPU。 |
| **作业 / run** | 一次被准入的提交。有 run id、台账状态，启动后还有后端句柄。一个实验可以对应很多次作业。                                                |
| **Profile**  | 服务端硬件注册表里的卡型名（`h200`、`h100` 等）。`--profile h200:8` 表示该卡型、一共 8 张卡。                               |

## 方法与打包

| 词                    | 含义                                                                          |
| -------------------- | --------------------------------------------------------------------------- |
| **Recipe**           | 某个后训练方法的版本化声明：入口、超参、指标、产物、运行时矩阵。文件在 `starforge-core` 的 `recipes/catalog/`。  |
| **Catalog**          | 当前连上的服务器已发布的 recipe 集合。客户端和服务端必须在 digest、版本上一致。                             |
| **方法 id**            | `<framework>/<method>`，例如 `trl/kto`。                                        |
| **recipe.lock.json** | `sf new` 写入。钉住 recipe digest 和框架版本。锁过期则提交拒绝。                                |
| **JobSpec**          | CLI 组装、服务端准入的 `forge/v2` JSON。不要手写。见 [JobSpec](/zh-Hans/reference/jobspec)。 |
| **Job Capsule**      | 准入后服务端注入的 `capsule.json` + `bootstrap.sh` + `runner.pex`。训练镜像里不要预装平台包。      |
| **runtime\_id**      | 部署工件键（OCI 镜像、SIF、SQSH）。从 catalog、`FORGE_IMAGE_*`、runtime 注册表或 `--image` 解析。 |

## 执行

| 词                   | 含义                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| **Executor / 执行器**  | 控制平面怎么起容器：`local`（控制台机器上的 Docker）、`agent`（节点上的 `forgelet`）、`kuberay`（RayJob）、`slurm`（只走 slurmrestd）。 |
| **池 / pool**        | JobSpec 里一组同构 GPU。异构作业用两个池（train + rollout），只在 `kuberay` / `slurm` 上能跑。                              |
| **FORGE\_OUT\_DIR** | 作业结束后还在的那一个产物目录。写到别处的 checkpoint 会跟临时目录一起没。                                                          |
| **Ingest**          | 训练容器打回控制台的 HTTP（日志、指标、样本）。`FORGE_INGEST_URL` 必须是 GPU 节点能访问的地址，不能是笔记本上的 `127.0.0.1`。                  |

## 自定义作业

| 词                 | 含义                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------ |
| **custom/custom** | catalog 里只跑 `experiments/<name>/train.sh` 的 recipe。不探测框架，也不会在别的 adapter 失败后回退过来。           |
| **观测 `platform`** | recipe 选项：runner 改 `PYTHONPATH`，镜像里不用装 wheel 也能 `import starforge`。                        |
| **观测 `external`** | 当前 catalog 里 `custom/custom` 的默认。提交必须带 `--observability-url`。控制台曲线仍然要靠 `starforge.report`。 |