diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 26d522c4..e59dfdbd 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -6,97 +6,67 @@ on: - main - master paths: - - 'src/**' - - 'spi/**' - - 'scripts/**' - - 'overrides/**' - - 'mkdocs.yml' - - 'requirements.txt' - - '.github/workflows/docs.yml' + - "src/**" + - "spi/**" + - "scripts/**" + - "overrides/**" + - "mkdocs.yml" + - "pyproject.toml" + - ".github/workflows/docs.yml" + pull_request: branches: - main - master paths: - - 'src/**' - - 'spi/**' - - 'scripts/**' - - 'overrides/**' - - 'mkdocs.yml' - workflow_dispatch: # 允许手动触发 + - "src/**" + - "spi/**" + - "scripts/**" + - "overrides/**" + - "mkdocs.yml" + - "pyproject.toml" + - ".github/workflows/docs.yml" + + workflow_dispatch: permissions: contents: write jobs: - build: - name: Build Documentation + documentation: + name: Build and Deploy Documentation runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.11' - - - name: Cache pip dependencies - uses: actions/cache@v4 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - - - name: Install system dependencies - run: sudo apt-get update && sudo apt-get install -y pngquant - - name: Install dependencies - run: | - pip install --upgrade pip - pip install -r requirements.txt - - - name: Build documentation - run: mkdocs build - - deploy: - name: Deploy to GitHub Pages - runs-on: ubuntu-latest - needs: build steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v7 with: - fetch-depth: 0 # 获取完整历史 + fetch-depth: 0 - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@v7 with: - python-version: '3.11' + python-version: "3.12" - - name: Cache pip dependencies - uses: actions/cache@v4 + - name: Install uv + uses: astral-sh/setup-uv@v9.0.0 with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} - restore-keys: | - ${{ runner.os }}-pip- + version: "latest" + enable-cache: true - name: Install system dependencies - run: sudo apt-get update && sudo apt-get install -y pngquant + run: | + sudo apt-get update + sudo apt-get install -y pngquant - name: Install dependencies - run: | - pip install --upgrade pip - pip install -r requirements.txt + run: uv sync - - name: Configure Git - run: | - git config --global user.name "github-actions[bot]" - git config --global user.email "github-actions[bot]@users.noreply.github.com" + - name: Build documentation + run: uv run mkdocs build - name: Deploy to GitHub Pages - run: mkdocs gh-deploy --force + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + run: uv run mkdocs gh-deploy --force env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 9b05eb05..7985af65 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,6 @@ __pycache__ site/ tmp/ .cache/ -.obsidian/ \ No newline at end of file +.obsidian/ +.venv/ +*.lock diff --git a/Makefile b/Makefile index e3b242bb..65bcd90b 100644 --- a/Makefile +++ b/Makefile @@ -16,13 +16,18 @@ help: # Install dependencies install: - @echo "正在安装文档依赖..." - pip install -r requirements.txt + @if command -v uv >/dev/null 2>&1; then \ + echo "检测到 uv，使用 uv 安装依赖..."; \ + uv sync; \ + else \ + echo "未检测到 uv，使用 pip 安装依赖..."; \ + python -m pip install -e .; \ + fi # Generate SPI registry page spi: @echo "正在生成 SPI 已收录产品页面..." - python3 scripts/generate_spi_registry.py + python scripts/generate_spi_registry.py # Live preview server serve: diff --git a/README.md b/README.md index b7dc9a7e..d2eaffeb 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,10 @@ ```bash # 使用 pip -pip install mkdocs mkdocs-material mkdocs-material-extensions jieba +pip install -e . # 或使用 uv -uv pip install -r pyproject.toml +uv sync && source .venv/bin/activate ``` ### 本地预览 @@ -58,7 +58,7 @@ mkdocs gh-deploy --force ## 目录结构 -``` +```bash superpod-whitepaper/ ├── mkdocs.yml # MkDocs 配置文件 ├── pyproject.toml # Python 项目配置 diff --git a/mkdocs.yml b/mkdocs.yml index b4057c52..e41d5ba8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -122,57 +122,57 @@ markdown_extensions: nav: - 首页: index.md - - 前言: - - 00-preface.md - - 编写委员会: 00-editorial-board.md + - 前言: + - 00-preface.md + - 编写委员会: 00-editorial-board.md - 架构分析: - - 01-architecture/index.md - - 产品实践: - - NVIDIA 超节点: 01-architecture/01-nvidia.md - - 华为超节点: 01-architecture/02-huawei.md - - 技术基础: - - 物理层与电气接口: 01-architecture/03-electrical.md - - 链路层与事务协议: 01-architecture/04-protocols.md - - 拓扑与组网: 01-architecture/05-topology.md - - 系统实现: - - 系统架构: 01-architecture/06-system-architecture.md - - 整机工程: 01-architecture/07-server-architecture.md + - 01-architecture/index.md + - 产品实践: + - NVIDIA 超节点: 01-architecture/01-nvidia.md + - 华为超节点: 01-architecture/02-huawei.md + - 技术基础: + - 物理层与电气接口: 01-architecture/03-electrical.md + - 链路层与事务协议: 01-architecture/04-protocols.md + - 拓扑与组网: 01-architecture/05-topology.md + - 系统实现: + - 系统架构: 01-architecture/06-system-architecture.md + - 整机工程: 01-architecture/07-server-architecture.md - 软件系统: - - 02-software/index.md - - 统一访存: - - 硬件内存语义: 02-software/hw-memory-foundations.md - - 软件访存机制: 02-software/memory-semantics.md - - 内存池化技术: 02-software/memory-pooling.md - - 编程模型: - - 集合通信: 02-software/ccl.md - - 共享内存: 02-software/shmem.md - - RAS体系: - - 02-software/ras.md - - 训推系统: - - 02-software/train-infer.md + - 02-software/index.md + - 统一访存: + - 硬件内存语义: 02-software/hw-memory-foundations.md + - 软件访存机制: 02-software/memory-semantics.md + - 内存池化技术: 02-software/memory-pooling.md + - 编程模型: + - 集合通信: 02-software/ccl.md + - 共享内存: 02-software/shmem.md + - RAS体系: + - 02-software/ras.md + - 训推系统: + - 02-software/train-infer.md - 建模仿真: - - 03-simulation/index.md - - 负载模型：定义需求侧的压力画像: 03-simulation/2.workload_modeling.md - - 系统模型：映射与编排的推演引擎: 03-simulation/3.system_simulation.md - - 校准验证与共演进闭环: 03-simulation/coevolution.md - - 方法论落地：异构推理架构的帕累托分析: 03-simulation/case-inference.md + - 03-simulation/index.md + - 负载模型：定义需求侧的压力画像: 03-simulation/2.workload_modeling.md + - 系统模型：映射与编排的推演引擎: 03-simulation/3.system_simulation.md + - 校准验证与共演进闭环: 03-simulation/coevolution.md + - 方法论落地：异构推理架构的帕累托分析: 03-simulation/case-inference.md - 参考设计: - - 04-reference-designs/index.md - - 标准构型：总线全对等互联方案: 04-reference-designs/standard-bus.md - - 标准构型：以太全对等互联方案: 04-reference-designs/standard-ether.md - - 探索构型：Dragonfly + OCS 方案: 04-reference-designs/dragonfly-ocs.md - - 探索构型：3D Torus + OCS 方案: 04-reference-designs/torus-ocs.md - - 探索构型：大环路 + 分布式 dOCS 方案: 04-reference-designs/ring-docs.md + - 04-reference-designs/index.md + - 标准构型：总线全对等互联方案: 04-reference-designs/standard-bus.md + - 标准构型：以太全对等互联方案: 04-reference-designs/standard-ether.md + - 探索构型：Dragonfly + OCS 方案: 04-reference-designs/dragonfly-ocs.md + - 探索构型：3D Torus + OCS 方案: 04-reference-designs/torus-ocs.md + - 探索构型：大环路 + 分布式 dOCS 方案: 04-reference-designs/ring-docs.md - 未来演进: - - 05-future/index.md - - 互联技术演进: - - 光互联与交换: 05-future/interconnect.md - - 先进互联拓扑演进: 05-future/topology.md - - Scale-Up 总线与互联语义: 05-future/bus.md - - 先进封装技术演进: - - 光电互连封装（LPO/NPO/CPO）: 05-future/packaging.md - - Chiplet 多Die 集成（2.5D/3D）: 05-future/chiplet.md - - 堆叠内存技术（HBM/3D DRAM）: 05-future/hbm.md + - 05-future/index.md + - 互联技术演进: + - 光互联与交换: 05-future/interconnect.md + - 先进互联拓扑演进: 05-future/topology.md + - Scale-Up 总线与互联语义: 05-future/bus.md + - 先进封装技术演进: + - 光电互连封装（LPO/NPO/CPO）: 05-future/packaging.md + - Chiplet 多Die 集成（2.5D/3D）: 05-future/chiplet.md + - 堆叠内存技术（HBM/3D DRAM）: 05-future/hbm.md # - 先进模型技术演进: # - 模型技术演进总览: 05-future/model-tech.md # - 低精度数值格式: 05-future/low-precision.md @@ -180,17 +180,17 @@ nav: # - 超稀疏模型技术: 05-future/ultra-sparse.md # - 多模态融合技术: 05-future/multimodal.md - 结语与附录: - - 总结: 06-conclusion.md - - 证据等级与判断口径: 07-evidence-grading.md - - 附录: 07-appendix.md + - 总结: 06-conclusion.md + - 证据等级与判断口径: 07-evidence-grading.md + - 附录: 07-appendix.md - 版本历史: 00-version-history.md - 参与方式: - - 如何参与: contributing.md - - 为何参与: contributing/industry-participation.md + - 如何参与: contributing.md + - 为何参与: contributing/industry-participation.md - 产业协同与 SPI 筹备: - - SuperPod Pareto Index (SPI) 筹备说明书: 07-spi.md - - SPI 现有收录产品名录: 07-spi-registry.md - - 产业生态地图: 08-ecosystem-map.md + - SuperPod Pareto Index (SPI) 筹备说明书: 07-spi.md + - SPI 现有收录产品名录: 07-spi-registry.md + - 产业生态地图: 08-ecosystem-map.md extra: analytics: @@ -294,4 +294,3 @@ extra_javascript: - javascripts/evidence-tags.js copyright: © 2026 DeepLink 团队. 保留所有权利. - diff --git a/pyproject.toml b/pyproject.toml index 26441f86..734373ae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,17 +5,19 @@ description = "SuperPod 技术白皮书 - 分布式 AI 推理加速架构" readme = "README.md" requires-python = ">=3.10" dependencies = [ - "mkdocs>=1.6.0", - "mkdocs-material>=9.5.0", - "mkdocs-material-extensions>=1.3.0", - "mkdocs-encryptcontent-plugin>=3.1.0", + "mkdocs>=1.6.1", + "mkdocs-material>=9.7.7", + "mkdocs-material-extensions>=1.3.1", + "mkdocs-charts-plugin", "mkdocs-excalidraw", "mkdocs-heti-plugin", - "jieba>=0.42.1", - "mkdocs-git-revision-date-localized-plugin>=1.5.1", - "mkdocs-glightbox>=0.4.0", - "mkdocs-minify-plugin>=0.8.0", - "pillow>=10.0", - "cairosvg>=2.7", + "mkdocs-encryptcontent-plugin>=3.1.0", # 内容加密 + "jieba>=0.42.1", # 中文搜索支持 + "pyyaml>=6.0.3", + "pygments==2.20.0", + "mkdocs-git-revision-date-localized-plugin>=1.5.3", # SEO & 站点增强 + "mkdocs-glightbox>=0.5.2", # 图片灯箱 + "mkdocs-minify-plugin>=0.8.0", # 构建优化 + "pillow>=12.3.0", + "cairosvg>=2.9.0", ] - diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index fb2c3441..00000000 --- a/requirements.txt +++ /dev/null @@ -1,27 +0,0 @@ -# MkDocs Documentation Dependencies -mkdocs==1.6.1 -mkdocs-material>=9.5.0 -mkdocs-material-extensions>=1.3.0 -mkdocs-charts-plugin -mkdocs-excalidraw - -# 中文搜索支持 -jieba>=0.42.1 - -# 内容加密 -mkdocs-encryptcontent-plugin>=3.1.0 - -mkdocs-heti-plugin -PyYAML>=6.0 -Pygments==2.19.2 - -# SEO & 站点增强 -mkdocs-git-revision-date-localized-plugin>=1.5.1 - -# 图片灯箱 -mkdocs-glightbox>=0.4.0 - -# 构建优化 -mkdocs-minify-plugin>=0.8.0 -pillow>=10.0 -cairosvg>=2.7 diff --git a/src/05-future/imgs/topo-dragonfly.png b/src/05-future/imgs/topo-dragonfly.png new file mode 100644 index 00000000..2647c2f7 Binary files /dev/null and b/src/05-future/imgs/topo-dragonfly.png differ diff --git a/src/07-spi-registry.md b/src/07-spi-registry.md index cf1e154a..8b0bf077 100644 --- a/src/07-spi-registry.md +++ b/src/07-spi-registry.md @@ -7,7 +7,7 @@ keywords: "SPI,产品名录,SuperPod Pareto Index,超节点,产品登记,互联, -本页由构建脚本自动扫描 `spi/products/` 目录生成。生成日期：2026-03-31。 +本页由构建脚本自动扫描 `spi/products/` 目录生成。生成日期：2026-08-10。 当前仓库共收录 **1** 个产品条目。 diff --git a/src/contributing.md b/src/contributing.md index 52ebcf23..913f2476 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -14,15 +14,26 @@ keywords: "MkDocs,Material,Markdown,Admonitions,Mermaid,Vega-Lite,脚注,项目 ## 项目结构 ```bash -. -├── mkdocs.yml # 站点配置文件 -├── requirements.txt # Python 依赖 -├── src/ # 文档源文件 -│ ├── assets/ # 静态资源（图片、CSS、JS） -│ ├── 01-architecture/ -│ ├── ... -│ └── index.md # 首页 -└── overrides/ # 主题覆盖模板 +superpod-whitepaper/ +├── mkdocs.yml # MkDocs 配置文件 +├── pyproject.toml # Python 项目配置 +├── Makefile # 构建脚本 +├── README.md # 本文件 +├── overrides/ # 模板覆盖 +│ └── main.html +└── src/ # 文档源文件 + ├── index.md # 首页 + ├── architecture/ # 架构分析 + ├── software/ # 软件系统 + ├── simulation/ # 建模仿真 + ├── reference-designs/ # 参考设计 + ├── future/ # 未来演进 + ├── conclusion.md # 总结 + ├── appendix.md # 附录 + └── assets/ # 静态资源 + ├── stylesheets/ + ├── images/ + └── javascripts/ ``` ## 常用排版语法