# kcpt ai llm

**Repository Path**: YYFDFS/kcpt-ai-llm

## Basic Information

- **Project Name**: kcpt ai llm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KCPT-AI-LLM

从零训练小型 LLM 的完整工程实践：5K 中英 BPE tokenizer + Hydrogen100M 架构 + CoT 思维链 + 现代训练技术栈。

## 项目概览

| 组件 | 规格 | 说明 |
|------|------|------|
| Tokenizer | 5K BPE v2 | 中英平衡，中文 token 效率 2.7x |
| 模型架构 | Hydrogen100M | d_model=768, 16 层, GQA 4:1, SwiGLU |
| 训练数据 | 51.92M tokens | 6 源精选（wikitext/tinystories/dolly/gsm8k/belle_cn/longcat_cot）|
| 特殊 Token | `<think>`/`<summary>` | CoT 思维链格式 |
| GPU 平台 | Kaggle P100 16GB | 免费 30h/周 |

---

## GPU 训练详细指南（Kaggle P100）

### 一、环境准备

#### 1.1 注册 Kaggle 账号
- 访问 https://www.kaggle.com/
- 用 Google 账号注册并登录
- 完成手机号验证（**必须**，否则无法使用 GPU）

#### 1.2 开启 GPU 配额
- 进入 https://www.kaggle.com/settings
- 找到 **GPU T4 x2** 或 **GPU P100** 选项
- Kaggle 免费配额：**GPU 30 小时/周**，每次会话最长 12 小时
- 周一 00:00 UTC 重置配额

#### 1.3 验证环境
在 Kaggle Notebook 第一个 cell 运行：
```python
!nvidia-smi
!python -c "import torch; print(f'torch={torch.__version__}, cuda={torch.cuda.is_available()}, gpu={torch.cuda.get_device_name(0)}')"
```
预期输出（P100）：
```
+-----------------------------------------------------------------------------+
| NVIDIA-SMI ... Driver Version: ...   CUDA Version: 12.2                    |
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC|
|   0  Tesla P100-PCIE...  Off  | 00000000:00:04.0 Off |                  Off|
torch=2.x.x, cuda=True, gpu=Tesla P100-PCIE-16GB
```

---

### 二、一键启动训练

#### 2.1 新建 Notebook
1. 点击右上角 **Create** → **New Notebook**
2. 右侧面板设置：
   - **Accelerator** → 选 `GPU (P100)`
   - **Internet** → 开启 `On`（clone 代码需要）
   - **Persistence** → 选 `Files Only` 或 `Variables and Files`

#### 2.2 粘贴启动代码
在第一个 cell 粘贴并运行（Shift+Enter）：

```python
import subprocess, os, sys

# 1. clone 源码（含 kaggle_train.py 自动迁移脚本）
print("[1/3] clone 源码...", flush=True)
subprocess.run(
    "git clone https://gitee.com/YYFDFS/kcpt-ai-llm.git /kaggle/working/repo",
    shell=True, check=True
)

# 2. 安装依赖
print("[2/3] 安装依赖...", flush=True)
subprocess.run(
    "pip install -q tokenizers tiktoken datasets pyarrow",
    shell=True, check=True
)

# 3. 运行迁移脚本（自动构建数据 + 切 100M + 训练）
print("[3/3] 启动训练...", flush=True)
os.chdir("/kaggle/working/repo")
# 用 exec 让 train.py 接管进程，实时输出日志
os.execv(sys.executable, [sys.executable, "-u", "kaggle_train.py"])
```

#### 2.3 kaggle_train.py 自动执行流程
脚本会依次完成：

| 步骤 | 内容 | 耗时 |
|------|------|------|
| Step 1 | 从 Gitee clone 源码 | ~10 秒 |
| Step 2 | 安装 tokenizers/tiktoken/datasets | ~1 分钟 |
| Step 3a | 重建 5K v2 BPE tokenizer | ~1 分钟 |
| Step 3b | 重建 hydrogen100m 训练数据（52M tokens）| ~5 分钟 |
| Step 4 | 自动切换到 100M 架构 + Kaggle 路径 | <1 秒 |
| Step 5 | 启动 GPU 训练 | ~3-4 小时 |

---

### 三、模型架构配置

#### 3.1 自动切换的 100M 架构
kaggle_train.py 会自动把 config.py 从 50M 切到 100M：

| 参数 | CPU 50M（降级版） | Kaggle 100M（完整版） |
|------|-------------------|----------------------|
| `model_name` | Hydrogen50M | **Hydrogen100M** |
| `d_model` | 512 | **768** |
| `n_layers` | 10 | **16** |
| `n_heads` | 8 | **12** |
| `n_kv_heads` | 2 (GQA 4:1) | **4** (GQA 3:1) |
| `d_ff` | 1408 | **2048** |
| `swa_pattern` | "9to1" | **"15to1"** |
| `batch_size` | 2 | **8** |
| `grad_accum_steps` | 16 | **4** |
| `grad_checkpoint` | False | **True** |
| `resume` | True（续训）| **False**（从头训） |

