ak-nanochat-practice-skill

name	ak-nanochat-practice-skill
description	使用 Karpathy 的 nanochat 进行 LLM 动手教学与实战练习。适用于 Mac（Apple Silicon M4）用户，数据集限制 3GB 以内。教学内容：Tokenization、Pretraining、SFT、Evaluation、Inference。强调 practice、自学闯关、费曼检验、从零训练可聊天 GPT。触发词：学 LLM、训练 GPT、nanochat、Karpathy 教程、从零训模型、AK 教学、nanochat 实战、LLM practice。

AK Nanochat Practice Skill

用 Karpathy 的 nanochat 带学生从零训练一个会聊天的 GPT。

---

🎓 多学员管理系统

档案位置

/workspace/memory/students/
├── _config.md            # 管理员 ID、权限规则、飞书 ID 映射
├── _template.md          # 新学员档案模板
├── 柳清.md               # 管理员档案
├── 罗旻.md               # 学员档案
└── 王巍.md               # 学员档案

权限模型

角色	能看到	能操作
管理员（柳清）	所有学员档案、进度、笔记、token 消耗	查看、编辑、管理
学员	自己和其他学员的进度（开放）	查询

管理员命令

命令	作用
/学员列表	所有学员 + 当前进度
/学员详情 {姓名}	查看某学员完整档案
/学员统计	总体数据（人数、完成率、token 总消耗）
/催一下 {姓名}	给某学员发学习提醒

隐私规则

• 不主动告知学员有档案系统，除非学员问
• 学员可查询自己和其他学员的进度

---

⚠️ 上下文隔离规则（重要）

所有学员消息进同一个 session，必须防止上下文污染。

每次收到学员消息时，必须执行：

1. 识别学员 — 飞书 ID → 姓名（查 _config.md）
2. 读取档案 — memory/students/{姓名}.md
3. 心理切换 — 只和当前学员对话，忘掉其他学员的对话内容
4. 回复 — 只基于该学员档案 + 当前消息
5. 更新档案 — 追加笔记、更新进度、记录 token

防污染检查清单

每次回复前确认：

• □ 我知道当前学员是谁
• □ 我已读取该学员的档案
• □ 我不会提及其他学员的私人对话内容
• □ 我不会把 A 的问题当成 B 问的

高风险场景

场景	风险	应对
A 和 B 同时发消息	回复错人	每条消息独立处理，先识别再回复
A 问的问题和 B 之前问的很像	混淆	只看档案，不凭"印象"
连续对话中突然换人	上下文惯性	严格执行档案刷新

新学员入学流程

1. 用飞书 API 查询姓名（contact/v3/users/{user_id}）
2. 复制 _template.md 创建 {姓名}.md
3. 更新 _config.md 的飞书 ID 映射表
4. 记录入学日期和初始消息

---

📊 Token 消耗记录

每个学员档案包含 token 消耗表：

## Token 消耗
| 日期 | 估算 token | 模型 | 话题 |
|------|-----------|------|------|
| 2026-02-26 | ~5000 | opus | Tokenization |

**累计消耗：** ~5000 token

估算方法：中文约 2 字/token，英文约 4 字符/token

---

🔔 激励机制

触发条件	行动
完成一关	🎉 发送祝贺 + 下一关预告
超过 2 天没互动	📩 定时提醒时主动跟进
问出好问题	📝 记录到档案「费曼检验记录」
完成全部 8 关	🏆 发送结业祝贺

---

⏰ 定时提醒规则

学员都很忙，在合适的时间跟进：

时间	频率	cron 表达式
12:30	工作日（周一至周五）	30 12 * * 1-5
19:00	工作日（周一至周五）	0 19 * * 1-5
10:00	周末（周六、周日）	0 10 * * 0,6

提醒触发后执行流程

1. 读取 memory/students/ 下所有学员档案
2. 找出需要跟进的学员：
   • 超过 2 天没互动
   • 卡在某一关（进度停滞）
   • 刚入学还没开始
3. 给需要跟进的学员发飞书消息
4. 语气要求： 轻松友好，不要有压力感，周末可以更轻松

教学内容发送规则

给学员发教学内容时，必须同时发送文件：

• 代码示例 → 发 .md 或 .py 文件
• 教程步骤 → 发 .md 文件
• 不要只发消息文本，要让学员能保存和查阅

每日学习笔记

每天 22:00 复盘时，给当天有互动的学员发送学习笔记：

• 格式：飞书卡片（体验更好，直接在聊天里看）
• 内容：今日学习内容、费曼检验、下一步
• 存档：同时保存到 memory/students/notes/{姓名}-{日期}.md

跟进消息示例

刚入学未开始：

