GPT 训练环境使用教程
本教程将引导你完成从环境搭建到模型训练、监控、生成的完整流程。项目提供了一套自动化脚本，支持 CUDA 检测、依赖安装、Web 控制台、训练监控、自适配置等功能。

目录
环境要求

项目文件说明

第一步：安装依赖

第二步：准备数据

第三步：配置参数

第四步：启动训练与监控

第五步：使用 Web 控制台

第六步：生成文本

高级功能与自定义

常见问题

1. 环境要求
操作系统：Windows / Linux / macOS

Python：3.8 及以上（推荐 3.10）

GPU：NVIDIA 显卡（可选，训练大幅加速）

显存建议 ≥ 8GB，4GB 文本数据推荐 12GB 以上

网络：用于下载依赖包

2. 项目文件说明
文件	作用
install_deps.py	自动检测 GPU 并安装 PyTorch、所有依赖
setup_launch.py	Web 控制台、训练启动/停止、CUDA 动态配置
train.py	训练主程序（数据处理、模型定义、训练循环）
model.py	GPT 模型结构（RoPE/SwiGLU/RMSNorm，高级）
data.py	数据集与 Tokenizer（流式加载）
generate.py	训练后文本生成脚本
config.yaml	训练超参数配置文件
requirements.txt	依赖列表（供参考）
utils.py	辅助工具（分布式、检查点等）
注意：项目包含两套模型定义（model.py 先进版 和 train.py 内嵌的经典版），当前 train.py 使用内嵌的 GPTLM 架构（经典 Transformer）。
若想使用 model.py 中的先进架构，需手动替换 train.py 中的模型定义。

3. 第一步：安装依赖
打开终端（cmd 或 PowerShell），进入项目根目录。

bash
cd your_project_folder
python install_deps.py
脚本会自动完成：

检测显卡及驱动 CUDA 版本

卸载旧版 PyTorch（如有冲突）

安装匹配的 PyTorch（CUDA 12.4 / 12.1 / 11.8 或 CPU）

过滤 requirements.txt，避免覆盖 PyTorch

安装所有其他依赖（tokenizers、tensorboard 等）

验证 torch.cuda.is_available() 是否正常

若没有 NVIDIA GPU，脚本会自动安装 CPU 版 PyTorch，仍可训练但速度较慢。

4. 第二步：准备数据
在项目根目录创建 data/corpus 文件夹：

bash
mkdir -p data/corpus
将所有 .txt 文本文件放入该文件夹（支持子目录，默认递归扫描）。
示例：data/corpus/novel1.txt, data/corpus/novel2.txt
文本内容为连续自然语言，中英文均可。

确认 config.yaml 中 data_path 指向正确：

yaml
data_path: "./data/corpus"
数据量：4GB 纯文本约 4-8 亿 token，足以训练小型 GPT。

5. 第三步：配置参数
5.1 自动配置（推荐）
运行 Web 控制台后，在界面点击 “CUDA自动配置” 按钮。
它会根据你的显卡显存自动推荐 batch_size、max_seq_len、gradient_accumulation_steps 等参数，并自动备份原配置文件。

5.2 手动修改
直接用文本编辑器打开 config.yaml 调整关键参数：

yaml
# ---------- 模型超参数 ----------
vocab_size: 32000          # 词表大小，一般不改
hidden_size: 768           # 隐藏层维度（越大模型越强，显存要求越高）
num_layers: 12             # Transformer 层数
num_heads: 12              # 注意力头数
max_seq_len: 1024          # 最大序列长度（训练时的上下文窗口）

# ---------- 训练超参数 ----------
per_gpu_batch_size: 8      # 单卡每次处理的样本数
gradient_accumulation_steps: 4   # 梯度累积步数（有效 batch = bs * accum）
total_train_steps: 50000   # 总训练步数
learning_rate: 3.0e-4      # 学习率
显存不足时：

减小 per_gpu_batch_size，增大 gradient_accumulation_steps，保持有效 batch 大小不变

减小 max_seq_len 或 hidden_size、num_layers

将 auto_oom_handling 设为 true 可自动处理 OOM 并降 batch

6. 第四步：启动训练与监控
确保已安装依赖并配置好数据路径，在终端执行：

bash
python setup_launch.py
脚本会：

自动查找空闲端口（默认从 7860 开始）

启动 Web 服务器

自动打开浏览器访问 http://127.0.0.1:端口号

如果浏览器未自动打开，手动打开控制台输出的 URL。

7. 第五步：使用 Web 控制台
Web 控制台提供完整的训练管理界面。

