核心概念

Observable Library 将计算什么、张量来自哪里和何时执行计算分开处理。

可观测量 spec 与 identity

ObservableSpec 描述 source、selector、有序 transform 链、reduction、temporal 元数据、frequency 和 budget hint。它的 id 是完整 spec 的稳定 16 字符哈希。修改 identity 字段可能改变 id。

Observable 把 spec 与 compute callable 组合起来。Pack 是执行 API 接受的稳定可迭代容器；Runtime 将其物化时会拒绝重复 id。

生成

generate(model, reductions=..., transforms=...) 枚举 model.named_parameters() 的每个条目，并为每个参数和请求的 reduction 创建一个可观测量。

0.1.0 的生成过程不会发现 activation、gradient 或 loss 值。请手写这些可观测量，并提供合适的 source。

Transform 在 reduction 之前从左到右运行。Registry 在生成时验证 transform 和 reduction 名称；张量兼容性只在操作实际执行时检查。

数据源

所有 source 都实现 TensorSource protocol：

• HookSource 读取实时参数，以及捕获的 activation、gradient 和显式记录的 loss。

• FileSource 按 key 从 NPZ 文件读取数组。

• CheckpointSource 从 Torch state dict 读取 param.* 值。

Source 值封装在 TypedTensor 中，可携带 axes、stage 和 provenance 元数据。

Runtime 与调度

Runtime.observe() 计算某个 step 上所有符合条件的可观测量，并返回以 spec id 为键的字典。一次调用内，Runtime 会缓存每个 source lookup，使多个 reduction 共享一次张量读取。

frequency 控制 step 是否符合条件。Budget(max_compute_ms=...) 限制已声明的 budget_hint["compute_ms"] 估算值总和。调度器不会测量墙钟执行时间，也不会重新校准估算值。

OfflineAnalyzer 通过 analyze(step, **context) 委托给同一条 runtime 路径。

存储

ValueSink 是存储契约。LocalStorage 是一个可选实现，使用 SQLite 元数据和 NPZ payload 文件。query() 只支持按精确可观测量 id 和 step 读回；它不是通用分析查询引擎。

选择与 temporal 函数

Observable Library 0.1.0 只支持 selector="all"。delta、ema、slope 和 rolling_std 函数对显式数值历史运行。Spec 的 temporal 字段参与 identity，但 Runtime 不会自动应用 temporal 函数。