企业官网建设流程全解析

train-llm-from-scratch 图表体系：手绘风格 Mermaid 架构图的制作、配色与再生成全指南

【免费下载链接】train-llm-from-scratchA straightforward method for training your LLM, from downloading data to generating text.项目地址: https://gitcode.com/GitHub_Trending/tr/train-llm-from-scratch

本指南以train-llm-from-scratch仓库的 docs/diagrams/README.md 为蓝本，系统讲解这套覆盖「数据 → 预训练 → SFT → 奖励模型 → DPO/PPO/GRPO → 评估 → 推理」全流程的彩色编码、手绘风格 Mermaid 架构图体系：为什么放弃 GitHub 的实时渲染而改用预渲染 PNG、源文件与产物如何组织、如何一键重新生成，以及每张图背后的mmd源码与配色规范。读完你不仅能看懂这套图，还能在自己修改文档后正确地重新渲染出同款风格的架构图。

为什么是「手绘风格 + 预渲染 PNG」

仓库的文档图表不是普通的 ``bash bash scripts/render_diagrams.sh

该脚本会把**每一个** `src/*.mmd` 重新渲染为 `docs/diagrams/<name>.png`，随后文档中嵌入的图片自动更新。 ### 运行前置条件 脚本依赖两样东西（见 [scripts/render_diagrams.sh](https://link.gitcode.com/i/59b842da270b8b21ff8769d46b4b4b69) 顶部注释）： - **Mermaid CLI**：`npm i -g @mermaid-js/mermaid-cli`，即命令 `mmdc`，需要 Node.js >= 18； - **一个 Chrome/Chromium** 用于无头渲染。脚本默认在 `/usr/bin/google-chrome-stable` 查找浏览器；如果你的 Chrome 不在这个位置，需要通过环境变量指定： ```bash CHROME=/path/to/chrome bash scripts/render_diagrams.sh

脚本内部实现解读

从源码看，render_diagrams.sh的实现非常精简，关键逻辑如下：

SRC=docs/diagrams/src OUT=docs/diagrams CHROME="${CHROME:-/usr/bin/google-chrome-stable}"

脚本会先用mktemp生成一个临时 Puppeteer 配置文件，把executablePath指向检测到的 Chrome，并追加无头渲染所需的参数：

{"executablePath":"<CHROME>","args":["--no-sandbox","--disable-gpu","--disable-dev-shm-usage"]}

然后对src/下每个.mmd调用mmdc：

mmdc -p "$PP" -i "$m" -o "$OUT/$base.png" -b white -s 2

其中-b white指定白底、-s 2表示以2 倍分辨率（@2x）输出 PNG。高分辨率输出正是为了让图在任何查看器（GitHub、VS Code 预览）中都清晰锐利，这也是选择 PNG 而非 SVG 的另一层考量。

与 README 图表的生成方式对照

docs/diagrams/面向 MkDocs 文档站，而顶层 README 使用的images/图表则由 images/make_diagrams.py 程序化生成。该脚本把每张图的 Mermaid 源码定义在 Python 字典DIAGRAMS中，再统一追加一份共享调色板PALETTE，渲染命令同样走npx @mermaid-js/mermaid-cli：

for f in *.mmd; do npx -y @mermaid-js/mermaid-cli -i "$f" -o "${f%.mmd}.png" -c mmdc.json -p puppeteer.json -b white -s 3 done

可以看到两条管线（render_diagrams.sh与make_diagrams.py）的思路完全一致：源码与产物分离、共享调色板、CLI 批量渲染，只是渲染倍率与目标目录不同。两份配套配置文件也直接躺在仓库里：

• images/mmdc.json —— Mermaid CLI 的样式配置，定义了look: handDrawn、theme: base，以及Comic Sans MS, Comic Sans, Chalkboard SE, cursive字体族、primaryColor: #ffe8a3（模型黄）、primaryBorderColor: #e8730c等主题变量，还有 flowchart 布局参数（htmlLabels: true、curve: basis、nodeSpacing: 22、rankSpacing: 55）；
• images/puppeteer.json —— Puppeteer 的无头浏览器参数（--no-sandbox --disable-setuid-sandbox）。

颜色图例：一张图读懂训练管线

这套图表最核心的设计是按语义统一着色。docs/diagrams/README.md给出的官方图例如下：

这一图例与顶层 README.md 中「Every diagram in this README is colored the same way」的说明完全呼应：绿色是原始数据、teal 是磁盘上已分词的存储、蓝色是处理步骤、黄色是模型/训练、橙色是 RL 与奖励、红色是损失、灰色是检查点、紫色是最终输出或评估。

图例并非口头约定，而是通过 Mermaid 的classDef在每份.mmd源码中硬编码落地的。以总览图 docs/diagrams/src/00_overview.mmd 为例，文件末尾统一声明：

每张图都通过:::data、:::model、:::rl、:::ckpt、:::eval这样的节点标记挂到对应类别上。make_diagrams.py中的共享PALETTE进一步扩展了这套体系：store（存储）、proc（处理）、loss（损失）等类别也都有各自固定的填充色与描边色，保证 README 图与文档站图风格统一、可跨文档对照阅读。

