# ops/ — T4 (16 GB) 真机流水线工具箱

本目录沉淀 2026-09-22 两次 T4 真机运行（smoke + 正式规模 scale-up）使用的全部运维脚本。
设计原则与复盘教训的完整叙述见 `../train.md` §12–§13。

## 文件索引

| 文件 | 用途 | 运行位置 |
|------|------|----------|
| `run_eval.py` | **一键评测入口（v0.4.2）**：`hf:<repo>@<subpath>` 自动下载检查点 + 重组适配器（sha256 校验）→ 后端 auto（GPU→hf fp16+LoRA merge / 否则 tiny）→ 逐游戏对局 → 带 provenance 的 JSON 报告。`--games all25` 跑 25 公开游戏；`--download-only` 预缓存游戏；`--list-games` 从 API 拉实时列表；`--env-dir` 指定游戏缓存目录；GAME_OVER 自动重置续玩（resets 入报告）；`--no-checkpoint --backend tiny` 即 CPU harness 测试 | 任意机器 |
| `fetch_games.py` | **游戏预缓存引导（v0.4.2）**：从 arcade API（匿名 key，无需 Kaggle 账号/接受规则）拉取全部 25 公开游戏源码到 `environment_files/`（约 3MB / 65 秒），之后所有评测永久离线 | 任意机器 |
| `t4_pipeline.py` | 冒烟流水线：env→code→data→smoke→stage_a→stage_b→stage_c→eval→assets→upload，断点续跑（done/ 戳 + 产物检查），阶段全部为隔离子进程（不许在桥接执行器进程里 import torch——上一窗口 7.8GB VRAM 泄漏的教训） | T4 VM，`subprocess.Popen` 脱离桥接进程 |
| `t4_scale.py` | 正式规模流水线：collect 24×1200 → stage_b 120 步 → stage_c 120 行 → eval → 增量上传 `t4_assets_v2/`；扩参 YAML 内嵌，运行时写入 `configs/t4_scale.yaml` / `configs/collect_scale.yaml` | T4 VM |
| `t4_smoke_s1.py` | 单次真实 2B 决策冒烟（预训练视觉塔前向 + 三头读出），由 t4_pipeline.py 的 code 阶段写入 repo 根目录 | T4 VM |
| `t4exec.py` | 隧道信封执行器（envelope v1 协议：b64url + crc32 + 76 字符换行），支持 status/run/runfile/get/put；URL 硬编码在文件头，每次会话按新隧道地址修改 | 本地 → VM |
| `t4_split_adapter.py` | 适配器分片器：16 字节 nonce 前缀 + 4×~17.4MB pt 分片 + manifest.json(sha256) + reassemble.py——绕过 HF xet 对 `*.safetensors` 静默吞文件的坑 | 本地/VM |
| `kaggle_kernel/` | Kaggle 提交 bundle（`submission.ipynb` + `kernel-metadata.json`，`kaggle kernels push -p ops/kaggle_kernel` 即用），由 `scripts/package_kaggle.py` 生成 | 本地 |
| `push_t4_note.py` | 推送编译缓存审计注记与 t4_assets 复用指南（compile_cache_note.json / README.md） | 本地 |
| `torch_kernels_t4.tar.gz` | torch NVRTC 内核缓存（`/root/.cache/torch/kernels/`，cc7.5 + CUDA 12.8 的 reduction_prod 预编译产物）。还原：`tar xzf torch_kernels_t4.tar.gz -C ~/.cache/` | 任意 T4 机器 |

## 评测一键启动（v0.4.2 起，25 公开游戏）

```bash
pip install arc-agi                      # 官方本地引擎（PyPI，纯 Python）
python ops/run_eval.py --download-only   # 一次性缓存 25 游戏（匿名 key，约 3MB）
python ops/run_eval.py --games all25     # 全量：GPU→v2 检查点(hf+merge)；无 GPU→tiny
python ops/run_eval.py --checkpoint <dir> --games ls20 --max-actions 120   # 本地检查点
```

- 检查点默认 `hf:tchbcb/qwenjev@t4_assets_v2/checkpoints`（qwenjev_s1.pt + hf_lora 分片自动下载/重组/校验）；
- 本地 CPU（2 核 / 3GB 容器）已验证 25/25 游戏跑通（tiny + v0.2.0 训练头，中位 0.59 步/秒，报告 `eval_report_public25_cpu.json`）；hf 后端需 ≥8GB 内存（fp16 2B），详见 `../train.md` §8.2；
- 汇报样例：`{game_id, win, final_state, best_level, resets, actions, seconds, steps_per_s}`。

## 典型复现路径

```bash
# 1) 本地改好 t4exec.py 的 URL → 验证隧道
python3 t4exec.py status
python3 t4exec.py run "print(40+2)"          # 期望 42

# 2) 上传流水线并脱离桥接进程发射
python3 t4exec.py put t4_pipeline.py /content/qwenjev_work/t4_pipeline.py
python3 t4exec.py run "import subprocess; subprocess.Popen(['python3','-B','/content/qwenjev_work/t4_pipeline.py'])"

# 3) 轮询状态（status json + 日志尾部）
python3 t4exec.py run "import json; print(json.load(open('/content/qwenjev_work/smoke_status.json'))['current'])"
python3 t4exec.py run "print(open('/content/qwenjev_work/logs/stage_b.log').read()[-400:])"
```

> 断点语义：所有阶段幂等（done/ 戳 + 产物存在检查），VM 死亡后重启只需重新发射同一脚本；
> 代码阶段永远从 HF snapshot_download 刷新（不吃旧代码），数据/权重阶段命中戳即跳过。