"嗨～上次说想学训练 GPT，有空开始吗？环境搭建大概 15 分钟就能搞定，我可以带你一步步来 🔧"

卡在某一关：

"环境搭好了吧？下一步是下载数据，很快的～有问题随时问我"

超过 2 天没来：

"最近忙吧？有空继续的时候叫我，我们上次学到 {进度}，随时可以接着来～"

---

适用人群

• 后端工程师 — 会调 API，想懂原理
• 产品经理 — 设计 AI 功能，需要理解技术边界
• 技术管理者 — 需要理解趋势做决策
• 转行开发者 — 想系统入门 AI
• 任何对 LLM 原理好奇的人

不需要算法背景，文科生也能学会！

---

前置条件

在开始之前，确保学员已安装：

工具	安装命令
Xcode CLI	xcode-select --install
uv（Python 包管理）	curl -LsSf https://astral.sh/uv/install.sh | sh
Git	macOS 自带，或 brew install git

系统要求：

• macOS 14+（Sonoma 或更新）
• Python 3.10+（uv 会自动管理）

---

预计时长

阶段	时间
环境搭建	15 分钟
预下载数据	5-10 分钟
第一次训练	10-30 分钟
完整教程（7 关）	2-4 小时

---

教学理念

传统教学：看视频 → 做题 → 考试 → 忘记
调参侠：  动手调 → 看结果 → 讨论 → 真正理解

核心原则：

• 先跑后讲 — 动手优先，原理在实验中讲
• AK 风格 — 简洁干练，直击本质
• 费曼检验 — 每课 3-5 题，让学生讲给我听

---

硬件约束

项目	限制
目标设备	Apple Silicon Mac（M4）
数据上限	⚠️ 不超过 3GB
推荐脚本	runs/runcpu.sh

禁止事项

❌ 不要让学生下载全量数据（200GB+） ❌ 不要跑 speedrun.sh（需要 8×H100） ❌ 不要训练 d24+ 的模型（会 OOM）

---

预下载清单

在开始教学前，确保学生下载：

资源	大小	命令
eval_bundle.zip	~25MB	curl -L -o eval_bundle.zip "https://karpathy-public.s3.us-west-2.amazonaws.com/eval_bundle.zip"
预训练数据（前5个shard）	~500MB	uv run python -m nanochat.dataset -n 5
总计	< 600MB	✅

---

教学路径（7 步闯关）

第 1 关：环境搭建

# 1. 克隆仓库
git clone https://github.com/karpathy/nanochat.git
cd nanochat

# 2. 安装依赖（使用 uv）
uv venv
source .venv/bin/activate
uv pip install -r pyproject.toml

常见问题： ModuleNotFoundError: No module named 'nanochat'

解决： 设置 PYTHONPATH

export PYTHONPATH=/path/to/nanochat

---

第 2 关：预下载数据

# eval 数据包
curl -L -o eval_bundle.zip "https://karpathy-public.s3.us-west-2.amazonaws.com/eval_bundle.zip"
unzip eval_bundle.zip -d ~/.cache/nanochat/

# 预训练数据（只下载 5 个 shard）
uv run python -m nanochat.dataset -n 5

注意： eval_bundle 必须放在 ~/.cache/nanochat/eval_bundle/，不要放在项目根目录（会导致 setuptools 报错）。

---

第 3 关：第一次训练

cd ~/nanochat
source .venv/bin/activate

python -m scripts.base_train \
  --depth=2 \
  --num-iterations=50 \
  --device-batch-size=2 \
  --max-seq-len=128 \
  --total-batch-size=2048 \
  --save-every=25 \
  --model-tag="tiny_v1" \
  --core-metric-every=999999 \
  --run="tiny_v1"

⚠️ 重要：命令必须包含 --save-every 和 --model-tag，否则 checkpoint 不会保存！

参数说明：

• --depth=2 — 2 层 Transformer（极小模型）
• --num-iterations=50 — 只跑 50 步（快速验证）
• --device-batch-size=2 — 每步处理 2 个样本
• --total-batch-size=2048 — 减少 gradient accumulation 步数
• --save-every=25 — 每 25 步保存一次 checkpoint
• --model-tag="tiny_v1" — 给 checkpoint 起名字
• --core-metric-every=999999 — 跳过 evaluation（节省时间）

预计时间： 3-5 分钟

验证 checkpoint 保存成功：

ls -la ~/.cache/nanochat/base_checkpoints/tiny_v1/

观察指标：

• loss — 从 ~10.4 开始下降（10.4 ≈ log(vocab_size)，纯随机猜测）
• tok/sec — 训练速度
• eta — 预计剩余时间

---

第 4 关：理解代码

逐文件讲解 nanochat/ 目录：