十张图表源码速览：从数据到推理的「图说」

src/下的每份.mmd都把某一段训练流程压缩成一张可读的流程图，与仓库代码一一对应：

• 00_overview.mmd：端到端总览 ——The Pile (9.8B tokens) → Pretrain (~400M base) → base_pretrained.pt → SFT (Alpaca · Dolly · GSM8K) → sft.pt → {Reward Model (Bradley-Terry), DPO/ORPO/KTO, PPO (GAE + clip + KL), GRPO (group-relative)} → GSM8K eval + chat，这正是 README.md 中「raw text → tokens → Transformer → base → SFT → RM → {PPO, DPO} → GRPO → eval/chat」路径的图形化；
• 01_data_pipeline.mmd：四条数据流并行 —— Pile 流式解压 +tiktoken r50k_base编码为pile_train.h5扁平 token 数组；Alpaca/Dolly/GSM8K 渲染聊天模板并掩码 prompt 后打包为sft_packed.h5；HH-RLHF/UltraFeedback 拆分为preferences.jsonl；GSM8K/arithmetic 抽取数值答案得到rl_prompts.jsonl；
• 02_pretraining.mmd：预训练循环 ——get_batch_iterator随机窗口采样 → bf16 前向 → 交叉熵 → 反向（乘 grad_accum）→ 梯度裁剪 1.0 → AdamW 步进（cosine LR + warmup），每 1000 步存base_pretrained.pt，与 scripts/pretrain_base.py 的训练主循环一致；
• 03_sft.mmd：SFT —— 从sft_packed.h5读 tokens + loss_mask，模型前向后做「shift 预测 t+1」的逐 token 交叉熵，loss_mask = 1仅落在 assistant token 上，最终只对掩码 token 求均值，对应 src/post_training/sft.py 的sft_loss；
• 04_reward_model.mmd：奖励模型 —— 偏好对经过 SFT 骨干的forward_hidden，取最后一个真实 token，过Linear→1奖励头得到r_chosen/r_rejected，用-log σ(r_chosen − r_rejected)（Bradley-Terry）训练，对应 src/post_training/reward_train.py；
• 05_dpo.mmd：DPO —— 同一偏好对分别过可训练策略与冻结的 SFT 参考副本，计算序列对数概率后套-log σ(β·Δlogratios)，无需奖励模型与 RL 循环，对应 src/post_training/dpo.py；
• 06_ppo.mmd：PPO —— GSM8K prompt 生成 rollout（含 log-probs），用 verifier 或奖励模型打分，叠加逐 token 的 KL-to-ref 惩罚，经compute_gae得到优势与回报，再做 K 个 epoch 的裁剪策略 + 价值更新，价值头通过 src/post_training/value_head.py 挂载；
• 07_grpo.mmd：GRPO —— 每个 prompt 采样一整组 G 条回答，逐条过 verifier，用组内(r − mean) / std作为组相对优势，再套裁剪代理目标 + k3 KL 惩罚更新策略，丢弃价值网络，对应 src/post_training/grpo.py；
• 08_evaluation.mmd：评估 —— 任意阶段检查点做贪心批量生成，extract_answer从<answer>标签（或####、最后一个数字）抽取数值与 gold 比对，汇总 Base→SFT→DPO→PPO→GRPO 的 GSM8K 准确率，对应 scripts/eval_post_training.py；
• 09_inference.mmd：推理 —— 从检查点读取模型维度，判断是 instruction 模型（套聊天模板）还是 base 模型（原始续写），再按 temperature / top-p / greedy 生成并解码为回复，对应 src/post_training/inference.py 与 scripts/chat.py。

实践要点与可复现性

综合原文档与源码，维护这套图表体系的实践要点可归纳为四条：

1. 只改源码，不手改图片。所有编辑都发生在docs/diagrams/src/*.mmd，渲染图一律由脚本产出，避免手工修图导致的「图源与图片不一致」；
2. 统一在仓库根目录触发渲染。bash scripts/render_diagrams.sh内部会cd "$(dirname "$0")/.."回到仓库根，保证相对路径稳定；
3. 环境只需配一次。Node.js ≥ 18 +@mermaid-js/mermaid-cli+ 一个 Chrome/Chromium；Chrome 不在默认路径时用CHROME=...覆盖，Puppeteer 的沙箱参数（--no-sandbox等）已内置于脚本，容器 / root 环境下也可直接运行；
4. 颜色规范是硬约束。新增图表时，节点必须通过:::data / :::proc / :::store / :::model / :::rl / :::loss / :::ckpt / :::eval挂到既有类别上，保持全仓库（README 与文档站）视觉语义一致。

这套「手绘 Mermaid + 预渲染 PNG + 一键脚本」的管线，让 train-llm-from-scratch 从数据下载到文本生成的每一阶段都有一张与代码同步、可复现的架构图，既是教学文档的组成部分，也直接反映了 scripts/ 与 src/post_training/ 各训练脚本的真实调用链。

【免费下载链接】train-llm-from-scratchA straightforward method for training your LLM, from downloading data to generating text.项目地址: https://gitcode.com/GitHub_Trending/tr/train-llm-from-scratch