Agent 环境

sf env push ./my-env --name calculator-tasks --version 1.0.0
sf env ls
sf env show alice/calculator-tasks@1.0.0

一个环境是一份 taskset 加一份 manifest，像数据集一样被拥有和版本化，引用形式为 <owner>/<name>@<version>。它是 agent 用来练习的东西。平台负责存储它、决定谁能引用它、把它服务出去——但从不编写在它里面运行的东西。

目录结构

my-env/
├── manifest.json     # 这个环境声明了什么
└── tasks.jsonl       # 一行一个任务

目录下的所有东西都会被上传。版本不可变。

tasks.jsonl

每行一个 JSON 对象：

{"prompt": "What is 17% of 340?", "reference": "57.8", "split": "train"}
{"prompt": "Convert 45 degrees Celsius to Fahrenheit.", "reference": "113", "split": "eval"}

train | eval

默认值:"train"

这一行属于 taskset 的哪一半，逐行声明。作业能看到哪一半是平台按操作类型决定的，所以训练作业拿不到留出任务，评测也要不到训练任务。评测去要一个环境从未声明过的 split 会被拒绝，而不是悄悄给它训练任务——那正是这个字段要防的那一种失败，也是唯一一种「看起来像好成绩」的失败。

taskset 从不外发。没有任何路由返回它的副本，也没有导出。一家企业认为什么算难，往往比它的训练数据更能说明问题，所以作业只能引用一个环境，任务内容只在获批的运行时里才出现。

manifest.json

{
  "schema": "forge/environment/v1",
  "protocol": "openenv",
  "verifier": { "kind": "rubric", "ref": "alice/arithmetic-correctness" },
  "tools": [
    {
      "name": "calculator",
      "endpoint": "/tools/calculator",
      "schema": {
        "type": "object",
        "properties": { "expression": { "type": "string" } },
        "required": ["expression"]
      }
    }
  ],
  "sandbox": { "required": false },
  "description": "Arithmetic word problems with a calculator tool."
}

string

必填

永远是 forge/environment/v1。

nemo-gym | openenv | openenv-remote | openenv-image

必填

trainer 怎么够到这个环境。见下文。

object

必填

{"kind": "rubric|plugin|endpoint", "ref": "..."}——判定任务是否完成的东西。见 verifier。

array

agent 可以调用什么：名字、端点，以及参数的 JSON Schema。

object

{"plugin": "<owner>/<name>", "version": "...", "entrypoint": "module:ClassName", "digest": "..."}。 nemo-gym 必填。代码属于一个 kind: environment 插件；平台最多写一个两行的 shim 去 import 它。

bool

默认值:"false"

harness 会运行模型生成的代码时为 true。需要沙箱的作业跑在没有配置沙箱提供方的部署上会被拒绝—— 它不会退化成「在训练容器里跑」。

string

默认值:"other"

NeMo Gym 的指标分组类别。nemo-gym 下必填且校验，其他协议下无意义。取值：math、coding、agent、knowledge、instruction_following、long_context、 safety、games、translation、e2e、rlhf、other。

string

openenv 环境的 OCI 镜像。和其他所有固定镜像一样按运行时产物解析，绝不临时拉取。

url

openenv-remote 必填，其他协议下禁止。服务已经跑在哪里。

四种协议

其中三种是作业真的能走的路径，区别在于谁来跑这个 server。

openenv —— 平台来服务
nemo-gym —— 框架来跑
openenv-remote —— 别人在跑
openenv-image —— 这里跑不了

回合级。平台用自己持有的 taskset 启动环境 server，trainer 通过 openenv-core 的客户端自己驱动 episode：reset、step、state。TRL、SkyRL、Unsloth 和 Axolotl 都走这条。不需要 harness——循环本来就归 trainer 管。

轨迹级（/seed_session + /verify）。NeMo Gym 会从一个配置入口启动它自己的 server，所以平台没有东西可服务。平台改为物化这个环境：把获授权的那个版本写进作业里，写成 NeMo Gym 期望看到的那些文件。轨迹循环总得有人跑，而平台不写它，所以 harness.plugin 必填—— 还要 harness.entrypoint，形如 module:ClassName，点名 Gym 要 import 的 SimpleResourcesServer 子类。

一个已经跑在别处的服务。平台既不启动它也不代理它；平台只决定作业能不能够到那台主机，然后把 URL 交给 trainer。代价只是一个出网决策。

sf env runner register http://envbox-3.corp:8080 \
  --name shared-sim --version 1.0.0 \
  --rubric alice/task-completion

这条命令会验证正在运行的服务并注册它，不需要管理员介入。

Harness

驱动模型走完环境的那段代码，以 kind: environment 插件提供。物化那条路需要它——框架要 import 并运行它。服务那条回合级路径不需要——trainer 自己驱动 episode。

plugin.yaml

schema: forge/plugin/v1
name: calculator-harness
version: 1.0.0
kind: environment
entrypoint: harness:CalculatorResources

manifest 里的 harness.digest 锁定这个环境编写时所针对的 harness 包。团队把 harness 和环境一起发布时留空是诚实的；两者分开版本化、且 harness 版本不匹配会导致打分不同时，就把它设上。它在提交时校验，不在 rollout 时校验。

推送与引用

sf env push ./my-env --name calculator-tasks --version 1.0.0 --public

<owner>/<name> 或裸名

必填

裸名进入你自己的命名空间。

string

必填

推送后不可变。

flag

只在环境首次创建时生效。

你笔记本上和控制平面里跑的是同一个模块里的同一份解析代码——所以能 push 的 manifest 就是能跑的 manifest。未知的协议或 verifier kind 在 push 时就被拒，而不是等到 rollout 才发现：一个校验通过却跑不起来的环境，已经浪费掉了某人的一次 GPU 分配。

确认成功

sf env show alice/calculator-tasks@1.0.0

打印协议、verifier、工具，以及是否需要沙箱。控制台的 Environments 页显示同样的内容，外加哪些 run 引用过它。

开始

核心概念

训练模型

评测与服务

扩展平台

集成

帮助

Agent 环境

目录结构

tasks.jsonl

manifest.json

四种协议

Harness

推送与引用

确认成功

下一步

Verifier

Rubric

​目录结构

​tasks.jsonl

​manifest.json

​四种协议

​Harness

​推送与引用

​确认成功

​下一步

Verifier

Rubric

目录结构

tasks.jsonl

manifest.json

四种协议

Harness

推送与引用

确认成功

下一步