大模型算法实战教程

Appearance

大模型算法实战教程题目与网页化模板指南 ​

为了保证整个项目在源码（Jupyter Notebook）和前端网页（VitePress）上的展示一致性、防剧透体验以及低维护成本，所有题目请严格遵循以下结构与模板规范。

一、 源码规范：Jupyter Notebook (.ipynb) 结构 ​

每一个题目的 Notebook 必须采用 "SSOT (Source of Truth)" 原则：所有的题目、测试用例、解析和答案都写在同一个 .ipynb 文件中。

标准文件结构 ​

  1. 【题目区】(Markdown + Code)
    • 介绍核心概念。
    • 给出填空代码（使用 TODO 占位符）。
  2. 【测试区】(Code)
    • 提供 test_xxx() 函数，用以验证用户填入的代码正确性以及输出性能（如有）。
  3. 【防剧透缓冲带】(Markdown)
    • 必须放置在测试代码块之后，答案块之前。用于在 Colab 或本地执行时防止用户不小心往下滚看到答案。
  4. 【解析与答案区】(Markdown + Code)
    • 提供详细的思路和无 Bug 的满分代码。

尾部三段式模板代码 ​

在 Notebook 的最末尾，请依次添加以下三个 Cell：

Cell 1: 防剧透缓冲带 (Markdown)

markdown
---

🛑 **STOP HERE** 🛑
<br><br><br><br><br><br><br><br><br><br>
> 请先尝试自己完成代码并跑通测试。<br>
> 如果你正在 Colab 中运行，并且遇到困难没有思路，可以向下滚动查看参考答案。
<br><br><br><br><br><br><br><br><br><br>

---

Cell 2: 答案文字解析 (Markdown)(注意：标题中必须包含 解析、答案 或 参考代码 关键词，以便转换脚本触发折叠！)

markdown
## 官方解析与参考代码

**解析：**
1. **TODO 1 (命名/目标)：** [解释第一步的思路...]
2. **TODO 2 (防溢出/加速等)：** [解释工程实现中的细节，如强转 float32，避免 nan 等...]
3. **复杂度与带宽：** [可选：分析 FLOPs 和访存带宽瓶颈...]

Cell 3: 完整参考代码 (Code)

python
# 建议命名带有 Solution 后缀，避免和上面的 TODO 模板类名冲突
class RMSNormSolution(nn.Module):
    def __init__(self, ...):
        ...

二、项目节分类与 Step1 模板 ​

项目节先按“主要产出”分类，再选择 Step1 的组织方式。分类不是新的难度等级，也不改变 Notebook 编号；它用于减少不同项目之间的模板漂移。

1. Project：端到端项目 ​

判断标准： 学习者需要完成一条相对完整的任务链，并提交模型、adapter、报告或其他可复核产物。

Step1 重点：

项目内容CPU：机制验证GPU / 真实环境实验约定
任务目标检查输入、函数和报告逻辑完成真实任务流程说明成功标准
模型与数据使用小型样例验证字段关系指定模型、数据集和版本记录模型、数据和切分
对照方案验证 baseline / candidate 的结构执行真实对照或训练只改变明确的核心变量
输出产物检查报告字段和交付记录保存模型、adapter、报告或日志说明如何复核产物
性能分析与证据解释对照输入、输出和机制假设记录指标差异、异常与证据等级说明结论由哪些数据支持
项目决策用示例数据测试决策函数根据真实指标输出结论使用 accept / tune / reject

适用项目包括 60、61、62、81。Project + Benchmark 项目还要补充固定 workload、候选方案和指标对比。

2. Benchmark：对照基准实验 ​

判断标准： 主要产出是不同方案在统一条件下的可比较指标，而不是某个模型或服务产物。

Step1 重点：

项目内容必须说明
实验问题要比较哪种策略、后端或并行方式
固定条件模型、数据、dtype、batch、seq_len、seed、硬件和运行次数
变化变量每轮只改变一个主要变量
候选方案baseline、candidate 及其实现边界
指标延迟、吞吐、显存、质量、OOM 或通信开销，并注明单位
性能分析与证据解释解释指标差异对应的机制，记录异常和重复运行结果
输出结果结果表、重复运行统计、失败原因和比较结论

CPU 路径用于验证指标计算、调度或策略逻辑；GPU / backend 路径用于产生真实性能证据。没有真实环境时，结果必须标记为模拟或未采集。

适用项目包括 63、66、68、69、70、76、79、80，以及 67、71 的 Benchmark 部分。

