Update README.md

README.md

@@ -1,10 +1,188 @@
 ---
-title: README
-emoji: 🦀
-colorFrom: yellow
+title: 自一致性与多数投票的收益边界研究
+emoji: 📊
+colorFrom: blue
 colorTo: indigo
 sdk: static
 pinned: false
 ---
 
-Edit this `README.md` markdown file to author your organization card.
+# 📊 LLM 自一致性与多数投票的收益边界研究
+
+> **CISC 7402 — Mathematics for Artificial Intelligence 课程项目**
+> **团队规模**：2 人 | **展示截止**：11月18日 | **当前状态**：🟢 实验执行中
+
+## 🔍 研究问题
+
+大语言模型在单次生成时具有随机性。自一致性（Self-Consistency）通过采样多条推理路径并**多数投票**来提升准确率，但这并非免费的午餐：采样规模扩大带来计算成本的线性增长，而准确率增益可能边际递减；温度升高虽增加多样性，却可能引入更多错误。
+
+本项目（基于 GSM8K 数据集与 Qwen2.5-7B 模型）旨在量化回答以下三个核心问题：
+1. **主效应**：多数投票（T=0.6, N=20）相对贪心解码（Greedy）的真实净增益是多少？
+2. **收益边界**：准确率增益随采样次数（N）和温度（T）如何变化？
+3. **置信度代理**：早期投票的一致性（c₅）能否有效预测“是否值得继续采样”？
+
+---
+
+## 👥 团队分工与进度规划
+
+为了保证在 11 月 18 日前交付可验收、可演示的版本，采用 **“管线与统计解耦 + 强制交接点”** 双人协作模式。
+
+### 🧑‍💻 成员 A：实验管线负责人
+* **核心职责**：保障 12,100 次生成任务“跑得完、跑得对、可复现、可续跑”。
+* **关键产出**：
+  * 环境配置与模型加载（Qwen2.5-7B-Instruct）
+  * 数据抽样冻结（dev 30 / test 100）与断点续跑脚本
+  * 原始数据落盘（`raw.parquet`）与成本/失败率统计（`cost.csv`）
+* **核心代码**：`common.py`, `gen.py`, `merge.py`
+
+### 🧑‍🔬 成员 B：统计分析与写作负责人
+* **核心职责**：将原始数据转化为可辩护的统计结论与可视化图表。
+* **关键产出**：
+  * C/D 分解（纠错数 vs 损害数）与配对 Bootstrap 置信区间
+  * c₅（前 5 票一致性）分层分析与敏感性检验
+  * 独立复算（`recompute.py`）、三张核心主图与报告主体撰写
+* **核心代码**：`analyze.py`, `recompute.py`, `plots.py`
+
+### 🚦 关键里程碑（11.18 D-Day 倒排）
+- [x] **D5 冻结交接**：确认参数口径，锁定提示词与解析规则（`frozen.json`）。
+- [ ] **D9 数据交接**：A 交出原始数据，B 需在 24h 内独立复算主结果，**数值一致才签字**。
+- [ ] **D13 结论交接**：共写“能说/不能说”的结果边界。
+- [ ] **D14 最终排练**：定稿，不再修改任何内容。
+
+---
+
+## 🛠️ 实验设计锁定 (Scope Lock)
+
+为了确保 2 周内交付确定性结果，我们对实验规模进行了如下锁定：
+
+| 维度 | 设定值 | 说明 |
+| :--- | :--- | :--- |
+| **模型** | Qwen2.5-7B-Instruct | 仅跑 7B，3B 作为后续扩展 |
+| **数据集** | GSM8K (Test 100 题) | dev 30 题用于 Pilot 验证 |
+| **温度 (T)** | {0.3, 0.6, 0.9} | 覆盖低、中、高随机性 |
+| **采样数 (N)** | {1, 5, 10, 20} | 观测边际递减，去掉 N=3 |
+| **独立流** | 2 Streams | 满足配对 Bootstrap 需求 |
+| **总生成量** | **12,100 次** | 100×3×2×20 + 100 (Greedy) |
+
+---
+
+## 📂 代码结构一览
+
+```text
+project/
+├── config.py              # 全局配置唯一真源（锁定版）
+├── common.py              # 提示构造 / 答案抽取 / 采样 / 投票
+├── gen.py                 # 正式生成（分片 + 断点续跑）
+├── merge.py               # 合并与管线内主统计
+├── recompute.py           # B 独立复算（交接点闸门）
+├── analyze.py             # C/D 分解 / c5 分层 / Bootstrap
+├── plots.py               # 三张核心主图绘制
+└── degrade.py             # 超时/失败应急降级脚本
+```
+
+---
+
+## 📌 交付标准与验收清单 (11.18)
+
+本项目不仅追求结果，更注重过程的严谨性。11 月 18 日的最终展示与提交必须包含以下四件套：
+
+### 1. 统计结果 (Statistical Results)
+- [ ] **主比较区间**：提供点估计与 95% 配对 Bootstrap 置信区间（基于 2000 次重采样）。
+- [ ] **增量分析**：展示相邻 N 的增量表（明确标注间距不均），并绘制三温度下的准确率曲线。
+- [ ] **C/D 分解**：清晰报告 \(C_N\)（纠错数）与 \(D_N\)（损害数），并绘制堆叠柱状图。
+- [ ] **一致性分层**：展示 \(c_5\) 三层分组（低/中/高）的组内样本量 \(n\)、N=5→20 的增益与区间（若 \(n<30\) 需标注“不稳定”）。
+- [ ] **敏感性分析**：提供“无效票计入分母”条件下的 \(c_5\) 对比附表。
+
+### 2. 可复现代码仓库 (Reproducible Repo)
+- [ ] 包含 `ids.json` 与 `frozen.json` 的冻结快照。
+- [ ] 包含完整的生成管线（`gen.py`）与分析脚本（`analyze.py`）。
+- [ ] 提供环境依赖文件（`requirements.txt`）。
+
+### 3. 最终报告 (Final Report)
+- [ ] 严格使用 ICLR 2027 MT_E 模板，正文控制在 **≤9 页**（附录不限）。
+- [ ] 包含“与 Proposal 的差异”说明（如：因时间约束，测试集降至 100 题，可检出效应约 ≥7pp）。
+- [ ] 附录包含：核心代码骨架、指标公式汇总、成员贡献声明、AI 工具使用声明。
+
+### 4. 演示材料 (Presentation)
+- [ ] 15 分钟的高质量展示（含三张核心主图 + 一页“我们没发现什么”的负结果/边界声明）。
+
+---
+
+## 🛡️ 核心代码示例：跨成员独立复算 (Double-Check)
+
+为了打破“一人跑实验、一人写报告”的串行反模式，我们在 `D9` 设置了强制交接点。**成员 B 必须使用独立的 `recompute.py` 从原始数据重新计算主结果，与成员 A 的管线产出逐项比对（容差 `1e-6`），一致后方可进入分析阶段。**
+
+```python
+# recompute.py - 由成员 B 独立编写与执行（不 import 成员 A 的分析代码）
+import pandas as pd
+import config as C
+
+def verify_main_results():
+    # 1. B 独立读取底层数据
+    df = pd.read_parquet(C.RAW_PARQUET)
+    
+    # 2. B 独立计算核心指标
+    greedy_acc = df.drop_duplicates("qid").greedy_correct.mean()
+    main_df = df[(df.T == C.MAIN_T) & (df.N == C.MAIN_N)]
+    main_acc = main_df.correct.mean()
+    C_count = int(((~main_df.greedy_correct) & main_df.correct).sum())
+    D_count = int((main_df.greedy_correct & (~main_df.correct)).sum())
+    
+    # 3. 与成员 A 的产出一一比对
+    ref = pd.read_csv(C.MAIN_STATS_A).iloc[0]
+    checks = {
+        "greedy_acc": (greedy_acc, ref.greedy_acc),
+        "main_acc":   (main_acc, ref.main_acc),
+        "C":          (C_count, int(ref.C)),
+        "D":          (D_count, int(ref.D))
+    }
+    
+    # 4. 强制一致性校验（不通过则阻断流水线）
+    for k, (v, r) in checks.items():
+        assert abs(float(v) - float(r)) < 1e-6, f"{k} 数值不一致！A={r}, B={v}"
+    
+    print("✅ [交接点 2 通过] 成员 B 独立复算成功，数据一致性校验通过。")
+
+if __name__ == "__main__":
+    verify_main_results()
+```
+
+---
+
+## 📅 项目时间线 (2-Week Sprint to D-Day)
+
+为了确保在 11.18 前交付高质量的展示版本，采用倒排期管理，将 2 周时间精确到天，并设置了三个“不通过不推进”的硬交接点：
+
+- **[D1-D2] 需求冻结 (11.04 - 11.05)**：环境搭建、数据抽样冻结（Test 100 / Dev 30）、文献矩阵梳理。
+- **[D3-D4] Pilot 与骨架 (11.06 - 11.07)**：跑通小网格测试，分析脚本与绘图模板使用 Pilot 数据联调。
+- **[D5] 🔒 硬闸门：参数冻结 (11.08)**：双方签字确认 `frozen.json` 与 `metrics_spec.md`，此后不得单方面修改实验口径。
+- **[D6-D8] 正式生成 (11.09 - 11.11)**：A 启动断点续跑生成（优先跑完 T=0.6），B 同步撰写 Method/Setup 草稿。
+- **[D9] 🚦 硬闸门：独立复算 (11.12)**：A 交付 `raw.parquet`，B 必须在 24h 内跑通 `recompute.py` 并签字，否则触发降级预案。
+- **[D10-D12] 分析与产出 (11.13 - 11.15)**：输出主比较区间、C/D 分解、c5 分层；B 完成主图绘制，A 完成实验演示页。
+- **[D13] 🤝 硬闸门：结论边界 (11.16)**：共同撰写“能说/不能说”的 Discussion 段落，防止过度推断。
+- **[D14] 最终定稿与排练 (11.17)**：15分钟展示排练，设备检查。**此后不再修改任何内容**。
+- **[D-Day] 项目展示 (11.18)** 🎯
+
+---
+
+## 📜 学术规范与声明 (Academic Integrity)
+
+作为课程项目的重要组成部分，我们严格遵守学术规范，并在最终报告中作如下声明：
+
+### 成员贡献声明 (CRediT)
+- **成员 A (实验管线)**：负责模型部署与显存调度、提示与解析规则验证、12,100次生成的网格调度与断点续跑、原始数据落盘及成本/失败率统计；参与冻结参数决策；负责展示的实验部分。
+- **成员 B (统计与写作)**：负责 C/D 分解与配对 Bootstrap 实现、\(c_5\) 分层与敏感性分析、全部图表绘制、文献综述与报告主体撰写；在 D9 执行独立复算；负责展示的分析部分。
+- **共同承担**：研究问题确定、主比较口径决策、结论边界撰写、报告交叉互审、排练。
+
+### AI 工具使用声明 (AI Usage)
+本项目在以下环节使用了生成式 AI 工具辅助：
+1. **环境与样板代码**：辅助生成数据加载、绘图模板代码，核心实验逻辑（随机种子设置、投票逻辑）由成员独立设计并逐行审查。
+2. **文本润色**：辅助对报告草稿的段落衔接与英文表述提出修改建议，全部研究结论、实验分析与局限性讨论均由团队成员独立完成。
+3. **数据完整性**：**未在任何环节使用 AI 工具伪造、生成或改写实验数据**。所有数值结果均可由仓库内代码与公��的原始记录文件复现。
+
+---
+<div align="center">
+  <p><b>CISC 7402 - Mathematics for Artificial Intelligence</b></p>
+  <p><i>"A 保数据真且可复现，B 保结论稳且说得清。"</i></p>
+  <p>© 2026 Team Self-Consistency. All Rights Reserved.</p>
+</div>