Skip to content

维护与发布手册 ​

本手册说明修改哪个源文件、怎样生成 docs/ 镜像,以及怎样验证和发布。内容贡献要求见贡献指南,环境和结果字段分别见环境资产索引与Part 02 结果说明。

维护信息所有权 ​

信息唯一维护入口本手册是否展开
教学页面、代码与图片的贡献要求贡献指南与同类源页面否
GitHub 与网页的公式兼容公式兼容说明否
模型与 Profile 索引、跨专题隔离关系环境资产索引否
结果字段、证据等级和项目资产Part 02 结果资产否
工具用途、参数与迁移限制仓库工具说明否
转换、同步、检查、构建和交接本手册是

规则冲突时,先确定信息属于哪一行,再修改对应唯一维护源。不要在 Notebook、专题页或维护页增加第二份完整规则。

本地记录与正式规则 ​

批次计划、审计过程、交接笔记和历史快照保存在被忽略的 .local/notes/;临时扫描报告保存在 .local/reports/。这些文件保留本地,不加入学习导航或作为正式文档的链接目标。

可长期复用的同步与验证规则保存在本手册;实验状态登记在对应专题资产表和结果文件中。详细编写模板保留在本地 .local/authoring/,不作为公开链接目标。将历史记录移出正式目录时,先保留当前完整内容和未提交差异,再清理正式引用。

源文件与派生文件 ​

  • 源 Notebook、源 Markdown 和根目录 README.md 是正文事实来源。
  • docs/ 下的正文和导航是派生镜像,不能作为最终修改入口。
  • docs/public/ 中的正式 SVG、图片等静态资产直接维护,不由 Notebook 转换生成。
  • 本手册、使用指南、贡献指南、环境索引、公共结果说明、术语表和公式兼容说明是直接维护的站点文档,不属于正文镜像。
  • 镜像与源文件不一致时,以源文件为准;重新同步会覆盖镜像。
  • 旧路径迁移先核对引用;日常同步入口见下方表格,迁移过程保存在本地交接记录中。

标准维护流程 ​

text
确定信息所有权
→ 修改源文件或正式静态资产
→ 运行定向检查
→ 同步 docs 镜像
→ 运行对应 Part 的统一验证
→ 检查 diff、链接和实际渲染
→ 记录已验证项与未执行证据

1. 修改前 ​

  1. 使用 git status --short 确认工作区已有改动,避免覆盖他人或此前实验结果。
  2. 从贡献指南判断页面类型,参考同类源文件;配置、结果字段、安装步骤分别在其现有维护入口修改。
  3. 涉及重命名、调号或目录迁移时,先搜索源文件、镜像、导航、脚本和结果资产中的全部引用。

2. 修改与定向检查 ​

  • Notebook 修改后先检查 JSON、cell ID 和目标代码路径。
  • SVG 修改后先检查 XML、节点边界、箭头和阅读尺寸。
  • 结果 schema 或项目身份变化时,先运行对应 helper/schema 测试,再更新消费者。
  • 真实 GPU、backend 或多卡实验未执行时,保留为待采证据;不能用 CPU smoke 或模拟结果替代。

3. 同步镜像 ​

修改对象同步入口
根目录 README.mdpython tools/sync_docs_index.py
Part 导读、组页、专题 Markdownpython tools/sync_docs_navigation.py
单个 Notebook 或正文文件python tools/convert_notebook.py --file <source>
一个源目录python tools/convert_notebook.py --dir <source-dir>

默认优先使用定向参数。全量同步只在导航、生成器或大量源文件同时变化时运行。tools/convert_chapter0_1.py 仅保留历史兼容,不进入日常流程。

4. 验证与交接 ​

  1. 运行对应 Part 的统一验证入口。
  2. 运行 git diff --check,确认没有空白错误。
  3. 检查源文件与 docs/ 镜像、本地链接和站点构建。
  4. 图片必须查看实际渲染结果;自动检查不能替代连线和阅读尺寸检查。
  5. 交接时记录:修改范围、已执行命令、未执行的 GPU/外部环境证据、存量问题和下一步。

同步与验证层级 ​

日常维护先使用 verify.py。底层脚本只用于定向检查、故障定位或 CI 规则开发。

范围主入口补充入口说明
Part 00–01python verify.py part0_1 --no-buildpython verify.py part0_1_audit讲解型 Notebook:顺序执行代码并审计导读、链接和 cell ID
Part 02python verify.py part2 --no-build对应 helper/schema 测试机制页和项目页:题目、测试、答案、实验契约
Part 03python verify.py part3 --no-buildKernel 专项测试Triton 与 Kernel 正确性、编译和性能入口
Part 04python verify.py part4 --no-build系统专项测试CUDA、通信、调度与系统实验入口
全仓python verify.py all --no-buildcd docs && npm run docs:build合并前或生成链变化后使用

Part 00–01 不使用 Part 02 的题目—测试—答案抽取规则;Part 02/03 也不能只用“所有代码 Cell 顺序执行”替代专项验证。

常用命令 ​

bash
# 统一验证
python verify.py part0_1 --no-build
python verify.py part0_1_audit
python verify.py part2 --no-build
python verify.py part3 --no-build
python verify.py part4 --no-build
python verify.py all --no-build

