Python SDK

starforge.report —— 让任何训练脚本都能把曲线打进控制台。

from starforge.report import init, log, finish

init(hparams={"lr": 1e-6, "kl_coef": 0.05})

for step, batch in enumerate(loader):
    loss = train_step(batch)
    log({"loss": loss, "reward": batch_reward}, step=step)

finish()

三个函数。不 import 任何训练框架，不需要继承任何东西，只要镜像里装了 starforge-core 就能用。

​

安装

catalog 里的镜像都自带。自定义镜像里：

pip install starforge-core

​

三条设计约束——它们会影响你的用法

绝不抛异常

回传是旁路。采集挂了，训练照常跑。你不需要给这些调用套 try。

没凭据就是空操作

同一个脚本在本机跑什么都不做，也不产生任何网络请求，所以不需要维护一个单独的「本地模式」分支。

哪都能 import

只依赖标准库。不会因为镜像里没装 requests 而 import 失败。

​

init()

init(
    hparams: Mapping[str, Any] | None = None,
    monitor_hardware: bool = True,
    monitor_interval: float | None = None,
) -> bool

启动回传会话。返回值表示回传是否真的开启了——在本机是 False，这不是错误。幂等：调两次是安全的， 第二次传 hparams 会把新的补进去。

hparams · Mapping

给控制台「配置」面板用的超参。嵌套字典会用点号摊平，{"policy": {"lr": 1e-6}} 变成 policy.lr。

monitor_hardware · bool · 默认值: "True"

启一个后台线程采集 GPU 利用率、显存和网络，供「系统」页展示。 如果作业里已经有别的东西在上报硬件，设成 False。

monitor_interval · float · 默认值: "10"

硬件采样间隔（秒）。STARFORGE_MONITOR_INTERVAL 可以覆盖默认值。

​

log()

log(metrics: Mapping[str, Any], step: int | None = None, prefix: str = "") -> None

发送一批标量。

log({"loss": 0.42, "reward": 0.71})                    # step 自动递增
log({"loss": 0.41}, step=121)                          # 显式指定 step
log({"loss": 0.41}, prefix="eval")                     # 变成 eval/loss
log({"grad": {"norm": 1.2, "clip": 0.8}}, step=121)    # 变成 grad.norm、grad.clip

非标量值在能取均值时折算成均值，折算不出来的直接丢弃——逐 token 的 loss 张量会变成一个数，字符串会被丢掉。 不传 step 时用内部计数器递增，这正是奖励函数里想要的行为：那里根本没有全局 step 的概念。

没先 init() 时 log() 会替你调。在奖励函数或环境代码里， 一行 from starforge.report import log 就够了——不用初始化，也不用把对象一层层传进去。

​

log_hparams() 与 finish()

log_hparams(params: Mapping[str, Any]) -> None
finish() -> None

log_hparams 在 init 之后往配置面板里补内容。finish 停止硬件采集并把缓冲区刷干净； 它是幂等的，也注册进了 atexit，所以正常退出的脚本严格来说可以不调用它。 还是调一下：进程在 atexit 执行前被杀掉时，缓冲区里剩的东西就丢了。

​

Hugging Face 与 TRL

from starforge.report import StarForgeCallback
from trl import GRPOTrainer

trainer = GRPOTrainer(..., callbacks=[StarForgeCallback()])

它按 Trainer 自己的生命周期完成 init、每个 log step 的 log 和结束时的 finish。 对任何 transformers.Trainer 以及所有基于它的 TRL trainer 都适用。

StarForgeCallback(monitor_hardware: bool = True, prefix: str = "")

它没有继承 transformers.TrainerCallback——Hugging Face 是按方法名调用回调的，鸭子类型就够了； 不继承还能让 starforge.report 在没装 transformers 的镜像里照样 import。

​

确认成功

提交作业，打开 Charts 页。第一次 log() 之后几秒内就会出现数据点。

如果日志在滚而曲线一直是空的，说明回传代码没跑到。进容器里确认：

echo $STARFORGE_ENABLED   # 必须是 1

如果是 1 但仍然没有点，说明 init() 根本没被执行到——在它旁边加一行 print 重新提交。

​

SDK 的其余部分

starforge.report 是公开接口。这个包同时导出 JobSpec 契约类型（JobSpec、Recipe、ResourceSpec 等） 以及 Reporter——平台自己的框架桥所用的底层客户端。它们分别记录在 ingest 契约和 JobSpec： 写框架适配器时才需要，给训练脚本加埋点时不需要。