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

# 作业环境变量

> 平台在训练容器里设了什么，以及你的代码该读哪些。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
env | grep -E '^(TUNEPLANE_|NRL_|VOLUMES_DIR|HF_)'
```

在作业里跑这条命令就能看到整份契约。下面每一项都由控制面设置；你的代码读它们，从不自己拼一个平台
路径。

这些是**作业侧**的变量。服务端设置是另一份清单、只是前缀相同 —— 见
[配置](/zh-Hans/ops/configuration)。

## 存储

| 变量                          | 是什么                                                        |
| --------------------------- | ---------------------------------------------------------- |
| `TUNEPLANE_OUT_DIR`         | **唯一一个内容能在作业结束后留存的目录。** checkpoint、导出、产物                   |
| `TUNEPLANE_RUN_DIR`         | 这次运行的目录，`out`、`work` 和 `logs` 都在它下面                        |
| `TUNEPLANE_STORAGE_ROOT`    | 部署配置的那一个存储根                                                |
| `TUNEPLANE_WORK_DIR`        | 作业包被解包到哪。由 capsule 的 bootstrap 导出而不是由 spec 给，因为它取决于包是怎么送达的 |
| `TUNEPLANE_EXP_DIR`         | 你的实验在包里的目录                                                 |
| `TUNEPLANE_DATASET_OUT_DIR` | 这次运行要发布的数据集往哪写。只在带 `--output-dataset` 时设置                  |
| `TUNEPLANE_DATA_CACHE`      | 共享数据集缓存                                                    |
| `TUNEPLANE_HUB_CACHE`       | 没有客户端库的那些 hub 的缓存                                          |
| `HF_HOME`                   | Hugging Face 缓存，在存储根里面                                     |

写在 `$TUNEPLANE_OUT_DIR` 之外的任何东西，都会在容器退出时随临时目录一起消失。

## 拓扑

| 变量                                | 是什么                                                                                 |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| `TUNEPLANE_CLUSTER_NUM_NODES`     | 这个作业真实拥有的节点数                                                                        |
| `TUNEPLANE_CLUSTER_GPUS_PER_NODE` | 每节点卡数                                                                               |
| `TUNEPLANE_PROFILE_OVERRIDES`     | 一个 `key=value` 的 JSON 数组，框架适配器把它追加到训练 argv 上                                        |
| `TUNEPLANE_POOL_TOPOLOGY`         | JSON，按 pool 给出 name、series、nodes、gpus\_per\_node、pin\_resource、roles。单 pool 作业没有这一项 |
| `NRL_PIN_RESOURCE`                | 这个作业的 series 要 pin 的 Ray 自定义资源                                                      |
| `CLUSTER_PROFILE`                 | 这次提交用的 profile 名字                                                                   |

配额和看门狗是按 `TUNEPLANE_CLUSTER_*` 衡量的。占用超过这个数会让作业被告警、也可能被停掉。把这
两个数字传给 `torchrun --nproc_per_node` 或 `accelerate launch --num_processes`。

## 上报

| 变量                               | 是什么                      |
| -------------------------------- | ------------------------ |
| `TUNEPLANE_JOB_ENABLED`          | 绑定了 ingest 时是 `1`，否则 `0` |
| `TUNEPLANE_JOB_ENDPOINT`         | 指标、日志和样本往哪去。必须从 GPU 节点可达 |
| `TUNEPLANE_JOB_RUN_ID`           | 这次运行的 id                 |
| `TUNEPLANE_JOB_TOKEN`            | 一个按运行、带作用域的 ingest 令牌    |
| `TUNEPLANE_JOB_JUDGE_ENDPOINT`   | 平台裁判，用于 rubric 奖励        |
| `TUNEPLANE_JOB_JUDGE_TOKEN`      | 它的令牌                     |
| `TUNEPLANE_JOB_MONITOR_INTERVAL` | 硬件采样间隔，单位秒，默认 `10`       |

`tuneplane.report` 会读上面这些。没有令牌时它什么都不做，那正是你在作业之外想要的。见
[上报指标](/zh-Hans/api-reference/python-sdk)。

## 数据与材料

| 变量                | 是什么                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `VOLUMES_DIR`     | 一个 [Volume](/zh-Hans/guides/volumes) 被只读挂载在哪个根下。一个变量，不是一个 volume 一个：读 `$VOLUMES_DIR/<name>` |
| `<NAME>_DATA_DIR` | 每个被引用的数据集一个，名字取自它的名称大写、`-` 和 `.` 变成 `_`。所以 `alice/gsm8k-zh@v2` 变成 `GSM8K_ZH_DATA_DIR`       |

## Agent 环境

| 变量                                | 什么时候有                                  |
| --------------------------------- | -------------------------------------- |
| `TUNEPLANE_JOB_ENVIRONMENT_DIR`   | 协议是物化的（`nemo-gym`）                     |
| `TUNEPLANE_JOB_ENVIRONMENT_URL`   | 协议是自服务（`openenv`）或远端（`openenv-remote`） |
| `TUNEPLANE_JOB_ENVIRONMENT_SPLIT` | 带环境的作业上总是有。`train` 或 `eval`，由操作决定      |

`TUNEPLANE_JOB_ENVIRONMENT_SPLIT` 没有参数也没有覆盖手段。见
[agent 环境](/zh-Hans/guides/agent-envs)。

## 沙箱

| 变量                                         | 是什么                           |
| ------------------------------------------ | ----------------------------- |
| `TUNEPLANE_JOB_SANDBOX_ENDPOINT`           | 模型生成的代码在哪跑                    |
| `TUNEPLANE_JOB_SANDBOX_TOKEN`              | 它的令牌                          |
| `TUNEPLANE_JOB_SANDBOX_FUSION_URL`         | 只在绑定的沙箱说 Sandbox Fusion 协议时给出 |
| `TUNEPLANE_JOB_SANDBOX_FUSION_CONCURRENCY` | 它的并发上限                        |

这些是可选的。没有它们时，环境会在容器内的一个子进程里跑工具代码。

## 身份与溯源

| 变量                                                 | 是什么                            |
| -------------------------------------------------- | ------------------------------ |
| `TUNEPLANE_RECIPE`、`_VERSION`、`_DIGEST`、`_PLUGINS` | 这到底是哪个方法                       |
| `TUNEPLANE_FRAMEWORK`、`_VERSION`                   | 哪个框架构建                         |
| `TUNEPLANE_RUNTIME_ID`                             | 用哪个交付产物来跑                      |
| `TUNEPLANE_CORE_VERSION`                           | 构造这份 spec 的 SDK 版本             |
| `NRL_RUN_ID`、`NRL_SUBMIT_USER`、`RUN_USER`          | run id 和提交人                    |
| `NRL_GIT_COMMIT`、`NRL_GIT_DIRTY`、`NRL_CONFIG_SHA`  | 溯源                             |
| `NRL_TRAIN_RUN_ID`                                 | 在一个后训练步骤上，它跟随的那次训练运行           |
| `NEMO_RL_DIR`                                      | NeMo-RL 在镜像里的位置。`nemo-rl` 作业必需 |

`NRL_` 这个前缀是历史遗留，而它仍然是真实的名字。不要在配置里改它。

## 密钥

| 变量                                  | 是什么                                                       |
| ----------------------------------- | --------------------------------------------------------- |
| `HF_TOKEN`、`HUGGING_FACE_HUB_TOKEN` | 部署有令牌时，或你[绑定了自己的账号](/zh-Hans/integrations/huggingface)时注入 |
| `CLUSTER_SECRETS_FILE`              | 一个密钥文件的路径，用于按路径而不是按值注入的部署                                 |

永远不要把令牌烧进镜像。平台会注入这些，而且空值会被丢掉而不是设成 `""`，这样你脚本里的
`${VAR:-default}` 仍然能回退。

## 确认成功

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
echo "$TUNEPLANE_OUT_DIR" "$TUNEPLANE_CLUSTER_GPUS_PER_NODE"
env | grep TUNEPLANE_JOB
ls -la "$VOLUMES_DIR"
```

一个空的变量是被有意丢掉的，那和平台没设它不是一回事。一个未知的 `TUNEPLANE_` 或 `NRL_` 变量会让
集群侧自检发出警告，因为它通常意味着部署的额外环境里打错了一个字。

## 下一步

[JobSpec](/zh-Hans/reference/jobspec) · [自带训练器](/zh-Hans/guides/custom-training) ·
[服务端配置](/zh-Hans/ops/configuration)