从训练代码回传

运行中的作业把曲线、样本、日志和产物送进控制台所讲的那份契约。

from starforge.report import init, log, finish

init(hparams={"lr": 1e-6, "kl_coef": 0.05})
log({"loss": 0.42, "reward": 0.71}, step=120)
finish()

对绝大多数人来说这就够了——Python SDK 已经替你讲了这份契约。 只有在给 catalog 之外的框架写适配器、或者要用别的语言写客户端时，才需要往下读。

​

平台注入了什么

每个训练容器里都会出现四个环境变量。你的代码读它们；它拿不到账号凭据、集群地址或对象存储密钥。

变量	含义
STARFORGE_ENABLED	回传已接通时为 1，作业被有意设为离线时为 0。其他取值（包括未设置）都是配置错误，应当直接抛错，而不是静默跳过
STARFORGE_ENDPOINT	ingest 路由的基础 URL，已经包含 /api/ingest
STARFORGE_RUN_ID	这些回传属于哪次 run。每个请求体都要重复它
STARFORGE_TOKEN	绑定这次 run 的 ingest token，有效期 30 天

用 X-StarForge-Token: <token> 认证。这些路由同时也接受 Authorization: Bearer <token>， 已经有 bearer 封装的客户端可以直接复用。

​

接口

全部是 POST，全部收 JSON，全部要带 run_id。

POST /api/ingest/lifecycle —— 声明训练真正开始的时刻

{ "run_id": "run-4f2a91", "event": "running", "ts": "2026-08-31T09:14:22+00:00" }

事件取值：starting、running、succeeded、failed。

在把控制权交给训练 entrypoint 之前的那一刻打 running。执行器自己报的 RUNNING 要早得多—— 它在建虚拟环境、拉权重之前就触发了，这两件事可能耗掉好几分钟——拿它当计量起点会系统性地多算。

POST /api/ingest/metrics —— 曲线

{
  "run_id": "run-4f2a91",
  "points": [
    { "key": "train/loss", "step": 120, "value": 0.42, "ts": "2026-08-31T09:14:22+00:00" },
    { "key": "train/reward", "step": 120, "value": 0.71, "ts": "2026-08-31T09:14:22+00:00" }
  ]
}

返回 {"ok": true, "inserted": 2}。数据点必须已经摊平：一个 key 一个 step 对应一个标量。 嵌套字典和非标量值由调用方自己先归约。

POST /api/ingest/hparams —— 配置面板

{ "run_id": "run-4f2a91", "params": { "policy.optimizer.kwargs.lr": 1e-6, "grpo.kl_coef": 0.05 } }

是 upsert，再调一次补新 key 即可。嵌套配置请用点号摊平。

POST /api/ingest/validation —— 样本对话与奖励分布

{
  "run_id": "run-4f2a91",
  "step": 120,
  "samples": [
    {
      "user": "A train leaves Chicago at 3pm...",
      "assistant": "Let me work through this step by step...",
      "reward": 0.83,
      "extra": { "reference": "4 hours" }
    }
  ],
  "avg_reward": 0.71,
  "accuracy": 0.64,
  "chunk_index": 0,
  "total_chunks": 1
}

user、assistant、env、reward 是控制台渲染的骨架。算法特有的字段——DPO 的 rejected、 SFT 的参考答案——放进每条样本的 extra，平台不需要理解它们就能展示。

验证轮次很大时可以分片：设置 total_chunks，每片带自己的 chunk_index 分别发送。

POST /api/ingest/logs —— stdout 和 stderr

{ "run_id": "run-4f2a91", "chunks": ["step 120 | loss 0.42\n"], "eof": false }

这是唯一一条要求调用方自己吞掉异常的通道。其他 ingest 接口都是失败即抛，因为丢一个指标或一个产物 是数据事故；丢几段日志不是，而控制台抖一下就把一次成功的训练判成失败，代价大得多。

不要自己发 eof。作业进入终态时由平台统一补——容器被 SIGKILL 时，转发进程根本没有机会发。

POST /api/ingest/artifact —— 登记产出

{
  "run_id": "run-4f2a91",
  "kind": "checkpoint",
  "path": "s3://starforge/runs/run-4f2a91/checkpoints/step-500",
  "format": "distcp",
  "step": 500,
  "size_bytes": 14203847362
}

kind 取值：checkpoint、hf_export、eval_report、merged_model。format 必填且不得为空。

容器类执行器下，path 必须是对象存储 URI。容器一销毁本地路径就不存在了，平台不会去猜它去了哪。 先用 GET /api/ingest/artifact/upload-url 拿一个签名 URL 上传。

POST /api/ingest/hardware 和 /environment —— 系统页

hardware 收采样点（GPU 利用率、显存、网络）。environment 收一次性的静态信息：包版本、CUDA 版本、 GPU 型号。environment/nodes 上报多节点作业的每节点硬件。

除非你传了 monitor_hardware=False，否则这三样 SDK 都会替你采集和发送。

POST /api/ingest/benchmark —— 外部产生的评测分数

给在平台之外打分、再把结果报回来的 harness 用。围绕它的完整流程见评测。

​

确认成功

在控制台打开这个作业。第一次调用 metrics 之后几秒内，Charts 页就会出现一个点。

如果日志在滚而曲线一直是空的，说明回传调用根本没执行——确认容器内 STARFORGE_ENABLED 是 1， 并且代码确实走到了 init()。

为什么回传代码放在 SDK 里，而不是用户上传的工作目录里

生命周期打点和产物登记，是平台判断作业何时真正开始、产出了什么的依据。如果这段代码放在用户自己的 common/ 里，删掉或改坏那个目录就会让平台变瞎，而动手的人还不会知道。这也是这个模块只依赖标准库的原因： 它必须能在任何训练镜像里干净地 import，而每多一个依赖，就多一处「镜像里恰好没装」的失败点。