# 上海 Mooncake 实验数据规范 v1.0

生效日期：2026-10-19。时区：Asia/Shanghai。

## 1. 权威目录与标识

权威源为上海共享目录 `/data/CPL/share/hty_workspace/result/`。Mac 目录为同步副本，网站仅使用发布目录。

```text
hty_workspace/
  result/<run_id>/
    manifest.json
    suite_results.json
    suite_complete.json
    <case_id>/
      run_metadata.json
      summary.json
      cleanup.json
      warmup_validation.json
      benchmark_store_validation.json
      traffic_summary.json
      kv_transfer_timing.json
      key_timestamps.csv
      traffic_rates.csv
      kv_tasks.csv
      store_handlers.csv
      raw/                       新实验原始追踪
      charts/                    新实验图表
  experiments/
    v1/runs/<run_id>/
      manifest.json
      cases/<case_id>/case.json
    public/
      catalog.json
      publish_ready.json
      runs/<run_id>/<case_id>/
  observability/catalog_v1/
    catalog.py
    experimentctl.py
```

- run_id 全局唯一，推荐 `kv_YYYYMMDD_HHMMSS_40_156`。
- case_id 推荐 `c01_16384_c128_f100_a001`。重试递增 attempt，创建新目录；不得复用失败目录。
- 原始结果不覆盖、不改名。校正、重算和图表改版另存 revision，记录父版本、原因、代码 SHA256。历史现有目录原样保留，由适配器读取。
- `role=main` 为主矩阵；`role=control` 为热连接等补充对照。重复实验用 repeat_of 指向原组，不与首次运行混合求均值。

## 2. manifest 必须记录

schema_version、run_id/suite、title、created_at、timezone；参与主机（client/warmup/benchmark/master）；model 名称与 revision；容器镜像、运行脚本 SHA256；协议；输入 tokens、并发、请求数、输出 tokens、名义前缀比例、预期匹配 tokens；网络条件及来源；校时偏移、误差界和缓存 namespace。

10G/100G 是实验者声明的条件标签，独立核验后才可设置 verified=true。不得把端口标称速率填作实测吞吐。历史五轮条件以 2026-10-19 用户声明标记；热连接对照继承所属100G轮条件。

1M 当前对应 **1,024,000 tokens**。16K/64K/256K 分别为16,384/65,536/262,144 tokens。

## 3. 指标与缺失值

| 字段 | 单位 / 定义 |
|---|---|
| nominal_hit_pct | 配置的前缀比例 |
| matched_tokens_min/max | 首次缓存查找实际匹配的 tokens 范围 |
| actual_hit_pct_min/max | 匹配 tokens / 输入 tokens ×100 |
| payload_bytes | 成功 GET 的有效字节数 |
| get_window_s | 最早 GET 开始至最晚 GET 完成的跨度 |
| effective_gbps | payload_bytes ×8 / get_window_s /10^9 |
| get_active_union_s | 所有 GET 时间区间的并集长度 |
| get_active_gbps | payload_bytes ×8 / get_active_union_s /10^9，独立列出 |
| ttft_mean_s | 逐请求首 token 延迟的算术平均 |
| cache_remaining_keys | 本组结束时剩余缓存键数 |
| NPU tx/rx Gbit/s、pps | 八端口区间速率合计，包含端口上其它通信 |

KV 完整复用粒度为4096 tokens；完整前缀通常匹配 N−1。名义80%可因块对齐成为实际75%，两者分别记录。

缺失为 null，不填0。0%命中且GET=0时带宽为 null；payload=0。不得平均各组带宽来宣称总体带宽；合并时必须使用一致的字节数与时间口径。

## 4. 时间与原始追踪

- epoch纳秒用十进制字符串，ISO8601保留 `+08:00`；另存相对时间。
- aligned_wall_ns 已校准，不再重复减偏移。保留每台主机 offset_ns 和 uncertainty_ns。
- 跨机时钟误差内不判先后；单机耗时使用单调时钟。
- 任务记录 operation、task_id、request_id、主机、worker、开始/结束、状态、字节数；区分查找、PUT、GET、发送handler。
- 原始JSONL/逐包头保存在实验源目录，不要求随网页全部分发。

## 5. 验收与发布

1. manifest 定义计划；每组使用唯一缓存前缀及 namespace。
2. 预热前确认本组键未命中，预热 PUT 完整可见后再压测。
3. 核对成功请求数、GET成功数、实际匹配、来源主机与键对应。
4. 0%要求GET=0、payload=0；有命中要求远端KV来源符合本轮计划。
5. 请求与异步写回排空后只清理本组键，记录cleanup.json，remaining_keys=0。
6. 每组验收后追加suite_results.json；整轮结束写suite_complete.json。JSON通过临时文件+os.replace原子落盘。
7. 发布器读取已验收组，生成规范索引、图表数据、文件清单和SHA256，最后写publish_ready.json。
8. CUVM校验清单后原子切换数据版本；失败保留上版，记录错误，不能覆盖成空索引。

## 6. 历史导入

历史五轮64组主实验及1组热连接对照均生成v1规范索引。两次observed单次观测标为historical，缺少的清理、批量验收等字段保持null。

旧successful_payload_bytes映射payload_bytes；aggregate_effective_Gbps映射effective_gbps；hostname依据clock_offsets映射主机；duration_ms映射elapsed_ms。

## 7. 后续操作

新实验优先使用 `experimentctl.py init` 创建清单，运行器按清单写结果。完成后执行 `experimentctl.py finalize --run-id <run_id>` 验收与发布。现有运行器兼容保留，其已验收结果会由catalog.py自动导入。

```bash
python3 /data/CPL/share/hty_workspace/observability/catalog_v1/experimentctl.py init \
  --title '完整前缀复测' --network 10G \
  --condition-source '实验者声明' --receiver 156 \
  --model '实际模型名称' --model-revision '实际版本或权重哈希' \
  --image '实际镜像及digest' --script /实际运行脚本.py \
  --matrix 16K:1:100 --matrix 16K:128:100

python3 /data/CPL/share/hty_workspace/observability/catalog_v1/experimentctl.py finalize \
  --run-id <run_id>
```

## 8. 网站发布范围

仅发布规范汇总、降采样时间线、任务与流量CSV、图表。云密钥、登录口令、SSH私钥、环境变量、完整提示词及无关运行日志不进入网站。发布工具使用文件允许清单。