321 lines
10 KiB
Markdown
321 lines
10 KiB
Markdown
# 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` 配置。 |