From 78135794270d3cb676cd094b65a8f8e0daacdc11 Mon Sep 17 00:00:00 2001 From: Yunpeng Huang Date: Sun, 5 Jul 2026 19:46:30 +0800 Subject: [PATCH] [WIP] Sphinx-style Documentation Setup (#39) * inited docs * added sphinx.yaml to deploy docs * set up zh docs po files * finished a naive translation of zh-docs * allow chinese char in EXEMPT_DOCUMENT_NAMES * fix pre-commit --------- Co-authored-by: HongyuJia --- .github/workflows/check_chinese_chars.py | 11 +- .github/workflows/sphinx.yaml | 38 ++ .gitignore | 1 + docs/Makefile | 42 ++ docs/README.md | 119 ++++++ docs/README_zh.md | 117 ++++++ .../LC_MESSAGES/blog/auto_cpu_offload.po | 298 ++++++++++++++ .../blog/auto_cuda_graph_design.po | 355 ++++++++++++++++ docs/locale/zh_CN/LC_MESSAGES/blog/toc.po | 25 ++ .../zh_CN/LC_MESSAGES/blog/why_magi_depyf.po | 379 ++++++++++++++++++ docs/locale/zh_CN/LC_MESSAGES/index.po | 58 +++ .../zh_CN/LC_MESSAGES/user_guide/install.po | 69 ++++ .../LC_MESSAGES/user_guide/quickstart.po | 69 ++++ .../zh_CN/LC_MESSAGES/user_guide/toc.po | 25 ++ docs/make.bat | 66 +++ docs/requirements.txt | 10 + docs/source/_static/custom.css | 25 ++ docs/source/_templates/language-switcher.html | 94 +++++ docs/source/blog/auto_cpu_offload.md | 68 ++++ docs/source/blog/auto_cuda_graph_design.md | 167 ++++++++ docs/source/blog/refs/.gitkeep | 2 + docs/source/blog/toc.md | 22 + docs/source/blog/why_magi_depyf.md | 193 +++++++++ docs/source/conf.py | 165 ++++++++ docs/source/index.md | 21 + docs/source/user_guide/install.md | 64 +++ docs/source/user_guide/quickstart.md | 64 +++ docs/source/user_guide/toc.md | 10 + 28 files changed, 2575 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/sphinx.yaml create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/README_zh.md create mode 100644 docs/locale/zh_CN/LC_MESSAGES/blog/auto_cpu_offload.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/blog/auto_cuda_graph_design.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/blog/toc.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/blog/why_magi_depyf.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/index.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/user_guide/install.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/user_guide/quickstart.po create mode 100644 docs/locale/zh_CN/LC_MESSAGES/user_guide/toc.po create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/_templates/language-switcher.html create mode 100644 docs/source/blog/auto_cpu_offload.md create mode 100644 docs/source/blog/auto_cuda_graph_design.md create mode 100644 docs/source/blog/refs/.gitkeep create mode 100644 docs/source/blog/toc.md create mode 100644 docs/source/blog/why_magi_depyf.md create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.md create mode 100644 docs/source/user_guide/install.md create mode 100644 docs/source/user_guide/quickstart.md create mode 100644 docs/source/user_guide/toc.md diff --git a/.github/workflows/check_chinese_chars.py b/.github/workflows/check_chinese_chars.py index 44bc410..7ca57fd 100644 --- a/.github/workflows/check_chinese_chars.py +++ b/.github/workflows/check_chinese_chars.py @@ -42,6 +42,8 @@ "]" ) +EXEMPT_DOCUMENT_NAMES: List[str] = ["docs/README_zh.md"] + BINARY_EXTENSIONS = frozenset( { ".png", @@ -130,7 +132,12 @@ def _check_diff(base_sha: str, head_sha: str) -> List[Tuple[str, int, str]]: if line.startswith("+"): line_num += 1 content = line[1:] - if current_file and not _is_binary(current_file) and CHINESE_CHAR_PATTERN.search(content): + if ( + current_file + and current_file not in EXEMPT_DOCUMENT_NAMES + and not _is_binary(current_file) + and CHINESE_CHAR_PATTERN.search(content) + ): findings.append((current_file, line_num, content)) elif not line.startswith("-"): line_num += 1 @@ -150,7 +157,7 @@ def _check_all_files() -> List[Tuple[str, int, str]]: findings: List[Tuple[str, int, str]] = [] for filepath in tracked: - if not filepath or _is_binary(filepath) or not os.path.isfile(filepath): + if not filepath or filepath in EXEMPT_DOCUMENT_NAMES or _is_binary(filepath) or not os.path.isfile(filepath): continue try: with open(filepath, encoding="utf-8", errors="ignore") as fh: diff --git a/.github/workflows/sphinx.yaml b/.github/workflows/sphinx.yaml new file mode 100644 index 0000000..7f90410 --- /dev/null +++ b/.github/workflows/sphinx.yaml @@ -0,0 +1,38 @@ +name: sphinx deploy + +on: + push: + branches: + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y rsync + cd docs + pip install -r requirements.txt + - name: Build docs + run: | + cd docs + make clean + # English at root (backward-compatible URLs) + DOCS_LANGUAGE=en sphinx-build -b html source/ build/html/ + # Chinese under zh_CN/ + DOCS_LANGUAGE=zh_CN sphinx-build -b html source/ build/html/zh_CN/ + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + if: ${{ github.event_name == 'push' }} + with: + branch: gh-pages + folder: docs/build/html + target-folder: docs/main diff --git a/.gitignore b/.gitignore index 28aff8f..765114b 100644 --- a/.gitignore +++ b/.gitignore @@ -79,6 +79,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/build/ # PyBuilder .pybuilder/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c2034ce --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,42 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build +LOCALEDIR = locale +GETTEXTDIR = $(BUILDDIR)/gettext + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +.PHONY: gettext update-po html-en html-zh html-multilang + +gettext: + @$(SPHINXBUILD) -M gettext "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +update-po: gettext + @sphinx-intl update -p "$(GETTEXTDIR)" -d "$(LOCALEDIR)" -l zh_CN + +# Multi-language docs layout: English lives at the site root ($(BUILDDIR)/html/), +# Chinese lives under $(BUILDDIR)/html/zh_CN/. This keeps single- and +# multi-language builds consistent with the language switcher and the CI deploy +# layout ("English at root, Chinese under zh_CN/"). +html-en: + @DOCS_LANGUAGE=en $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) + +html-zh: + @DOCS_LANGUAGE=zh_CN $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/zh_CN" $(SPHINXOPTS) $(O) + +html-multilang: html-en html-zh + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..246538c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,119 @@ +Chinese version: [`README_zh.md`](./README_zh.md) + +# MagiCompiler Documentation Guide + +This guide explains how to build, preview, and contribute to the MagiCompiler documentation. No prior Sphinx experience is required. + +## Prerequisites + +- Python 3.10+ +- `pip` (comes with Python) +- A terminal (bash, zsh, PowerShell, etc.) +- A text editor (VS Code, Vim, etc.) + +## Quick Start (5 minutes) + +```bash +# 1. Enter the docs directory +cd docs + +# 2. Install dependencies (one-time) +pip install -r requirements.txt + +# 3. Build the docs +make html + +# 4. Open in browser +open build/html/index.html # macOS +xdg-open build/html/index.html # Linux +start build/html/index.html # Windows (Git Bash) +``` + +That's it! You should see the documentation in your browser. + +> **Tip:** Run `make clean && make html` to force a full rebuild if you see stale content. + +--- + +## Directory Structure + +``` +docs/ +├── source/ # All documentation source files live here +│ ├── index.md # Homepage +│ ├── conf.py # Sphinx configuration (rarely need to edit) +│ ├── _static/ # Custom CSS, images referenced by docs +│ ├── _templates/ # HTML templates (e.g. language switcher) +│ ├── user_guide/ # User-facing guides +│ │ ├── toc.md # Table of contents for user guide section +│ │ ├── install.md # Installation guide +│ │ └── quickstart.md # Quick start guide +│ └── blog/ # Technical blog posts +│ ├── toc.md # Table of contents for blog section +│ └── refs/ # BibTeX citation files (one per blog post) +├── locale/ # Chinese translation files (.po) +│ └── zh_CN/LC_MESSAGES/ +├── build/ # Generated output (git-ignored) +├── requirements.txt # Python dependencies +├── Makefile # Build commands (Linux/macOS) +└── make.bat # Build commands (Windows) +``` + +--- + +## Build Commands + +| Command | Description | +|---------|-------------| +| `make html` | Build the English docs (default) | +| `make html-en` | Build the English docs into `build/html` (site root) | +| `make html-zh` | Build the Chinese docs into `build/html/zh_CN` | +| `make html-multilang` | Build both English and Chinese docs | +| `make update-po` | Regenerate `.po` translation templates | +| `make clean` | Remove the `build/` directory | + +--- + +## How to Write Documentation + +All documentation is written in **Markdown** using [MyST syntax](https://myst-parser.readthedocs.io/en/latest/), which extends standard Markdown with Sphinx-specific features. + +### Adding a New User Guide Page + +1. Create a new `.md` file in `source/user_guide/`. +2. Register its filename (without `.md`) in `source/user_guide/toc.md`. +3. Build and preview with `make clean && make html`. + +### Adding a New Blog Post + +1. Create `source/blog/my_topic.md` with a YAML frontmatter header + (`blogpost: true`, `date`, `author`, ...). +2. If it has citations, create `source/blog/refs/my_topic.bib` and add the + title to the `blog_titles` list in `source/conf.py`. +3. Register it in `source/blog/toc.md`. +4. Build and preview. + +--- + +## Bilingual Docs (English + Chinese) + +All documentation uses **English as the single source of truth**. Chinese +translations are managed via `.po` files following the standard Sphinx +internationalization (i18n) workflow. + +``` +source/*.md (English source, "single source of truth") + │ + ▼ make update-po +locale/zh_CN/LC_MESSAGES/*.po (Chinese translations) + │ + ▼ make html-multilang +build/html/ (English site, at the site root) +build/html/zh_CN/ (Chinese site, with a language switcher) +``` + +1. Edit the English `.md` sources under `source/` as usual. +2. Run `make update-po` to extract/refresh translation strings. +3. Translate the `msgstr` entries in `locale/zh_CN/LC_MESSAGES/*.po` + (leave the `msgid` untouched). +4. Run `make html-multilang` to build both languages. diff --git a/docs/README_zh.md b/docs/README_zh.md new file mode 100644 index 0000000..99ab5ef --- /dev/null +++ b/docs/README_zh.md @@ -0,0 +1,117 @@ +英文版本请见：[`README.md`](./README.md) + +# MagiCompiler 文档指南 + +本指南说明如何构建、预览和贡献 MagiCompiler 文档。无需任何 Sphinx 经验即可上手。 + +## 前置条件 + +- Python 3.10+ +- `pip`（Python 自带） +- 终端（bash、zsh、PowerShell 等均可） +- 文本编辑器（VS Code、Vim 等均可） + +## 快速上手（5 分钟） + +```bash +# 1. 进入 docs 目录 +cd docs + +# 2. 安装依赖（仅首次需要） +pip install -r requirements.txt + +# 3. 构建文档 +make html + +# 4. 在浏览器中打开 +open build/html/index.html # macOS +xdg-open build/html/index.html # Linux +start build/html/index.html # Windows (Git Bash) +``` + +完成！你应该能在浏览器中看到文档了。 + +> **提示：** 如果看到旧内容，运行 `make clean && make html` 强制全量重建。 + +--- + +## 目录结构 + +``` +docs/ +├── source/ # 所有文档源文件都在这里 +│ ├── index.md # 首页 +│ ├── conf.py # Sphinx 配置文件（一般不需要改） +│ ├── _static/ # 自定义 CSS、文档引用的图片 +│ ├── _templates/ # HTML 模板（如语言切换器） +│ ├── user_guide/ # 面向用户的指南 +│ │ ├── toc.md # 用户指南章节的目录 +│ │ ├── install.md # 安装指南 +│ │ └── quickstart.md # 快速开始 +│ └── blog/ # 技术博客文章 +│ ├── toc.md # 博客章节的目录 +│ └── refs/ # BibTeX 引用文件（每篇博客一个） +├── locale/ # 中文翻译文件（.po） +│ └── zh_CN/LC_MESSAGES/ +├── build/ # 生成的输出（已被 git 忽略） +├── requirements.txt # Python 依赖 +├── Makefile # 构建命令（Linux/macOS） +└── make.bat # 构建命令（Windows） +``` + +--- + +## 构建命令 + +| 命令 | 说明 | +|------|------| +| `make html` | 构建英文文档（默认） | +| `make html-en` | 构建英文文档到 `build/html`（站点根目录） | +| `make html-zh` | 构建中文文档到 `build/html/zh_CN` | +| `make html-multilang` | 同时构建英文和中文文档 | +| `make update-po` | 重新生成 `.po` 翻译模板 | +| `make clean` | 删除 `build/` 目录 | + +--- + +## 如何编写文档 + +所有文档都使用 **Markdown** 编写，采用 [MyST 语法](https://myst-parser.readthedocs.io/en/latest/)——它在标准 Markdown 基础上扩展了 Sphinx 特有的功能。 + +### 新增一篇用户指南 + +1. 在 `source/user_guide/` 下创建一个新的 `.md` 文件。 +2. 在 `source/user_guide/toc.md` 中注册其文件名（不含 `.md`）。 +3. 用 `make clean && make html` 构建并预览。 + +### 新增一篇博客文章 + +1. 创建带 YAML frontmatter 头部（`blogpost: true`、`date`、`author` 等）的 + `source/blog/my_topic.md`。 +2. 如果包含引用文献，创建 `source/blog/refs/my_topic.bib`，并在 + `source/conf.py` 的 `blog_titles` 列表中添加该标题。 +3. 在 `source/blog/toc.md` 中注册。 +4. 构建并预览。 + +--- + +## 中英文双语文档 + +所有文档以**英文为主源**，中文翻译通过 `.po` 文件管理，遵循标准的 Sphinx 国际化（i18n）工作流。 + +``` +source/*.md（英文源文件，"唯一真相源"） + │ + ▼ make update-po +locale/zh_CN/LC_MESSAGES/*.po（中文翻译） + │ + ▼ make html-multilang +build/html/ （英文站点，位于站点根目录） +build/html/zh_CN/ （中文站点，带语言切换器） +``` + +1. 照常编辑 `source/` 下的英文 `.md` 源文件。 +2. 运行 `make update-po` 提取/刷新翻译字符串。 +3. 在 `locale/zh_CN/LC_MESSAGES/*.po` 中翻译 `msgstr` 条目 + （不要修改 `msgid`）。 +4. 运行 `make html-multilang` 同时构建两种语言。 diff --git a/docs/locale/zh_CN/LC_MESSAGES/blog/auto_cpu_offload.po b/docs/locale/zh_CN/LC_MESSAGES/blog/auto_cpu_offload.po new file mode 100644 index 0000000..e5f3367 --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/blog/auto_cpu_offload.po @@ -0,0 +1,298 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/blog/auto_cpu_offload.md:9 +msgid "Analysis of Automatic Offloading" +msgstr "自动 Offloading 解析" + +#: ../../source/blog/auto_cpu_offload.md:11 +msgid "" +"When training or inferencing ultra-large models, GPU memory capacity is " +"the primary bottleneck. The standard industry solution is " +"Offloading—moving a portion of model weights to the CPU and dynamically " +"Prefetching them back to the GPU just before computation." +msgstr "" +"在训练或推理超大模型时，GPU 显存容量是首要瓶颈。业界标准的解决方案是 Offloading——" +"将一部分模型权重转移到 CPU，并在计算前动态地将它们预取（Prefetch）回 GPU。" + +#: ../../source/blog/auto_cpu_offload.md:13 +msgid "" +"However, the emergence of high-computational-efficiency models, such as " +"[daVinci-MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman) base " +"256p, poses a challenge to traditional offload strategies. Because these " +"models execute operators extremely quickly, the ``Overlap Window`` left " +"for PCIe data transfer is exceptionally short. If prefetching is not " +"precise, the GPU frequently enters a ``starvation`` state while waiting " +"for data, resulting in significant pipeline bubbles." +msgstr "" +"然而，[daVinci-MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman) base " +"256p 这类高计算效率模型的出现，对传统 offload 策略提出了挑战。由于这些模型的算子执行" +"极快，留给 PCIe 数据传输的``重叠窗口``异常短暂。如果预取不够精准，GPU 会频繁进入等待数据的" +"``饥饿``状态，从而产生显著的流水线气泡。" + +#: ../../source/blog/auto_cpu_offload.md:15 +msgid "Base Offload Profile" +msgstr "基础 Offload Profile" + +#: ../../source/blog/auto_cpu_offload.md:20 +msgid "Heuristic Offload Profile" +msgstr "启发式 Offload Profile" + +#: ../../source/blog/auto_cpu_offload.md:25 +msgid "" +"*Left: Base Offload with noticeable GPU starvation (bubbles). Right: " +"Heuristic Offload eliminating pipeline bubbles and accelerating daVinci-" +"MagiHuman.*" +msgstr "" +"*左：基础 Offload，存在明显的 GPU 饥饿（气泡）。右：启发式 Offload，消除了流水线气泡并" +"加速了 daVinci-MagiHuman。*" + +#: ../../source/blog/auto_cpu_offload.md:27 +msgid "" +"This article dives into the core source code of MagiCompiler " +"([api.py](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/api.py), " +"[offload_wrapper.py](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py), and" +" [scheduler.py](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/scheduler.py)) to " +"deconstruct how it achieves deep overlap between computation and " +"transmission." +msgstr "" +"本文深入 MagiCompiler 的核心源码（[api.py](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/api.py)、" +"[offload_wrapper.py](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py) 与" +" [scheduler.py](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/scheduler.py)），" +"剖析它如何实现计算与传输之间的深度重叠。" + +#: ../../source/blog/auto_cpu_offload.md:29 +msgid "Architectural Overview: Graph-Based Asynchronous Pipeline" +msgstr "架构概览：基于图的异步流水线" + +#: ../../source/blog/auto_cpu_offload.md:30 +msgid "" +"MagiCompiler's Offload mechanism is built upon the torch.fx graph mode. " +"Its core logic involves using an independent CUDA Stream to pull weights " +"for subsequent modules while the current submodule is still computing." +msgstr "" +"MagiCompiler 的 Offload 机制构建在 torch.fx 图模式之上。其核心逻辑是：在当前子模块" +"仍在计算时，使用一条独立的 CUDA Stream 为后续模块拉取权重。" + +#: ../../source/blog/auto_cpu_offload.md:32 +msgid "" +"[OffloadExecutor](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py) / " +"[OffloadWrapper](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py): " +"Responsible for operator graph parsing, memory lifecycle management, and " +"execution flow scheduling." +msgstr "" +"[OffloadExecutor](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py) / " +"[OffloadWrapper](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py)：" +"负责算子图解析、内存生命周期管理与执行流调度。" + +#: ../../source/blog/auto_cpu_offload.md:33 +msgid "" +"[OffloadScheduler](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/scheduler.py): The core " +"strategy layer that determines the residency priority of weights and the " +"precise timing of prefetch triggers." +msgstr "" +"[OffloadScheduler](https://github.com/SandAI-" +"org/MagiCompiler/blob/main/magi_compiler/offload/scheduler.py)：核心策略层，" +"决定权重的驻留优先级以及预取触发的精确时机。" + +#: ../../source/blog/auto_cpu_offload.md:35 +msgid "Low-Level Optimization: Shared & Pinned Memory" +msgstr "底层优化：共享内存与锁页内存" + +#: ../../source/blog/auto_cpu_offload.md:36 +msgid "" +"Efficient data movement relies on low-level physical memory optimization." +" During the compilation phase, MagiCompiler implements two critical " +"configurations for CPU Offload:" +msgstr "" +"高效的数据搬运依赖底层的物理内存优化。在编译阶段，MagiCompiler 为 CPU Offload " +"实现了两项关键配置：" + +#: ../../source/blog/auto_cpu_offload.md:37 +msgid "" +"Distributed Shared Memory: When [model_cpu_offload](https://github.com" +"/SandAI-org/MagiCompiler/blob/main/magi_compiler/config.py) is enabled, " +"all weights are reused within contiguous memory blocks via " +"[torch.from_file(shared=True)](https://docs.pytorch.org/docs/stable/generated/torch.from_file.html)." +" This effectively reduces CPU overhead and memory fragmentation in multi-" +"GPU environments." +msgstr "" +"分布式共享内存：当启用 [model_cpu_offload](https://github.com" +"/SandAI-org/MagiCompiler/blob/main/magi_compiler/config.py) 时，" +"所有权重通过 " +"[torch.from_file(shared=True)](https://docs.pytorch.org/docs/stable/generated/torch.from_file.html) " +"在连续内存块中复用。这有效降低了多 GPU 环境下的 CPU 开销与内存碎片。" + +#: ../../source/blog/auto_cpu_offload.md:38 +msgid "" +"Pinned Memory: By using pin_memory_in_place, weights are forced to reside" +" in non-pageable physical memory. This is the foundation for maximizing " +"PCIe bandwidth utilization and achieving high-speed Host-to-Device (H2D) " +"transfers." +msgstr "" +"锁页内存：通过 pin_memory_in_place，权重被强制驻留在不可分页的物理内存中。" +"这是最大化 PCIe 带宽利用率、实现高速主机到设备（H2D）传输的基础。" + +#: ../../source/blog/auto_cpu_offload.md:40 +msgid "Operational Mechanism: Fine-Grained Executor Control" +msgstr "运行机制：细粒度的执行器控制" + +#: ../../source/blog/auto_cpu_offload.md:41 +msgid "" +"Graph Analysis: _analyze_graph pre-traverses the torch.fx.GraphModule to " +"calculate reference counts (user_counts) for each node, providing the " +"basis for ``use-and-discard`` memory release." +msgstr "" +"图分析：_analyze_graph 预先遍历 torch.fx.GraphModule，为每个节点计算引用计数" +"（user_counts），为``用完即弃``的内存释放提供依据。" + +#: ../../source/blog/auto_cpu_offload.md:42 +msgid "" +"Profiling: During the initial runs, the OffloadProfiler measures the " +"computation time and H2D bandwidth for each submodule. Once warming up " +"concludes, _finalize_warmup() feeds this empirical data into the " +"scheduler to generate a static optimal strategy." +msgstr "" +"Profiling：在最初的几次运行中，OffloadProfiler 测量每个子模块的计算时间与 H2D 带宽。" +"预热结束后，_finalize_warmup() 将这些经验数据喂给调度器，生成静态的最优策略。" + +#: ../../source/blog/auto_cpu_offload.md:43 +msgid "" +"Dynamic Memory Management: Asynchronous prefetching is triggered before " +"call_module. Immediately after execution, tensors are cleared from the " +"environment based on reference counts, utilizing record_stream to ensure " +"the memory is physically released only when safe." +msgstr "" +"动态内存管理：异步预取在 call_module 之前触发。执行结束后，立即根据引用计数从环境中" +"清除张量，并借助 record_stream 确保内存只在安全时才被物理释放。" + +#: ../../source/blog/auto_cpu_offload.md:45 +msgid "Scheduling Strategies: Heuristics for High-Speed Models (scheduler.py)" +msgstr "调度策略：面向高速模型的启发式方法（scheduler.py）" + +#: ../../source/blog/auto_cpu_offload.md:46 +msgid "" +"To handle fast-paced models like [daVinci-MagiHuman](https://github.com" +"/GAIR-NLP/daVinci-MagiHuman), MagiCompiler offers three evolving " +"schedulers:" +msgstr "" +"为应对 [daVinci-MagiHuman](https://github.com" +"/GAIR-NLP/daVinci-MagiHuman) 这类快节奏模型，MagiCompiler 提供了三种逐步演进的调度器：" + +#: ../../source/blog/auto_cpu_offload.md:48 +msgid "" +"**BaseScheduler**: A basic look-ahead strategy that prefetches only 1–2 " +"modules in advance. In scenarios with long sequences or fast operators, " +"this simple approach often fails to cover the transmission latency." +msgstr "" +"**BaseScheduler**：一种基础的前瞻策略，仅提前预取 1–2 个模块。在长序列或快速算子的场景下，" +"这种简单方法往往无法覆盖传输延迟。" + +#: ../../source/blog/auto_cpu_offload.md:50 +msgid "" +"**CostEffectiveScheduler**: This strategy corrects the intuitive error of" +" prioritizing ``long-computation operators.`` It identifies that modules " +"with massive weight volumes but lightning-fast computation are the " +"primary source of bubbles. Consequently, it allocates the limited GPU " +"residency quota to these ``transfer-heavy, compute-light`` modules." +msgstr "" +"**CostEffectiveScheduler**：该策略纠正了优先照顾``长计算算子``的直觉误区。" +"它识别出：权重体量巨大但计算极快的模块才是气泡的主要来源。因此，它把有限的 GPU 驻留配额" +"分配给这些``传输重、计算轻``的模块。" + +#: ../../source/blog/auto_cpu_offload.md:52 +msgid "**HeuristicScheduler**：" +msgstr "**HeuristicScheduler**：" + +#: ../../source/blog/auto_cpu_offload.md:54 +msgid "Heuristic Offload" +msgstr "启发式 Offload" + +#: ../../source/blog/auto_cpu_offload.md:60 +msgid "" +"JIT (Just-In-Time) Latest Loading: The most advanced solution, " +"introducing a mechanism. It uses profiling data to reverse-calculate the " +"exact start time for transmission, ensuring weights arrive at the GPU at " +"the ``last possible second`` before computation. This prevents memory " +"bloat from queued weights and compresses peak memory usage to its " +"theoretical minimum." +msgstr "" +"JIT（Just-In-Time）最晚加载：最先进的方案。它利用 profiling 数据反推出传输的精确开始时刻，" +"确保权重在计算前的``最后一刻``抵达 GPU。这避免了排队权重造成的内存膨胀，" +"并将峰值内存占用压缩到理论最小值。" + +#: ../../source/blog/auto_cpu_offload.md:61 +msgid "" +"Weight Residency Optimization: If residual GPU memory is detected (based " +"on the gpu_resident_weight_ratio), it will designate specific weights to " +"remain resident on the GPU, thereby alleviating pressure on the PCIe " +"bandwidth." +msgstr "" +"权重驻留优化：若检测到有剩余 GPU 显存（依据 gpu_resident_weight_ratio），" +"它会指定特定权重常驻 GPU，从而缓解 PCIe 带宽的压力。" + +#: ../../source/blog/auto_cpu_offload.md:63 +msgid "Performance: Zero-Bubble Experience on RTX 5090" +msgstr "性能：RTX 5090 上的零气泡体验" + +#: ../../source/blog/auto_cpu_offload.md:64 +msgid "" +"In an RTX 5090 environment using a CP4 parallel strategy for a 10-second " +"long-video generation inference test with [daVinci-" +"MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman) base 256p:" +msgstr "" +"在 RTX 5090 环境下，采用 CP4 并行策略，使用 [daVinci-" +"MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman) base 256p 进行 10 秒" +"长视频生成推理测试：" + +#: ../../source/blog/auto_cpu_offload.md:66 +#, python-format +msgid "" +"By setting gpu_resident_weight_ratio to 35%, the system allocates this " +"``prime`` GPU memory to large-volume, fast-computation operators. The " +"remaining 65% of weights are managed via the HeuristicScheduler for " +"precise JIT prefetching." +msgstr "" +"通过将 gpu_resident_weight_ratio 设为 35%，系统把这块``黄金``GPU 显存分配给" +"大体量、快计算的算子。剩余 65% 的权重则由 HeuristicScheduler 管理，进行精确的 JIT 预取。" + +#: ../../source/blog/auto_cpu_offload.md:68 +msgid "" +"The Result: The 10s video inference process achieved complete overlap " +"between H2D communication and computation. Despite the extremely high " +"operator throughput, the GPU remained fully utilized with zero pipeline " +"bubbles, reaching the theoretical limits of both memory efficiency and " +"system throughput." +msgstr "" +"结果：这段 10 秒的视频推理过程实现了 H2D 通信与计算的完全重叠。尽管算子吞吐极高，" +"GPU 仍保持满负荷运转、零流水线气泡，同时达到了内存效率与系统吞吐的理论极限。" diff --git a/docs/locale/zh_CN/LC_MESSAGES/blog/auto_cuda_graph_design.po b/docs/locale/zh_CN/LC_MESSAGES/blog/auto_cuda_graph_design.po new file mode 100644 index 0000000..2fe1a7e --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/blog/auto_cuda_graph_design.po @@ -0,0 +1,355 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/blog/auto_cuda_graph_design.md:9 +msgid "AutoCudaGraph Design" +msgstr "AutoCudaGraph 设计" + +#: ../../source/blog/auto_cuda_graph_design.md:11 +msgid "Overview" +msgstr "概览" + +#: ../../source/blog/auto_cuda_graph_design.md:12 +msgid "" +"AutoCudaGraph is a CUDA Graph optimization module integrated into the " +"MagiCompiler framework, designed to automate CUDA Graph capture, caching," +" replay, and tensor memory management for PyTorch-based neural network " +"inference. It targets Transformer architectures with dynamic sequence " +"lengths, optimizing kernel execution by reusing pre-captured computation " +"graphs and static tensor buffers. Core Goals:" +msgstr "" +"AutoCudaGraph 是集成在 MagiCompiler 框架中的 CUDA Graph 优化模块，旨在为基于 PyTorch 的" +"神经网络推理自动完成 CUDA Graph 的捕获、缓存、回放与张量内存管理。它面向具有动态序列长度的" +" Transformer 架构，通过复用预先捕获的计算图与静态张量缓冲区来优化 kernel 执行。核心目标：" + +#: ../../source/blog/auto_cuda_graph_design.md:13 +msgid "" +"Automate CUDA Graph lifecycle (capture/replay/cache) with minimal code " +"intrusion" +msgstr "" +"以最小的代码侵入自动化 CUDA Graph 生命周期（捕获/回放/缓存）" + +#: ../../source/blog/auto_cuda_graph_design.md:14 +msgid "Support dynamic shape adaptation (sequence length expansion)" +msgstr "支持动态 shape 适配（序列长度扩展）" + +#: ../../source/blog/auto_cuda_graph_design.md:15 +msgid "Optimize memory efficiency via global memory pool and static tensor reuse" +msgstr "通过全局内存池与静态张量复用优化内存效率" + +#: ../../source/blog/auto_cuda_graph_design.md:16 +msgid "Ensure consistency between cached graphs and runtime inputs/outputs" +msgstr "确保缓存图与运行时输入/输出之间的一致性" + +#: ../../source/blog/auto_cuda_graph_design.md:18 +msgid "Key Components" +msgstr "关键组件" + +#: ../../source/blog/auto_cuda_graph_design.md:20 +msgid "CudaGraphMgr (Core Manager)" +msgstr "CudaGraphMgr（核心管理器）" + +#: ../../source/blog/auto_cuda_graph_design.md:21 +msgid "Singleton class managing all CUDA Graph operations:" +msgstr "管理所有 CUDA Graph 操作的单例类：" + +#: ../../source/blog/auto_cuda_graph_design.md:29 +msgid "**Core Methods**" +msgstr "**核心方法**" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "Method" +msgstr "方法" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "Purpose" +msgstr "用途" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "run()" +msgstr "run()" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "Main entry: Replay cached graph or warm up & capture new graph" +msgstr "主入口：回放缓存图，或预热并捕获新图" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "wrapped_graph_capture()" +msgstr "wrapped_graph_capture()" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "Capture CUDA Graph with sliced static input/output tensors" +msgstr "使用切片后的静态输入/输出张量捕获 CUDA Graph" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "wrapped_graph_replay()" +msgstr "wrapped_graph_replay()" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "" +"Replay cached CUDA Graph with sliced static tensors and output template " +"wrapping" +msgstr "" +"使用切片后的静态张量回放缓存的 CUDA Graph，并进行输出模板包装" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "get_expanded_static_tensors()" +msgstr "get_expanded_static_tensors()" + +#: ../../source/blog/auto_cuda_graph_design.md +msgid "Expand static tensors, reuse buffers if dimensionally compatible" +msgstr "扩展静态张量，在维度兼容时复用缓冲区" + +#: ../../source/blog/auto_cuda_graph_design.md:37 +msgid "Signature System" +msgstr "签名系统" + +#: ../../source/blog/auto_cuda_graph_design.md:39 +msgid "StaticSignature" +msgstr "StaticSignature" + +#: ../../source/blog/auto_cuda_graph_design.md:46 +msgid "Encodes fixed properties of input tensors (dtype, static dimensions)" +msgstr "编码输入张量的固定属性（dtype、静态维度）" + +#: ../../source/blog/auto_cuda_graph_design.md:47 +msgid "Used as primary key for static tensor buffer caching" +msgstr "作为静态张量缓冲区缓存的主键" + +#: ../../source/blog/auto_cuda_graph_design.md:49 +msgid "DynamicSignature" +msgstr "DynamicSignature" + +#: ../../source/blog/auto_cuda_graph_design.md:56 +msgid "Tracks dynamic dimensions (sequence length) and literal parameters" +msgstr "追踪动态维度（序列长度）与字面量参数" + +#: ../../source/blog/auto_cuda_graph_design.md:57 +msgid "Secondary key for graph entry lookup" +msgstr "图条目查找的次级键" + +#: ../../source/blog/auto_cuda_graph_design.md:59 +msgid "Tensor Management" +msgstr "张量管理" + +#: ../../source/blog/auto_cuda_graph_design.md:67 +msgid "" +"Memory Reuse: Reuse existing tensor buffers when possible to avoid " +"reallocation" +msgstr "" +"内存复用：尽可能复用已有的张量缓冲区，避免重新分配" + +#: ../../source/blog/auto_cuda_graph_design.md:68 +msgid "" +"Dynamic Expansion: Only expand static tensors when new input dimensions " +"exceed current buffer size" +msgstr "" +"动态扩展：仅当新的输入维度超过当前缓冲区大小时才扩展静态张量" + +#: ../../source/blog/auto_cuda_graph_design.md:69 +msgid "" +"Shape Validation: Ensure static dimensions (non-sequence) match between " +"cached and new tensors" +msgstr "" +"Shape 校验：确保缓存张量与新张量之间的静态维度（非序列维度）一致" + +#: ../../source/blog/auto_cuda_graph_design.md:71 +msgid "Graph Management" +msgstr "图管理" + +#: ../../source/blog/auto_cuda_graph_design.md:84 +msgid "" +"Graph State Tracking: GraphEntry tracks CUDA Graph instances and validity" +" states to control replay eligibility." +msgstr "" +"图状态追踪：GraphEntry 追踪 CUDA Graph 实例及其有效性状态，以控制是否允许回放。" + +#: ../../source/blog/auto_cuda_graph_design.md:85 +msgid "" +"Layer-wise Organization: OutputTemplateEntry maps dynamic signatures to " +"per-layer GraphEntry for layer-specific graph reuse." +msgstr "" +"分层组织：OutputTemplateEntry 将动态签名映射到各层的 GraphEntry，实现按层的图复用。" + +#: ../../source/blog/auto_cuda_graph_design.md:86 +msgid "" +"Output Consistency: output_template preserves output object structure to " +"ensure consistent result wrapping during replay." +msgstr "" +"输出一致性：output_template 保留输出对象结构，确保回放时结果包装的一致性。" + +#: ../../source/blog/auto_cuda_graph_design.md:88 +msgid "Execution Flow" +msgstr "执行流程" + +#: ../../source/blog/auto_cuda_graph_design.md:89 +msgid "Inline Replay (Fast Path)" +msgstr "内联回放（快路径）" + +#: ../../source/blog/auto_cuda_graph_design.md:90 +msgid "Extract input signatures from runtime arguments" +msgstr "从运行时参数中提取输入签名" + +#: ../../source/blog/auto_cuda_graph_design.md:91 +msgid "" +"Look up cached CUDA Graph via StaticSignature + DynamicSignature + layer " +"number" +msgstr "" +"通过 StaticSignature + DynamicSignature + 层号查找缓存的 CUDA Graph" + +#: ../../source/blog/auto_cuda_graph_design.md:92 +msgid "Validate graph consistency (not inconsistent/invalid)" +msgstr "校验图的一致性（非 inconsistent/invalid）" + +#: ../../source/blog/auto_cuda_graph_design.md:93 +msgid "Reuse static tensors with dynamic slicing" +msgstr "通过动态切片复用静态张量" + +#: ../../source/blog/auto_cuda_graph_design.md:94 +msgid "Replay graph and return sliced output" +msgstr "回放图并返回切片后的输出" + +#: ../../source/blog/auto_cuda_graph_design.md:95 +msgid "Graph Capture (Slow Path)" +msgstr "图捕获（慢路径）" + +#: ../../source/blog/auto_cuda_graph_design.md:96 +msgid "Triggered when no valid cached graph exists or tensor expansion is needed:" +msgstr "当不存在有效的缓存图，或需要扩展张量时触发：" + +#: ../../source/blog/auto_cuda_graph_design.md:97 +msgid "Execute function to get output tensors" +msgstr "执行函数以获得输出张量" + +#: ../../source/blog/auto_cuda_graph_design.md:98 +msgid "Ensure input signatures match post-warmup" +msgstr "确保预热后输入签名匹配" + +#: ../../source/blog/auto_cuda_graph_design.md:99 +msgid "Expand static buffers if new shapes require it" +msgstr "若新 shape 需要则扩展静态缓冲区" + +#: ../../source/blog/auto_cuda_graph_design.md:100 +msgid "Capture new CUDA Graph with static tensors" +msgstr "使用静态张量捕获新的 CUDA Graph" + +#: ../../source/blog/auto_cuda_graph_design.md:101 +msgid "Store new graph and update tensor entries" +msgstr "存储新图并更新张量条目" + +#: ../../source/blog/auto_cuda_graph_design.md:102 +msgid "Return warmup execution output as final result" +msgstr "将预热执行的输出作为最终结果返回" + +#: ../../source/blog/auto_cuda_graph_design.md:103 +msgid "Sequence Length Handling" +msgstr "序列长度处理" + +#: ../../source/blog/auto_cuda_graph_design.md:104 +msgid "Only last dimension is static for ND tensors (ND > 1)" +msgstr "对于 ND 张量（ND > 1），仅最后一维为静态" + +#: ../../source/blog/auto_cuda_graph_design.md:105 +msgid "All dimension is dynamic for 1D tensors (ND=1)" +msgstr "对于 1D 张量（ND=1），所有维度均为动态" + +#: ../../source/blog/auto_cuda_graph_design.md:106 +msgid "Automatic buffer expansion for increasing sequence lengths" +msgstr "随序列长度增长自动扩展缓冲区" + +#: ../../source/blog/auto_cuda_graph_design.md:107 +msgid "Invalidates old graphs when tensors are expanded" +msgstr "当张量被扩展时使旧图失效" + +#: ../../source/blog/auto_cuda_graph_design.md:109 +msgid "Examples" +msgstr "示例" + +#: ../../source/blog/auto_cuda_graph_design.md:154 +msgid "Limitations and Constraints" +msgstr "局限与约束" + +#: ../../source/blog/auto_cuda_graph_design.md:155 +msgid "No support for data-dependent control flow in captured functions" +msgstr "不支持被捕获函数中依赖数据的控制流" + +#: ../../source/blog/auto_cuda_graph_design.md:156 +msgid "Graph capture fails if function contains CPU/GPU synchronization" +msgstr "若函数包含 CPU/GPU 同步，图捕获会失败" + +#: ../../source/blog/auto_cuda_graph_design.md:157 +msgid "Only supports CUDA tensors (CPU tensors trigger fallback)" +msgstr "仅支持 CUDA 张量（CPU 张量会触发回退）" + +#: ../../source/blog/auto_cuda_graph_design.md:158 +msgid "Custom input classes must inherit from InplaceSubstituteFakeClass" +msgstr "自定义输入类必须继承自 InplaceSubstituteFakeClass" + +#: ../../source/blog/auto_cuda_graph_design.md:159 +msgid "" +"Assumes input tensors of captured graphs are not reused externally (risk " +"of cross-scenario static tensor reuse)" +msgstr "" +"假设被捕获图的输入张量不会在外部被复用（存在跨场景静态张量复用的风险）" + +#: ../../source/blog/auto_cuda_graph_design.md:160 +msgid "" +"Relies on identical function, input tensors shapes, and constants for " +"valid graph reuse" +msgstr "" +"依赖相同的函数、输入张量 shape 与常量才能有效复用图" + +#: ../../source/blog/auto_cuda_graph_design.md:161 +msgid "No support for multi-stream execution scenarios" +msgstr "不支持多 stream 执行场景" + +#: ../../source/blog/auto_cuda_graph_design.md:163 +msgid "Best Practices" +msgstr "最佳实践" + +#: ../../source/blog/auto_cuda_graph_design.md:164 +msgid "" +"Dynamic Dimensions: Tensor use sequence length as dimension 0 where " +"possible" +msgstr "" +"动态维度：尽可能让张量以序列长度作为第 0 维" + +#: ../../source/blog/auto_cuda_graph_design.md:165 +msgid "" +"Monitor Memory Usage: Track graph_mem_pool_size and tensor_mem_size to " +"avoid OOM" +msgstr "" +"监控内存占用：追踪 graph_mem_pool_size 与 tensor_mem_size 以避免 OOM" + +#: ../../source/blog/auto_cuda_graph_design.md:166 +msgid "" +"Specify Layer IDs: Use layer_number to distinguish graphs across " +"different models/layers" +msgstr "" +"指定层 ID：使用 layer_number 区分不同模型/层的图" + +#: ../../source/blog/auto_cuda_graph_design.md:167 +msgid "" +"LRU Cache (Future): Implement cache eviction to limit total graph/tensor " +"count" +msgstr "" +"LRU 缓存（未来）：实现缓存淘汰以限制图/张量的总数量" diff --git a/docs/locale/zh_CN/LC_MESSAGES/blog/toc.po b/docs/locale/zh_CN/LC_MESSAGES/blog/toc.po new file mode 100644 index 0000000..c06f5d1 --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/blog/toc.po @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/blog/toc.md:1 ../../source/blog/toc.md:7 +msgid "Blogs" +msgstr "博客" diff --git a/docs/locale/zh_CN/LC_MESSAGES/blog/why_magi_depyf.po b/docs/locale/zh_CN/LC_MESSAGES/blog/why_magi_depyf.po new file mode 100644 index 0000000..50ba15f --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/blog/why_magi_depyf.po @@ -0,0 +1,379 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/blog/why_magi_depyf.md:9 +msgid "Why magi_depyf" +msgstr "为什么需要 magi_depyf" + +#: ../../source/blog/why_magi_depyf.md:11 +msgid "" +"`magi_depyf` is the compilation observability layer for `MagiCompiler`. " +"It answers three practical questions:" +msgstr "" +"`magi_depyf` 是 `MagiCompiler` 的编译可观测性层。它回答三个实际问题：" + +#: ../../source/blog/why_magi_depyf.md:14 +msgid "**What exactly happened during compilation?**" +msgstr "**编译过程中究竟发生了什么？**" + +#: ../../source/blog/why_magi_depyf.md:15 +msgid "" +"**Did the outcome match expectations?** (for example: graph split shape, " +"cache reuse, retry behavior)" +msgstr "" +"**结果是否符合预期？**（例如：图切分形状、缓存复用、重试行为）" + +#: ../../source/blog/why_magi_depyf.md:16 +msgid "**If something failed, where should I look first?**" +msgstr "**如果出错了，我应该先看哪里？**" + +#: ../../source/blog/why_magi_depyf.md:20 +msgid "1. Positioning: Built-in observability for MagiCompiler" +msgstr "1. 定位：MagiCompiler 的内建可观测性" + +#: ../../source/blog/why_magi_depyf.md:22 +msgid "" +"In a real MagiCompiler pipeline, compilation spans multiple stages: " +"Dynamo capture, Magi backend graph transforms/splitting, Inductor " +"codegen, and AOT/JIT reuse. Plain logs are often not enough to reliably " +"answer:" +msgstr "" +"在真实的 MagiCompiler 流水线中，编译跨越多个阶段：Dynamo 捕获、Magi 后端图变换/" +"切分、Inductor 代码生成，以及 AOT/JIT 复用。仅靠普通日志往往难以可靠地回答：" + +#: ../../source/blog/why_magi_depyf.md:25 +msgid "Did the failure happen at full-graph level or in a specific subgraph?" +msgstr "失败发生在全图层面，还是某个具体的子图中？" + +#: ../../source/blog/why_magi_depyf.md:26 +msgid "Did a pass change graph behavior unexpectedly?" +msgstr "某个 pass 是否意外改变了图的行为？" + +#: ../../source/blog/why_magi_depyf.md:27 +msgid "Why did this run miss cache?" +msgstr "这次运行为什么没有命中缓存？" + +#: ../../source/blog/why_magi_depyf.md:29 +msgid "" +"`magi_depyf` writes these signals as structured events and artifacts on " +"disk, so you can replay, compare, and debug deterministically." +msgstr "" +"`magi_depyf` 将这些信号以结构化的事件与产物形式写入磁盘，让你可以确定性地回放、" +"对比与调试。" + +#: ../../source/blog/why_magi_depyf.md:33 +msgid "2. Primary scenario: `magi_compile`" +msgstr "2. 主要场景：`magi_compile`" + +#: ../../source/blog/why_magi_depyf.md:35 +msgid "2.1 Recommended usage model" +msgstr "2.1 推荐的使用方式" + +#: ../../source/blog/why_magi_depyf.md:37 +msgid "" +"For `magi_compile` users, `magi_depyf` is most useful as a built-in " +"observability layer:" +msgstr "" +"对于 `magi_compile` 用户，`magi_depyf` 作为内建可观测性层最为实用：" + +#: ../../source/blog/why_magi_depyf.md:39 +msgid "Streams events to `timeline_events/timeline.jsonl` during compilation" +msgstr "在编译期间将事件流式写入 `timeline_events/timeline.jsonl`" + +#: ../../source/blog/why_magi_depyf.md:40 +msgid "Writes event artifacts under `timeline_events/files/`" +msgstr "将事件产物写入 `timeline_events/files/` 目录" + +#: ../../source/blog/why_magi_depyf.md:41 +msgid "Exports a structured `compiled_functions/` artifact tree" +msgstr "导出结构化的 `compiled_functions/` 产物树" + +#: ../../source/blog/why_magi_depyf.md:43 +msgid "" +"In most cases, you do not need to manually wire custom hooks. Run through" +" the MagiCompiler path and inspect the output directory." +msgstr "" +"大多数情况下你无需手动挂接自定义 hook。走完整的 MagiCompiler 路径，然后查看输出目录即可。" + +#: ../../source/blog/why_magi_depyf.md:45 +msgid "2.2 What you get automatically in the Magi compile path" +msgstr "2.2 在 Magi 编译路径下你会自动获得什么" + +#: ../../source/blog/why_magi_depyf.md:47 +msgid "" +"For the `magi_compile` scenario, you do **not** need to call " +"`explain_compilation` manually. As long as the model runs through " +"MagiCompiler, `magi_depyf` outputs are written automatically." +msgstr "" +"在 `magi_compile` 场景下，你**无需**手动调用 `explain_compilation`。" +"只要模型走完 MagiCompiler 路径，`magi_depyf` 的输出就会被自动写入。" + +#: ../../source/blog/why_magi_depyf.md:50 +msgid "For example, one real run produced:" +msgstr "例如，某次真实运行产生了：" + +#: ../../source/blog/why_magi_depyf.md:52 +msgid "`magi_depyf_torch_compile_debug/magi_depyf/run_20260322_192147/model_1_TwoLayerTransformer_rank_0/timeline_events`" +msgstr "`magi_depyf_torch_compile_debug/magi_depyf/run_20260322_192147/model_1_TwoLayerTransformer_rank_0/timeline_events`" + +#: ../../source/blog/why_magi_depyf.md:54 +msgid "In general, the output pattern is:" +msgstr "一般来说，输出的目录模式为：" + +#: ../../source/blog/why_magi_depyf.md:56 +msgid "`/magi_depyf/run_*/model_*_rank_*/timeline_events/`" +msgstr "`/magi_depyf/run_*/model_*_rank_*/timeline_events/`" + +#: ../../source/blog/why_magi_depyf.md:58 +msgid "Key artifacts under this directory:" +msgstr "该目录下的关键产物：" + +#: ../../source/blog/why_magi_depyf.md:60 +msgid "`timeline.jsonl`: streaming event log written during compilation" +msgstr "`timeline.jsonl`：编译期间写入的流式事件日志" + +#: ../../source/blog/why_magi_depyf.md:61 +msgid "`files/0000_*`, `files/0001_*`, ... event folders with attached artifacts" +msgstr "`files/0000_*`、`files/0001_*`、…… 带附属产物的事件文件夹" + +#: ../../source/blog/why_magi_depyf.md:62 +msgid "`files/*/attributes.json`: structured metadata for each event folder" +msgstr "`files/*/attributes.json`：每个事件文件夹的结构化元数据" + +#: ../../source/blog/why_magi_depyf.md:64 +msgid "Related compiled artifact view is also emitted under:" +msgstr "相关的编译产物视图还会输出到：" + +#: ../../source/blog/why_magi_depyf.md:66 +msgid "`/magi_depyf/run_*/model_*_rank_*/compiled_functions/`" +msgstr "`/magi_depyf/run_*/model_*_rank_*/compiled_functions/`" + +#: ../../source/blog/why_magi_depyf.md:68 +msgid "See the full runnable example:" +msgstr "完整可运行示例见：" + +#: ../../source/blog/why_magi_depyf.md:70 +msgid "`magi_compiler/magi_depyf/example/magi_compile_transformer_example.py`" +msgstr "`magi_compiler/magi_depyf/example/magi_compile_transformer_example.py`" + +#: ../../source/blog/why_magi_depyf.md:72 +msgid "Typical questions this path answers quickly:" +msgstr "这条路径能快速回答的典型问题：" + +#: ../../source/blog/why_magi_depyf.md:74 +msgid "Did fullgraph/subgraph events happen in the expected order?" +msgstr "全图/子图事件是否按预期顺序发生？" + +#: ../../source/blog/why_magi_depyf.md:75 +msgid "Which pass changed graph structure?" +msgstr "是哪个 pass 改变了图结构？" + +#: ../../source/blog/why_magi_depyf.md:76 +msgid "Did `RestartAnalysis` happen, and was cache load skipped as expected?" +msgstr "是否发生了 `RestartAnalysis`，缓存加载是否如预期被跳过？" + +#: ../../source/blog/why_magi_depyf.md:77 +msgid "Which event folder contains the exact graph/code snapshot for debugging?" +msgstr "哪个事件文件夹包含用于调试的精确图/代码快照？" + +#: ../../source/blog/why_magi_depyf.md:81 +msgid "3. Secondary scenario: plain `torch.compile` (manual entry)" +msgstr "3. 次要场景：纯 `torch.compile`（手动接入）" + +#: ../../source/blog/why_magi_depyf.md:83 +msgid "" +"`magi_depyf` also works with plain `torch.compile`, but this is a " +"secondary workflow and requires manual context wrapping:" +msgstr "" +"`magi_depyf` 同样适用于纯 `torch.compile`，但这是次要工作流，需要手动包裹上下文：" + +#: ../../source/blog/why_magi_depyf.md:104 +msgid "See the concrete example here:" +msgstr "具体示例见此处：" + +#: ../../source/blog/why_magi_depyf.md:106 +msgid "`magi_compiler/magi_depyf/example/torch_compile_toy_example.py`" +msgstr "`magi_compiler/magi_depyf/example/torch_compile_toy_example.py`" + +#: ../../source/blog/why_magi_depyf.md:108 +msgid "" +"This demo shows the minimal way to use `explain_compilation` in a pure " +"`torch.compile` setup." +msgstr "" +"该示例展示了在纯 `torch.compile` 场景下使用 `explain_compilation` 的最简方式。" + +#: ../../source/blog/why_magi_depyf.md:112 +msgid "4. Event model (concise)" +msgstr "4. 事件模型（简述）" + +#: ../../source/blog/why_magi_depyf.md:114 +msgid "Each event contains:" +msgstr "每个事件包含：" + +#: ../../source/blog/why_magi_depyf.md:116 +msgid "`name`: event name (with `fullgraph_` or `subgraph_N_` prefix)" +msgstr "`name`：事件名称（带 `fullgraph_` 或 `subgraph_N_` 前缀）" + +#: ../../source/blog/why_magi_depyf.md:117 +msgid "" +"`attributes`: structured metadata (for example `lifecycle_name`, " +"`runtime_shape`, `graph_index`, `reason`)" +msgstr "" +"`attributes`：结构化元数据（例如 `lifecycle_name`、`runtime_shape`、`graph_index`、`reason`）" + +#: ../../source/blog/why_magi_depyf.md:118 +msgid "`files`: attached text artifacts (graph code, inductor output, etc.)" +msgstr "`files`：附属的文本产物（图代码、inductor 输出等）" + +#: ../../source/blog/why_magi_depyf.md:120 +msgid "4.1 Lifecycle naming pattern" +msgstr "4.1 生命周期命名模式" + +#: ../../source/blog/why_magi_depyf.md:122 +msgid "Lifecycle events are normalized into the following pattern:" +msgstr "生命周期事件被规范化为以下模式：" + +#: ../../source/blog/why_magi_depyf.md:124 +msgid "`*_before_`" +msgstr "`*_before_`" + +#: ../../source/blog/why_magi_depyf.md:125 +msgid "`*_after_`" +msgstr "`*_after_`" + +#: ../../source/blog/why_magi_depyf.md:126 +msgid "`*_failed_`" +msgstr "`*_failed_`" + +#: ../../source/blog/why_magi_depyf.md:127 +msgid "`*_skip_`" +msgstr "`*_skip_`" + +#: ../../source/blog/why_magi_depyf.md:129 +msgid "Where `*` is `fullgraph` or `subgraph_`." +msgstr "其中 `*` 为 `fullgraph` 或 `subgraph_`。" + +#: ../../source/blog/why_magi_depyf.md:131 +msgid "4.2 Representative examples" +msgstr "4.2 代表性示例" + +#: ../../source/blog/why_magi_depyf.md:133 +msgid "`fullgraph_before_graph_split`" +msgstr "`fullgraph_before_graph_split`" + +#: ../../source/blog/why_magi_depyf.md:134 +msgid "`fullgraph_after_graph_split`" +msgstr "`fullgraph_after_graph_split`" + +#: ../../source/blog/why_magi_depyf.md:135 +msgid "`fullgraph_before_compiler_manager_compile`" +msgstr "`fullgraph_before_compiler_manager_compile`" + +#: ../../source/blog/why_magi_depyf.md:136 +msgid "`fullgraph_after_compiler_manager_load`" +msgstr "`fullgraph_after_compiler_manager_load`" + +#: ../../source/blog/why_magi_depyf.md:137 +msgid "`subgraph_2_before_postcleanuppass`" +msgstr "`subgraph_2_before_postcleanuppass`" + +#: ../../source/blog/why_magi_depyf.md:138 +msgid "`subgraph_2_after_postcleanuppass`" +msgstr "`subgraph_2_after_postcleanuppass`" + +#: ../../source/blog/why_magi_depyf.md:142 +msgid "5. Output layout (current implementation)" +msgstr "5. 输出布局（当前实现）" + +#: ../../source/blog/why_magi_depyf.md:169 +msgid "6. Recommended triage order" +msgstr "6. 推荐的排查顺序" + +#: ../../source/blog/why_magi_depyf.md:171 +msgid "When debugging a compile issue, use this order:" +msgstr "调试编译问题时，按以下顺序进行：" + +#: ../../source/blog/why_magi_depyf.md:173 +msgid "`timeline.jsonl`: verify event ordering first" +msgstr "`timeline.jsonl`：先核对事件顺序" + +#: ../../source/blog/why_magi_depyf.md:174 +msgid "" +"`*_failed_*` / cache-related lifecycle events (`compiler_manager_load`, " +"`compiler_manager_cache_store`)" +msgstr "" +"`*_failed_*` / 缓存相关的生命周期事件（`compiler_manager_load`、`compiler_manager_cache_store`）" + +#: ../../source/blog/why_magi_depyf.md:175 +msgid "" +"Graph files attached to relevant events: verify before/after pass graph " +"state" +msgstr "" +"相关事件附带的图文件：核对 pass 前后的图状态" + +#: ../../source/blog/why_magi_depyf.md:176 +msgid "" +"`compiled_functions/*/overview.md`: verify final compiled artifact " +"structure" +msgstr "" +"`compiled_functions/*/overview.md`：核对最终的编译产物结构" + +#: ../../source/blog/why_magi_depyf.md:178 +msgid "The key is not just absolute timing. The key is:" +msgstr "关键不只是绝对耗时，而是：" + +#: ../../source/blog/why_magi_depyf.md:180 +msgid "what happened," +msgstr "发生了什么，" + +#: ../../source/blog/why_magi_depyf.md:181 +msgid "whether it matched expectations," +msgstr "是否符合预期，" + +#: ../../source/blog/why_magi_depyf.md:182 +msgid "and where to drill down when it failed." +msgstr "以及失败时应深入到哪里排查。" + +#: ../../source/blog/why_magi_depyf.md:186 +msgid "7. Compatibility and entry-point summary" +msgstr "7. 兼容性与入口点小结" + +#: ../../source/blog/why_magi_depyf.md:188 +msgid "**Primary entry**: MagiCompiler main path (`magi_compile`)" +msgstr "**主入口**：MagiCompiler 主路径（`magi_compile`）" + +#: ../../source/blog/why_magi_depyf.md:189 +msgid "**Optional entry**: plain `torch.compile` + manual `explain_compilation`" +msgstr "**可选入口**：纯 `torch.compile` + 手动 `explain_compilation`" + +#: ../../source/blog/why_magi_depyf.md:191 +msgid "One-line summary:" +msgstr "一句话总结：" + +#: ../../source/blog/why_magi_depyf.md:193 +msgid "" +"`magi_depyf` is first and foremost MagiCompiler's internal observability " +"infrastructure, while still being usable as a manual troubleshooting tool" +" for plain `torch.compile` when needed." +msgstr "" +"`magi_depyf` 首先是 MagiCompiler 的内部可观测性基础设施，同时在需要时也可作为纯 " +"`torch.compile` 的手动排障工具使用。" diff --git a/docs/locale/zh_CN/LC_MESSAGES/index.po b/docs/locale/zh_CN/LC_MESSAGES/index.po new file mode 100644 index 0000000..36e5752 --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/index.po @@ -0,0 +1,58 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/index.md:13 +msgid "Contents" +msgstr "目录" + +#: ../../source/index.md:4 +msgid "MagiCompiler documentation" +msgstr "MagiCompiler 文档" + +#: ../../source/index.md:7 +msgid "**Overview :**" +msgstr "**概览：**" + +#: ../../source/index.md:9 +msgid "" +"MagiCompiler is an advanced compiler and runtime augmentation framework " +"built on top of `torch.compile`. Designed for large-scale Transformer-" +"like architectures, it moves beyond traditional local operator " +"optimization and introduces system-level optimizations—whole-graph " +"capture, FSDP-aware layer-wise compilation, asynchronous offloading, and " +"heuristic activation recomputation—to seamlessly accelerate both " +"**training** and **multi-modality inference** with minimal code " +"intrusion." +msgstr "" +"MagiCompiler 是一个构建在 `torch.compile` 之上的先进编译与运行时增强框架。" +"它面向大规模 Transformer 类架构设计，超越了传统的局部算子优化，引入了系统级优化——" +"全图捕获、FSDP 感知的分层编译、异步 offloading 以及启发式激活重计算——" +"以极小的代码侵入无缝加速**训练**与**多模态推理**。" + +#: ../../source/index.md:11 +msgid "" +"We are committed to continually improving the performance and generality " +"of MagiCompiler for the broader research community. Stay tuned for " +"exciting enhancements and new features on the horizon!" +msgstr "" +"我们致力于为更广泛的研究社区持续提升 MagiCompiler 的性能与通用性。" +"敬请期待即将到来的激动人心的增强功能与新特性！" diff --git a/docs/locale/zh_CN/LC_MESSAGES/user_guide/install.po b/docs/locale/zh_CN/LC_MESSAGES/user_guide/install.po new file mode 100644 index 0000000..39b255b --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/user_guide/install.po @@ -0,0 +1,69 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/user_guide/install.md:1 +msgid "Installation" +msgstr "安装" + +#: ../../source/user_guide/install.md:7 +msgid "Requirements" +msgstr "环境要求" + +#: ../../source/user_guide/install.md:9 +msgid "Python >= 3.12" +msgstr "Python >= 3.12" + +#: ../../source/user_guide/install.md:10 +msgid "PyTorch >= 2.9" +msgstr "PyTorch >= 2.9" + +#: ../../source/user_guide/install.md:11 +msgid "CUDA Toolkit" +msgstr "CUDA Toolkit" + +#: ../../source/user_guide/install.md:14 +msgid "" +"For reproducibility, we recommend starting from the prebuilt Docker image" +" first, then running examples inside the container." +msgstr "" +"为了可复现性，我们建议先从预构建的 Docker 镜像开始，然后在容器内运行示例。" + +#: ../../source/user_guide/install.md:18 +msgid "Option A (recommended) — Prebuilt Docker Image" +msgstr "方式 A（推荐）— 预构建 Docker 镜像" + +#: ../../source/user_guide/install.md:32 +msgid "Option B — Local Source Installation" +msgstr "方式 B — 本地源码安装" + +#: ../../source/user_guide/install.md:50 +msgid "Optional — Install CUTLASS for matmul epilogue fusion" +msgstr "可选 — 安装 CUTLASS 以启用 matmul epilogue 融合" + +#: ../../source/user_guide/install.md:52 +msgid "" +"Required for the CUTLASS-based matmul + epilogue fusion pass (`sm_90` / " +"`sm_120`). Without CUTLASS the compiler still works but skips this " +"optimization." +msgstr "" +"基于 CUTLASS 的 matmul + epilogue 融合 pass（`sm_90` / `sm_120`）需要它。" +"不安装 CUTLASS 编译器仍可正常工作，只是会跳过该项优化。" diff --git a/docs/locale/zh_CN/LC_MESSAGES/user_guide/quickstart.po b/docs/locale/zh_CN/LC_MESSAGES/user_guide/quickstart.po new file mode 100644 index 0000000..f3fac4c --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/user_guide/quickstart.po @@ -0,0 +1,69 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/user_guide/quickstart.md:1 +msgid "QuickStart" +msgstr "快速开始" + +#: ../../source/user_guide/quickstart.md:7 +msgid "One Decorator to Rule Them All (`@magi_compile`)" +msgstr "一个装饰器搮定一切（`@magi_compile`）" + +#: ../../source/user_guide/quickstart.md:9 +msgid "" +"Remove scattered `torch.compile` or `torch.compiler.disable` calls. " +"Decorate your core Transformer block once for automatic full-graph " +"capture and dynamic shape support (defaulting to dim 0)." +msgstr "" +"无需再到处散落地写 `torch.compile` 或 `torch.compiler.disable`。" +"只需对核心 Transformer 块装饰一次，即可自动获得全图捕获与动态 shape 支持（默认第 0 维）。" + +#: ../../source/user_guide/quickstart.md:38 +msgid "Bridge Custom Kernels (`@magi_register_custom_op`)" +msgstr "桥接自定义 Kernel（`@magi_register_custom_op`）" + +#: ../../source/user_guide/quickstart.md:40 +msgid "" +"Using custom kernels (FlashAttention, MoE routers) that break FX tracing?" +" Don't disable compilation. Wrap them to teach the compiler how to handle" +" them during graph partitioning and recomputation." +msgstr "" +"使用会破坏 FX tracing 的自定义 kernel（FlashAttention、MoE router）？" +"不要禁用编译。将它们包装起来，告诉编译器在图划分与重计算时如何处理它们。" + +#: ../../source/user_guide/quickstart.md:57 +msgid "Advanced Configurations" +msgstr "高级配置" + +#: ../../source/user_guide/quickstart.md:59 +msgid "" +"Explore `magi_compiler/config.py` for power-user features like custom " +"backend toggles and fine-grained memory management." +msgstr "" +"在 `magi_compiler/config.py` 中探索面向高级用户的功能，例如自定义后端开关与细粒度内存管理。" + +#: ../../source/user_guide/quickstart.md:63 +msgid "" +"Comprehensive guides for popular training/inference frameworks are coming" +" soon." +msgstr "" +"面向主流训练/推理框架的完整指南即将推出。" diff --git a/docs/locale/zh_CN/LC_MESSAGES/user_guide/toc.po b/docs/locale/zh_CN/LC_MESSAGES/user_guide/toc.po new file mode 100644 index 0000000..4d43ba1 --- /dev/null +++ b/docs/locale/zh_CN/LC_MESSAGES/user_guide/toc.po @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025-2026, SandAI +# This file is distributed under the same license as the MagiCompiler +# package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: MagiCompiler \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-07-04 11:20+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: zh_CN\n" +"Language-Team: zh_CN \n" +"Plural-Forms: nplurals=1; plural=0;\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../source/user_guide/toc.md:1 ../../source/user_guide/toc.md:3 +msgid "User Guide" +msgstr "用户指南" diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..912a8fe --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,66 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %SOURCEDIR% %BUILDDIR%/gettext %SPHINXOPTS% %O% + goto end +) + +if "%1" == "update-po" ( + %SPHINXBUILD% -b gettext %SOURCEDIR% %BUILDDIR%/gettext %SPHINXOPTS% %O% + sphinx-intl update -p %BUILDDIR%/gettext -d locale -l zh_CN + goto end +) + +if "%1" == "html-en" ( + set DOCS_LANGUAGE=en + %SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%/html %SPHINXOPTS% %O% + goto end +) + +if "%1" == "html-zh" ( + set DOCS_LANGUAGE=zh_CN + %SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%/html/zh_CN %SPHINXOPTS% %O% + goto end +) + +if "%1" == "html-multilang" ( + set DOCS_LANGUAGE=en + %SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%/html %SPHINXOPTS% %O% + set DOCS_LANGUAGE=zh_CN + %SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%/html/zh_CN %SPHINXOPTS% %O% + goto end +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..f00494f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,10 @@ +ablog +babel==2.18.0 +myst_parser +pydata-sphinx-theme +sphinx +sphinx-copybutton +sphinx-intl +sphinx-subfigure +sphinx_design +sphinxcontrib-bibtex diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..cd0d6de --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,25 @@ +/* control the size of the logo in the top left of the navigation bar */ +.navbar-brand img { + height: 32px !important; + width: auto !important; +} + +/* diff add line */ +.highlight .gi { + color: #22863a; + background-color: #f0fff4; + display: block; +} + +/* diff delete line */ +.highlight .gd { + color: #d73a49; + background-color: #ffeef0; + display: block; +} + +/* diff line start +/- symbol */ +.highlight .gp { + color: #6a737d; + font-weight: bold; +} diff --git a/docs/source/_templates/language-switcher.html b/docs/source/_templates/language-switcher.html new file mode 100644 index 0000000..e1940d1 --- /dev/null +++ b/docs/source/_templates/language-switcher.html @@ -0,0 +1,94 @@ +{# Language switcher for multi-language documentation builds. #} +{# Sphinx 8+ normalises language to BCP 47 (e.g. zh-CN), so match both forms. #} +{% set is_chinese = language and ("zh" in language) %} + + diff --git a/docs/source/blog/auto_cpu_offload.md b/docs/source/blog/auto_cpu_offload.md new file mode 100644 index 0000000..419e76d --- /dev/null +++ b/docs/source/blog/auto_cpu_offload.md @@ -0,0 +1,68 @@ +--- +blogpost: true +date: 2026-03-23 +author: Taoran Wang +category: Design +tags: offload, memory, scheduling +--- + +# Analysis of Automatic Offloading + +When training or inferencing ultra-large models, GPU memory capacity is the primary bottleneck. The standard industry solution is Offloading—moving a portion of model weights to the CPU and dynamically Prefetching them back to the GPU just before computation. + +However, the emergence of high-computational-efficiency models, such as [daVinci-MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman) base 256p, poses a challenge to traditional offload strategies. Because these models execute operators extremely quickly, the ``Overlap Window`` left for PCIe data transfer is exceptionally short. If prefetching is not precise, the GPU frequently enters a ``starvation`` state while waiting for data, resulting in significant pipeline bubbles. + +```{image} ../../assets/offload/base_offload_profile.png +:alt: Base Offload Profile +:width: 49% +``` + +```{image} ../../assets/offload/heuristic_offload_profile.png +:alt: Heuristic Offload Profile +:width: 49% +``` + +*Left: Base Offload with noticeable GPU starvation (bubbles). Right: Heuristic Offload eliminating pipeline bubbles and accelerating daVinci-MagiHuman.* + +This article dives into the core source code of MagiCompiler ([api.py](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/api.py), [offload_wrapper.py](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py), and [scheduler.py](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/offload/scheduler.py)) to deconstruct how it achieves deep overlap between computation and transmission. + +## Architectural Overview: Graph-Based Asynchronous Pipeline +MagiCompiler's Offload mechanism is built upon the torch.fx graph mode. Its core logic involves using an independent CUDA Stream to pull weights for subsequent modules while the current submodule is still computing. + +- [OffloadExecutor](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py) / [OffloadWrapper](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/offload/offload_warpper.py): Responsible for operator graph parsing, memory lifecycle management, and execution flow scheduling. +- [OffloadScheduler](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/offload/scheduler.py): The core strategy layer that determines the residency priority of weights and the precise timing of prefetch triggers. + +## Low-Level Optimization: Shared & Pinned Memory +Efficient data movement relies on low-level physical memory optimization. During the compilation phase, MagiCompiler implements two critical configurations for CPU Offload: +- Distributed Shared Memory: When [model_cpu_offload](https://github.com/SandAI-org/MagiCompiler/blob/main/magi_compiler/config.py) is enabled, all weights are reused within contiguous memory blocks via [torch.from_file(shared=True)](https://docs.pytorch.org/docs/stable/generated/torch.from_file.html). This effectively reduces CPU overhead and memory fragmentation in multi-GPU environments. +- Pinned Memory: By using pin_memory_in_place, weights are forced to reside in non-pageable physical memory. This is the foundation for maximizing PCIe bandwidth utilization and achieving high-speed Host-to-Device (H2D) transfers. + +## Operational Mechanism: Fine-Grained Executor Control +- Graph Analysis: _analyze_graph pre-traverses the torch.fx.GraphModule to calculate reference counts (user_counts) for each node, providing the basis for ``use-and-discard`` memory release. +- Profiling: During the initial runs, the OffloadProfiler measures the computation time and H2D bandwidth for each submodule. Once warming up concludes, _finalize_warmup() feeds this empirical data into the scheduler to generate a static optimal strategy. +- Dynamic Memory Management: Asynchronous prefetching is triggered before call_module. Immediately after execution, tensors are cleared from the environment based on reference counts, utilizing record_stream to ensure the memory is physically released only when safe. + +## Scheduling Strategies: Heuristics for High-Speed Models (scheduler.py) +To handle fast-paced models like [daVinci-MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman), MagiCompiler offers three evolving schedulers: + +**BaseScheduler**: A basic look-ahead strategy that prefetches only 1–2 modules in advance. In scenarios with long sequences or fast operators, this simple approach often fails to cover the transmission latency. + +**CostEffectiveScheduler**: This strategy corrects the intuitive error of prioritizing ``long-computation operators.`` It identifies that modules with massive weight volumes but lightning-fast computation are the primary source of bubbles. Consequently, it allocates the limited GPU residency quota to these ``transfer-heavy, compute-light`` modules. + +**HeuristicScheduler**： + +```{image} ../../assets/offload/heuristic_offload.png +:alt: Heuristic Offload +:width: 85% +:align: center +``` + + - JIT (Just-In-Time) Latest Loading: The most advanced solution, introducing a mechanism. It uses profiling data to reverse-calculate the exact start time for transmission, ensuring weights arrive at the GPU at the ``last possible second`` before computation. This prevents memory bloat from queued weights and compresses peak memory usage to its theoretical minimum. + - Weight Residency Optimization: If residual GPU memory is detected (based on the gpu_resident_weight_ratio), it will designate specific weights to remain resident on the GPU, thereby alleviating pressure on the PCIe bandwidth. + +## Performance: Zero-Bubble Experience on RTX 5090 +In an RTX 5090 environment using a CP4 parallel strategy for a 10-second long-video generation inference test with [daVinci-MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman) base 256p: + +By setting gpu_resident_weight_ratio to 35%, the system allocates this ``prime`` GPU memory to large-volume, fast-computation operators. The remaining 65% of weights are managed via the HeuristicScheduler for precise JIT prefetching. + +The Result: The 10s video inference process achieved complete overlap between H2D communication and computation. Despite the extremely high operator throughput, the GPU remained fully utilized with zero pipeline bubbles, reaching the theoretical limits of both memory efficiency and system throughput. diff --git a/docs/source/blog/auto_cuda_graph_design.md b/docs/source/blog/auto_cuda_graph_design.md new file mode 100644 index 0000000..a60eed1 --- /dev/null +++ b/docs/source/blog/auto_cuda_graph_design.md @@ -0,0 +1,167 @@ +--- +blogpost: true +date: 2026-03-23 +author: Zhiyao Cen +category: Design +tags: cuda-graph, inference, memory +--- + +# AutoCudaGraph Design + +## Overview +AutoCudaGraph is a CUDA Graph optimization module integrated into the MagiCompiler framework, designed to automate CUDA Graph capture, caching, replay, and tensor memory management for PyTorch-based neural network inference. It targets Transformer architectures with dynamic sequence lengths, optimizing kernel execution by reusing pre-captured computation graphs and static tensor buffers. Core Goals: +* Automate CUDA Graph lifecycle (capture/replay/cache) with minimal code intrusion +* Support dynamic shape adaptation (sequence length expansion) +* Optimize memory efficiency via global memory pool and static tensor reuse +* Ensure consistency between cached graphs and runtime inputs/outputs + +## Key Components + +### CudaGraphMgr (Core Manager) +Singleton class managing all CUDA Graph operations: +```python +class CudaGraphMgr: + def __init__(self): + self.cache: Dict[StaticSignature, StaticTensorEntry] = dict() + self.graph_mem_pool: Optional[torch.cuda.graph_pool_handle] = None +``` + +**Core Methods** +| Method | Purpose | +|---------------------------------|----------------------------------------| +| run() | Main entry: Replay cached graph or warm up & capture new graph| +| wrapped_graph_capture() | Capture CUDA Graph with sliced static input/output tensors | +| wrapped_graph_replay() | Replay cached CUDA Graph with sliced static tensors and output template wrapping +| get_expanded_static_tensors() | Expand static tensors, reuse buffers if dimensionally compatible| + +### Signature System + +StaticSignature +```python +@dataclass(unsafe_hash=True) +class StaticSignature(HashableDataclass): + func_name: str = "" + tensor_static_infos: Tuple[TensorStaticInfo, ...] = tuple() +``` +* Encodes fixed properties of input tensors (dtype, static dimensions) +* Used as primary key for static tensor buffer caching + +DynamicSignature +```python +@dataclass(unsafe_hash=True) +class DynamicSignature(HashableDataclass): + tensor_dynamic_infos: Tuple[TensorDynamicInfo, ...] = tuple() + literals_info: LiteralsInfo = None +``` +* Tracks dynamic dimensions (sequence length) and literal parameters +* Secondary key for graph entry lookup + +### Tensor Management +```python +@dataclass +class StaticTensorEntry: + input_tensors: Optional[List[torch.Tensor]] = None + output_tensors: Optional[List[torch.Tensor]] = None + template_entry_dict: Dict[DynamicSignature, OutputTemplateEntry] = None +``` +* Memory Reuse: Reuse existing tensor buffers when possible to avoid reallocation +* Dynamic Expansion: Only expand static tensors when new input dimensions exceed current buffer size +* Shape Validation: Ensure static dimensions (non-sequence) match between cached and new tensors + +### Graph Management +```python +@dataclass +class GraphEntry: + graph: Optional[torch.cuda.CUDAGraph] = None + inconsistent: bool = False + invalid: bool = False + +@dataclass +class OutputTemplateEntry: + graph_entry_dict: Dict[int, GraphEntry] = None + output_template: Any = None +``` +* Graph State Tracking: GraphEntry tracks CUDA Graph instances and validity states to control replay eligibility. +* Layer-wise Organization: OutputTemplateEntry maps dynamic signatures to per-layer GraphEntry for layer-specific graph reuse. +* Output Consistency: output_template preserves output object structure to ensure consistent result wrapping during replay. + +## Execution Flow +### Inline Replay (Fast Path) +* Extract input signatures from runtime arguments +* Look up cached CUDA Graph via StaticSignature + DynamicSignature + layer number +* Validate graph consistency (not inconsistent/invalid) +* Reuse static tensors with dynamic slicing +* Replay graph and return sliced output +### Graph Capture (Slow Path) +Triggered when no valid cached graph exists or tensor expansion is needed: +* Execute function to get output tensors +* Ensure input signatures match post-warmup +* Expand static buffers if new shapes require it +* Capture new CUDA Graph with static tensors +* Store new graph and update tensor entries +* Return warmup execution output as final result +### Sequence Length Handling +* Only last dimension is static for ND tensors (ND > 1) +* All dimension is dynamic for 1D tensors (ND=1) +* Automatic buffer expansion for increasing sequence lengths +* Invalidates old graphs when tensors are expanded + +## Examples +```python +import torch +import torch.nn as nn +from magi_compiler.magi_backend.cuda_graph_mgr import cuda_graph_mgr, cuda_graph_enable_if + +class SimpleTransformerLayer(nn.Module): + def __init__(self, hidden_dim: int = 1024, num_heads: int = 8): + super().__init__() + self.self_attn = nn.MultiheadAttention(hidden_dim, num_heads, batch_first=True) + self.linear = nn.Linear(hidden_dim, hidden_dim) + self.layer_norm = nn.LayerNorm(hidden_dim) + self.layer_number = 0 + + @cuda_graph_enable_if(lambda: torch.cuda.is_available()) + def forward(self, x: torch.Tensor): + attn_out, _ = self.self_attn(x, x, x) + out = self.linear(self.layer_norm(x + attn_out)) + return out + +device = torch.device("cuda" if torch.cuda.is_available() else "cpu") +model = SimpleTransformerLayer(hidden_dim=1024, num_heads=8).to(device).eval() +graph_mgr = cuda_graph_mgr() + +with torch.no_grad(): + input_1 = torch.randn(2, 512, 1024, device=device) + output_1 = model(input_1) + print(f"First run (graph capture): Output shape = {output_1.shape}") + print(f"Cached graphs count: {graph_mgr.graph_count}") + + input_2 = torch.randn(2, 512, 1024, device=device) + output_2 = model(input_2) + print(f"Second run (graph replay): Output shape = {output_2.shape}") + print(f"Cached graphs count: {graph_mgr.graph_count}") + + input_3 = torch.randn(2, 1024, 1024, device=device) + output_3 = model(input_3) + print(f"Third run (tensor expansion): Output shape = {output_3.shape}") + print(f"Cached graphs count: {graph_mgr.graph_count}") + print(f"Static tensor memory usage: {graph_mgr.tensor_mem_size:.2f} MB") + + print("\nCUDA Graph Cache Details:") + print(graph_mgr.formatted_cache_str()) +``` + +## Limitations and Constraints +* No support for data-dependent control flow in captured functions +* Graph capture fails if function contains CPU/GPU synchronization +* Only supports CUDA tensors (CPU tensors trigger fallback) +* Custom input classes must inherit from InplaceSubstituteFakeClass +* Assumes input tensors of captured graphs are not reused externally (risk of cross-scenario static tensor reuse) +* Relies on identical function, input tensors shapes, and constants for valid graph reuse +* No support for multi-stream execution scenarios + +## Best Practices +* Dynamic Dimensions: Tensor use sequence length as dimension 0 where possible +* Monitor Memory Usage: Track graph_mem_pool_size and tensor_mem_size to avoid OOM +* Specify Layer IDs: Use layer_number to distinguish graphs across different models/layers +* LRU Cache (Future): Implement cache eviction to limit total graph/tensor count diff --git a/docs/source/blog/refs/.gitkeep b/docs/source/blog/refs/.gitkeep new file mode 100644 index 0000000..f61230e --- /dev/null +++ b/docs/source/blog/refs/.gitkeep @@ -0,0 +1,2 @@ +# Place one BibTeX file per blog post here, named `.bib`, and +# register the corresponding title in the `blog_titles` list in `../conf.py`. diff --git a/docs/source/blog/toc.md b/docs/source/blog/toc.md new file mode 100644 index 0000000..f3ded7a --- /dev/null +++ b/docs/source/blog/toc.md @@ -0,0 +1,22 @@ +# Blogs + +```{postlist} +:excerpts: +``` + +```{toctree} +:caption: Blogs +:maxdepth: 1 +:hidden: + +why_magi_depyf.md +auto_cpu_offload.md +auto_cuda_graph_design.md + +``` + + diff --git a/docs/source/blog/why_magi_depyf.md b/docs/source/blog/why_magi_depyf.md new file mode 100644 index 0000000..7b159cf --- /dev/null +++ b/docs/source/blog/why_magi_depyf.md @@ -0,0 +1,193 @@ +--- +blogpost: true +date: 2026-03-23 +author: MagiCompiler Team +category: Design +tags: magi_depyf, observability, debugging +--- + +# Why magi_depyf + +`magi_depyf` is the compilation observability layer for `MagiCompiler`. +It answers three practical questions: + +1. **What exactly happened during compilation?** +2. **Did the outcome match expectations?** (for example: graph split shape, cache reuse, retry behavior) +3. **If something failed, where should I look first?** + +--- + +## 1. Positioning: Built-in observability for MagiCompiler + +In a real MagiCompiler pipeline, compilation spans multiple stages: Dynamo capture, Magi backend graph transforms/splitting, Inductor codegen, and AOT/JIT reuse. +Plain logs are often not enough to reliably answer: + +- Did the failure happen at full-graph level or in a specific subgraph? +- Did a pass change graph behavior unexpectedly? +- Why did this run miss cache? + +`magi_depyf` writes these signals as structured events and artifacts on disk, so you can replay, compare, and debug deterministically. + +--- + +## 2. Primary scenario: `magi_compile` + +### 2.1 Recommended usage model + +For `magi_compile` users, `magi_depyf` is most useful as a built-in observability layer: + +- Streams events to `timeline_events/timeline.jsonl` during compilation +- Writes event artifacts under `timeline_events/files/` +- Exports a structured `compiled_functions/` artifact tree + +In most cases, you do not need to manually wire custom hooks. Run through the MagiCompiler path and inspect the output directory. + +### 2.2 What you get automatically in the Magi compile path + +For the `magi_compile` scenario, you do **not** need to call `explain_compilation` manually. +As long as the model runs through MagiCompiler, `magi_depyf` outputs are written automatically. + +For example, one real run produced: + +- `magi_depyf_torch_compile_debug/magi_depyf/run_20260322_192147/model_1_TwoLayerTransformer_rank_0/timeline_events` + +In general, the output pattern is: + +- `/magi_depyf/run_*/model_*_rank_*/timeline_events/` + +Key artifacts under this directory: + +- `timeline.jsonl`: streaming event log written during compilation +- `files/0000_*`, `files/0001_*`, ... event folders with attached artifacts +- `files/*/attributes.json`: structured metadata for each event folder + +Related compiled artifact view is also emitted under: + +- `/magi_depyf/run_*/model_*_rank_*/compiled_functions/` + +See the full runnable example: + +- `magi_compiler/magi_depyf/example/magi_compile_transformer_example.py` + +Typical questions this path answers quickly: + +- Did fullgraph/subgraph events happen in the expected order? +- Which pass changed graph structure? +- Did `RestartAnalysis` happen, and was cache load skipped as expected? +- Which event folder contains the exact graph/code snapshot for debugging? + +--- + +## 3. Secondary scenario: plain `torch.compile` (manual entry) + +`magi_depyf` also works with plain `torch.compile`, but this is a secondary workflow and requires manual context wrapping: + +```python +import torch + +from magi_compiler.magi_depyf.inspect import explain_compilation + + +@torch.compile +def toy_example(a, b): + x = a / (torch.abs(a) + 1) + if b.sum() < 0: + b = -b + return x * b + + +with explain_compilation("./magi_depyf_torch_compile_debug"): + for _ in range(10): + toy_example(torch.randn(10), torch.randn(10)) +``` + +See the concrete example here: + +- `magi_compiler/magi_depyf/example/torch_compile_toy_example.py` + +This demo shows the minimal way to use `explain_compilation` in a pure `torch.compile` setup. + +--- + +## 4. Event model (concise) + +Each event contains: + +- `name`: event name (with `fullgraph_` or `subgraph_N_` prefix) +- `attributes`: structured metadata (for example `lifecycle_name`, `runtime_shape`, `graph_index`, `reason`) +- `files`: attached text artifacts (graph code, inductor output, etc.) + +### 4.1 Lifecycle naming pattern + +Lifecycle events are normalized into the following pattern: + +- `*_before_` +- `*_after_` +- `*_failed_` +- `*_skip_` + +Where `*` is `fullgraph` or `subgraph_`. + +### 4.2 Representative examples + +- `fullgraph_before_graph_split` +- `fullgraph_after_graph_split` +- `fullgraph_before_compiler_manager_compile` +- `fullgraph_after_compiler_manager_load` +- `subgraph_2_before_postcleanuppass` +- `subgraph_2_after_postcleanuppass` + +--- + +## 5. Output layout (current implementation) + +```text +debug_output/ + timeline_events/ + timeline.jsonl + files/ + 0000_fullgraph_.../ + attributes.json + *.py / *.txt + 0001_subgraph_.../ + submod_/ + attributes.json + *.py / *.txt + + compiled_functions/ + / + overview.md + decompiled_code.py + entry_0/ + guards.txt + compiled_fns/ + piecewise_subgraphs/ +``` + +--- + +## 6. Recommended triage order + +When debugging a compile issue, use this order: + +1. `timeline.jsonl`: verify event ordering first +2. `*_failed_*` / cache-related lifecycle events (`compiler_manager_load`, `compiler_manager_cache_store`) +3. Graph files attached to relevant events: verify before/after pass graph state +4. `compiled_functions/*/overview.md`: verify final compiled artifact structure + +The key is not just absolute timing. The key is: + +- what happened, +- whether it matched expectations, +- and where to drill down when it failed. + +--- + +## 7. Compatibility and entry-point summary + +- **Primary entry**: MagiCompiler main path (`magi_compile`) +- **Optional entry**: plain `torch.compile` + manual `explain_compilation` + +One-line summary: + +`magi_depyf` is first and foremost MagiCompiler's internal observability infrastructure, while still being usable as a manual troubleshooting tool for plain `torch.compile` when needed. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..905e5cc --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,165 @@ +# Copyright (c) 2025-2026 SandAI. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys + +sys.path.insert(0, os.path.abspath("../../")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "MagiCompiler" +copyright = "2025-2026, SandAI" +author = "SandAI" +release = "main" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.mathjax", + "myst_parser", + "sphinx_copybutton", + "ablog", + "sphinxcontrib.bibtex", + "sphinx_subfigure", +] + +# -- Bibtex configuration --------------------------------------------------- +# https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html + +# If you add a new blog post with bibliography, please also add its title here. +# NOTE: if the bibtex file has duplicate labels, +# please rename them first, otherwise Sphinx will raise errors. +blog_titles = [] # type: ignore + +blog_bibtex_template = "blog/refs/{title}.bib" +bibtex_bibfiles = [blog_bibtex_template.format(title=title) for title in blog_titles] +bibtex_default_style = "plain" # numbered style +bibtex_reference_style = "author_year" +suppress_warnings = ["bibtex.duplicate_label"] # duplicate numbers for each blog post + +# -- Doc configuration --------------------------------------------------- + +myst_enable_extensions = ["colon_fence", "deflist", "html_image", "tasklist"] + +myst_tasklist_checkbox = True +myst_tasklist_exclude_colon = True + +autodoc_default_options = { + "members": None, + "inherited-members": None, + "show-inheritance": True, + "imported-members": False, + "special-members": False, + "exclude-members": "__weakref__,__dict__,__module__", + "private-members": False, + "member-order": "bysource", + "undoc-members": False, +} + +autodoc_typehints = "description" + +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = False +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = True +napoleon_use_admonition_for_references = False +napoleon_use_ivar = True +napoleon_use_param = True +napoleon_use_rtype = True + +copybutton_prompt_text = r">>> |\.\.\. |\$ " +copybutton_prompt_is_regexp = True +pygments_style = "colorful" + +numfig = True +todo_include_todos = True + +templates_path = ["_templates"] +exclude_patterns = [] # type: ignore + +source_suffix = {".rst": "restructuredtext", ".md": "markdown"} + +master_doc = "index" + +# -- Internationalization ----------------------------------------------------- + +language = os.environ.get("DOCS_LANGUAGE", "en") +locale_dirs = ["../locale/"] +gettext_compact = False + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] +html_baseurl = "https://sandai-org.github.io/MagiCompiler/docs/" +html_show_sourcelink = False + +html_theme_options = { + "show_nav_level": 1, + "show_toc_level": 3, + "navigation_depth": 4, + "collapse_navigation": False, + "logo": {"text": "MagiCompiler"}, + "show_prev_next": False, + "navbar_start": ["navbar-logo"], + "navbar_center": ["navbar-nav"], + "navbar_end": ["theme-switcher", "language-switcher", "navbar-icon-links"], + "icon_links": [{"name": "Github", "url": "https://github.com/SandAI-org/MagiCompiler", "icon": "fa-brands fa-github"}], +} + +html_context = {"supported_doc_languages": [{"code": "en", "label": "English"}, {"code": "zh_CN", "label": "简体中文"}]} + +html_sidebars = { + "blog/**": [ + "ablog/postcard.html", + "ablog/recentposts.html", + "ablog/tagcloud.html", + "ablog/categories.html", + "ablog/archives.html", + "ablog/authors.html", + "ablog/locations.html", + ], + "user_guide/**": ["sidebar-nav-bs", "sidebar-ethical-ads"], +} + + +# -- Setup function --------------------------------------------------- + + +def skip_signature(app, what, name, obj, options, signature, return_annotation): + return "", None + + +def setup(app): + app.connect("autodoc-process-signature", skip_signature) + app.add_css_file("custom.css") diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..c8d7150 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,21 @@ +% MagiCompiler documentation master file +% :github_url: https://github.com/SandAI-org/MagiCompiler + +MagiCompiler documentation +=================================== + +**Overview :** + +MagiCompiler is an advanced compiler and runtime augmentation framework built on top of `torch.compile`. Designed for large-scale Transformer-like architectures, it moves beyond traditional local operator optimization and introduces system-level optimizations—whole-graph capture, FSDP-aware layer-wise compilation, asynchronous offloading, and heuristic activation recomputation—to seamlessly accelerate both **training** and **multi-modality inference** with minimal code intrusion. + +We are committed to continually improving the performance and generality of MagiCompiler for the broader research community. Stay tuned for exciting enhancements and new features on the horizon! + +```{toctree} +:glob: +:maxdepth: 2 +:caption: Contents + +user_guide/toc +blog/toc + +``` diff --git a/docs/source/user_guide/install.md b/docs/source/user_guide/install.md new file mode 100644 index 0000000..5d28785 --- /dev/null +++ b/docs/source/user_guide/install.md @@ -0,0 +1,64 @@ +# Installation + +```{contents} +:local: true +``` + +## Requirements + +- Python >= 3.12 +- PyTorch >= 2.9 +- CUDA Toolkit + +:::{tip} +For reproducibility, we recommend starting from the prebuilt Docker image first, +then running examples inside the container. +::: + +## Option A (recommended) — Prebuilt Docker Image + +```bash +# Step 1 — Pull the image +docker pull sandai/magi-compiler:latest + +# Step 2 — Start the container +docker run --name my-magi-compiler -it -d --privileged --gpus all --network host --ipc host \ + -v /path/on/host:/workspace sandai/magi-compiler:latest /bin/bash + +# Step 3 — Attach the container +docker exec -it my-magi-compiler /bin/bash +``` + +## Option B — Local Source Installation + +```bash +# Step 1 — Clone the repo +git clone https://github.com/SandAI-org/MagiCompiler.git +cd MagiCompiler + +# Step 2 — System dependencies (optional, for FX graph visualization; Debian/Ubuntu) +sudo apt update && sudo apt install -y graphviz + +# Step 3 — Python dependencies +pip install -r requirements.txt + +# Step 4 — Install MagiCompiler (pick one) +pip install . # End users (recommended) +# pip install -e . --no-build-isolation --config-settings editable_mode=compat # Developer / editable +``` + +## Optional — Install CUTLASS for matmul epilogue fusion + +Required for the CUTLASS-based matmul + epilogue fusion pass (`sm_90` / `sm_120`). +Without CUTLASS the compiler still works but skips this optimization. + +```bash +git clone --depth 1 https://github.com/NVIDIA/cutlass.git /usr/local/cutlass +# Or specify a custom path: +# git clone --depth 1 https://github.com/NVIDIA/cutlass.git /your/path +# export MAGI_CUTLASS_ROOT=/your/path +export CUDACXX=${CUDA_INSTALL_PATH}/bin/nvcc +mkdir /usr/local/cutlass/build && cd /usr/local/cutlass/build +cmake .. -DCUTLASS_NVCC_ARCHS=90a # NVIDIA Hopper GPU architecture +# cmake .. -DCUTLASS_NVCC_ARCHS=120a # NVIDIA consumer Blackwell (RTX 50 series) +``` diff --git a/docs/source/user_guide/quickstart.md b/docs/source/user_guide/quickstart.md new file mode 100644 index 0000000..e39c213 --- /dev/null +++ b/docs/source/user_guide/quickstart.md @@ -0,0 +1,64 @@ +# QuickStart + +```{contents} +:local: true +``` + +## One Decorator to Rule Them All (`@magi_compile`) + +Remove scattered `torch.compile` or `torch.compiler.disable` calls. Decorate your +core Transformer block once for automatic full-graph capture and dynamic shape +support (defaulting to dim 0). + +```python +import torch +from torch import nn +from magi_compiler import magi_compile + +# Decorate your core module once. No more scattered compile tweaks! +@magi_compile +class TransformerBlock(nn.Module): + def __init__(self, hidden_dim): + super().__init__() + self.attn = Attention(hidden_dim) + self.mlp = MLP(hidden_dim) + + def forward(self, x: torch.Tensor, mask: torch.Tensor | None) -> torch.Tensor: + x = x + self.attn(x, mask) + x = x + self.mlp(x) + return x + +model = TransformerBlock(hidden_dim=1024).cuda() + +# Execute normally - whole-graph compilation handles dynamic batches automatically! +out = model(torch.randn(4, 128, 1024, device="cuda"), None) +out = model(torch.randn(8, 128, 1024, device="cuda"), None) +``` + +## Bridge Custom Kernels (`@magi_register_custom_op`) + +Using custom kernels (FlashAttention, MoE routers) that break FX tracing? Don't +disable compilation. Wrap them to teach the compiler how to handle them during +graph partitioning and recomputation. + +```python +from magi_compiler import magi_register_custom_op + +@magi_register_custom_op( + name="athena::flash_attn", + infer_output_meta_fn=["q"], # Output shape matches parameter 'q' + is_subgraph_boundary=True, # Split graph here for subgraph compilation + is_compute_sensitive=True, # Retain this output during recomputation +) +def flash_attn(q: torch.Tensor, k: torch.Tensor, v: torch.Tensor) -> torch.Tensor: + ... # Your custom kernel or C++ extension +``` + +## Advanced Configurations + +Explore `magi_compiler/config.py` for power-user features like custom backend +toggles and fine-grained memory management. + +:::{note} +Comprehensive guides for popular training/inference frameworks are coming soon. +::: diff --git a/docs/source/user_guide/toc.md b/docs/source/user_guide/toc.md new file mode 100644 index 0000000..da40a47 --- /dev/null +++ b/docs/source/user_guide/toc.md @@ -0,0 +1,10 @@ +# User Guide + +```{toctree} +:caption: User Guide +:maxdepth: 2 + +install.md +quickstart.md + +```