**Effective batch = 8 × 4 = 32**（与 CPU 一致，保证训练动态一致）

#### 3.2 显存预估（P100 16GB）

| 项目 | 占用 |
|------|------|
| 100M 参数 bf16 权重 | 200 MB |
| 激活（batch=8 × seq=768）| ~1.2 GB |
| Optimizer state (adamw fp32) | 800 MB |
| 梯度 | 400 MB |
| KV cache（推理时）| 200 MB |
| **合计** | **~2.8 GB** |

16GB 显存绰绰有余，甚至可以把 batch 提到 16。

#### 3.3 速度预估

| 平台 | tok/s | 2000 iter 耗时 |
|------|-------|---------------|
| 2 核 CPU（当前）| 520 | ~27 小时 |
| Kaggle P100 bf16 | ~80,000 | **~3-4 小时** |
| Kaggle T4 | ~60,000 | ~5 小时 |
| A100 80GB | ~500,000 | ~30 分钟 |

---

### 四、训练监控

#### 4.1 实时日志
Kaggle Notebook 会实时显示训练日志，格式如下：
```
[device] CUDA: Tesla P100-PCIE-16GB (16.0GB VRAM, TF32 enabled, cudnn.benchmark on)
[1/5] 准备数据...
[datasets] hydrogen-100m: train=51.72M tokens, val=0.20M
[2/5] 构建模型...
  params: 100.00M  init std=0.0035, cuda
[3/5] 构建优化器...
[4/5] 开始训练...
iter    10/2000 | loss 9.4521 | lr 4.00e-05 | 78500 tok/s
iter    20/2000 | loss 8.2103 | lr 8.00e-05 | 81200 tok/s
...
```

#### 4.2 关键指标解读

| 指标 | 健康范围 | 异常处理 |
|------|---------|---------|
| `loss` | 从 ~10 降到 < 4 | 7.x 平台 = 容量不足 |
| `tok/s` | P100 > 50000 | 过低 = 检查 grad_checkpoint |
| `rep_rate`（eval）| < 0.3 | > 0.8 = mode collapse |
| `val_loss` | 接近 train_loss | 差距大 = 过拟合 |

#### 4.3 Checkpoint 保存
- 每 50 iter 自动保存 bf16 权重到 `/kaggle/working/checkpoints/`
- 文件名：`hydrogen100m_iter{N}_bf16.pt`（~200MB/个）
- **Kaggle 会话结束后 /kaggle/working/ 内容保留**，可在 Output 区下载

#### 4.4 防止会话超时
Kaggle 有反空闲机制，长时间无操作会断开。建议：
- 保持 Notebook 标签页打开（不要最小化）
- 训练日志持续输出即视为活跃
- 最长 12 小时自动断开，训练必须在 12h 内完成

---

### 五、获取训练结果

#### 5.1 下载权重
训练结束后：
1. Notebook 右侧 **Output** 面板
2. 展开 `/kaggle/working/checkpoints/`
3. 下载 `hydrogen100m_iter2000_bf16.pt`（最终权重）
4. 下载 `hydrogen100m.pt`（best 权重，优先 EMA）

#### 5.2 下载日志
- `train_log.txt` - 完整训练日志
- `profile.json` - PyTorch profiler trace

#### 5.3 续训（配额用完时）
如果 12h 没跑完，下次会话可续训：
```python
# 上传 ckpt.pt 到 Kaggle Dataset
# 修改 kaggle_train.py 的 step4_patch_config：
#   'resume: bool = False' → 'resume: bool = True'
# 把 ckpt.pt 放到 /kaggle/working/checkpoints/
```

---

### 六、故障排查

#### 6.1 CUDA OOM
```
RuntimeError: CUDA out of memory.
```
**解决**：减小 batch_size
```python
# 在 kaggle_train.py step4 的 replacements 里改：
'batch_size: int = 8' → 'batch_size: int = 4'
```

#### 6.2 数据下载失败（网络问题）
```
RuntimeError: 下载 xxx 所有端点均失败
```
**解决**：Kaggle 可能屏蔽了 HF 镜像。改用官方端点：
```python
# 编辑 data.py / datasets_loader.py
# 把 _HF_ENDPOINTS 改为只含 "https://huggingface.co"
```

#### 6.3 训练 NaN
```
[warn] iter 50: loss=nan, 跳过本步
```
**解决**：脚本已内置 NaN 跳过 + grad clip，一般自动恢复。持续 NaN 则降低 lr：
```python
# config.py
'lr: float = 2e-4' → 'lr: float = 1e-4'
```

#### 6.4 配额耗尽
```
Your GPU quota has been exceeded.
```
**解决**：等周一 UTC 00:00 重置，或换用 Google Colab（T4，配额更灵活）

