# TrainingTutorial

**Repository Path**: jpc_chenjianping/training-tutorial

## Basic Information

- **Project Name**: TrainingTutorial
- **Description**: 模型训练教程
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-08
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# training-tutorial

端到端模型训练实战教程集合。每个子目录是一个独立、可运行的教学项目，从数据到部署，每一步都可运行、可修改、可理解。

---

## 当前包含

### [`01_model-training-tutorial/`](01_model-training-tutorial/) — Mini Transformer 文本分类（从零训练）

一个面向初学者的端到端 NLP 分类教程：用从零搭建的 Mini Transformer（~0.9M 参数）做 AG News 英文新闻 4 分类（World / Sports / Business / SciTech）。

**能力概览**

| 项目 | 说明 |
|------|------|
| 任务 | 英文新闻 4 分类（AG News 数据集） |
| 模型 | Mini Transformer（Encoder-only，2 层，d_model=128） |
| 框架 | PyTorch（CPU 可跑，有 GPU 自动用） |
| 效果 | 测试集准确率 ~86%（随机基线 25%） |
| 耗时 | 约 30–45 分钟（CPU） |

**完整流程，四步走通**

```
01_data_and_vocab.py  →  数据准备 + 词表构建
02_model.py           →  模型架构定义 + 前向自测
03_train.py           →  训练循环（AdamW + cosine，带种子可复现）
04_evaluate.py        →  测试集评估 + 混淆矩阵 + 交互推理
```

也可 `python run_all.py` 一键跑完全流程。

**主要特性**

- **可复现**：训练设了随机种子，每次结果一致。
- **架构单一来源**：模型超参集中在 `model_def.py` 的 `MODEL_HYPERPARAMS`，并写进 `config.json`，训练/评估用同一套，杜绝 shape 不匹配。
- **代码逐行注释**：面向不熟 Python 的读者，每行都标注语法与作用。
- **底层原理齐全**：README 含「每一步为什么这么做」的原理专节（词表/UNK/PAD、位置编码、训练循环五步、优化器、评估指标等）。
- **容错友好**：每步检查前置产物是否存在，缺失会提示先跑上一步。

**快速上手**

```bash
cd 01_model-training-tutorial
pip install -r requirements.txt          # 需 Python 3.9–3.11
# 国内网络必看：配置 HF 镜像
export HF_ENDPOINT=https://hf-mirror.com
python run_all.py                         # 或按 01→04 分步运行
```

详细说明（安装、分步运行、动手实验、原理、常见问题、项目结构）见该目录下的 [README.md](01_model-training-tutorial/README.md)。

---

> 后续会在此仓下继续添加更多主题的教程子目录。