Blame for README.md

---
title: 自一致性与多数投票的收益边界研究
emoji: 📊
colorFrom: blue
colorTo: indigo
sdk: static
pinned: false
---

# 📊 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 倒排）
- [ ] **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>© 2026 Team Self-Consistency. All Rights Reserved.</p>
</div>