---

### 七、模型测试

训练完成后，在同一个 Kaggle Notebook 新建 cell 测试：

```python
import sys, torch
sys.path.insert(0, "/kaggle/working/repo")
from tokenizers import Tokenizer
from config import ModelConfig
from model import LanguageModel

# 加载 tokenizer + 模型
tok = Tokenizer.from_file("/kaggle/working/datasets/tokenizer_5k_v2.json")
model = LanguageModel(ModelConfig())
state = torch.load(
    "/kaggle/working/checkpoints/hydrogen100m_iter2000_bf16.pt",
    map_location="cuda", weights_only=False
)
model.load_state_dict({k: v.float() for k, v in state["model"].items()})
model = model.cuda().eval()

# 生成测试
prompt = "什么是机器学习"
ids = [2] + tok.encode(prompt).ids  # BOS + prompt
x = torch.tensor([ids], dtype=torch.long).cuda()

with torch.no_grad():
    with torch.amp.autocast("cuda", dtype=torch.bfloat16):
        out = model(x, use_cache=True, past_kvs=None, start_pos=0)
    gen = x[0].tolist()
    past = out[1]
    for _ in range(50):
        nxt = out[0][:, -1, :].float().argmax(dim=-1, keepdim=True)
        gen.append(nxt.item())
        if nxt.item() == 3:  # EOS
            break
        with torch.amp.autocast("cuda", dtype=torch.bfloat16):
            out = model(nxt, use_cache=True, past_kvs=past, start_pos=len(gen)-1)
            past = out[1]

print(f"Prompt: {prompt}")
print(f"生成: {tok.decode(gen[len(ids):])}")
```

**预期结果**（100M 训练充分后）：
- loss < 4.0
- 4-gram 重复率 < 0.3
- 生成连贯的中英文片段

---

### 八、技术栈

#### 8.1 训练技术
- **权重初始化**：GPT-2 风格 + 残差缩放（std=0.02/√(2·n_layers)）
- **参数分组**：norm/bias/emb 不衰减，其余 weight decay
- **学习率调度**：Cosine + Warmup（可切 WSD）
- **LLDR**：Layer-wise LR Decay（浅层 lr × 0.85^d）
- **BF16 混合精度**：autocast（GPU 原生支持）
- **梯度累积**：模拟大 batch
- **梯度裁剪**：防爆炸
- **EMA**：指数移动平均（推理更稳）
- **SWA**：随机权重平均
- **OHEM**：Online Hard Example Mining（高 loss 样本加权采样）
- **激活重计算**：grad_checkpoint 省 100M 显存
- **断点续训**：保存 model + optimizer + iter + rng state

#### 8.2 架构技术
- **GQA**：Grouped Query Attention（KV heads 4:1 压缩）
- **SwiGLU**：FFN 激活（比 ReLU 强）
- **RoPE**：旋转位置编码（Llama-3 风格 base=500000）
- **QK-Norm**：稳定 attention 训练
- **Sandwich Norm**：embedding 后加 RMSNorm
- **SWA**：Sliding Window Attention（15 层 SWA + 1 层全局）
- **Parallel Attn+FFN**：GPT-J 风格残差
- **DropPath**：Stochastic Depth
- **Early Exit**：中间层分类头，置信度高提前退出
- **CoT**：思维链格式训练（think + summary 双格式）

#### 8.3 推理技术
- **KV Cache**：增量解码 O(n) 生成
- **投机解码**：Prompt Lookup / Lookahead / Medusa / MTP
- **INT4/INT8 量化**：推理压缩
- **torch.compile**：图优化加速

---

### 九、项目结构

```
kcpt-ai-llm/
├── README.md                    ← 本文件
├── kaggle_train.py              ← Kaggle GPU 一键训练脚本
├── train.py                     ← 训练主循环（CPU/GPU 双模式）
├── config.py                    ← 模型 + 训练配置
├── model.py                     ← 模型架构（GQA/SWA/RoPE/SwiGLU）
├── data.py                      ← 数据管线（下载/过滤/去重/tokenize）
├── datasets_loader.py           ← 多数据集加载器
├── generate.py                  ← 推理生成（KV Cache + 投机解码）
├── _train_tokenizer_5k_v2.py    ← 5K BPE tokenizer 训练
├── _build_hydrogen100m.py       ← 100M 训练数据集构建
├── quant.py                     ← INT4/INT8 量化
├── spec_decode.py               ← 投机解码
├── optimizer.py                 ← 优化器工具
└── cot_data.py                  ← CoT 数据增强
```

---

### 十、CPU 训练（备用）

无 GPU 时可在 CPU 训练（50M 降级版，2 核约 27 小时）：

```bash
cd /workspace/ai-llm-latest
python train.py
```

**注意**：CPU 训练 100M 模型不可行（OOM 或 >30min/iter），仅 50M 可用。

---

## License

MIT