3. Analysis / 性能分析：测量与证据分析 ​

判断标准： 主要产出是测量口径、瓶颈假设、证据解释和针对性复测，不是单纯比较“哪个数字更好”。

Step1 重点：

项目内容必须说明
现象与问题要解释训练或推理中的哪个性能现象
测量边界计时从哪里开始，到哪里结束，哪些开销计入
可测假设现象可能来自容量、计算、带宽、通信或同步中的哪一类
CPU 能验证什么字段、账本、统计和报告合并逻辑
GPU / Trace 能验证什么CUDA 时间线、kernel、显存峰值、搬运和同步活动
性能分析与证据解释指标对比、trace 路径、瓶颈解释和一次针对性复测

分析类项目不能把单次热点、CPU 模拟或 trace 文件存在本身写成完整优化结论。适用项目包括 73、74；64 也包含数据质量分析部分。

4. Decision：约束下的方案决策 ​

判断标准： 主要产出是在预算、吞吐、质量或 SLA 约束下筛选可行方案，并观察结论对阈值变化是否稳定。

Step1 重点：

项目内容必须说明
输入报告来自哪个 benchmark 或真实项目，使用什么 workload
资源约束显存上限、吞吐下限、延迟上限或质量下限
候选方案如何判断候选可行，淘汰原因是什么
敏感性分析改变哪些阈值，观察可行集合和最佳候选是否变化
性能分析与证据解释检查上游指标是否足以支撑决策，区分实测、估算和假设
输出结果预算表、敏感性统计和 accept / tune / reject

Decision 类项目通常不重新训练或测量 GPU；它读取已有报告执行规划。若需要新硬件或新 workload 的真实性能，必须回到对应 Benchmark 或 Analysis 项目补采。

适用项目包括 65、75。

5. 分类使用规则 ​

  • 统一表格外壳可以使用“项目内容｜CPU：机制验证｜GPU / 真实环境｜实验约定”，但每类项目的行内容必须围绕自身产出调整。
  • Project + Benchmark 表示既要完成端到端流程，又要进行固定条件下的方案比较，例如 67、71。
  • Project + Analysis 表示项目产物之外，还要解释数据或训练现象，例如 64。
  • Decision + Benchmark 表示先产生对照数据，再根据约束进行方案选择，例如 65。
  • 不要把项目类型与运行环境混用：项目类型表示主要产出；运行环境同时说明硬件、运行方式和依赖配置。
  • Step1 只定义问题、输入、操作、输出和证据边界；具体 TODO、测试区和解析区分别在后续 Step 展开。

三、网页化转换规范：转换脚本逻辑 (tools/convert_notebook.py) ​

我们在 tools/ 下使用统一的章节转换脚本：

  • tools/convert_notebook.py：负责第零部分到第四部分的 .ipynb 与 .md 同步生成，是当前主链路
  • tools/convert_chapter0_1.py：仅保留为历史兼容脚本，不再作为日常同步入口

实现“源码写一次，网页自动生成”的工作流。

转换脚本当期支持的特性： ​

  1. 自动生成云端运行徽章 (Hero Badges)
    • 脚本会在每一页的最上方自动植入 "Open In Colab" 和 "Open In ModelScope" (魔搭) 徽章。
    • 自动映射 GitHub 源码路径，确保一键跳转。
  2. 智能识别并折叠答案 (Smart Folding)
    • 脚本扫描 Markdown Cell 的文本，一旦匹配到 答案、解析 或 solution 关键词，会自动注入 VitePress 的 ::: details 💡 点击查看官方解析与参考代码 容器。
    • 将这之后的解析文字和答案代码块全部包裹并默认折叠。
  3. 评论区与 PR 引导 (Community CTA)
    • 在每篇文章的底部，脚本会自动追加引导提交 PR 的 Markdown 块。
    • VitePress 底部自动挂载配置好的 GitHub Giscus 讨论区组件。

四、维护者的日常工作流 ​

  1. 出题/修改代码：只在根目录下的相应目录（如 02_PyTorch_Algorithms/）打开或新建 .ipynb，按照上文的“尾部三段式”模板编写题目和答案。
  2. 生成网页：
    • 统一运行 python tools/convert_notebook.py
  3. 预览校验：进入 docs/ 运行 npm run docs:preview 查看网页排版是否完美。
  4. 提交代码：git add 修改过的 .ipynb 和 docs/ 下的 .md，然后 git commit & git push。

Released under the MIT License.

Copyright © 2024-present