GPU Runner 训练

使用条件

先更新客户端并检查当前环境中的提交参数：

python -m pip install --upgrade envloop-cli
el job submit --help

使用下方快捷命令前，确认帮助列出 --trials、--gpu-type 和 --gpu。若没有，检查 el 是否来自刚更新的 Python 环境；也可使用本页的请求文件或 SDK 方式。

项目须具备 training.run 权限，能够读取已发布的 GPU Runner Revision，并具有可用 GPU 容量。CLI、请求文件和 SDK 都需要平台支持 Runner 训练。查询到 Runner 不会预留 GPU；提交被拒绝时按错误码检查权限、Runner 或容量，必要时联系项目管理员。

在 Console 的 Runners 列表中，点击名称或 版本 数量查看该 Runner 已发布的 Revision。选择 Revision 查看执行定义和文件，详情页的 版本 入口可切换 Revision。版本继续使用完整、不可变的 Git commit 标识。Console 只读浏览，Job 通过下方 CLI 提交。

用 el runner list --json 查找有权读取的 Runner，固定完整 namespace/name@revision 选择器。平台先检查项目 training.run 和 Runner 读取权限，再冻结已发布文件，始终执行该 Revision 的 main.sh 或 main.py 入口。

请求文件与 SDK

确认 el job submit --help 列出 --spec。若没有，先在提供 el 命令的 Python 环境中更新客户端，再继续操作。

--spec 读取 Job 规格 JSON 文件，显式 Runner/资源参数优先覆盖各 Trial 对应字段，保留未指定资源键；--trials 仍与文件互斥。将下列请求保存为 gpu-run.json，替换完整已发布 commit：

{
  "request_id": "gpu-run-001",
  "trials": [
    {"name": "first", "spec": {"runner": "envloop/bash@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_seconds": 600}},
    {"name": "second", "spec": {"runner": "envloop/bash@FULL_COMMIT", "resources": {"gpu_type": "H100", "gpus": 4}, "timeout_seconds": 600}}
  ]
}

el job submit --type train --spec gpu-run.json

SDK 通过 client.training_jobs.submit(request) 接收同一请求。单 Trial 可写成 {"request_id":"gpu-single-001","spec":{"runner":"envloop/bash@FULL_COMMIT"}}。HTTP 调用在 POST /v1/jobs 根层加入 "type":"train"。不能混合配方和 Runner spec；Runner 模式拒绝 Dataset/Task、上传文件和客户端注入的解析快照。

提交结果不确定时，以同一 request ID 和完全相同输入重试。首次授权的 Runner 快照保持不变，源引用后续移动不影响重试。数量、资源或其他显式输入变化会冲突，应使用新 ID；权限撤销仍然生效。

复制提交返回的 job_id，用于下方查询。每次运行只选择一种提交方式，避免重复 Job。每个 Trial 独立运行；程序支持时，可先减少 Trial 数或卡数进行较小规模的首次运行。

可选 CLI 快捷方式

若 el job submit --help 列出所需快捷参数，也可不写请求文件提交同一工作：

el job submit --type train \
  --runner envloop/bash@FULL_COMMIT \
  --trials 2 --gpu-type H100 --gpu 4 \
  --docker YOUR_PUBLIC_GPU_IMAGE \
  --cpu 8 --memory 64Gi --disk 100Gi --shm-size 16Gi \
  --command 'python -c "import torch; print(torch.cuda.device_count())"' \
  --timeout-seconds 600 --request-id gpu-run-001

参数拼写严格为 --trials、--gpu-type、--gpu。上例提交一个 Job、两个独立 Trial，每个 Trial 在单节点请求四张 H100；若同时执行，共需八张卡。实际并发由队列、配额和预算决定；这些 Trial 不组成分布式集群。Trial 数量默认一、最多 16，数量和卡数必须为正整数。

--docker 选择镜像，省略时使用 Runner 镜像；平台在分配资源前解析并冻结不可变 digest。镜像须为公开可拉取的 Linux GPU 镜像，含 Bash 与受支持 Python，并满足平台 bootstrap 和驱动要求。应用依赖和额外文件由预构建镜像提供。本流程不会扫描、打包或上传本地目录、脚本、源码文件。

