观测与 ingest

训练指标、日志、产物怎么回到控制台，以及部署时要注意什么

训练容器里会注入 STARFORGE_ENDPOINT / STARFORGE_RUN_ID / STARFORGE_TOKEN。官方方法由 runner 自动埋点；自定义训练用 starforge.report 把曲线打进来。stdout/stderr 也是 runner 转发的，脚本里不用自己报日志。

​

端点一览

这些是 runner / SDK 用的，一般不用手搓 HTTP。

端点	数据
/api/ingest/metrics	训练标量（key / step / value 批量）
/api/ingest/logs	日志行（chunks + eof）
/api/ingest/validation	验证样本（多轮对话 + 奖励）
/api/ingest/hardware	GPU 利用率 / 显存等硬件时序
/api/ingest/lifecycle	starting / running / succeeded / failed
/api/ingest/artifact	checkpoint / hf_export / 评测报告登记
/api/ingest/benchmark	标准基准分数（幂等）
/api/ingest/environment	环境自定义指标

Ingest token 按 run 签发，限定 scope 和有效期（FORGE_INGEST_TOKEN_DAYS，要盖得住最长那次训练）。Web 守卫会拒绝拿 ingest token 去调普通 API。

​

运维要点

FORGE_INGEST_URL 必须是训练节点能访问的地址

图表没数据，最常见是填了 127.0.0.1 或集群外的地址。容器 / Pod / 计算节点要能直连这个 URL。

SSE 与反代

实时日志是 SSE：nginx 对 /api 关掉 proxy_buffering，读超时放宽。断线的客户端会按游标续传，不丢行。

指标失败不会打断训练

SDK 上报是旁路，挂了只打日志，不抛异常。lifecycle 是硬语义，失败会重试。

AI 诊断

作业失败会自动跑诊断（可配 LLM），输入是日志尾部、指标趋势、验证样本和配置快照。诊断失败不影响作业状态。

​

自定义训练怎么上报

不要手写 urllib，也不要拷 tutorial 里已经删掉的 common/telemetry.py。

from starforge.report import init, log, finish

init(hparams={"lr": 1e-5})
log({"loss": 0.42}, step=1)
finish()

包名 starforge-core，import 名 starforge。镜像、train.sh、图表是空的怎么查，见自定义训练。