> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 观测与 ingest

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

训练容器里会注入 `STARFORGE_ENDPOINT` / `STARFORGE_RUN_ID` / `STARFORGE_TOKEN`。官方方法由 runner 自动埋点；自定义训练用 [`starforge.report`](/zh-Hans/api-reference/python-sdk) 把曲线打进来。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。

## 运维要点

<AccordionGroup>
  <Accordion title="FORGE_INGEST_URL 必须是训练节点能访问的地址" icon="network">
    图表没数据，最常见是填了 `127.0.0.1` 或集群外的地址。容器 / Pod / 计算节点要能直连这个 URL。
  </Accordion>

  <Accordion title="SSE 与反代" icon="radio">
    实时日志是 SSE：nginx 对 `/api` 关掉 `proxy_buffering`，读超时放宽。断线的客户端会按游标续传，不丢行。
  </Accordion>

  <Accordion title="指标失败不会打断训练" icon="shield-check">
    SDK 上报是旁路，挂了只打日志，不抛异常。lifecycle 是硬语义，失败会重试。
  </Accordion>

  <Accordion title="AI 诊断" icon="stethoscope">
    作业失败会自动跑诊断（可配 LLM），输入是日志尾部、指标趋势、验证样本和配置快照。诊断失败不影响作业状态。
  </Accordion>
</AccordionGroup>

## 自定义训练怎么上报

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

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`、图表是空的怎么查，见[自定义训练](/zh-Hans/guides/custom-training)。