# 🧪 MiniMind 实验管理系统

> **系统概述**: 标准化的实验管理框架，确保 MiniMind 预训练实验的可重现性、可追踪性和高质量协作。

---

## 📋 目录

- [快速开始](#快速开始)
- [协作流程](#协作流程)  
- [模版使用](#模版使用)
- [实验规范](#实验规范)
- [文件结构](#文件结构)
- [故障排除](#故障排除)

---

## 🚀 快速开始

### 1. 实验创建流程

```bash
# 1. 🧑‍🔬 人类: 确定实验目标和版本号
EXPERIMENT_VERSION="1.4.1"

# 2. 🤖 AI: 复制模版创建新实验
cp experiment/EXPERIMENT_TEMPLATE.md experiment/experiment_${EXPERIMENT_VERSION}.md
cp run_file/experiment_template.sh run_file/experiment_${EXPERIMENT_VERSION}.sh

# 3. 🧑‍🔬 人类: 填写实验基本信息（见下文详细说明）

# 4. 🤖 AI: 根据实验目标配置参数并执行
bash run_file/experiment_${EXPERIMENT_VERSION}.sh

# 5. 🤖 AI: 完成实验记录和结果分析

# 6. 🧑‍🔬 人类: 审核实验记录

# 7. 🤖 AI: 提交实验到git（经人类确认后）
```

### 2. 实验版本命名规范

| 版本格式 | 说明 | 示例 |
|---------|------|------|
| `X.Y.Z` | 主要.次要.修订 | `1.4.1` |
| 主要版本 (X) | 重大架构变更 | 从 model_original 到 model |
| 次要版本 (Y) | 功能增强或重要参数调整 | 新增知识库功能 |
| 修订版本 (Z) | 小幅调整和优化 | 学习率调整、批次大小优化 |

---

## 🤝 协作流程

### 人类研究者职责 🧑‍🔬

#### 实验前期 (必填项目)
在 `experiment_X.Y.Z.md` 中填写：

```markdown
## 📋 实验基本信息

### 🧑‍🔬 **[人类填写]** 实验目标
**实验目的**: 
[具体描述要解决的问题，如："验证增大知识库规模对生成质量的影响"]

**研究假设**: 
[明确的可验证假设，如："knowledge_num从1M增加到2M会提升文本连贯性"]

**预期结果**: 
[量化的期望指标，如："Loss降低至0.5以下，生成文本连贯性评分>7.0"]

**实验重点**: 
[关键验证点，如："重点观察内存使用情况和训练稳定性"]
```

#### 实验后期 (审核职责)
- ✅ **结果审核**: 验证AI分析的准确性和合理性
- ✅ **假设验证**: 确认实验是否回答了预设问题
- ✅ **质量把关**: 确保实验记录完整、结论可信
- ✅ **提交决策**: 决定是否将实验提交到git仓库

### AI助手职责 🤖

#### 实验构建期
1. **参数配置**: 根据实验目标自动填写所有 `[AI构建]` 标记的参数
2. **环境检查**: 验证GPU、数据文件、Python环境等
3. **脚本生成**: 创建可执行的实验脚本
4. **预检验证**: 确保配置的合理性和可执行性

#### 实验执行期  
1. **实时监控**: 记录训练进度、资源使用情况
2. **异常处理**: 捕获和记录错误信息
3. **状态更新**: 实时更新实验记录中的执行状态

#### 实验完成期
1. **结果分析**: 自动分析训练曲线、性能指标
2. **质量评估**: 生成文本样例和质量评分
3. **问题诊断**: 识别异常情况并提供改进建议
4. **记录完善**: 填写所有 `[AI完成]` 标记的分析内容

---

## 📝 模版使用

### 实验记录模版 (`EXPERIMENT_TEMPLATE.md`)

#### 🧑‍🔬 人类填写区域
- **实验目标**: 明确、具体、可量化
- **研究假设**: 可验证的科学假设
- **预期结果**: 具体的成功标准

#### 🤖 AI构建区域
- **配置参数**: 所有模型和训练参数
- **执行记录**: 训练过程的实时状态
- **环境信息**: 硬件和软件环境快照

#### ✅ AI完成区域
- **结果分析**: 训练指标和性能评估
- **问题诊断**: 异常检测和原因分析
- **改进建议**: 基于结果的优化方案

### 实验脚本模版 (`experiment_template.sh`)

#### 关键占位符说明

| 占位符 | 类型 | 说明 | 示例值 |
|--------|------|------|--------|
| `[VERSION]` | 🧑‍🔬 人类 | 实验版本号 | `1.4.1` |
| `[DESCRIPTION]` | 🧑‍🔬 人类 | 实验简短描述 | `"验证2M知识库对生成质量的影响"` |
| `[CUDA_DEVICES]` | 🤖 AI | GPU设备配置 | `0` 或 `0,1,2,3` |
| `[BATCH_SIZE]` | 🤖 AI | 批次大小 | `128` |
| `[LEARNING_RATE]` | 🤖 AI | 学习率 | `8e-5` |
| `[MODEL_TYPE]` | 🤖 AI | 模型类型 | `model` |
| `[KNOWLEDGE_NUM]` | 🤖 AI | 知识库大小 | `2097152` |

---

## 📋 实验规范

### 实验分类标准

#### 🧪 **探索性实验**
- **目的**: 验证新想法、测试可行性
- **规模**: 小规模、快速验证
- **版本**: 通常为 X.Y.0（新功能首次测试）
- **时长**: 1-3小时内完成

#### 🔬 **验证性实验**  
- **目的**: 确认假设、对比基线
- **规模**: 中等规模、完整训练
- **版本**: 通常为 X.Y.1-X.Y.9（功能优化迭代）
- **时长**: 3-12小时

#### 🏆 **生产性实验**
- **目的**: 最终模型训练、性能优化
- **规模**: 大规模、完整流程
- **版本**: 通常为 X.0.0（重要里程碑）
- **时长**: 12小时以上

### 质量标准

#### ✅ **合格实验标准**
- [ ] 实验目标明确具体
- [ ] 参数配置完整无误
- [ ] 训练过程稳定收敛
- [ ] 结果记录详细准确
- [ ] 问题分析深入合理
- [ ] 改进建议具体可行

#### 🚫 **不合格实验情况**
- ❌ 目标模糊或无法验证
- ❌ 训练中断或严重错误
- ❌ 数据异常或无法解释
- ❌ 记录不完整或有明显错误
- ❌ 缺乏有效的改进建议

### 审核流程

1. **AI自检**: 完成实验记录后进行自我检查
2. **人类初审**: 研究者检查实验的完整性和准确性
3. **问题反馈**: 如有问题，AI修正后重新提交审核
4. **最终确认**: 确认无误后标记"✅ 已审核"
5. **Git提交**: 审核通过后提交到版本控制系统

---

## 📁 文件结构

```
experiment/
├── README.md                           # 本文档
├── EXPERIMENT_TEMPLATE.md              # 实验记录模版
├── experiment_1.4.0.md               # 具体实验记录
├── experiment_1.4.1.md               
└── ...

run_file/
├── experiment_template.sh              # 实验脚本模版
├── experiment_1.4.0.sh               # 具体实验脚本
├── experiment_1.4.1.sh
└── ...

out/
├── experiment_1.4.0/                  # 实验输出目录
│   ├── checkpoint_*.pt                # 模型检查点
│   ├── train.log                      # 训练日志
│   └── experiment_info.txt            # 实验信息
└── ...
```

---

## 🛠️ 故障排除

### 常见问题

#### 1. 模版占位符未替换
**现象**: 脚本执行时出现 `[PLACEHOLDER]` 相关错误
**解决**: 
```bash
# 检查未替换的占位符
grep -n "\[.*\]" run_file/experiment_X.Y.Z.sh
```

#### 2. GPU内存不足
**现象**: CUDA out of memory
**解决**: 
- 减小 `batch_size`
- 增加 `accumulation_steps` 
- 调整 `max_seq_len`

#### 3. 数据文件路径错误
**现象**: FileNotFoundError
**解决**:
```bash
# 检查数据文件是否存在
ls -la /home/pci/ycz/Code/Minimind/dataset/stable/
```

#### 4. SwanLab连接失败
**现象**: SwanLab API错误
**解决**:
- 检查API密钥配置
- 确认网络连接正常
- 验证项目名称正确

### 调试技巧

#### 开启详细日志
```bash
# 在脚本中添加调试选项
export NCCL_DEBUG=INFO
export PYTHONFAULTHANDLER=1
export CUDA_LAUNCH_BLOCKING=1
```

#### 快速验证
```bash
# 测试环境配置
python -c "import torch; print(f'CUDA可用: {torch.cuda.is_available()}')"

# 验证数据加载
python -c "from model.dataset import *; print('数据集加载成功')"

# 检查模型初始化
python -c "from model.model import *; print('模型加载成功')"
```

---

## 📚 最佳实践

### 实验设计原则

1. **单一变量**: 每次实验只改变一个关键参数
2. **对照基线**: 始终与 model_original 进行对比
3. **渐进优化**: 从小规模到大规模逐步验证
4. **记录详尽**: 记录所有可能影响结果的因素

### 协作效率提升

1. **明确目标**: 人类提供清晰的实验目标和假设
2. **及时反馈**: 对AI的分析及时给出反馈和指导  
3. **知识积累**: 将有效的配置和发现整理成知识库
4. **版本管理**: 重要实验及时提交到git保存

### 实验优化策略

1. **资源利用**: 合理配置批次大小和GPU使用
2. **时间管理**: 根据实验重要性分配计算资源
3. **结果复用**: 保存有价值的模型检查点和配置
4. **持续改进**: 基于实验结果不断优化流程

---

## 🔗 相关链接

- [CLAUDE.md](../CLAUDE.md) - 项目总体指南
- [SwanLab平台](https://swanlab.cn/) - 实验监控和可视化
- [模型架构文档](../model/) - 模型实现细节
- [数据处理流程](../preprocessing/) - 数据预处理说明

---

> 💡 **提示**: 使用此实验管理系统前，请先仔细阅读 [CLAUDE.md](../CLAUDE.md) 了解项目整体架构和配置要求。

**最后更新**: 2024-XX-XX  
**维护者**: MiniMind 项目组