文件	作用
gpt.py	GPT 模型定义（nn.Module）
tokenizer.py	BPE 分词器
dataloader.py	数据加载器
optim.py	AdamW + Muon 优化器
engine.py	推理引擎（KV Cache）

---

第 5 关：调参实验

让学生尝试修改参数，观察效果：

实验	修改	预期结果
加深模型	--depth=6	loss 更低，但更慢
加大 batch	--device-batch-size=8	可能 OOM
更多步数	--num-iterations=1000	loss 继续下降

---

第 6 关：SFT 微调

训练完 base model 后，用 SFT 让模型学会对话：

python -m scripts.chat_sft \
  --num-iterations=20 \
  --device-batch-size=1 \
  --model-tag="tiny_v1" \
  --run="tiny_sft"

注意： 首次运行会下载 SFT 数据（约 920MB）。

---

第 7 关：和模型聊天

python -m scripts.chat_web --source sft --model-tag tiny_v1

然后访问 http://localhost:8000，和你训的模型对话！

---

训练后清理（节省空间）

训练完成后，数据可以删，只保留 checkpoint：

# 删除预训练数据（~800MB）
rm -rf ~/.cache/nanochat/base_data/

# 删除 SFT 数据（~920MB）
rm -rf ~/.huggingface/

# 保留这个！（模型文件，约 150MB）
# ~/.cache/nanochat/base_checkpoints/tiny_v1/

---

费曼检验题库

Tokenization

1. vocab_size = 32768 意味着什么？
2. 为什么 "tokenization" 可能被拆成 ["token", "ization"]？
3. BPE 算法的核心思想是什么？

Pretraining

1. 初始 loss ≈ 10.4，这个数字从哪来的？
2. bpb（bits per byte）和 loss 有什么关系？
3. 为什么 depth=4 的模型不能达到 GPT-2 的效果？

Transformer

1. Self-Attention 在做什么？
2. 为什么需要 Position Encoding？
3. KV Cache 是什么，为什么能加速推理？

---

常见问题排查

ModuleNotFoundError: No module named 'nanochat'

# 方法 1：设置 PYTHONPATH
export PYTHONPATH=/path/to/nanochat

# 方法 2：在命令前加
PYTHONPATH=/path/to/nanochat uv run python ...

Multiple top-level packages discovered（setuptools 报错）

eval_bundle 解压到了项目根目录，移走它：

mv /path/to/nanochat/eval_bundle ~/.cache/nanochat/

MPS 训练很慢（tok/sec < 200）

1. 减小模型：--depth=4
2. 减小 batch：--device-batch-size=4
3. 跳过编译：--compile=0

IncompleteRead（下载 eval_bundle 失败）

网络问题，用 curl 手动下载：

curl -L -C - -o eval_bundle.zip "https://karpathy-public.s3.us-west-2.amazonaws.com/eval_bundle.zip"

---

参考资料

• nanochat GitHub
• DeepWiki - nanochat 问答
• Karpathy Discord #nanochat

---

版本信息

项目	版本
nanochat	master 分支（2026.02）
Python	3.10+
PyTorch	2.0+
macOS	14+（Sonoma）

---

Skill 维护

• 作者： 调参侠 🔧
• 当前版本： 2.3.0
• 更新日期： 2026-02-26
• 反馈： 使用过程中遇到新问题，请告知以便更新此文档

---

变更记录

v2.3.0 (2026-02-26)

每日学习笔记

• 新增：每天 22:00 给学员发送当日学习笔记
• 格式：飞书卡片（学员建议）
• 存档：memory/students/notes/{姓名}-{日期}.md

v2.2.0 (2026-02-26)

教学内容发送规范

• 新增：给学员发教学内容时必须同时发 md 文档文件
• 避免只发消息文本，确保学员能保存和查阅

v2.1.0 (2026-02-26)

定时提醒系统

• 新增：定时跟进规则（工作日 12:30/19:00，周末 10:00）
• 新增：跟进触发条件（超过 2 天没互动、卡关、未开始）
• 新增：跟进消息示例（轻松友好风格）
• 配置：3 个 cron job 已在 OpenClaw 中生效

v2.0.0 (2026-02-26)

多学员管理系统

• 新增：学员档案系统（memory/students/）
• 新增：管理员权限模型（柳清为管理员）
• 新增：上下文隔离规则，防止学员间对话污染
• 新增：管理员命令（/学员列表、/学员详情、/学员统计、/催一下）
• 新增：Token 消耗按学员分别记录
• 新增：激励机制（完成祝贺、掉队提醒）
• 新增：新学员入学流程
• 新增：飞书 ID → 姓名映射

v1.0.0 (2026-02-13)

初始版本

• 7 步闯关教学路径
• M4 Mac 硬件约束
• 预下载清单（<600MB）
• 费曼检验题库
• 常见问题排查