--command 是已发布 Runner 声明的可选 run_command 参数，不替换入口；未声明支持的 Runner 会拒绝。保留多行和引号语义，必须含非空白内容、不能有 NUL、最多 65536 UTF-8 字节；省略时运行该 Revision 的默认逻辑。首版 Runner 模式不接受 Profile、自定义参数表或环境变量覆盖。

卡型、卡数、CPU、内存、磁盘、共享内存和超时均按每个 Trial 计。省略值由 Runner 与服务端策略补齐；必须得到有效 GPU 请求，服务端核对支持的硬件、数量、预算和上限。客户端不选择 executor、provider 或 backend。

核对执行与释放

el job get JOB_ID
el trial list --type train --job-id JOB_ID --json
el job log JOB_ID --follow
el job result JOB_ID
el job stop JOB_ID

逐 Trial 检查冻结 Runner 引用、镜像 digest、有效资源、发布入口、command、状态、原始退出码、输出状态和独立 cleanup_confirmed。非零退出保持失败；退出零但输出收集失败不能视为完整成功。日志保留真实 stdout/stderr 与 EOF，不把任意文本解释成虚构 loss/metrics。按 execution.outputs 声明保存的 Artifact 记录上传状态、大小和 SHA-256；它不会自动成为可恢复 Checkpoint。

一个 Trial 失败不取消其他 Trial。停止 Job 会取消所有待运行/运行中的 Trial，进行有界输出收集并逐项释放资源。用户代码开始后，执行丢失不会透明重放；需要重跑时提交新 Job。

Console Experiment 提供只读视图。通过 CLI/SDK 提交和管理 Job，再检查各 Trial 的输出与清理状态。

标签

请求文件与 SDK 支持在每个 Trial 的 spec 中填写可选 tags，最多 16 对字符串。键匹配 [A-Za-z0-9_][A-Za-z0-9_.-]{0,63}，值最多 256 个可打印字符。例如在 runner 旁增加 "tags": {"experiment": "gpu-baseline", "purpose": "sft"}，用 el job submit --type train --spec REQUEST.json 提交；没有单独的 --tags 参数。Job 与 Trial 返回 tags，Console 在 tag 区域展示。多个 Trial 时 Job 汇总显示第一个 Trial 的 tags，各 Trial 标签见 training.trials。此新增能力需要配套平台实现。

固定 Job Profile

兼容 Runner 可通过 spec.profile 接收 envloop.job-profile/v1 快照：inputs 是带 manifest 摘要的授权内容引用，recipe 是固定参数，plugins 是已批准插件绑定。平台验证内容与权限后才分配 GPU；客户端不上传路径或选择 provider。十进制 recipe 参数使用字符串。

Profile v2 将可执行 Recipe 引用与参数分开。各引用使用发布时的完整 manifest SHA-256，并选择声明匹配 envloop.train-recipe/1 ABI 和 Recipe 入口的 Runner Revision。例如，将 spec.profile 设置为以下结构，摘要占位符必须替换为发布结果中的真实摘要：

{
  "schema": "envloop.job-profile/v2",
  "recipe": {
    "uri": "envloop://recipes/envloop/pev-recipe@<recipe-manifest-sha256>",
    "manifest_sha256": "<recipe-manifest-sha256>"
  },
  "parameters": {"steps": 1},
  "inputs": {
    "data": {
      "uri": "envloop://datasets/envloop/pev-smoke-data@smoke-1",
      "manifest_sha256": "<dataset-manifest-sha256>",
      "config": "default",
      "split": "train"
    }
  },
  "plugins": []
}

Recipe 固定源码依赖和参数 schema。平台核验每个依赖的权限，将校验后的默认值与显式参数一同冻结。Recipe 源码归 recipes，数据输入归 datasets，输出仍归 artifacts。此能力需要配套平台与已发布 Runner 实现。

声明的输出经流式上传并读回校验。只有包含 adapter_config.json 和 adapter_model.safetensors 的兼容 LoRA 输出才登记为可供推理绑定的 durable Checkpoint；一般产物不自动成为模型。查看 Job result 的 checkpoint 列表和独立 cleanup_confirmed。