ars-opd-rebuild/CLAUDE.md

CLAUDE.md

[!URGENT]

1. 本项目是学习驱动的科研重构项目：通过分层重建 OmniOPD 参考实现来学习论文方法，同时产出可作为后续研究基座的干净代码库。学习优先——用户要逐章理解每个模块，不要一次性替用户写完所有代码；每章先讲清楚，重构任务由用户主导、你配合。
2. 所有思考过程和回复必须使用简体中文。

1. 项目元数据

• 论文: OmniOPD (arXiv:2606.01476v2)，logit-free 的 chunk 级 on-policy 蒸馏。PDF 在 references/2606.01476v2.pdf
• 参考实现: references/ars-opd/（只读、不入 git），核心在 trl/trl/experimental/distillation/
• Conda 环境: ars-opd（Python 3.11）；远程环境建在 /data 下（根分区已满）
• 版本管理: git，远程 git@gitea.iomgaa.online:iomgaa/ars-opd-rebuild.git，本地 push → 远程 pull 同步

2. 架构哲学（Ousterhout 深模块，非 Clean Architecture）

• 模块按论文概念划分，不按技术角色划分。判据：看到论文某公式能说出它在哪个文件；打开一个文件能说出它对应论文哪一节。
• 纯逻辑核心 / IO 边缘：similarity.py、chunking.py、estimator.py 是纯逻辑模块——只依赖 torch/numpy 标准运算，禁止 import transformers / vllm / openai / requests；所有外部 IO 收口在 teacher.py（API/vLLM 客户端）与 trainer.py（模型编排）。纯逻辑模块必须能在本地 CPU 上用 toy 数据测试。
• 不做防御性膨胀：不写接口层/工厂/注册表；一个模块从上读到下能看懂全部流程。但纯逻辑模块必须有单元测试（对拍参考实现）。
• 配置显式化：所有实验参数走 configs.py 的 dataclass；严禁硬编码路径、模型名、URL（参考实现里的 /fsx 硬编码是反面教材）。密钥走 .env。

3. 模块 ↔ 论文映射（单一事实源）

模块	论文	内容
ars_opd/similarity.py	§3.2.1 式(3)	语义相似度 φ（rouge1 / edit_distance）
ars_opd/estimator.py	§3.2.2 式(4)(5)	MC 估计 + Dirichlet 贝叶斯平滑 π̂
ars_opd/chunking.py	§3.2.3 式(6)(7)	熵计算 + peak-entropy chunk 选择
ars_opd/teacher.py	§3.2.1	teacher rollout 采样（OpenAI 兼容 API + 缓存 / vLLM）
ars_opd/trainer.py	§3.2.4 式(8)	chunk 蒸馏损失 + trust-region KL 锚定，编排全流程

4. 常用命令

conda activate ars-opd && pytest tests/ -x -q     # 单元测试（本地 CPU）
conda activate ars-opd && ruff check ars_opd/ --fix && ruff format ars_opd/

5. 本地-远程规则

[!CRITICAL]

• 远程机 gpu-a800-060：8×A800-80G，只允许用其中 4 块；所有 GPU 命令必须显式 CUDA_VISIBLE_DEVICES=<idx>，先 nvidia-smi 确认空闲卡，严禁自动选卡。
• 远程根分区仅剩 12G：conda 环境、HF 缓存（HF_HOME）、模型、checkpoint、数据集一律放 /data/zym/ 下。
• 长任务用 tmux 跑，日志不缓存（python -u / PYTHONUNBUFFERED=1），确保可实时检查。
• 远程机器上不改代码，只 git pull + 跑脚本；本地不跑训练。

6. 学习工作流

1. 章节文档在 docs/，按 docs/00-roadmap.md 的分层顺序推进；每章结构：论文精读 → 参考实现解剖（带行号）→ 重构任务 → 验证方式。
2. 重构一个模块前，先对照参考实现列出其全部行为（含 trick 和 workaround），逐一确认保留/替代/删除。
3. 每个纯逻辑模块完成后，用 toy 数据对拍参考实现的对应逻辑（参考其 validate_mc_estimator.py / validate_chunk_mc_estimator.py）。
4. 文档规范：优先表格与公式，代码块 ≤15 行（展示思路用伪代码，完整代码引用文件路径），引用参考实现必须带 文件:行号。

7. 代码规范

• 公共函数完整类型注解；模块/类/函数写中文 docstring（功能、参数、返回、关键实现细节）。
• 严禁 except Exception: pass；出错直接报错，不用默认值兜底。
• 张量函数在 docstring 中注明各参数的 shape。
• 提交信息用中文，说明"这一步对应哪一章/哪个模块"。