# 方向 9 实验代码使用指南

## 代码结构

```
experiments/
├── cross_model_convergence.py    # E1: 跨模型谱收敛流水线
├── emergence_detection.py         # E3: 能力涌现谱突变检测
├── visualization_direction9.py    # 可视化模块
├── run_direction9_experiments.py  # 统一运行脚本
└── DIRECTION9_GUIDE.md           # 本文档
```

## 快速开始

### 1. 前置检查

```bash
source venv/bin/activate
python experiments/run_direction9_experiments.py
```

### 2. 运行所有实验

```bash
# 运行 E1 + E3 + 可视化
python experiments/run_direction9_experiments.py --all
```

### 3. 运行单个实验

```bash
# E1: 基础谱收敛验证
python experiments/run_direction9_experiments.py --experiment E1

# E3: 能力涌现检测
python experiments/run_direction9_experiments.py --experiment E3

# 仅生成可视化
python experiments/run_direction9_experiments.py --visualize
```

## 实验说明

### E1: 基础谱收敛验证

**目的**: 验证不同模型对同一文本集的 r_eff 是否随模型能力增大而收敛

**输出**:

- `output/cross_model/e1_result.json` - 完整结果
- `output/cross_model/e1_summary.md` - 摘要报告
- `output/figures/rs_cross_comparison.png` - RS_cross 对比图
- `output/figures/spd_heatmap_*.png` - SPD 热力图

**配置**: 在 `run_direction9_experiments.py` 中修改 `run_experiment_e1()` 函数

### E3: 能力涌现谱突变检测

**目的**: 检测 r_eff 曲线中的突变点，关联能力涌现

**输出**:

- `output/emergence/emergence_results.json` - 完整结果
- `output/emergence/emergence_summary.md` - 摘要报告
- `output/figures/emergence_curves.png` - 涌现曲线图

**配置**: 在 `run_direction9_experiments.py` 中修改 `run_experiment_e3()` 函数

## 直接使用底层 API

### 跨模型谱收敛分析

```python
from experiments.cross_model_convergence import CrossModelConvergence, ExperimentConfig

config = ExperimentConfig(
    models=["llama3.2-3b-instruct", "Mistral-7B-v0.3", ...],
    model_paths={...},
    datasets=["gsm8k", "math", ...],
    output_dir="output/e1"
)

analyzer = CrossModelConvergence(config)
result = analyzer.run_experiment_e1()
```

### 能力涌现检测

```python
from experiments.emergence_detection import EmergenceDetector

detector = EmergenceDetector(
    model_sequence=[...],
    model_paths={...},
    model_mmlu={...},
    output_dir="output/e3"
)

results = detector.run_full_analysis(
    abilities=["cot_reasoning", "arithmetic", ...]
)
```

## 输出文件说明

### JSON 结果文件

- `r_effs`: 各模型在各数据集上的有效秩
- `rs_cross`: 跨模型谱方差（核心指标）
- `spd_matrices`: 模型间谱距离矩阵
- `r_eff_curve`: 能力轴上的 r_eff 变化曲线
- `changepoints`: 检测到的突变点位置

### 可视化图片

- `rs_cross_comparison.png`: RS_cross 跨域分层对比
- `spd_heatmap_*.png`: SPD 模型间谱距离热力图
- `emergence_curves.png`: 能力涌现 r_eff 曲线
- `summary_dashboard.png`: 实验摘要仪表盘

## 自定义配置

### 添加新模型

在 `run_direction9_experiments.py` 中修改：

```python
MODEL_SEQUENCE = [
    ...,  # 现有模型
    "your-model-name"  # 新增
]

MODEL_PATHS = {
    ...,
    "your-model-name": "model/weights/your-model"
}

MODEL_MMLU = {
    ...,
    "your-model-name": 75.0  # 近似 MMLU 分数
}
```

### 添加新数据集

```bash
# 下载数据
python database/download_direction9_datasets.py --dataset your_dataset --sample-num 500
```

然后在实验配置中添加数据集名称。

## 故障排除

### GPU 显存不足

降低 batch_size：

```python
config = ExperimentConfig(..., batch_size=4)
```

### Tokenizer 错误

已自动处理，如仍有问题检查模型是否有有效 eos_token。

### 数据集缺失

运行前置检查确认数据集存在：

```bash
python experiments/run_direction9_experiments.py
```

## 性能估算

| 实验 | 模型数 | 数据集数 | 预估时长  |
| ---- | ------ | -------- | --------- |
| E1   | 5      | 5        | ~2 小时   |
| E3   | 5      | 4 能力   | ~1.5 小时 |

实际时长取决于 GPU 性能和文本数量。