# CLAUDE.md - MiniMind 预训练项目指南

> **项目概述**: MiniMind 大语言模型预训练项目，研究使用人类可理解的 KnowledgeDataset 替代传统 Transformer Feed-Forward 层作为记忆层。

## 📋 目录

- [项目架构](#项目架构)
- [环境配置](#环境配置)
- [训练流程](#训练流程)
- [实验管理](#实验管理)
- [配置参数](#配置参数)
- [故障排除](#故障排除)

## 🏗️ 项目架构

### 核心模型

| 文件 | 用途 | 说明 |
|-----|------|------|
| `model/model.py` | 主要模型 | Transformer + KnowledgeDataset 记忆层 |
| `model/model_no_feed.py` | 无FFN变体 | 不使用 Feed-Forward 层的实验版本 |
| `model/model_original.py` | 基线模型 | 传统 Transformer 架构（实验对照） |
| `model/LMConfig.py` | 配置管理 | 支持 MOE、数据库、知识图谱功能 |
| `model/dataset.py` | 数据处理 | 预训练数据集加载和处理 |

### 关键特性

- ✨ **人类可理解记忆层**: 使用 KnowledgeDataset 替代传统 FFN
- 🚀 **分布式训练**: Accelerate + DeepSpeed 支持
- 📊 **实时监控**: SwanLab 训练可视化
- 🔧 **灵活配置**: 支持多种模型架构实验

### 目录结构

```
pretrains-worktree/
├── model/                    # 模型定义
│   ├── model.py             # 主要模型（含KnowledgeDataset）
│   ├── model_original.py    # 基线模型
│   ├── model_no_feed.py     # 无FFN变体
│   ├── LMConfig.py          # 配置类
│   └── dataset.py           # 数据集处理
├── preprocessing/           # 数据预处理
├── run_file/               # 实验脚本
├── out/                    # 输出目录
├── accelerate_config.yaml  # 分布式配置
├── ds_config.json         # DeepSpeed配置
├── train_pretrain_accelerate.py  # 主训练脚本
└── eval_model.py           # 模型推理评估脚本
```

## 🔬 研究现状

### 研究重点
- **KnowledgeDataset**: 探索人类可理解的神经网络记忆机制

### 当前问题
1. **文本生成质量**: 
   - Loss 收敛良好 (model: 0.6 vs baseline: 1.9)
   - 但输出文本为词组碎片，缺乏句法连贯性

2. **SFT 效果差异**: 
   - model 的 SFT 效果远低于 model_original 基线

## ⚙️ 环境配置

### 1. 环境管理
```bash
# 使用 uv 包管理器的 .venv 环境

# 添加新包
uv add <package_name>

# 同步环境
uv sync
```

### 2. 数据预处理
```bash
# 预处理预训练数据
python preprocessing/preprocess_pretrain.py

# 预处理三元组数据
python preprocessing/preprocess_trex.py

# 预处理组合数据
python preprocessing/preprocess_combined_json.py
```

## 🚀 训练流程

### 快速开始
```bash
# 执行实验脚本
bash run_file/experiment_1.4.XX.sh
```

## 🧪 实验管理

### 核心文件
- **实验记录模版**: `experiment/EXPERIMENT_TEMPLATE.md` - 标准化的实验记录格式
- **实验脚本模版**: `run_file/experiment_template.sh` - 自动化的实验执行脚本
- **管理指南**: `experiment/README.md` - 详细的实验管理流程说明

### 🤝 人类-AI 协作模式

#### 🧑‍🔬 人类职责（最简化）
1. **填写实验目标** - 在实验记录中填写：
   - 基于实验（上一版实验编号）
   - 实验目的、研究假设、预期结果
2. **审核确认** - 审核AI生成的完整记录
3. **提交决策** - 决定是否git commit

#### 🤖 AI职责（全流程管理）
1. **实验设计** - 记录详细的思考过程和决策逻辑
2. **脚本管理** - 完全负责生成和管理实验脚本
3. **执行监控** - 实时记录训练过程和资源使用
4. **结果分析** - 自动分析性能指标和问题诊断
5. **Git记录** - 生成代码变更记录和版本对比

### 实验流程
```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完成所有技术工作：
#    - 思考过程记录
#    - 参数配置
#    - 脚本生成
#    - 实验执行（使用nohup后台运行）
#    - 结果分析

# 5. 人类审核 -> AI提交git
```

### 🔧 后台训练执行

#### 使用nohup确保训练持续进行
所有实验脚本现已集成nohup后台运行功能：

```bash
# 执行实验（自动使用nohup后台运行）
bash run_file/experiment_X.X.X.sh

# 实时监控训练进度
tail -f out/experiment_X_X_X/experiment.log

# 检查训练进程状态
ps aux | grep train_pretrain_accelerate

# 手动停止训练（如需要）
kill [PID]
```

#### 重要特性
- ✅ **后台运行**: 使用nohup确保训练在SSH断开后继续
- 📝 **日志记录**: 所有输出自动记录到实验日志文件
- 🔍 **进程监控**: 提供PID和状态检查命令
- 🛑 **优雅停止**: 支持安全的训练中断机制
- ⏰ **时间估算**: 自动显示预计训练完成时间

### 实验记录结构
```
experiment_X.Y.Z.md
├── 🧠 AI思考过程        # AI的设计思路和决策推理
├── 📝 Git变更记录       # 代码修改详情和原因
├── 📋 实验基本信息      # 人类填写目标，AI填写配置
├── ⚙️ 配置参数         # AI根据目标自动配置
├── 🚀 执行记录         # 训练过程实时更新
├── 📊 训练结果         # 自动化的结果分析
├── 🔍 推理评估         # 使用eval_model.py的实际推理效果
├── 📈 深度分析         # 问题诊断和改进建议
└── 🎯 实验结论         # 假设验证和后续计划
```

### 🔍 实验评估要求

**重要**: 每个实验在训练完成后，必须运行 `eval_model.py` 进行实际推理效果评估：

```bash
# 基本评估命令（使用默认参数）
.venv/bin/python eval_model.py \
    --model_path out/experiment_X_Y_Z/pretrain_512.pth \
    --model_type model

# 完整评估命令（指定所有参数）
.venv/bin/python eval_model.py \
    --model_path out/experiment_X_Y_Z/pretrain_512.pth \
    --model_type model \
    --dim 512 \
    --n_layers 8 \
    --n_heads 32 \
    --knowledge_num 1048576 \
    --knowledge_length 32 \
    --knowledge_dim 128
```

#### 评估指标说明
- **输入/输出对比**: 展示模型对前30个token的续写能力
- **Loss值**: 量化预测准确度，越低越好
- **文本连贯性**: 观察生成文本是否符合语法和语义
- **模型对比**: 比较model、model_original、model_no_feed的差异

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

### 质量标准
✅ **合格实验必须满足**:
- 明确的实验目标和可验证假设
- 完整的AI思考过程记录
- 详细的Git变更记录
- 训练过程稳定且结果可解释
- **运行eval_model.py进行推理评估**
- 具体可行的改进建议

❌ **不合格情况**:
- 目标模糊或无法验证
- 缺少思考过程或Git记录
- 训练异常中断或数据错误
- **未进行推理评估或缺少评估结果**
- 结论不明确或缺乏下一步计划

## ⚙️ 配置参数

### 配置文件

| 文件 | 用途 |
|-----|------|
| `accelerate_config.yaml` | Accelerate 分布式训练配置 |
| `ds_config.json` | DeepSpeed ZeRO Stage 2 优化配置 |
| `pyproject.toml` | 项目依赖和环境配置 |

### 硬件配置 (单张 RTX 4090)

#### 核心参数
| 参数类别 | 参数名 | 值 | 说明 |
|---------|-------|----|----- |
| **训练设置** | epochs | 3 | 训练轮次 |
| | batch_size | 128 | 批次大小 |
| | accumulation_steps | 8 | 梯度累积步数 |
| | mixed_precision | bf16 | 混合精度训练 |
| **模型架构** | dim | 512 | 模型维度 |
| | n_layers | 8 | Transformer 层数 |
| | n_heads | ≤32 | 注意力头数 |
| | max_seq_len | 512 | 最大序列长度 |
| **知识库** | knowledge_num | 1048576 | 知识条目数量 |
| | knowledge_length | 32 | 单条知识长度 |
| **其他** | use_moe | false | 不使用专家混合 |

#### 数据路径
```bash
# 预训练数据
data_path="/home/pci/ycz/Code/Minimind/dataset/stable/merged_pretrain.jsonl"

# 知识库初始化
database_init_path="/home/pci/ycz/Code/Minimind/dataset/stable/sentence_trex_data.json"

# 聚类缓存（可选）
cluster_cache_path=None  # 默认关闭
```

## 📊 训练监控

### SwanLab 可视化
- ✅ **训练指标**: 实时监控 loss、学习率变化
- 📈 **资源监控**: GPU 内存、计算利用率追踪
- 🌐 **多模式**: 支持在线/离线监控模式

## 🛠️ 故障排除

### 常见问题

#### 1. 文本生成质量问题
- **现象**: 输出为词组碎片，缺乏连贯性
- **可能原因**: KnowledgeDataset 记忆机制与语言建模目标不匹配
- **排查方向**: 检查知识库索引机制、记忆层输出分布

#### 2. SFT 效果差异
- **现象**: model 的 SFT 效果显著低于 baseline
- **可能原因**: 预训练阶段的表示学习偏差
- **排查方向**: 对比两种模型的隐层表示、梯度流动

#### 3. 训练资源
- **GPU 内存**: 如遇显存不足，调整 batch_size / accumulation_steps
- **训练速度**: 确认 DeepSpeed ZeRO Stage 2 正确启用

### 调试工具
```bash
# 检查模型加载
.venv/bin/python -c "from model.model import *; print('模型加载成功')"

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

# 测试训练脚本
.venv/bin/python train_pretrain_accelerate.py --help

# 测试评估脚本
.venv/bin/python eval_model.py --help

# 快速评估测试（仅5个样本）
.venv/bin/python eval_model.py \
    --model_path out/experiment_1_4_0/pretrain_512.pth \
    --model_type model \
    --num_samples 5
```

---

> 💡 **提示**: 使用本文档前，请确保已正确配置 uv 虚拟环境和相关依赖。如有问题，请检查 `pyproject.toml` 配置。