维护与发布手册
本手册说明修改哪个源文件、怎样生成 docs/ 镜像,以及怎样验证和发布。内容贡献要求见贡献指南,环境和结果字段分别见环境资产索引与Part 02 结果说明。
维护信息所有权
| 信息 | 唯一维护入口 | 本手册是否展开 |
|---|---|---|
| 教学页面、代码与图片的贡献要求 | 贡献指南与同类源页面 | 否 |
| GitHub 与网页的公式兼容 | 公式兼容说明 | 否 |
| 模型与 Profile 索引、跨专题隔离关系 | 环境资产索引 | 否 |
| 结果字段、证据等级和项目资产 | Part 02 结果资产 | 否 |
| 工具用途、参数与迁移限制 | 仓库工具说明 | 否 |
| 转换、同步、检查、构建和交接 | 本手册 | 是 |
规则冲突时,先确定信息属于哪一行,再修改对应唯一维护源。不要在 Notebook、专题页或维护页增加第二份完整规则。
本地记录与正式规则
批次计划、审计过程、交接笔记和历史快照保存在被忽略的 .local/notes/;临时扫描报告保存在 .local/reports/。这些文件保留本地,不加入学习导航或作为正式文档的链接目标。
可长期复用的同步与验证规则保存在本手册;实验状态登记在对应专题资产表和结果文件中。详细编写模板保留在本地 .local/authoring/,不作为公开链接目标。将历史记录移出正式目录时,先保留当前完整内容和未提交差异,再清理正式引用。
源文件与派生文件
- 源 Notebook、源 Markdown 和根目录
README.md是正文事实来源。 docs/下的正文和导航是派生镜像,不能作为最终修改入口。docs/public/中的正式 SVG、图片等静态资产直接维护,不由 Notebook 转换生成。- 本手册、使用指南、贡献指南、环境索引、公共结果说明、术语表和公式兼容说明是直接维护的站点文档,不属于正文镜像。
- 镜像与源文件不一致时,以源文件为准;重新同步会覆盖镜像。
- 旧路径迁移先核对引用;日常同步入口见下方表格,迁移过程保存在本地交接记录中。
标准维护流程
确定信息所有权
→ 修改源文件或正式静态资产
→ 运行定向检查
→ 同步 docs 镜像
→ 运行对应 Part 的统一验证
→ 检查 diff、链接和实际渲染
→ 记录已验证项与未执行证据1. 修改前
- 使用
git status --short确认工作区已有改动,避免覆盖他人或此前实验结果。 - 从贡献指南判断页面类型,参考同类源文件;配置、结果字段、安装步骤分别在其现有维护入口修改。
- 涉及重命名、调号或目录迁移时,先搜索源文件、镜像、导航、脚本和结果资产中的全部引用。
2. 修改与定向检查
- Notebook 修改后先检查 JSON、cell ID 和目标代码路径。
- SVG 修改后先检查 XML、节点边界、箭头和阅读尺寸。
- 结果 schema 或项目身份变化时,先运行对应 helper/schema 测试,再更新消费者。
- 真实 GPU、backend 或多卡实验未执行时,保留为待采证据;不能用 CPU smoke 或模拟结果替代。
3. 同步镜像
| 修改对象 | 同步入口 |
|---|---|
根目录 README.md | python tools/sync_docs_index.py |
| Part 导读、组页、专题 Markdown | python 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. 验证与交接
- 运行对应 Part 的统一验证入口。
- 运行
git diff --check,确认没有空白错误。 - 检查源文件与
docs/镜像、本地链接和站点构建。 - 图片必须查看实际渲染结果;自动检查不能替代连线和阅读尺寸检查。
- 交接时记录:修改范围、已执行命令、未执行的 GPU/外部环境证据、存量问题和下一步。
同步与验证层级
日常维护先使用 verify.py。底层脚本只用于定向检查、故障定位或 CI 规则开发。
| 范围 | 主入口 | 补充入口 | 说明 |
|---|---|---|---|
| Part 00–01 | python verify.py part0_1 --no-build | python verify.py part0_1_audit | 讲解型 Notebook:顺序执行代码并审计导读、链接和 cell ID |
| Part 02 | python verify.py part2 --no-build | 对应 helper/schema 测试 | 机制页和项目页:题目、测试、答案、实验契约 |
| Part 03 | python verify.py part3 --no-build | Kernel 专项测试 | Triton 与 Kernel 正确性、编译和性能入口 |
| Part 04 | python verify.py part4 --no-build | 系统专项测试 | CUDA、通信、调度与系统实验入口 |
| 全仓 | python verify.py all --no-build | cd docs && npm run docs:build | 合并前或生成链变化后使用 |
Part 00–01 不使用 Part 02 的题目—测试—答案抽取规则;Part 02/03 也不能只用“所有代码 Cell 顺序执行”替代专项验证。
常用命令
# 统一验证
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–01 | tools/test_chapter0_1_notebooks.py、tools/audit_chapter0_1_notebooks.py | 顺序执行代码、结构审计与 warning 归档 |
| Part 02/03 | tools/test_notebook_answers.py | 验证题目区与答案区 |
| SVG | tools/check_svg_arrows.py、tools/check_svg_layout.py | 检查箭头结构、画布和页面尺度 |
| 历史迁移 | tools/md_to_notebook.py | Markdown → Notebook 迁移辅助,不进入日常流程 |
Part 03 单节验证示例(在 llm_algo_cnb_gpu 环境运行):
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
- 评测数据可信度和领域指标:对应横向专题及其实验资产表
迁移、重命名与兼容页
- 先建立引用清单,再修改源文件名、H1、导航、专题链接、项目注册表和镜像名。
- 旧入口仍被引用时保留明确的兼容或
Reserved页面,并指向新入口。 - 迁移完成后运行镜像、链接和站点构建检查,确认无引用后再删除旧入口。
- 不通过手改
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、外部数据或多卡证据没有被模拟结果替代。
- 提交范围不包含无关工作区修改、临时脚本、缓存或本地凭据。
