[Ji11]

概要

在 SDK 侧打通 swanlab.Histogram 的完整链路：用户在 log() 里传入 Histogram 对象，后台线程分批转换为 HistogramRecord，本地持久化后上传。proto 定义见 #1808。

数据流

swanlab.Histogram(sequence | np_histogram)
  → log() → BackgroundConsumer（histogram_batch）
  → RecordBuilder 分发 → HistogramRecord
  → CorePython.upsert_histograms（自动建列 / define_metric 显式建列）
  → 本地持久化 + sender.upload_histogram
  → POST /house/metrics（type=histogram）

变更内容

文件	内容
swanlab/sdk/internal/run/transforms/histogram/	Histogram 转换类：原始序列分桶（默认 64 桶、上限 512 桶）与预分桶两种输入；计数、边界的完整校验；继承 TransformHistogram
swanlab/sdk/internal/context/transformer.py	新增 TransformHistogram 基类，固化 HistogramRecord 信封
swanlab/sdk/protocol/core.py、core_python/core.py	CoreProtocol 与 CorePython 实现 upsert_histograms；列注册区分 scalar / histogram / media 三分支
swanlab/sdk/internal/core_python/metrics/	HistogramMetric 与 RunMetrics.define_histogram
swanlab/sdk/internal/core_python/pkg/builder/	build_histogram_record 与 build_auto_column 扩展
swanlab/sdk/internal/run/components/consumer/	consumer 新增 histogram_batch 批次、builder 分发注册、resolver 对非 SCALAR 指标回退 _step
swanlab/sdk/internal/core_python/transport/sender/	upload_histogram：按 UploadResult 约定编码上传，epoch 固定为 0，重试由 transport 层调度
swanlab/sdk/internal/core_python/api/upload.py、typings DTO	POST /house/metrics 的 histogram 请求封装
swanlab/sdk/internal/core_python/sync.py	断点续传回放的 histogram 分支
swanlab/__init__.py 等	swanlab.Histogram 导出（含 .pyi）

验证

• 全量单测 2094 passed / 36 skipped
• ruff、basedpyright 全过
• 进程内 HTTP 服务验证 sender → client → 请求体（epoch=0、_type、values、bins）

[Nexisato]

审核结论：通过（4 条改进建议，不阻塞合并）

本 PR 在 SDK 侧打通 swanlab.Histogram → HistogramRecord → 本地持久化 → 上传的完整链路，实现完整，本地与 CI 均通过；以下建议供参考。

#	级别	位置	问题	建议
1	建议	swanlab/sdk/internal/run/transforms/histogram/__init__.py:90	bins 只接受 Python int / list / tuple，np.ndarray、np.int64、range 都会被拒绝；np.int64 的报错为 must be an int ... got int64，信息自相矛盾。同时 np_histogram 的边界接受 ndarray，同一参数的两条输入通路行为不一致。	整数判断改用 numbers.Integral，边界统一交给 _validate_edges 处理；同步调整 test_bins_wrong_type 中把 np.array 视为非法类型的断言。
2	建议	swanlab/sdk/internal/run/transforms/histogram/__init__.py:121	sequence 为 requires_grad=True 的 torch.Tensor 时，np.asarray 会抛 RuntimeError；Histogram(...) 在 log() 之前构造，不在 consumer 的 safe.block 保护范围内，会直接中断训练。	对带 requires_grad 的对象先 detach()，或在 docstring 中明确只支持无梯度张量。
3	建议	swanlab/sdk/internal/core_python/sync.py:281	新增的 _handle_histogram 没有测试，而它是 swanlab sync 离线回放的唯一入口，逻辑与 _handle_metric 平行复制。	参照 tests/unit/sdk/internal/core_python/test_core_sync.py 中 media 的用例补一条 histogram 版本，覆盖自动补列与 step 过滤。
4	建议	swanlab/sdk/internal/core_python/transport/sender/__init__.py:248	512 桶时单条 histogram 载荷约 20KB，而 record_batch 默认 10000，理论上一轮 flush 可拼出约 200MB 的单请求。	为 histogram 单独设置较小的批次上限，或按序列化字节数切批。

验证

• uv run pytest -q：2109 passed, 21 skipped
• uv run ruff check .：通过
• uv run basedpyright：0 errors, 0 warnings
• PR Actions：19 个 job 通过，1 个 skipping

[Nexisato]

另外还有几项需要等待后端上线后再实现:

• swanlab sync 同步离线数据
• swanlab openapi/cli 支持 histogram 类型的数据 （同步更新 skill），这个我来处理吧