Agent 环境

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

Agent Environment 是 agent 执行动作并获取观察结果的上下文。任务集提供任务，验证器判断是否完成。当前发布格式把任务集和环境清单打包，以 <owner>/<name>@<version> 管理不可变版本。清单声明如何连接或运行环境；发布包本身不是已经启动的沙箱。

布局

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

目录下的一切都会被上传。版本不可变。只有 deployment: local 需要 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"

这一行属于任务集的哪一半。逐行声明。平台由操作本身决定一个作业看到哪一半，所以训练作业拿不到留出任务，评测也要不到训练任务。一次评测索要环境从未声明过的 split 会被拒绝，而不是被悄悄喂上训练任务 —— 这就是这个字段存在要防的那一种失败，而它恰好是那种看起来像好成绩的失败。

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

manifest.json

{
  "schema": "tuneplane/environment/v1",
  "protocol": "openenv",
  "deployment": "local",
  "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

必填

永远是 tuneplane/environment/v1。

nemo-gym | openenv

必填

交互契约：OpenEnv 使用 reset / step / state；NeMo Gym 使用轨迹会话。

local | remote | container

必填

谁启动环境实现：local 在作业内运行；remote 连接已有服务；container 由执行后端托管镜像。 NeMo Gym 当前仅支持 local。v1 清单和原来混合部署方式的协议名称会被拒绝。

object

必填

{"kind": "rubric|plugin|endpoint", "ref": "..."} —— 由什么决定一个任务是否完成。见判定器。

array

agent 能调什么：一个名字、一个端点，以及参数的 JSON Schema。

object

{"plugin": "<owner>/<name>", "version": "...", "entrypoint": "module:ClassName", "digest": "..."}。 nemo-gym 必填。代码属于一个 capability: 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 镜像。像其他任何镜像一样按钉住的 runtime 产物解析；从不临时拉取。

url

仅适用于 deployment: remote。可以使用固定 endpoint、Fleet 或已注册 runner。endpoint 和 Fleet 不能同时指定。

协议与部署方式

两种交互契约与三种部署方式组成四种已支持的组合。Docker、E2B 等沙箱提供方是另一个选择，不是协议值。

OpenEnv + local
NeMo Gym + local
OpenEnv + remote
OpenEnv + container

回合级。平台从它持有的任务集起环境服务端，训练器通过 openenv-core 的客户端自己驱动 episode： reset、step、state。TRL、SkyRL、Unsloth 和 Axolotl 都用这种。不需要 harness —— 循环已经在训练器手里。

轨迹级（/seed_session + /verify）。NeMo Gym 从一个配置入口启动自己的服务端，所以没有东西需要平台去提供。平台改为物化这个环境：把被授权的那个版本按 NeMo Gym 期望找到的文件形态写进作业。得有人来跑轨迹循环，而平台不写它，所以 harness.plugin 必填 —— 另外还要 harness.entrypoint 写成 module:ClassName，指出 Gym 要 import 的那个 SimpleResourcesServer 子类。

一个已经跑在别处的服务。平台从不启动它、从不代理它；它决定作业能否访问那台主机，解析出它此刻在哪里应答，再把这个地址交给训练器。代价只有一个出网决定。

tp env runner register http://envbox-3.corp:8080 \
  --name shared-sim --version 1.0.0 \
  --description "共享仿真器，由运维维护"

这会校验一个正在运行的服务并把它注册成环境，不需要管理员介入。默认情况下由环境自己判分 —— OpenEnv 的 Observation 里带着 reward，manifest 也如实这么写。加 --rubric <owner>/<name> 可以把这个判断交给平台的 judge。“在哪里应答”和”它是什么”是两件事。 固定地址是封进不可变版本里的，机器一搬就得推新版本。另外两种形态不会：

tp env runner serve <env> --at <url> —— 把这台机器注册成 runner 并持续心跳。多台机器可以服务同一个环境，作业会被送到最近应答的那一台。
注册时传 --fleet <id> —— 由平台在作业需要时从那个 Fleet 里挑一台机器。

已注册的 runner 会显示在控制台的环境详情里，也可以用 tp env runner ls <env> 查看。两个界面都会列出所有 runner（无论处于什么状态），并逐行标注是否在应答：“注册了但不应答”和”根本没人注册过”是两件完全不同的事，如果列表把前者藏起来，你会被引去重新搭一套已经存在的东西。想让某台机器停止接活又不丢掉记录，在任一界面把它排空即可。集群路由不到那台主机时怎么办，见访问远程环境。

以容器镜像形式发布的环境 —— OpenEnv 生态发布的就是这种。执行器把它起在训练器旁边、同一个网络命名空间里，再把地址交给训练器；从作业这一侧看，它和”别人在跑的服务”没有区别。完全不需要任何网络安排，所以只要环境能容器化，这就是首选的那条路。在 Kubernetes 上它是 Ray head Pod 里的一个 sidecar，所以它在 Pod 自己的 loopback 上应答 —— 同一节点上的两个作业不会抢同一个端口，两个容器也都碰不到节点自身的服务。环境容器拿不到 GPU，也拿不到任何卷挂载。它只负责判分，不是作业本身；它拿不到的每一样资源，都是它伸不出去的一只手。除非镜像监听 8900，否则请声明它实际监听的端口：

{ "protocol": "openenv", "deployment": "container", "image": "ghcr.io/acme/env:1", "image_port": 8000 }

这个镜像不是平台构建的，平台也无法影响它绑定到哪个端口，所以端口只能由镜像自己声明，而不是由平台指派。如果镜像监听在作业不会去拨的端口上，就等于什么都没有应答，作业会在训练器内部因连接错误而失败——而那条错误既不会提到是哪个环境，也不会提到是哪个端口。

目前只支持 kubernetes fleet。node 有这个能力但还没做 —— 在普通容器运行时上它需要每作业一个网络，因为另外两条路都更糟：宿主网络等于把节点的 loopback 交给第三方代码，而发布宿主端口会让同一节点上跑同一镜像的两个作业撞车。Slurm 不会做：在别人的登录节点上物化 OCI 镜像不是这个平台该干的事。

访问远程环境

openenv (deployment: remote) 环境能不能用，取决于训练作业能否向它发起连接。控制平面负责解析它在哪里应答并把地址交出去，但它从不承载 episode 本身（ADR-0025）。一次 episode 是一连串回合，每个生成轮一次；把它路由穿过那个负责判定准入的进程，等于在每一回合上都加一跳，而那一跳离数据很远。所以当环境位于集群路由不到的网络上时，下面三条至少要成立一条：

做法	什么时候合适	代价
把机器放进集群网络	一个组织内部通常就是这个答案。`node` Fleet 本身就是这么做的。	一次网络变更。
覆盖网络（Tailscale、Nebula、ZeroTier）	环境确实在集群路由不到的地方，而你希望它看起来像本地的。	环境主机和集群两侧都要装 agent。数据保持点对点 —— 协调服务器看不到它。
反向隧道打进集群（frp、chisel、inlets）	只有一两台主机，又不想上 mesh。	隧道服务端要部署在集群里。环境往外拨，作业访问一个集群本地地址。

哪一条都不是”通过控制台代理”。如果你发现自己想要那个，答案通常是第一行。

或者让这个问题消失。 openenv (deployment: container) 环境跑在作业旁边的容器里，没有距离要跨，上面三行一行都用不上。只要环境能容器化，这就是该优先考虑的路 —— OpenEnv 生态也正在往那个方向走。目前需要 kubernetes fleet。

Harness

驱动模型走完一个环境的代码，以 capability: environment 插件提供。物化那条路需要它，框架会 import 并运行它。自服务的回合级那条路不需要，训练器自己驱动 episode。

plugin.yaml

schema: tuneplane/plugin/v1
name: calculator-harness
version: 1.0.0
capability: environment
entrypoint: harness:CalculatorResources

manifest 里的 harness.digest 钉住这个环境所依据的 harness 包。团队把 harness 和环境一起发布时留空它；两者分开做版本、且不匹配的 harness 会给出不同分数时,设上它。它在提交时校验，不在每次 rollout 时校验。

推送并引用

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

<owner>/<name> 或裸名字

必填

裸名字落进你自己的命名空间。

string

必填

推上去之后不可变。

flag

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

同一份解析代码从一个模块跑在 CLI 里和控制面里 —— 所以能推上去的 manifest 就是能跑起来的 manifest。未知的协议或判定器 kind 在推送时就被拒绝，而不是在 rollout 时才发现，因为一个校验通过却跑不起来的环境已经让某个人花掉了一次 GPU 分配。

确认成功

tp env show alice/calculator-tasks@1.0.0

打印协议、判定器、工具，以及是否需要沙箱。控制台的环境页显示同样的信息，另外还有哪些运行引用过它。

下一步

判定器讲判定完成的三种方式 · 编写评分标准 · 使用环境

质量证据

tuneplane-examples 中的 common/envkit/quality.py 在用户项目内执行回调，再通过 Reporter.environment_quality() 上报。请接入环境实际使用的模型、判分器和 harness，固定 checkpoint，并在测量期间禁用模型更新；控制面不负责实现这些执行逻辑。创建 my_quality:adapter 工厂，返回 measure() 的参数：

参数	要求
`environment`	作业固定的 `<owner>/<name>@<version>`；提交者必须是环境所有者
`checkpoint`	不可变模型修订或 checkpoint 引用
`runtime_digest`、`verifier_digest`、`harness_digest`	实际 SHA-256 修订摘要；manifest 固定的 harness 摘要必须匹配
`predict(task, repetition)`	固定策略生成；只接收 `id` 和 `prompt`，不接收参考答案或 metadata
`verify(task, response)`	接收原始任务与预测；返回 `success`、`failure` 或 `unscored`
`fixtures`	命名回调，返回 `(actual, evidence)`；actual 为 `pass`、`fail` 或 `unknown`
`split`、`repetitions`、`settings`	默认 `train`、4 次、空对象；请明确记录解码设置和随机种子

可调用 verifier_fixtures(verify, fixture_task, correct=..., incorrect=...)，对真实判分器执行正例、反例与执行检查。错误答案被正确拒绝时，反例应上报 fail。要求沙箱的环境还需要 egress_allowed、egress_denied、reference_isolation 回调，对实际运行时进行探测。缺失检查不会视为成功；回调需自行设置网络和进程超时。生成回调可返回字符串或 Prediction(text=..., tokens=...)；缺失 token 用量显示为未知。回调异常记为 infra_error，不算模型答错。入口保存全部计划试验的 JSON 报告及单独的本地验收证据文件，然后上报元数据。原始验收证据留在本地，可能含敏感诊断信息，应妥善保管。上传失败会明确报错并保留本地报告。上报内容不包含模型正文或参考答案。在环境所有者的作业内固定环境版本后运行：

python -m common.envkit.quality \
  --adapter my_quality:adapter \
  --directory "$TUNEPLANE_JOB_ENVIRONMENT_DIR" \
  --output environment-quality.json \
  --upload

训练适用性测量使用训练作业，保留评估部分的测量使用评估作业，不能覆盖平台分配的 TUNEPLANE_JOB_ENVIRONMENT_SPLIT。本地执行时省略 --upload，将 --directory 指向原始编写目录。这是现有项目作业中的函数／CLI 集成入口，不是新增的一键模型执行服务；GPU 生成和沙箱强制隔离仍由实际运行时负责。

开始

核心概念

训练模型

评测与服务

扩展平台

协作

集成

参考

帮助

Agent 环境

布局

tasks.jsonl

manifest.json

协议与部署方式

访问远程环境

Harness

推送并引用

确认成功

下一步

质量证据

​布局

​tasks.jsonl

​manifest.json

​协议与部署方式

​访问远程环境

​Harness

​推送并引用

​确认成功

​下一步

​质量证据

布局

tasks.jsonl

manifest.json

协议与部署方式

访问远程环境

Harness

推送并引用

确认成功

下一步

质量证据