# ars-opd-rebuild

对论文 **OmniOPD: Logit-Free On-Policy Distillation via Speculative Verification**（arXiv:2606.01476）参考实现的分层重构。

## 项目双重目标

1. **学习**：通过按论文概念逐层重建代码，吃透 OmniOPD 的方法（chunk 级 MC 估计、peak-entropy 调度、贝叶斯平滑、trust-region 锚定）。
2. **研究基座**：产出一个结构清晰、模块化、可测试的代码库，作为后续研究的起点——替代原版 3200 行自包含 trainer 的组织方式。

原始参考实现位于 `references/ars-opd/`（只读、不入 git），核心是其 trl fork 中的 `trl/experimental/distillation/`。

## 方法一句话

学生模型在线生成推理轨迹；在轨迹的高熵"推理分叉点"选取 M 个 C-token 的 chunk，向黑盒 teacher 按前缀采样 N 条 rollout，用语义相似度（ROUGE-1）做 Monte Carlo 估计并经 Dirichlet 先验平滑，得到有界的 chunk 级监督权重；未被审计的 token 用对冻结初始模型的 KL 锚定防漂移（论文式 8）。全程不需要 teacher 的 logits。

## 目录结构

```
ars_opd/            核心包（模块 ↔ 论文概念一一对应）
  configs.py        dataclass 配置
  similarity.py     语义相似度 φ：rouge1 / edit_distance（式 3）  [纯逻辑]
  chunking.py       peak-entropy chunk 调度器（式 6-7）           [纯逻辑]
  estimator.py      MC 估计 + Dirichlet 贝叶斯平滑（式 4-5）      [纯逻辑]
  teacher.py        teacher 客户端（OpenAI 兼容 API / vLLM）      [IO 边缘]
  trainer.py        薄编排层：生成 → 审计 → 损失（式 8）
scripts/            训练/评测入口脚本
tests/              纯逻辑模块的单元测试（本地 CPU 可跑）
docs/               循序渐进的学习章节（论文↔代码映射）
references/         原论文 PDF + 参考实现（gitignore，只读对照）
```

## 规模选型（跑通优先，不追论文数值）

| 角色 | 模型 | 部署 |
|------|------|------|
| Student | Qwen3-0.6B | 远程 4×A800 训练 |
| API teacher（OmniOPD 主路径） | DeepSeek / MiniMax | OpenAI 兼容 API |
| White-box teacher（baseline 对照） | Qwen3-4B | 远程本地 vLLM |

## 工作流

- **本地**（这台机器）：读论文、写代码、跑 `tests/` 单元测试（CPU toy 数据对拍原实现）。
- **远程**（gpu-a800-060，4×A800-80G）：只跑训练与评测。代码经 gitea 同步：本地 push → 远程 pull → 启动脚本。
- 学习按 `docs/` 章节推进：每章 = 论文一节精读 + 原实现解剖 + 重构任务 + 验证方式。路线图见 `docs/00-roadmap.md`。