7.1 启动训练
点击 “开始训练” 按钮，后台将启动 train.py。
日志将实时显示在右侧面板，图表会动态更新。

7.2 监控指标
Step / Progress：当前步数与进度百分比

Loss / Val Loss：训练损失与验证损失（每 eval_every 步评估）

LR：当前学习率

Tokens/s：每秒处理 token 数

GPU：显存使用情况

ETA：预计剩余时间

四个实时折线图：Loss、LR、Tokens/s、GPU 占用。

7.3 停止与暂停
停止训练：安全终止训练进程，自动保存 checkpoint

暂停/继续：当前版本在 setup_launch.py 中未直接提供，但你可以通过直接终止进程来停止

7.4 配置文件编辑
右侧面板可直接编辑 config.yaml，点击 “保存配置” 生效。
修改配置后需重新启动训练。

7.5 导出功能
导出日志：下载完整 train.log

导出状态 JSON：下载 training_state.json（含历史图表数据）

导出全部 ZIP：打包配置、日志、模型文件（.pt）、tokenizer

8. 第六步：生成文本
训练完成后（或训练过程中），可以使用 generate.py 进行文本生成。

8.1 命令格式
bash
python generate.py \
  --checkpoint checkpoints/final_model.pt \
  --tokenizer checkpoints/tokenizer.json \
  --prompt "从前有座山" \
  --max_new_tokens 200 \
  --temperature 0.8 \
  --top_p 0.9 \
  --repetition_penalty 1.05
8.2 参数说明
参数	默认值	说明
--checkpoint	必填	模型权重文件路径
--tokenizer	必填	分词器文件路径
--prompt	"从前有座山"	起始文本
--max_new_tokens	200	最大生成 token 数
--temperature	0.8	温度（越高越多样）
--top_k	None	Top-K 采样
--top_p	0.9	Nucleus 采样
--repetition_penalty	1.05	重复惩罚（>1 减少重复）
--greedy	False	贪心解码（temperature 无效）
--compile	False	使用 torch.compile 加速
9. 高级功能与自定义
9.1 使用更先进的模型架构
项目提供了 model.py（含 RoPE、SwiGLU、RMSNorm），若希望使用该架构，需将 train.py 中模型定义替换为导入 model.py。
注意：新架构与经典架构的权重不兼容，需重新训练。

9.2 多 GPU 训练
当前 train.py 仅支持单卡，若需多卡，可修改 train.py 引入 torch.distributed 和 DistributedDataParallel。utils.py 已包含分布式初始化函数。

9.3 TensorBoard 可视化
训练目录（checkpoints/）下会自动生成 TensorBoard 日志。
在终端输入：

bash
tensorboard --logdir checkpoints/tensorboard
即可查看标量曲线。

9.4 恢复训练
训练中断后，重新执行 python setup_launch.py 并启动训练，train.py 会自动从最新的 checkpoint_step_*.pt 恢复。

9.5 自定义数据
config.yaml 支持使用 HuggingFace 数据集：
将 dataset_name 设为数据集的名称（如 "wikitext"），并设置 text_field 为包含文本的字段。

10. 常见问题
Q1: 安装依赖时出现 nvcc 错误
不需要安装 CUDA Toolkit，只需 NVIDIA 驱动。PyTorch 自带 CUDA 运行时。

Q2: 显存溢出 (OOM)
启用 auto_oom_handling: true（默认开启），训练会自动降低 batch_size

减小 hidden_size、num_layers 或 max_seq_len

关闭 torch.compile（大型模型编译可能额外占用显存）

Q3: 训练速度慢
确保 num_workers 设置为 CPU 核心数的一半（如 8 或 16）

在 NVIDIA 30/40 系列显卡上，将 precision 设为 bf16（需 torch.cuda.is_bf16_supported() 为 True）

使用 model.py 中的 Flash Attention（需手动集成）

Q4: 验证损失不下降
检查数据质量（是否包含垃圾字符、重复片段）

降低学习率或增加 warmup

增加 gradient_accumulation_steps 以提高有效 batch

Q5: 生成文本乱码
确认 tokenizer 与训练时一致

尝试调低 temperature 或启用 --greedy

完整流程示例
bash
# 1. 安装依赖
python install_deps.py

# 2. 放置数据到 data/corpus/

# 3. 启动控制台并训练
python setup_launch.py
# 在浏览器中点击“开始训练”

# 4. 训练完成后生成文本
python generate.py \
  --checkpoint checkpoints/final_model.pt \
  --tokenizer checkpoints/tokenizer.json \
  --prompt "人工智能的发展" \
  --max_new_tokens 200