# 定向同步
python tools/sync_docs_index.py
python tools/sync_docs_navigation.py
python tools/convert_notebook.py --file <source-file>
python tools/convert_notebook.py --dir <source-dir>

# 通用检查
python tools/check_source_docs_mirror.py
python tools/check_chapter_links.py --scope source
python tools/check_chapter_links.py --scope docs
python tools/check_svg_arrows.py <svg...>
python tools/check_svg_layout.py
git diff --check

# 站点构建
cd docs && npm run docs:build

测试脚本索引 ​

层稳定入口作用
统一验证verify.py按 Part 组织转换、检查和测试
转换tools/convert_notebook.py从源 Notebook / Markdown 生成正文镜像
导航同步tools/sync_docs_index.py、tools/sync_docs_navigation.py同步首页、导读、组页和专题导航
镜像与链接tools/check_source_docs_mirror.py、tools/check_chapter_links.py、tools/check_docs_links.py检查源/镜像与本地链接
Notebook 格式tools/validate_notebook_format.py检查 JSON、schema、cell ID 与 metadata
Part 00–01tools/test_chapter0_1_notebooks.py、tools/audit_chapter0_1_notebooks.py顺序执行代码、结构审计与 warning 归档
Part 02/03tools/test_notebook_answers.py验证题目区与答案区
SVGtools/check_svg_arrows.py、tools/check_svg_layout.py检查箭头结构、画布和页面尺度
历史迁移tools/md_to_notebook.pyMarkdown → Notebook 迁移辅助,不进入日常流程

Part 03 单节验证示例(在 llm_algo_cnb_gpu 环境运行):

bash
python tools/test_notebook_answers.py 03_Triton_Kernels/01_Triton_Vector_Addition.ipynb --mode both

题目区显示“按预期失败”表示 TODO 仍未完成;答案区应通过。无 GPU 时的 SKIPPED 不算运行级验证通过。

工具分类、批量改写风险和迁移限制见仓库工具说明,回归测试入口见工具测试说明。

环境与实验维护 ​

  • requirements/base.txt 不放 PyTorch、GPU 驱动或 Serving backend。
  • CPU / CUDA PyTorch、能力 Profile 和 backend 的机器规则在 requirements/environment-profiles.json 维护;跨专题入口和隔离关系在环境资产索引维护。
  • Notebook 可以检查环境,但不能静默替换 PyTorch、驱动、vLLM、SGLang 或其他 CUDA 执行栈。
  • 安装流程和项目预检见使用指南;Notebook 只保留当前页需要修改的配置和短入口。
  • 运行结果必须保存 runtime snapshot、配置、状态和失败原因;已完成标签进入结果 JSON 和专题实验资产表,不回写为源 Notebook 默认配置。

模型评测与跨专题质量门槛 ​

本节保留为历史链接入口,不在维护手册重复定义评测字段。凡候选方案会改变模型输出,项目决策必须同时检查质量、失败状态和性能,不能只凭吞吐或显存变化采用方案。

  • 公共结果外层、证据等级和字段复用:Part 02 结果资产
  • 项目特有的质量门槛、决策和交接步骤:对应源 Notebook 的 Step 5
  • 评测数据可信度和领域指标:对应横向专题及其实验资产表

迁移、重命名与兼容页 ​

  1. 先建立引用清单,再修改源文件名、H1、导航、专题链接、项目注册表和镜像名。
  2. 旧入口仍被引用时保留明确的兼容或 Reserved 页面,并指向新入口。
  3. 迁移完成后运行镜像、链接和站点构建检查,确认无引用后再删除旧入口。
  4. 不通过手改 docs/ 镜像绕过源文件迁移。

项目语义 ID 和产物关系见 benchmarks/project_registry.json 与 benchmarks/project_asset_relations.json。原始路径、备份位置和尚未处理的外部引用记录在本地交接中,不再增加一份公开迁移台账。

故障处理 ​

现象处理
源文件与网页不一致重新定向转换,并运行 check_source_docs_mirror.py
Notebook 在当前 shell 能运行、Jupyter 不能运行核对 kernelspec、sys.executable 和环境 Profile
Notebook JSON 合法但测试失败使用对应 Part 的测试模型,不混用 Part 00–01 与 Part 02 规则
链接检查失败从源文件修复相对路径,再同步镜像
SVG 自动检查通过但页面不可读在实际页面宽度下检查字号、留白、连线端点和箭头
GPU 或 backend 能力不可用保存 preflight/failure,停止形成目标机制或性能结论
全量同步产生大量无关差异停止后续编辑,核对源文件与生成器范围,不覆盖已有工作区改动

提交前最小检查 ​

  • 改动发生在正确的唯一维护源。
  • docs/ 镜像来自同步脚本,没有反向手改。
  • 对应 Part 验证通过,或明确记录未运行原因。
  • 本地链接、SVG 渲染和 git diff --check 已检查。
  • GPU、backend、外部数据或多卡证据没有被模拟结果替代。
  • 提交范围不包含无关工作区修改、临时脚本、缓存或本地凭据。

Released under the MIT License.