From b42fc56966157a9902bcb623ee313278bddc17fd Mon Sep 17 00:00:00 2001 From: tianhao909 <843101550@qq.com> Date: Wed, 18 Mar 2026 05:22:19 +0000 Subject: [PATCH 1/3] docs: complete bilingual EN/ZH documentation system for SimAI 1.6 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build a comprehensive bilingual (English/Chinese) documentation system covering: - SimAI 1.6 Technical Report (EN/ZH) with GPU memory inference architecture - Complete user guides: installation, quickstart, workload generation, simulation - Developer guides: contributing, architecture overview - Project READMEs in EN/ZH/JA with feature highlights and quickstart - vidur-alibabacloud module documentation (EN/ZH + original Vidur README) - CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CHANGELOG in bilingual format 构建全面的双语（中英文）文档体系，涵盖： - SimAI 1.6 技术报告（中英文），含 GPU 内存推理架构说明 - 完整用户指南：安装、快速开始、工作负载生成、仿真运行 - 开发者指南：贡献指南、架构概览 - 项目 README 中英日三语版本，含功能亮点与快速开始 - vidur-alibabacloud 模块文档（中英文 + 原始 Vidur README） - CONTRIBUTING、SECURITY、CODE_OF_CONDUCT、CHANGELOG 双语版本 Co-authored-by: tianhao909 <843101550@qq.com> Co-authored-by: MXtremist <44829997+MXtremist@users.noreply.github.com> --- CHANGELOG.md | 62 +++ CHANGELOG_CN.md | 62 +++ CODE_OF_CONDUCT.md | 136 ++++++ CODE_OF_CONDUCT_CN.md | 91 ++++ CONTRIBUTING.md | 487 +++++++++++++++++++ CONTRIBUTING.zh-CN.md | 487 +++++++++++++++++++ README.ja.md | 3 +- README.md | 129 +++-- README_CN.md | 273 +++++++++++ SECURITY.md | 47 ++ SECURITY_CN.md | 47 ++ docs/SimAI_1.6_Tech_Report.md | 429 ++++++++++++++++ docs/SimAI_1.6_Tech_Report_CN.md | 429 ++++++++++++++++ docs/en/benchmarking/index.md | 33 ++ docs/en/benchmarking/test_suite.md | 139 ++++++ docs/en/community/index.md | 90 ++++ docs/en/components/aicb.md | 212 ++++++++ docs/en/components/astra_sim.md | 147 ++++++ docs/en/components/index.md | 80 +++ docs/en/components/ns3.md | 175 +++++++ docs/en/components/simccl.md | 82 ++++ docs/en/components/vidur.md | 196 ++++++++ docs/en/developer_guide/adding_models.md | 204 ++++++++ docs/en/developer_guide/architecture.md | 176 +++++++ docs/en/developer_guide/contributing.md | 224 +++++++++ docs/en/developer_guide/extending_ns3.md | 219 +++++++++ docs/en/developer_guide/index.md | 25 + docs/en/getting_started/index.md | 25 + docs/en/getting_started/installation.md | 96 ++++ docs/en/getting_started/quickstart.md | 85 ++++ docs/en/index.md | 73 +++ docs/en/technical_reference/cli_reference.md | 185 +++++++ docs/en/technical_reference/configuration.md | 163 +++++++ docs/en/technical_reference/index.md | 13 + docs/en/technical_reference/memory_module.md | 155 ++++++ docs/en/user_guide/index.md | 25 + docs/en/user_guide/inference_simulation.md | 176 +++++++ docs/en/user_guide/result_analysis.md | 183 +++++++ docs/en/user_guide/simai_analytical.md | 104 ++++ docs/en/user_guide/simai_physical.md | 123 +++++ docs/en/user_guide/simai_simulation.md | 113 +++++ docs/en/user_guide/supported_models.md | 141 ++++++ docs/en/user_guide/workload_generation.md | 160 ++++++ docs/images/simai_dingtalk.jpg | Bin 94912 -> 305265 bytes docs/images/simai_wechat.jpeg | Bin 158457 -> 268153 bytes docs/zh/benchmarking/index.md | 33 ++ docs/zh/benchmarking/test_suite.md | 139 ++++++ docs/zh/community/index.md | 91 ++++ docs/zh/components/aicb.md | 212 ++++++++ docs/zh/components/astra_sim.md | 147 ++++++ docs/zh/components/index.md | 80 +++ docs/zh/components/ns3.md | 175 +++++++ docs/zh/components/simccl.md | 82 ++++ docs/zh/components/vidur.md | 194 ++++++++ docs/zh/developer_guide/adding_models.md | 204 ++++++++ docs/zh/developer_guide/architecture.md | 176 +++++++ docs/zh/developer_guide/contributing.md | 224 +++++++++ docs/zh/developer_guide/extending_ns3.md | 219 +++++++++ docs/zh/developer_guide/index.md | 25 + docs/zh/getting_started/index.md | 25 + docs/zh/getting_started/installation.md | 96 ++++ docs/zh/getting_started/quickstart.md | 85 ++++ docs/zh/index.md | 73 +++ docs/zh/technical_reference/cli_reference.md | 185 +++++++ docs/zh/technical_reference/configuration.md | 163 +++++++ docs/zh/technical_reference/index.md | 13 + docs/zh/technical_reference/memory_module.md | 155 ++++++ docs/zh/user_guide/index.md | 25 + docs/zh/user_guide/inference_simulation.md | 151 ++++++ docs/zh/user_guide/result_analysis.md | 183 +++++++ docs/zh/user_guide/simai_analytical.md | 104 ++++ docs/zh/user_guide/simai_physical.md | 113 +++++ docs/zh/user_guide/simai_simulation.md | 113 +++++ docs/zh/user_guide/supported_models.md | 133 +++++ docs/zh/user_guide/workload_generation.md | 160 ++++++ vidur-alibabacloud/README-vidur.md | 162 +++++- vidur-alibabacloud/README.md | 314 ++++++++---- vidur-alibabacloud/README_CN.md | 458 +++++++++++++++++ 78 files changed, 11068 insertions(+), 148 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CHANGELOG_CN.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CODE_OF_CONDUCT_CN.md create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.zh-CN.md create mode 100644 README_CN.md create mode 100644 SECURITY.md create mode 100644 SECURITY_CN.md create mode 100644 docs/SimAI_1.6_Tech_Report.md create mode 100644 docs/SimAI_1.6_Tech_Report_CN.md create mode 100644 docs/en/benchmarking/index.md create mode 100644 docs/en/benchmarking/test_suite.md create mode 100644 docs/en/community/index.md create mode 100644 docs/en/components/aicb.md create mode 100644 docs/en/components/astra_sim.md create mode 100644 docs/en/components/index.md create mode 100644 docs/en/components/ns3.md create mode 100644 docs/en/components/simccl.md create mode 100644 docs/en/components/vidur.md create mode 100644 docs/en/developer_guide/adding_models.md create mode 100644 docs/en/developer_guide/architecture.md create mode 100644 docs/en/developer_guide/contributing.md create mode 100644 docs/en/developer_guide/extending_ns3.md create mode 100644 docs/en/developer_guide/index.md create mode 100644 docs/en/getting_started/index.md create mode 100644 docs/en/getting_started/installation.md create mode 100644 docs/en/getting_started/quickstart.md create mode 100644 docs/en/index.md create mode 100644 docs/en/technical_reference/cli_reference.md create mode 100644 docs/en/technical_reference/configuration.md create mode 100644 docs/en/technical_reference/index.md create mode 100644 docs/en/technical_reference/memory_module.md create mode 100644 docs/en/user_guide/index.md create mode 100644 docs/en/user_guide/inference_simulation.md create mode 100644 docs/en/user_guide/result_analysis.md create mode 100644 docs/en/user_guide/simai_analytical.md create mode 100644 docs/en/user_guide/simai_physical.md create mode 100644 docs/en/user_guide/simai_simulation.md create mode 100644 docs/en/user_guide/supported_models.md create mode 100644 docs/en/user_guide/workload_generation.md create mode 100644 docs/zh/benchmarking/index.md create mode 100644 docs/zh/benchmarking/test_suite.md create mode 100644 docs/zh/community/index.md create mode 100644 docs/zh/components/aicb.md create mode 100644 docs/zh/components/astra_sim.md create mode 100644 docs/zh/components/index.md create mode 100644 docs/zh/components/ns3.md create mode 100644 docs/zh/components/simccl.md create mode 100644 docs/zh/components/vidur.md create mode 100644 docs/zh/developer_guide/adding_models.md create mode 100644 docs/zh/developer_guide/architecture.md create mode 100644 docs/zh/developer_guide/contributing.md create mode 100644 docs/zh/developer_guide/extending_ns3.md create mode 100644 docs/zh/developer_guide/index.md create mode 100644 docs/zh/getting_started/index.md create mode 100644 docs/zh/getting_started/installation.md create mode 100644 docs/zh/getting_started/quickstart.md create mode 100644 docs/zh/index.md create mode 100644 docs/zh/technical_reference/cli_reference.md create mode 100644 docs/zh/technical_reference/configuration.md create mode 100644 docs/zh/technical_reference/index.md create mode 100644 docs/zh/technical_reference/memory_module.md create mode 100644 docs/zh/user_guide/index.md create mode 100644 docs/zh/user_guide/inference_simulation.md create mode 100644 docs/zh/user_guide/result_analysis.md create mode 100644 docs/zh/user_guide/simai_analytical.md create mode 100644 docs/zh/user_guide/simai_physical.md create mode 100644 docs/zh/user_guide/simai_simulation.md create mode 100644 docs/zh/user_guide/supported_models.md create mode 100644 docs/zh/user_guide/workload_generation.md create mode 100644 vidur-alibabacloud/README_CN.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..9ad03ac6 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,62 @@ +

+ 中文  ｜  English +

+ +# Changelog + +All notable changes to SimAI will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +> **Note**: This changelog covers v1.0 (initial open-source release) and later versions. + +## [Unreleased] + +## [1.6.0] - 2026-03-16 + +### Added + +- GPU memory calculation module: accurate parameter counting and KV cache management for DeepSeek-V3-671B, Qwen3-MoE-235B, and Qwen3-Next-80B +- PD-separation memory planning for independent Prefill/Decode memory budgets +- Improved AICB decode time estimation with linear interpolation and global cache +- 4-scenario end-to-end inference test suite (`run_scenarios.sh`) +- SimAI 1.6 Technical Report (EN/ZH) +- Complete bilingual documentation system (30+ files under `docs/en/`, `docs/zh/`) +- GitHub community health files: issue/PR templates, Code of Conduct, Security Policy, Contributing Guide + +### Changed + +- Replaced print statements with logging across vidur-alibabacloud modules +- Added bilingual docstrings for public APIs +- Standardized TODO comments format + +### Removed + +- Removed ~390 lines of dead code in vidur-alibabacloud +- Cleaned personal debug markers across 8 files + +## [1.5.0] - 2025-12-30 + +### Added + +- **End-to-end multi-request inference simulation**: Full simulation support for multi-request inference workloads. +- **Prefill/Decode separation**: Model complex inference scenarios with Prefill/Decode phase separation. +- **Modern model support**: Added support for DeepSeek, Qwen3-MoE, and Qwen3-Next models. +- **Request scheduling via Vidur**: Integrated request scheduling component adapted from Microsoft's [Vidur](https://github.com/microsoft/vidur) (see [vidur-alibabacloud](./vidur-alibabacloud/)). +- **AICB inference workload generation**: AICB now supports generating prefill/decode inference workloads for DeepSeek, Qwen3-MoE, and Qwen3-Next. +- **DeepSeek training workload support**: AICB now supports generating training workloads for DeepSeek (contributed by [@parthpower](https://github.com/parthpower)). +- **SimCCL initial release**: First public release of the SimCCL collective communication transformation module. + +## [1.0.0] - 2024-10-18 + +### Added + +- Initial open-source release of SimAI: full-stack simulator for AI large-scale training +- Core components: AICB, SimCCL, astra-sim-alibabacloud, ns-3-alibabacloud +- SimAI-Analytical: fast simulation using bus bandwidth abstraction +- SimAI-Simulation: full-stack NS3-based network simulation +- SimAI-Physical (Beta): CPU RDMA cluster physical traffic generation + +### Academic + +- SimAI paper accepted by **NSDI'25 Spring**. See [paper](https://arxiv.org/abs/2410.07346). diff --git a/CHANGELOG_CN.md b/CHANGELOG_CN.md new file mode 100644 index 00000000..a9e50a03 --- /dev/null +++ b/CHANGELOG_CN.md @@ -0,0 +1,62 @@ +

+ 中文  ｜  English +

+ +# 更新日志 + +SimAI 的所有重要变更均记录在此文件中。 + +格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)。 + +> **注意**：本更新日志涵盖 v1.0（首次开源发布）及之后的版本。 + +## [未发布] + +## [1.6.0] - 2026-03-16 + +### 新增 + +- GPU 内存计算模块：支持 DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B 的精确参数计数与 KV Cache 管理 +- PD 分离内存规划：Prefill/Decode 阶段独立的内存预算计算 +- 改进 AICB decode 时间估算（首尾线性插值 + 全局缓存） +- 4 场景端到端推理测试套件（`run_scenarios.sh`） +- SimAI 1.6 技术报告（EN/ZH） +- 完整双语文档系统（`docs/en/`、`docs/zh/` 下 30+ 文件） +- GitHub 社区规范文件：Issue/PR 模板、行为准则、安全政策、贡献指南 + +### 变更 + +- vidur-alibabacloud 各模块 print 输出替换为 logging +- 公开 API 添加双语 docstring +- TODO 注释格式统一规范化 + +### 移除 + +- 清理 vidur-alibabacloud 中约 390 行死代码 +- 清理 8 个文件中的个人调试标记 + +## [1.5.0] - 2025-12-30 + +### 新增 + +- **端到端多请求推理仿真**：全面支持多请求推理工作负载的端到端仿真。 +- **Prefill/Decode 分离**：支持 Prefill/Decode 阶段分离等复杂推理场景建模。 +- **主流模型支持**：新增对 DeepSeek、Qwen3-MoE 和 Qwen3-Next 模型的支持。 +- **基于 Vidur 的请求调度**：集成了基于微软 [Vidur](https://github.com/microsoft/vidur) 适配的请求调度组件（详见 [vidur-alibabacloud](./vidur-alibabacloud/)）。 +- **AICB 推理工作负载生成**：AICB 现已支持为 DeepSeek、Qwen3-MoE 和 Qwen3-Next 生成 prefill/decode 推理工作负载。 +- **DeepSeek 训练工作负载支持**：AICB 新增 DeepSeek 训练工作负载生成支持（由 [@parthpower](https://github.com/parthpower) 贡献）。 +- **SimCCL 首次发布**：SimCCL 集合通信转换模块首次对外公开发布。 + +## [1.0.0] - 2024-10-18 + +### 新增 + +- SimAI 首次开源发布：业界首个全栈高精度 AI 大规模训练模拟器 +- 核心组件：AICB、SimCCL、astra-sim-alibabacloud、ns-3-alibabacloud +- SimAI-Analytical：基于总线带宽抽象的快速仿真 +- SimAI-Simulation：基于 NS3 的全栈网络仿真 +- SimAI-Physical（Beta）：CPU RDMA 集群物理流量生成 + +### 学术 + +- SimAI 论文被 **NSDI'25 Spring** 接收。详见 [论文](https://arxiv.org/abs/2410.07346)。 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..1a84e5ce --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,136 @@ +

+ 中文  ｜  English +

+ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at: + +* yunding.lg@alibaba-inc.com +* xuefeiyang.xfy@alibaba-inc.com +* qingxu.lqx@alibaba-inc.com + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CODE_OF_CONDUCT_CN.md b/CODE_OF_CONDUCT_CN.md new file mode 100644 index 00000000..79faac72 --- /dev/null +++ b/CODE_OF_CONDUCT_CN.md @@ -0,0 +1,91 @@ +

+ 中文  ｜  English +

+ +# 贡献者公约行为准则 + +## 我们的承诺 + +作为成员、贡献者和领导者，我们承诺让参与我们社区的每个人都能获得无骚扰的体验，无论其年龄、体型、可见或不可见的残疾、种族、性别特征、性别认同与表达、经验水平、受教育程度、社会经济地位、国籍、个人外貌、种族、宗教或性取向如何。 + +我们承诺以有助于建设开放、包容、多元、友好和健康社区的方式行事与互动。 + +## 我们的标准 + +有助于为我们社区创造积极环境的行为示例包括： + +* 对他人表现出同理心和善意 +* 尊重不同的意见、观点和经历 +* 给予建设性的反馈，并能优雅地接受建设性反馈 +* 承担责任，向受到我们错误影响的人道歉，并从中学习 +* 关注对整个社区最有利的事情，而不仅仅是对个人最有利的事情 + +不可接受的行为示例包括： + +* 使用性暗示的语言或图像，以及任何形式的性关注或性挑逗 +* 恶意评论、侮辱性或贬损性言论，以及人身攻击或政治攻击 +* 公开或私下的骚扰行为 +* 未经明确许可，发布他人的私人信息（如实际地址或电子邮件地址） +* 在职业环境中可能被合理认为不适当的其他行为 + +## 执行职责 + +社区领导者负责阐明和执行我们的可接受行为标准，并将对任何被认为不适当、威胁性、冒犯性或有害的行为采取适当且公平的纠正措施。 + +社区领导者有权利和责任删除、编辑或拒绝与本行为准则不一致的评论、提交、代码、Wiki 编辑、Issue 及其他贡献，并在适当时说明审核决定的原因。 + +## 适用范围 + +本行为准则适用于所有社区空间，也适用于个人在公共场合正式代表社区的情形。代表我们社区的示例包括：使用官方电子邮件地址、通过官方社交媒体账户发帖，或在线上或线下活动中担任指定代表。 + +## 执行 + +若发生滥用、骚扰或其他不可接受的行为，可向负责执行的社区领导者举报： + +* yunding.lg@alibaba-inc.com +* xuefeiyang.xfy@alibaba-inc.com +* qingxu.lqx@alibaba-inc.com + +所有投诉都将得到及时、公平的审查和调查。 + +所有社区领导者都有义务尊重任何事件举报者的隐私和安全。 + +## 执行指南 + +社区领导者在确定违反本行为准则的行为的处理后果时，将遵循以下社区影响指南： + +### 1. 纠正 + +**社区影响**：使用不恰当的语言或其他被认为在社区中不专业或不受欢迎的行为。 + +**处理结果**：由社区领导者发出私下书面警告，说明违规行为的性质，并解释为何该行为不恰当。可能要求公开道歉。 + +### 2. 警告 + +**社区影响**：通过单一事件或一系列行为造成的违规。 + +**处理结果**：发出警告，并说明持续此类行为的后果。在规定时间内，禁止与相关人员互动，包括禁止与执行行为准则的人员进行未经请求的互动。这包括避免在社区空间以及社交媒体等外部渠道进行互动。违反这些条款可能导致临时或永久禁止参与。 + +### 3. 临时禁止 + +**社区影响**：严重违反社区标准，包括持续的不适当行为。 + +**处理结果**：在规定时间内，临时禁止与社区进行任何形式的互动或公开交流。在此期间，禁止与相关人员进行任何公开或私下互动，包括禁止与执行行为准则的人员进行未经请求的互动。违反这些条款可能导致永久禁止参与。 + +### 4. 永久禁止 + +**社区影响**：表现出违反社区标准的规律性行为，包括持续的不适当行为、骚扰某个人，或对某类人群的攻击或贬低。 + +**处理结果**：永久禁止在社区内进行任何形式的公开互动。 + +## 署名 + +本行为准则改编自 [贡献者公约][homepage] 2.0 版本， +原文见 https://www.contributor-covenant.org/version/2/0/code_of_conduct.html。 + +社区影响指南参考了 [Mozilla 的行为准则执行阶梯](https://github.com/mozilla/diversity)。 + +[homepage]: https://www.contributor-covenant.org + +有关本行为准则常见问题的解答，请参阅 https://www.contributor-covenant.org/faq。 +译文见 https://www.contributor-covenant.org/translations。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a6a3658b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,487 @@ +# Contributing to SimAI + +[中文版](CONTRIBUTING.zh-CN.md) + +Thank you for your interest in contributing to SimAI! This guide will help you get started with contributing code, documentation, and ideas. + +--- + +## What We're Building + +**Vision**: The industry's first full-stack, high-precision simulator for AI large-scale inference and training. + +**Goal**: Provide end-to-end modeling and simulation of AI training/inference processes—encompassing framework, collective communication, network layers, and more—so researchers can analyze performance, evaluate optimizations, and explore infrastructure designs without real hardware. + +**Current Progress**: SimAI 1.5 released (Dec 2025), with end-to-end multi-request inference simulation, DeepSeek/Qwen3 model support, and Prefill/Decode separation. + +**Academic Background**: Accepted by NSDI'25 Spring. See our [paper](https://arxiv.org/abs/2410.07346) for technical details. + +--- + +## How to Contribute + +### Ways to Contribute + +1. **New features** — Add model support, parallelism strategies, scheduling policies, etc. +2. **Bug fixes** — Fix simulation inaccuracies, crashes, or incorrect results +3. **Performance optimization** — Improve simulation speed, memory usage, or scalability +4. **Documentation** — Improve tutorials, add examples, fix errors +5. **Benchmarks & validation** — Add validation against real hardware results +6. **Issue reports** — Report bugs, request features, or share feedback + +--- + +## Project Architecture + +SimAI is a modular project composed of 5 core submodules (Git submodules) and several supporting directories: + +``` +SimAI/ +├── aicb/ # AI Computation Benchmark — workload generation (Python) +│ ├── workload_generator/ # Generates training/inference workloads +│ └── aicb.py # Main entry point +├── astra-sim-alibabacloud/ # Simulation engine — core simulator (C++) +│ ├── astra-sim/ # Extended from astra-sim 1.0 +│ └── build.sh # Build script +├── ns-3-alibabacloud/ # NS-3 network simulator backend (C++) +├── vidur-alibabacloud/ # LLM inference simulation (Python) +│ ├── vidur/ # Core simulation framework +│ └── setup.py # Python package config +├── SimCCL/ # Collective communication transformation +├── docs/ # Documentation and tutorials +├── example/ # Example workloads and configurations +├── scripts/ # Build and utility scripts +│ └── build.sh # Main build script +├── results/ # Simulation output directory +├── bin/ # Compiled binary output +├── Dockerfile # Docker container definition +└── README.md # Project documentation +``` + +--- + +## Development Environment Setup + +### Prerequisites + +- **Python** 3.8+ (3.12 recommended with Docker image) +- **CMake** 3.16+ +- **GCC/G++** 9.4+ +- **Git** with submodule support + +### Option A: Docker (Recommended) + +```bash +# Build the Docker image +docker build -t simai:latest . + +# Run a container with GPU support +docker run --gpus all -it --rm \ + -v $(pwd)/results:/workspace/SimAI/results \ + simai:latest /bin/bash +``` + +### Option B: Build from Source + +```bash +# 1. Clone with submodules +git clone --recurse-submodules https://github.com/aliyun/SimAI.git +cd SimAI + +# 2. Build C++ components (choose one mode) +# Analytical mode (fast, no network detail): +bash scripts/build.sh -c analytical + +# NS-3 simulation mode (full-stack, detailed network): +bash scripts/build.sh -c ns3 + +# Physical mode (beta, RDMA clusters): +bash scripts/build.sh -c phy + +# 3. Install Python dependencies +pip install -r aicb/requirements.txt +pip install -r vidur-alibabacloud/requirements.txt + +# 4. Verify the build +ls bin/ # Should contain SimAI_analytical or SimAI_simulator +``` + +### Verify Installation + +```bash +# Quick check: run a simple analytical simulation +cd bin +./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml +``` + +--- + +## Working with Submodules + +SimAI uses Git submodules for its core components. Understanding this is crucial for contributing. + +### Submodule Overview + +| Submodule | Repository | Language | Description | +|-----------|-----------|----------|-------------| +| `aicb` | [aliyun/aicb](https://github.com/aliyun/aicb) | Python | Workload generation | +| `SimCCL` | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | Python | Collective communication | +| `ns-3-alibabacloud` | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | C++ | Network simulation | +| `astra-sim-alibabacloud` | In-tree | C++ | Simulation engine | +| `vidur-alibabacloud` | In-tree | Python | Inference simulation | + +### Key Rules + +1. **Submodules have independent Git histories.** Changes inside a submodule directory are tracked by that submodule's own repo, not the parent. +2. **The parent repo only tracks the commit hash** of each submodule. After modifying a submodule, you must commit in both the submodule and the parent repo. +3. **Always initialize submodules** after cloning: + ```bash + git submodule update --init --recursive + ``` + +### Cross-Submodule Changes + +If your contribution spans multiple submodules (e.g., adding a new model in `aicb` and simulation support in `astra-sim-alibabacloud`): + +1. Make and commit changes in each submodule separately +2. Update the parent repo to point to the new submodule commits +3. Create separate PRs for each submodule repository if they have independent remotes +4. Reference the related PRs in your descriptions + +--- + +## Development Workflow + +### Step 1: Fork and Clone + +```bash +# Fork the repository on GitHub, then: +git clone --recurse-submodules https://github.com/YOUR_USERNAME/SimAI.git +cd SimAI + +# Add upstream remote +git remote add upstream https://github.com/aliyun/SimAI.git +``` + +### Step 2: Create a Feature Branch + +```bash +# Sync with upstream first +git fetch upstream +git checkout -b feature/your-feature-name upstream/master + +# Branch naming conventions: +# feature/xxx — New features +# fix/xxx — Bug fixes +# docs/xxx — Documentation +# perf/xxx — Performance improvements +# refactor/xxx — Code refactoring +``` + +### Step 3: Develop and Test + +```bash +# Make your changes... +# Run relevant tests (see Testing section below) + +# For C++ changes, rebuild: +bash scripts/build.sh -c analytical # or ns3 + +# For Python changes, verify imports and basic functionality +python -c "from aicb import ..." +``` + +### Step 4: Commit Your Changes + +```bash +# Stage your changes +git add -A + +# Commit with a descriptive message (see Commit Convention below) +git commit -m "feat(aicb): add Llama-4 model workload generation" +``` + +### Step 5: Push and Create PR + +```bash +# Push to your fork +git push origin feature/your-feature-name + +# Then create a Pull Request on GitHub +``` + +--- + +## Code Style + +### Python + +- **Formatter**: [black](https://github.com/psf/black) (default settings) +- **Import sorting**: [isort](https://pycqa.github.io/isort/) (compatible with black) +- **Linter**: [flake8](https://flake8.pycqa.org/) +- **Max line length**: 120 characters + +```bash +# Format your Python code +black --line-length 120 your_file.py +isort your_file.py +flake8 your_file.py --max-line-length 120 +``` + +### C++ + +- Follow the existing code style in `astra-sim-alibabacloud/` +- Use 4-space indentation +- Keep function and variable names in `snake_case` +- Add comments for non-trivial logic + +### Shell Scripts + +- Use `#!/bin/bash` shebang +- Quote all variables: `"${VAR}"` not `$VAR` +- Use `set -e` for error handling where appropriate + +### General Rules + +- Write comments in **English** +- All new functions/classes should have docstrings or header comments +- Avoid hardcoded paths; use relative paths or configuration variables +- Keep changes focused — one feature/fix per PR + +--- + +## Commit Message Convention + +Use [Conventional Commits](https://www.conventionalcommits.org/) format: + +``` +(): + +[optional body] + +[optional footer] +``` + +### Types + +| Type | Description | +|------|-------------| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation only | +| `refactor` | Code refactoring (no feature/fix) | +| `test` | Adding or updating tests | +| `perf` | Performance improvement | +| `chore` | Build process, tooling, dependencies | + +### Scopes + +`aicb`, `vidur`, `astra-sim`, `ns3`, `simccl`, `docs`, `docker`, `scripts` + +### Examples + +**Good:** +``` +feat(aicb): add DeepSeek-V3 inference workload generation +fix(astra-sim): correct AllReduce latency calculation for ring algorithm +docs: update build instructions for NS-3 mode +perf(vidur): reduce memory allocation in request scheduler +``` + +**Bad:** +``` +update code # Too vague +fix bug # No scope, no description +feat(aicb): Add DeepSeek-V3 inference workload generation support for the new model architecture # Too long +``` + +--- + +## Pull Request Guidelines + +### PR Title + +Use the same format as commit messages: `(): ` + +### PR Description Template + +```markdown +## Summary +Brief description of what this PR does. + +## Changes +- Change 1 +- Change 2 + +## Testing +Describe how you tested these changes. + +## Related Issues +Closes #xxx (if applicable) + +## Checklist +- [ ] Code compiles without errors +- [ ] Existing simulations produce unchanged results (no precision regression) +- [ ] New code has appropriate comments +- [ ] Tests added for new functionality +- [ ] Documentation updated if needed +``` + +--- + +## Testing + +### Training Simulation (Analytical Mode) + +```bash +# Generate a training workload +cd aicb +python aicb.py -m training --model_name GPT-175B + +# Run analytical simulation +cd ../bin +./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml +``` + +### Training Simulation (NS-3 Mode) + +```bash +# Build NS-3 backend first +bash scripts/build.sh -c ns3 + +# Run full-stack simulation +cd bin +./SimAI_simulator [simulation_parameters] +``` + +### Inference Simulation + +```bash +# Run inference simulation via vidur +cd vidur-alibabacloud +python -m vidur.main [config_options] +``` + +### Verify No Regression + +When modifying simulation logic, always compare results against a known-good baseline: + +```bash +# Save baseline results before your changes +cp results/output_baseline.csv /tmp/baseline.csv + +# After changes, compare +diff results/output_baseline.csv /tmp/baseline.csv +``` + +--- + +## Pre-Submission Quality Checklist + +Before submitting your PR, run through this checklist: + +```bash +# 1. C++ compilation check (if you changed C++ code) +bash scripts/build.sh -c analytical +bash scripts/build.sh -c ns3 + +# 2. Python lint check +black --check --line-length 120 your_changed_files.py +flake8 your_changed_files.py --max-line-length 120 + +# 3. Basic simulation test +cd bin && ./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml + +# 4. Submodule state check +git submodule status # Ensure no unexpected submodule changes + +# 5. Verify no unintended files +git diff --stat # Review all changes before committing +``` + +**Checklist Summary:** +- [ ] C++ code compiles without errors or warnings +- [ ] Python code passes lint checks (black, flake8) +- [ ] Basic simulation runs successfully +- [ ] No unintended submodule pointer changes +- [ ] Commit messages follow the convention +- [ ] PR description is complete + +--- + +## Review Process and Acceptance Criteria + +### Acceptance Criteria + +Your contribution will be accepted if it meets these standards: + +| Criterion | Requirement | +|-----------|-------------| +| **Build** | Compiles without errors (C++ and Python) | +| **Precision** | Does not degrade existing simulation accuracy | +| **Tests** | Key code paths are covered by tests or validated | +| **Documentation** | New features have comments and/or doc updates | +| **Style** | Follows the code style guidelines above | +| **Scope** | Changes are focused and well-explained | + +### Reasons for Rejection + +- Build failures +- Simulation precision regression without justification +- Missing tests for new functionality +- Overly large PRs mixing unrelated changes +- Insufficient description of what/why + +### Review Timeline + +1. **Initial review**: Within 3-5 business days +2. **Feedback**: Constructive comments with actionable suggestions +3. **Iteration**: Address feedback and update PR +4. **Merge**: Approved PRs are merged to the main branch + +--- + +## What NOT to Contribute + +- Proprietary or closed-source dependencies +- Changes that break backward compatibility without discussion +- Large-scale reformatting changes (open an issue first) +- Untested code in simulation-critical paths +- Commits with sensitive information (API keys, internal URLs, etc.) + +--- + +## Recognition + +Contributors will be: +- Acknowledged in release notes +- Listed in project documentation +- Credited in commit history + +Significant contributors may be invited to join the maintainer team. + +--- + +## Getting Help + +- **Issues**: [GitHub Issues](https://github.com/aliyun/SimAI/issues) +- **Discussions**: Open an issue with "Question:" prefix +- **Documentation**: See [docs/Tutorial.md](docs/Tutorial.md) for detailed usage guides +- **Community Events**: Check [README.md](README.md) for upcoming events and workshops + +--- + +## Thank You! + +SimAI is built by a growing community of researchers and engineers. Your contributions help advance AI systems research for everyone. + +**Let's build something amazing together!** diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 00000000..4d27c930 --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,487 @@ +# SimAI 贡献指南 + +[English Version](CONTRIBUTING.md) + +感谢你对 SimAI 项目的关注！本指南将帮助你了解如何贡献代码、文档和想法。 + +--- + +## 项目愿景与目标 + +**愿景**：打造业界首个全栈、高精度的 AI 大规模推理与训练仿真器。 + +**目标**：提供端到端的 AI 训练/推理过程建模与仿真——涵盖框架层、集合通信层、网络层等——使研究人员无需真实硬件即可分析性能、评估优化方案、探索基础设施设计。 + +**当前进展**：SimAI 1.5 已发布（2025年12月），支持端到端多请求推理仿真、DeepSeek/Qwen3 模型、Prefill/Decode 分离。 + +**学术背景**：已被 NSDI'25 Spring 接收。技术细节请参阅我们的[论文](https://arxiv.org/abs/2410.07346)。 + +--- + +## 贡献方式 + +### 你可以通过以下方式参与贡献 + +1. **新功能开发** — 添加模型支持、并行策略、调度策略等 +2. **Bug 修复** — 修复仿真精度问题、崩溃或错误结果 +3. **性能优化** — 提升仿真速度、内存使用或可扩展性 +4. **文档改进** — 完善教程、添加示例、修正错误 +5. **基准测试与验证** — 添加与真实硬件结果的对比验证 +6. **Issue 报告** — 报告 Bug、提出需求或分享反馈 + +--- + +## 项目架构 + +SimAI 是一个模块化项目，由 5 个核心子模块（Git submodules）和若干辅助目录组成： + +``` +SimAI/ +├── aicb/ # AI 计算基准 — 工作负载生成（Python） +│ ├── workload_generator/ # 训练/推理工作负载生成器 +│ └── aicb.py # 主入口 +├── astra-sim-alibabacloud/ # 仿真引擎 — 核心仿真器（C++） +│ ├── astra-sim/ # 基于 astra-sim 1.0 扩展 +│ └── build.sh # 编译脚本 +├── ns-3-alibabacloud/ # NS-3 网络仿真后端（C++） +├── vidur-alibabacloud/ # LLM 推理仿真框架（Python） +│ ├── vidur/ # 核心仿真框架 +│ └── setup.py # Python 包配置 +├── SimCCL/ # 集合通信变换库 +├── docs/ # 文档与教程 +├── example/ # 示例工作负载和配置 +├── scripts/ # 构建和工具脚本 +│ └── build.sh # 主编译脚本 +├── results/ # 仿真结果输出目录 +├── bin/ # 编译产物目录 +├── Dockerfile # Docker 容器定义 +└── README.md # 项目文档 +``` + +--- + +## 开发环境搭建 + +### 前置依赖 + +- **Python** 3.8+（Docker 镜像中推荐 3.12） +- **CMake** 3.16+ +- **GCC/G++** 9.4+ +- **Git**（支持 submodule） + +### 方式一：Docker（推荐） + +```bash +# 构建 Docker 镜像 +docker build -t simai:latest . + +# 启动容器（支持 GPU） +docker run --gpus all -it --rm \ + -v $(pwd)/results:/workspace/SimAI/results \ + simai:latest /bin/bash +``` + +### 方式二：源码编译 + +```bash +# 1. 克隆仓库（含子模块） +git clone --recurse-submodules https://github.com/aliyun/SimAI.git +cd SimAI + +# 2. 编译 C++ 组件（选择一种模式） +# 分析模式（快速仿真，不含网络细节）： +bash scripts/build.sh -c analytical + +# NS-3 仿真模式（全栈，详细网络建模）： +bash scripts/build.sh -c ns3 + +# 物理模式（Beta，RDMA 集群）： +bash scripts/build.sh -c phy + +# 3. 安装 Python 依赖 +pip install -r aicb/requirements.txt +pip install -r vidur-alibabacloud/requirements.txt + +# 4. 验证编译结果 +ls bin/ # 应包含 SimAI_analytical 或 SimAI_simulator +``` + +### 验证安装 + +```bash +# 快速测试：运行一个简单的分析仿真 +cd bin +./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml +``` + +--- + +## 子模块开发指南 + +SimAI 使用 Git submodule 管理核心组件。理解子模块的工作方式对于贡献至关重要。 + +### 子模块概览 + +| 子模块 | 仓库 | 语言 | 说明 | +|--------|------|------|------| +| `aicb` | [aliyun/aicb](https://github.com/aliyun/aicb) | Python | 工作负载生成 | +| `SimCCL` | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | Python | 集合通信变换 | +| `ns-3-alibabacloud` | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | C++ | 网络仿真 | +| `astra-sim-alibabacloud` | 仓库内 | C++ | 仿真引擎 | +| `vidur-alibabacloud` | 仓库内 | Python | 推理仿真 | + +### 关键规则 + +1. **子模块有独立的 Git 历史。** 子模块目录内的更改由该子模块自身的仓库跟踪，而非父仓库。 +2. **父仓库只跟踪子模块的 commit hash。** 修改子模块后，需在子模块和父仓库中分别提交。 +3. **克隆后务必初始化子模块：** + ```bash + git submodule update --init --recursive + ``` + +### 跨子模块修改 + +如果你的贡献涉及多个子模块（例如在 `aicb` 中添加新模型，同时在 `astra-sim-alibabacloud` 中添加仿真支持）： + +1. 在每个子模块中分别修改并提交 +2. 更新父仓库，指向子模块的新 commit +3. 如果子模块有独立的远程仓库，需分别创建 PR +4. 在 PR 描述中互相引用关联的 PR + +--- + +## 开发工作流 + +### 第一步：Fork 和 Clone + +```bash +# 先在 GitHub 上 Fork 仓库，然后： +git clone --recurse-submodules https://github.com/YOUR_USERNAME/SimAI.git +cd SimAI + +# 添加上游远程仓库 +git remote add upstream https://github.com/aliyun/SimAI.git +``` + +### 第二步：创建功能分支 + +```bash +# 先同步上游代码 +git fetch upstream +git checkout -b feature/your-feature-name upstream/master + +# 分支命名约定： +# feature/xxx — 新功能 +# fix/xxx — Bug 修复 +# docs/xxx — 文档更新 +# perf/xxx — 性能优化 +# refactor/xxx — 代码重构 +``` + +### 第三步：开发与测试 + +```bash +# 进行修改... +# 运行相关测试（见下方"测试要求"章节） + +# C++ 代码修改后需重新编译： +bash scripts/build.sh -c analytical # 或 ns3 + +# Python 代码修改后，验证导入和基本功能： +python -c "from aicb import ..." +``` + +### 第四步：提交变更 + +```bash +# 暂存更改 +git add -A + +# 使用规范的提交消息（见下方 Commit 规范） +git commit -m "feat(aicb): add Llama-4 model workload generation" +``` + +### 第五步：推送并创建 PR + +```bash +# 推送到你的 Fork +git push origin feature/your-feature-name + +# 然后在 GitHub 上创建 Pull Request +``` + +--- + +## 代码规范 + +### Python + +- **格式化工具**：[black](https://github.com/psf/black)（默认设置） +- **导入排序**：[isort](https://pycqa.github.io/isort/)（兼容 black） +- **静态检查**：[flake8](https://flake8.pycqa.org/) +- **最大行宽**：120 字符 + +```bash +# 格式化 Python 代码 +black --line-length 120 your_file.py +isort your_file.py +flake8 your_file.py --max-line-length 120 +``` + +### C++ + +- 遵循 `astra-sim-alibabacloud/` 中现有的代码风格 +- 使用 4 空格缩进 +- 函数和变量名使用 `snake_case` +- 为非平凡逻辑添加注释 + +### Shell 脚本 + +- 使用 `#!/bin/bash` 声明 +- 变量一律加引号：`"${VAR}"` 而非 `$VAR` +- 适当使用 `set -e` 进行错误处理 + +### 通用规则 + +- 代码注释使用**英文** +- 所有新函数/类应有文档字符串或头注释 +- 避免硬编码路径，使用相对路径或配置变量 +- 保持改动聚焦——每个 PR 只做一件事 + +--- + +## Commit 消息规范 + +使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： + +``` +(): + +[可选的正文] + +[可选的脚注] +``` + +### 类型（Type） + +| 类型 | 说明 | +|------|------| +| `feat` | 新功能 | +| `fix` | Bug 修复 | +| `docs` | 仅文档变更 | +| `refactor` | 代码重构（非新功能/修复） | +| `test` | 添加或更新测试 | +| `perf` | 性能优化 | +| `chore` | 构建流程、工具、依赖 | + +### 作用域（Scope） + +`aicb`、`vidur`、`astra-sim`、`ns3`、`simccl`、`docs`、`docker`、`scripts` + +### 示例 + +**正确：** +``` +feat(aicb): add DeepSeek-V3 inference workload generation +fix(astra-sim): correct AllReduce latency calculation for ring algorithm +docs: update build instructions for NS-3 mode +perf(vidur): reduce memory allocation in request scheduler +``` + +**错误：** +``` +update code # 太模糊 +fix bug # 无作用域，无描述 +feat(aicb): Add DeepSeek-V3 inference workload generation support for the new model architecture # 太长 +``` + +--- + +## Pull Request 规范 + +### PR 标题 + +与 Commit 消息格式一致：`(): ` + +### PR 描述模板 + +```markdown +## 概述 +简要描述本 PR 的内容。 + +## 变更内容 +- 变更 1 +- 变更 2 + +## 测试方式 +描述你如何测试了这些变更。 + +## 关联 Issue +Closes #xxx（如适用） + +## 自检清单 +- [ ] 代码编译无错误 +- [ ] 现有仿真结果不受影响（无精度回归） +- [ ] 新代码有适当的注释 +- [ ] 为新功能添加了测试 +- [ ] 必要时更新了文档 +``` + +--- + +## 测试要求 + +### 训练仿真测试（分析模式） + +```bash +# 生成训练工作负载 +cd aicb +python aicb.py -m training --model_name GPT-175B + +# 运行分析仿真 +cd ../bin +./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml +``` + +### 训练仿真测试（NS-3 模式） + +```bash +# 先编译 NS-3 后端 +bash scripts/build.sh -c ns3 + +# 运行全栈仿真 +cd bin +./SimAI_simulator [仿真参数] +``` + +### 推理仿真测试 + +```bash +# 通过 vidur 运行推理仿真 +cd vidur-alibabacloud +python -m vidur.main [配置选项] +``` + +### 精度回归验证 + +修改仿真逻辑时，务必与已知基线结果进行对比： + +```bash +# 修改前保存基线结果 +cp results/output_baseline.csv /tmp/baseline.csv + +# 修改后对比 +diff results/output_baseline.csv /tmp/baseline.csv +``` + +--- + +## 提交前质量检查清单 + +提交 PR 之前，请逐项检查： + +```bash +# 1. C++ 编译检查（如果修改了 C++ 代码） +bash scripts/build.sh -c analytical +bash scripts/build.sh -c ns3 + +# 2. Python 代码检查 +black --check --line-length 120 your_changed_files.py +flake8 your_changed_files.py --max-line-length 120 + +# 3. 基本仿真测试 +cd bin && ./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml + +# 4. 子模块状态检查 +git submodule status # 确保没有意外的子模块变更 + +# 5. 确认无遗漏文件 +git diff --stat # 提交前审查所有变更 +``` + +**检查清单总结：** +- [ ] C++ 代码编译无错误或警告 +- [ ] Python 代码通过 lint 检查（black、flake8） +- [ ] 基本仿真运行成功 +- [ ] 无意外的子模块指针变更 +- [ ] Commit 消息符合规范 +- [ ] PR 描述完整 + +--- + +## 审查流程与接受标准 + +### 接受标准 + +你的贡献需要满足以下标准才能被接受： + +| 标准 | 要求 | +|------|------| +| **编译** | C++ 和 Python 代码均无编译/语法错误 | +| **精度** | 不降低现有仿真精度 | +| **测试** | 关键代码路径有测试或验证覆盖 | +| **文档** | 新功能有注释和/或文档更新 | +| **风格** | 遵循上述代码规范 | +| **范围** | 变更聚焦且解释清晰 | + +### 拒绝原因 + +- 编译失败 +- 仿真精度回归且无合理解释 +- 新功能缺少测试 +- PR 过大且混合了不相关的变更 +- 描述不充分 + +### 审查时间线 + +1. **初始审查**：3-5 个工作日内 +2. **反馈**：建设性的意见和可操作的建议 +3. **迭代**：根据反馈更新 PR +4. **合并**：审批通过后合入主分支 + +--- + +## 不接受的贡献 + +- 引入私有或闭源依赖 +- 未经讨论就破坏向后兼容性的变更 +- 大规模格式化变更（请先开 Issue 讨论） +- 仿真关键路径上的未测试代码 +- 包含敏感信息的提交（API 密钥、内部 URL 等） + +--- + +## 致谢与认可 + +贡献者将获得以下认可： +- 在发布说明中致谢 +- 在项目文档中列名 +- 在 commit 历史中署名 + +重要贡献者可能被邀请加入维护者团队。 + +--- + +## 获取帮助 + +- **Issue**：[GitHub Issues](https://github.com/aliyun/SimAI/issues) +- **讨论**：以 "Question:" 前缀开一个 Issue +- **文档**：参阅 [docs/Tutorial.md](docs/Tutorial.md) 获取详细使用指南 +- **社区活动**：查看 [README.md](README.md) 了解近期活动和研讨会 + +--- + +## 感谢 + +SimAI 由一个不断壮大的研究者和工程师社区共同构建。你的每一份贡献都在推动 AI 系统研究的发展。 + +**让我们一起创造更好的未来！** diff --git a/README.ja.md b/README.ja.md index dd96f29f..fd98ac53 100644 --- a/README.ja.md +++ b/README.ja.md @@ -8,12 +8,13 @@ | 日付 | イベント | 場所 | 内容 | 形式 | |:----:|:------|:---------|:--------|:----:| -| 未定 | SimAI 2.0 | 🌐 オンライン | SimAI 2.0のリリース | 💻 バーチャル | +| -- | | | | | ### 🌟 過去のイベント | 日付 | イベント | 場所 | 内容 | 形式 | |:----:|:------|:---------|:--------|:----:| +| 2025年12月30日 | SimAI 1.5 | 🌐 オンライン | SimAI 1.5のリリース | 💻 バーチャル | | 2025年6月4日 | SimAIコミュニティ第1回ワークショップ | 📍 北京大学 | コミュニティ貢献者による3つの講演 | 🎓 現地 | | 2025年5月24日 | 第28回Chinasysワークショップ | 📍 重慶大学 | SimAIに関する招待講演 | 🎓 現地 | | 2024年12月27日 | SimAI技術発表会 | 📍 北京航空航天大学 | SimAI技術共有とディスカッション | 🎓 現地 | diff --git a/README.md b/README.md index 85fbcb63..3edf4667 100755 --- a/README.md +++ b/README.md @@ -1,12 +1,31 @@ +

+ 中文  ｜  English +

+ +# SimAI + +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) +[![NSDI'25](https://img.shields.io/badge/NSDI'25-SimAI-blue.svg)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) + # Latest News ### Recent Updates +- [2026/03] **SimAI 1.6 Released!** This release adds GPU memory modeling for inference simulation. Key features include: + + - **GPU Memory Module:** Accurate parameter counting and KV cache management for DeepSeek-V3-671B, Qwen3-MoE-235B, and Qwen3-Next-80B. See [SimAI 1.6 Tech Report](./docs/SimAI_1.6_Tech_Report.md). + - **PD-Separation Memory Planning:** Independent parameter memory and KV cache budget calculation for Prefill and Decode phases. See [memory_planner.py](./vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py). + - **Improved Decode Time Estimation:** Linear interpolation replacing nearest-neighbor for AICB decode time prediction, with global cache for cross-run reuse. See [execution_time.py](./vidur-alibabacloud/vidur/entities/execution_time.py). + - **4-Scenario Test Suite:** End-to-end validation covering Qwen3-Next-80B, DeepSeek-671B, and Qwen3-MoE-235B. See [run_scenarios.sh](./vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh). + - **Bilingual Documentation:** Complete EN/ZH documentation system. See [English Docs](./docs/en/index.md) | [中文文档](./docs/zh/index.md). + - **GitHub Community Health Files:** Added [Issue Templates](./.github/ISSUE_TEMPLATE/), [PR Template](./.github/pull_request_template.md), [Code of Conduct](./CODE_OF_CONDUCT.md), [Security Policy](./SECURITY.md), [Contributing Guide](./CONTRIBUTING.md), and [Changelog](./CHANGELOG.md). + - **Code Quality:** Replaced print with logging, added bilingual docstrings, removed ~390 lines of dead code, standardized TODOs, and added type annotations across vidur-alibabacloud modules. + - [2025/12] **SimAI 1.5 Released!** This release brings end-to-end simulation for multi-request **inference** workloads. Key features include: - - - **Advanced Inference Simulation:** Model complex scenarios with Prefill/Decode separation. - - **Modern Model Support:** Now includes DeepSeek, Qwen3Moe and Qwen3Next. See [AICB's README](./aicb/README.md) for more detailed information. - - **Request Scheduling:** Request scheduling is now handled by a component adapted from Microsoft's [Vidur](https://github.com/microsoft/vidur). See [Vidur-Alibabacloud's README](./vidur-alibabacloud/README.md) for more detailed information. + + - **Advanced Inference Simulation:** Model complex scenarios with Prefill/Decode separation. + - **Modern Model Support:** Now includes DeepSeek, Qwen3Moe and Qwen3Next. See [AICB's README](./aicb/README.md) for more detailed information. + - **Request Scheduling:** Request scheduling is now handled by a component adapted from Microsoft's [Vidur](https://github.com/microsoft/vidur). See [Vidur-Alibabacloud's README](./vidur-alibabacloud/README.md) for more detailed information. - [2025/11] [AICB](https://github.com/aliyun/aicb/tree/master) now supports generating **prefill/decode** inference workloads for **DeepSeek**, **Qwen3-MoE** and **Qwen3-Next**. @@ -14,7 +33,8 @@ - [2025/06] The code of SimCCL is first released in the branch [SimCCL](https://github.com/aliyun/SimAI/tree/SimCCL) and will be released in SimCCL repository soon. -**We warmly welcome contributions from the community!** If you are interested in helping shape the future of SimAI, please feel free to open an issue to discuss your ideas or submit a pull request. +**We warmly welcome contributions from the community!** If you are interested in helping shape the future of SimAI, please feel free to open an issue to discuss your ideas or submit a pull request. +
🎯 Events & Community Engagement 🎯 @@ -29,6 +49,7 @@ | Date | Event | Location | Content | Type | |:----------------:|:------------------------------------------------------------------------ |:----------------------- |:-------------------------------------------------------- |:-------------:| +| Mar 16, 2026 | SimAI 1.6 | 🌐 Online | The release of SimAI 1.6 | 💻 Virtual | | Dec 30, 2025 | SimAI 1.5 | 🌐 Online | The release of SimAI 1.5 | 💻 Virtual | | Jun 4, 2025 | The first workshop of the SimAI community | 📍 Peking University | Three talks from community contributors | 🎓 On-site | | May 24, 2025 | The 28th Chinasys workshop | 📍 Chongqing University | An invited talk about SimAI | 🎓 On-site | @@ -44,6 +65,15 @@ --- +## Documentation + +| | | +|---|---| +| [English Documentation](./docs/en/index.md) | Full documentation in English | +| [中文文档](./docs/zh/index.md) | 完整中文文档 | + +--- + # Table of Contents - [SimAI Overview](#simai-overview) @@ -51,18 +81,17 @@ - [Components](#components) - [Scenario](#scenario) - [Citation](#citation) -- [Usage](#usage) +- [Quick Start](#quick-start) - [Setup](#setup) - - [From Source Code](#from-source-code) - [Use SimAI-Analytical](#use-simai-analytical) - [Use SimAI-Simulation](#use-simai-simulation) - - [Use Vidur-AICB](#use-vidur-aicb) + - [Use Multi-requests Inference Simulation](#use-multi-requests-inference-simulation) # SimAI Overview ## Introduction -**SimAI** is the industry's first full-stack, high-precision **Sim**ulator for **AI** large-scale **\*\*inference\*\*** and **training**. It provides detailed modeling and simulation of the entire LLM training process, encompassing framework, collective communication, network layers, and more. This comprehensive approach offers end-to-end performance data, enabling researchers to: +**SimAI** is the industry's first full-stack, high-precision **Sim**ulator for **AI** large-scale **inference** and **training**. It provides detailed modeling and simulation of the entire LLM training process, encompassing framework, collective communication, network layers, and more. This comprehensive approach offers end-to-end performance data, enabling researchers to: - Analyze inference/training process details - Evaluate the time consumption of AI tasks under specific conditions @@ -86,7 +115,7 @@ SimAI --|--- SimCCL |--- vidur-alibabacloud -Building on pure simulation capabilities, SimAI has evolved into a versatile full-stack toolkit comprising four components ([aicb](https://github.com/aliyun/aicb), [SimCCL](https://github.com/aliyun/SimCCL), [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud), [ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud)). These components can be combined in various ways to achieve different functionalities. Below, we present the six main usage scenarios for SimAI. We encourage users to explore even more possibilities with this powerful tool. +Building on pure simulation capabilities, SimAI has evolved into a versatile full-stack toolkit comprising four components ([aicb](https://github.com/aliyun/aicb), [SimCCL](https://github.com/aliyun/SimCCL), [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud), [ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud)). These components can be combined in various ways to achieve different functionalities. Below, we present the main usage scenarios for SimAI. We encourage users to explore even more possibilities with this powerful tool. Below is the architecture diagram of the SimAI Simulator: ![SimAI_Arc](./docs/images/SimAI_Arc.png) @@ -103,15 +132,15 @@ SimAI supports three major operation modes to meet different simulation requirem **SimAI-Physical** *(Beta)* enables physical traffic generation for CPU RDMA cluster environments. This mode generates NCCL-like traffic patterns, allowing in-depth study of NIC behaviors during LLM training. It is currently in internal testing phase. -| Scenario | Description | Component Combination | -| -------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1. AICB Test Suite | Run communication patterns on GPU clusters using AICB Test suite | [AICB](https://github.com/aliyun/aicb) | -| 2. AICB/AIOB Workload | Model compute/communication patterns of **\*\*inference\*\*/training** process to generate workload | [AICB](https://github.com/aliyun/aicb) | -| 3. Collective Comm Analyze | Break down collective communication operations into point-to-point communication sets | [SimCCL](https://github.com/aliyun/SimCCL) | -| 4. Collective Comm w/o GPU | Perform RDMA collective communication traffic on non-GPU clusters | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(physical) | +| Scenario | Description | Component Combination | +|----------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1. AICB Test Suite | Run communication patterns on GPU clusters using AICB Test suite | [AICB](https://github.com/aliyun/aicb) | +| 2. AICB/AIOB Workload | Model compute/communication patterns of **inference**/training process to generate workload | [AICB](https://github.com/aliyun/aicb) | +| 3. Collective Comm Analyze | Break down collective communication operations into point-to-point communication sets | [SimCCL](https://github.com/aliyun/SimCCL) | +| 4. Collective Comm w/o GPU | Perform RDMA collective communication traffic on non-GPU clusters | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(physical) | | 5. SimAI-Analytical | Conduct rapid AICB workload analysis and simulation on any server (ignoring underlying network details) | [AICB](https://github.com/aliyun/aicb) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(analytical) | -| 6. SimAI-Simulation | Perform full simulation on any server | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(simulation) + [ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | -| 7. Multi-requests Inference Simulation | Perform full multi-requests **inference** simulation using one GPU server | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [vidur-alibabacloud](./vidur-alibabacloud) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(analytical/simulation) | +| 6. SimAI-Simulation | Perform full simulation on any server | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(simulation) + [ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | +| 7. Multi-requests Inference Simulation | Perform full multi-requests **inference** simulation using one GPU server | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [vidur-alibabacloud](./vidur-alibabacloud) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(analytical/simulation) | ## Citation @@ -125,15 +154,15 @@ We encourage innovative research and extensions based on SimAI. Welcome to join # Quick Start -Here are some simple examples, SimAI full tutorials can be found here: [**SimAI@Tutorial**](./docs/Tutorial.md), [**aicb@Tutorial**](https://github.com/aliyun/aicb/blob/master/training/tutorial.md), [SimCCL@Tutorial], [ns-3-alibabacloud@Tutorial] +Here are some simple examples. SimAI full tutorials can be found here: [**SimAI@Tutorial**](./docs/Tutorial.md), [**aicb@Tutorial**](https://github.com/aliyun/aicb/blob/master/training/tutorial.md), [SimCCL@Tutorial], [ns-3-alibabacloud@Tutorial] ## Setup -You can follow the instrucitons below to quickly set up the environtments and run SimAI +You can follow the instructions below to quickly set up the environments and run SimAI. ### From Source Code -The following code has been successfully tested on GCC/G++ 9.4.0, python 3.8.10 in Ubuntu 20.04 +The following code has been successfully tested on GCC/G++ 9.4.0, python 3.8.10 in Ubuntu 20.04. You can use the official Ubuntu 20.04 image, and do not install ninja. @@ -159,13 +188,13 @@ $ ./scripts/build.sh -c ns3 ## Use SimAI-Analytical ```bash -$ ./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml +$ ./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml ``` -For calculating bus bandwidth autolly, please try the following command: +For calculating bus bandwidth automatically, please try the following command: ```bash -$ ./bin/SimAI_analytical -w ./example/workload_analytical.txt -g 9216 -nv 360 -nic 48.5 -n_p_s 8 -g_p_s 8 -r example- +$ ./bin/SimAI_analytical -w ./example/workload_analytical.txt -g 9216 -nv 360 -nic 48.5 -n_p_s 8 -g_p_s 8 -r example- ``` ## Use SimAI-Simulation @@ -180,39 +209,57 @@ $ AS_SEND_LAT=3 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator -t 16 -w ./example/microA ## Use Multi-requests Inference Simulation -For detailed information, please refer to the [README](./vidur-alibabacloud/README.md) file in the `vidur-alibabacloud` directory. This module leverages AICB to profile the computation time of **inference** workloads. Due to its reliance on specific hardware-accelerated libraries like DeepGEMM and FlashMLA, it is exclusively compatible with NVIDIA GPUs based on the **Hopper (SM90)** and **Blackwell (SM100)** architectures. +For detailed information, please refer to the [README](./vidur-alibabacloud/README.md) file in the `vidur-alibabacloud` directory. This module leverages AICB to profile the computation time of **inference** workloads. Due to its reliance on specific hardware-accelerated libraries like DeepGEMM and FlashMLA, it is exclusively compatible with NVIDIA GPUs based on the **Hopper (SM90)** and **Blackwell (SM100)** architectures. -```shell +```bash # Build from Dockerfile docker build -t image:latest . -docker run --gpus all -it --rm image:latest +docker run --gpus all -it --rm image:latest ``` -**Note**: please add `ENV FLASH_MLA_DISABLE_SM100=1` to Dockerfile if using Hopper GPUs. +**Note:** Please add `ENV FLASH_MLA_DISABLE_SM100=1` to Dockerfile if using Hopper GPUs. -# Acknowledgments +To quickly validate all supported inference scenarios (Qwen3-Next-80B, DeepSeek-671B, Qwen3-MoE-235B), use the bundled 4-scenario test suite: -A huge thanks to the following people and organizations who have contributed to this project: +```bash +# Prerequisites: conda activate vidur +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all +# Or run a single scenario: +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 +``` -- TianHao Fu (Peking University) and [TELOS-syslab](https://github.com/TELOS-syslab/), +> **Prerequisites:** Requires `conda activate vidur` environment. See [Environment Setup](./vidur-alibabacloud/README.md#-environment-setup) for details. +> +> For detailed scenario configuration table and output file descriptions, see [Vidur-AlibabaCloud README](./vidur-alibabacloud/README.md#4-scenario-configuration). -- Parth Parikh (KEYSIGHT), +# Acknowledgments -- Sarah-Michelle Hammer & Ziyi Wang (TU-Berlin), +A huge thanks to the following people and organizations who have contributed to this project: -- Xinyue Li (BUPT), +- TianHao Fu (Peking University) and [TELOS-syslab](https://github.com/TELOS-syslab/) +- Parth Parikh (KEYSIGHT) +- Sarah-Michelle Hammer & Ziyi Wang (TU-Berlin) +- Xinyue Li (BUPT) +- Tong Chen (Zhejiang University) +- Ming Wang (BUPT) +- Tao Jiang (Institute of Computing Technology, Chinese Academy of Sciences) -- Tong Chen (Zhejiang University), +...and many other individual contributors from the community (See the [Contributors to aliyun/SimAI](https://github.com/aliyun/SimAI/graphs/contributors)). -- Ming Wang (BUPT), +We also thank Chenning Li (MIT CSAIL) who initiated the cooperation on integrating SimAI into [M4](https://github.com/netiken/m4), a new, innovative simulator. -- Tao Jiang (Institute of Computing Technology, Chinese Academy of Sciences), +**This project still welcomes more contributions and suggestions.** -and many other individual contributors from the community (See the [Contributors to aliyun/SimAI · GitHub](https://github.com/aliyun/SimAI/graphs/contributors)). +# Contributing -We also thank Chenning Li (MIT CSAIL) who initiated the cooperation on integrating SimAI into [M4](https://github.com/netiken/m4), a new, innovative simulator. +We welcome all contributions! Please read the following guides before getting started: -**This project still welcomes more contributions and suggestions**. +| | | +|---|---| +| [Contributing Guide](./CONTRIBUTING.md) | How to submit issues and pull requests | +| [Security Policy](./SECURITY.md) | How to report security vulnerabilities | +| [Code of Conduct](./CODE_OF_CONDUCT.md) | Our community standards | +| [Changelog](./CHANGELOG.md) | Version history from v1.5 onwards | # Contact us @@ -224,5 +271,3 @@ Welcome to join the SimAI community chat groups, with the DingTalk group on the SimAI DingTalk SimAI WeChat
- -
diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 00000000..1302de50 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,273 @@ +

+ 中文  ｜  English +

+ +# SimAI + +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) +[![NSDI'25](https://img.shields.io/badge/NSDI'25-SimAI-blue.svg)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) + +# 最新动态 + +### 近期更新 + +- [2026/03] **SimAI 1.6 正式发布！** 本版本新增推理仿真的 GPU 内存建模能力。主要特性包括： + + - **GPU 内存计算模块：** 支持 DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B 的精确参数计数与 KV Cache 管理。详见 [SimAI 1.6 技术报告](./docs/SimAI_1.6_Tech_Report_CN.md)。 + - **PD 分离内存规划：** Prefill 与 Decode 阶段独立的参数内存和 KV Cache 预算计算。详见 [memory_planner.py](./vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py)。 + - **Decode 时间估算改进：** 首尾线性插值替代最近邻的 AICB decode 时间预测，全局缓存支持跨运行复用。详见 [execution_time.py](./vidur-alibabacloud/vidur/entities/execution_time.py)。 + - **4 场景端到端测试：** 覆盖 Qwen3-Next-80B、DeepSeek-671B、Qwen3-MoE-235B 的完整验证套件。详见 [run_scenarios.sh](./vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh)。 + - **双语文档体系：** 全套 EN/ZH 文档系统。详见 [English Docs](./docs/en/index.md) | [中文文档](./docs/zh/index.md)。 + - **GitHub 社区规范文件：** 新增 [Issue 模板](./.github/ISSUE_TEMPLATE/)、[PR 模板](./.github/pull_request_template.md)、[行为准则](./CODE_OF_CONDUCT.md) ([中文](./CODE_OF_CONDUCT_CN.md))、[安全政策](./SECURITY.md) ([中文](./SECURITY_CN.md))、[贡献指南](./CONTRIBUTING.md) ([中文](./CONTRIBUTING.zh-CN.md)) 和 [更新日志](./CHANGELOG.md) ([中文](./CHANGELOG_CN.md))。 + - **代码质量提升：** logging 替换 print 输出、双语 docstring、清理 ~390 行死代码、TODO 规范化、类型标注补全。 + +- [2025/12] **SimAI 1.5 正式发布！** 本版本新增对多请求**推理**工作负载的端到端仿真支持，主要特性包括： + + - **高级推理仿真：** 支持 Prefill/Decode 分离等复杂场景建模。 + - **主流模型支持：** 新增 DeepSeek、Qwen3Moe 和 Qwen3Next 模型。详见 [AICB README](./aicb/README.md)。 + - **请求调度：** 请求调度组件基于微软 [Vidur](https://github.com/microsoft/vidur) 适配，详见 [Vidur-Alibabacloud README](./vidur-alibabacloud/README_CN.md)。 + +- [2025/11] [AICB](https://github.com/aliyun/aicb/tree/master) 新增对 **DeepSeek**、**Qwen3-MoE** 和 **Qwen3-Next** 的 **prefill/decode** 推理工作负载生成支持。 + +- [2025/09] [AICB](https://github.com/aliyun/aicb/tree/master) 新增 DeepSeek 训练工作负载生成支持。感谢 [@parthpower](https://github.com/parthpower) 的贡献。 + +- [2025/06] SimCCL 代码首次在 [SimCCL](https://github.com/aliyun/SimAI/tree/SimCCL) 分支发布，后续将在独立仓库正式开源。 + +**欢迎社区贡献！** 如有想法，欢迎提交 Issue 讨论或发起 Pull Request。 + +
+🎯 活动与社区 🎯 + +### 📅 即将举办 + +| 日期 | 活动 | 地点 | 内容 | 形式 | +|:----:|:----- |:-------- |:------- |:----:| +| -- | | | | | + +### 🌟 往期活动 + +| 日期 | 活动 | 地点 | 内容 | 形式 | +|:----------------:|:------------------------------------------------------------------------ |:----------------------- |:-------------------------------------------------------- |:-------------:| +| Mar 16, 2026 | SimAI 1.6 | 🌐 线上 | SimAI 1.6 正式发布 | 💻 线上直播 | +| Dec 30, 2025 | SimAI 1.5 | 🌐 线上 | SimAI 1.5 正式发布 | 💻 线上直播 | +| Jun 4, 2025 | SimAI 社区第一届研讨会 | 📍 北京大学 | 三场社区贡献者演讲 | 🎓 线下 | +| May 24, 2025 | 第 28 届 Chinasys 研讨会 | 📍 重庆大学 | SimAI 受邀演讲 | 🎓 线下 | +| Dec 27, 2024 | SimAI 技术分享 | 📍 北京航空航天大学 | SimAI 技术分享与交流 | 🎓 线下 | +| Dec 6, 2024 | 香港科技大学技术研讨会 | 📍 香港科技大学（广州） | SimAI 技术分享与交流 | 🎓 线下 | +| Dec 5, 2024 | [Bench'24 会议](https://mp.weixin.qq.com/s/STic_E12xMhZRxhzK9wRnw) | 📍 广州 | SimAI 教程与深度技术专场 | 🎓 线下 | +| Nov 26, 2024 | SimAI 社区直播 | 🌐 线上 | 互动技术交流与演示（400+ 参与者） | 💻 线上直播 | +| Nov 15, 2024 | 技术研讨会 | 📍 千岛湖 | SimAI 线下技术交流 | 🎯 线下 | +| Oct 18, 2024 | 嘉宾讲座 | 📍 复旦大学 | SimAI 教程与公开课 | 🎓 线下 | +| Sept 24-26, 2024 | CCF HPC China 2024 | 📍 武汉 | SimAI 介绍与技术报告 | 🎤 会议 | + +
+ +--- + +## 文档 + +| | | +|---|---| +| [English Documentation](./docs/en/index.md) | Full documentation in English | +| [中文文档](./docs/zh/index.md) | 完整中文文档 | + +--- + +# 目录 + +- [SimAI 概述](#simai-概述) + - [简介](#简介) + - [组件](#组件) + - [应用场景](#应用场景) + - [引用](#引用) +- [快速开始](#快速开始) + - [环境搭建](#环境搭建) + - [使用 SimAI-Analytical](#使用-simai-analytical) + - [使用 SimAI-Simulation](#使用-simai-simulation) + - [使用多请求推理仿真](#使用多请求推理仿真) + +# SimAI 概述 + +## 简介 + +**SimAI** 是业界首个全栈高精度 AI 大规模**推理**与**训练**模拟器（**Sim**ulator for **AI**）。它对 LLM 训练全流程进行详细建模和仿真，涵盖框架、集合通信、网络层等，提供端到端的性能数据，帮助研究人员： + +- 分析推理/训练过程细节 +- 评估特定条件下 AI 任务的耗时 +- 评估各类算法优化带来的 E2E 性能收益，包括： + - 框架参数配置 + - 集合通信算法 + - NCCL 环境变量 + - 网络传输协议 + - 拥塞控制算法 + - 自适应路由算法 + - 扩展/集合网络拓扑调整 + - …… + +## 组件 + +
+        |--- AICB
+SimAI --|--- SimCCL
+        |--- astra-sim-alibabacloud
+        |--- ns-3-alibabacloud
+        |--- vidur-alibabacloud
+
+ +在纯仿真能力基础上，SimAI 已演进为一个由四个组件（[aicb](https://github.com/aliyun/aicb)、[SimCCL](https://github.com/aliyun/SimCCL)、[astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)、[ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud)）构成的全栈工具套件。这些组件可以灵活组合以实现不同功能。我们鼓励用户探索更多可能性。 + +下图为 SimAI 模拟器架构图： +![SimAI_Arc](./docs/images/SimAI_Arc.png) + +astra-sim-alibabacloud 基于 [astra-sim](https://github.com/astra-sim/astra-sim/tree/ASTRA-sim-1.0) 扩展开发。感谢 astra-sim 团队的优秀工作和开源贡献。我们在其基础上集成了 NCCL 算法并添加了若干新特性。 + +## 应用场景 + +SimAI 支持三种主要运行模式： + +**SimAI-Analytical** 通过使用总线带宽（busbw）抽象网络通信细节来估算集合通信时间，实现快速仿真。目前支持用户自定义 busbw，自动计算 busbw 功能即将推出。 + +**SimAI-Simulation** 提供基于细粒度网络通信建模的全栈仿真。利用 NS-3 或其他网络模拟器（当前 NS-3 已开源）实现对所有通信行为的详细仿真，力求高保真还原真实训练环境。 + +**SimAI-Physical** *(Beta)* 支持在 CPU RDMA 集群环境下生成物理流量，通过生成类 NCCL 的流量模式深入研究 LLM 训练中的 NIC 行为。当前处于内测阶段。 + +| 场景 | 描述 | 组件组合 | +|------|------|----------| +| 1. AICB 测试套件 | 在 GPU 集群上使用 AICB 测试套件运行通信模式 | [AICB](https://github.com/aliyun/aicb) | +| 2. AICB/AIOB 工作负载 | 建模**推理**/训练过程的计算/通信模式以生成工作负载 | [AICB](https://github.com/aliyun/aicb) | +| 3. 集合通信分析 | 将集合通信操作分解为点对点通信集合 | [SimCCL](https://github.com/aliyun/SimCCL) | +| 4. 无 GPU 集合通信 | 在非 GPU 集群上执行 RDMA 集合通信流量 | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(physical) | +| 5. SimAI-Analytical | 在任意服务器上快速进行 AICB 工作负载分析与仿真（忽略底层网络细节） | [AICB](https://github.com/aliyun/aicb) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(analytical) | +| 6. SimAI-Simulation | 在任意服务器上进行全栈仿真 | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(simulation) + [ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | +| 7. 多请求推理仿真 | 在单 GPU 服务器上进行多请求**推理**全栈仿真 | [AICB](https://github.com/aliyun/aicb) + [SimCCL](https://github.com/aliyun/SimCCL) + [vidur-alibabacloud](./vidur-alibabacloud) + [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud)(analytical/simulation) | + +## 引用 + +SimAI 论文已被 NSDI'25 Spring 接收，详情请参阅： + +*SimAI: Unifying Architecture Design and Performance Tuning for Large-Scale Large Language Model Training with Scalability and Precision.* + +[[pdf](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf)] / [[slides](./docs/SimAI_Intro_Online.pdf)] / [[video](https://n.dingtalk.com/dingding/live-room/index.html?roomId=OF5BkBUXVxmgsK7x&liveUuid=305736cd-aa70-498b-8003-2b471a53decd)] + +欢迎基于 SimAI 开展创新研究和功能扩展。欢迎加入社区群或通过邮件联系我们交流，我们可提供技术支持。 + +# 快速开始 + +以下为简单示例。完整教程请参见：[**SimAI@Tutorial**](./docs/Tutorial.md)、[**aicb@Tutorial**](https://github.com/aliyun/aicb/blob/master/training/tutorial.md)、[SimCCL@Tutorial]、[ns-3-alibabacloud@Tutorial] + +## 环境搭建 + +请按照以下步骤快速搭建环境并运行 SimAI。 + +### 从源码安装 + +以下步骤已在 Ubuntu 20.04 的 GCC/G++ 9.4.0、python 3.8.10 环境下验证。 + +可使用官方 Ubuntu 20.04 镜像，**不要安装 ninja**。 + +（对于工作负载生成场景，推荐直接使用 NGC 容器镜像。） + +```bash +# 克隆仓库 +$ git clone https://github.com/aliyun/SimAI.git +$ cd ./SimAI/ + +# 初始化子模块 +$ git submodule update --init --recursive +# 更新到最新提交 +$ git submodule update --remote + +# 编译 SimAI-Analytical +$ ./scripts/build.sh -c analytical + +# 编译 SimAI-Simulation (ns3) +$ ./scripts/build.sh -c ns3 +``` + +## 使用 SimAI-Analytical + +```bash +$ ./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml +``` + +若需自动计算总线带宽，请尝试： + +```bash +$ ./bin/SimAI_analytical -w ./example/workload_analytical.txt -g 9216 -nv 360 -nic 48.5 -n_p_s 8 -g_p_s 8 -r example- +``` + +## 使用 SimAI-Simulation + +```bash +# 生成网络拓扑 +$ python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +# 运行仿真 +$ AS_SEND_LAT=3 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator -t 16 -w ./example/microAllReduce.txt -n ./Spectrum-X_128g_8gps_100Gbps_A100 -c astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +## 使用多请求推理仿真 + +详情请参见 `vidur-alibabacloud` 目录下的 [README](./vidur-alibabacloud/README_CN.md)。该模块利用 AICB 对**推理**工作负载的计算时间进行 profiling。由于依赖 DeepGEMM 和 FlashMLA 等特定硬件加速库，目前仅兼容基于 **Hopper（SM90）** 和 **Blackwell（SM100）** 架构的 NVIDIA GPU。 + +```bash +# 从 Dockerfile 构建 +docker build -t image:latest . +docker run --gpus all -it --rm image:latest +``` + +**注意：** 若使用 Hopper GPU，请在 Dockerfile 中添加 `ENV FLASH_MLA_DISABLE_SM100=1`。 + +如需快速验证所有支持的推理场景（Qwen3-Next-80B、DeepSeek-671B、Qwen3-MoE-235B），可使用内置的四场景测试套件： + +```bash +# 前置条件：conda activate vidur +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all +# 或单独运行某个场景： +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 +``` + +> **前置条件：** 需先激活 `conda activate vidur` 环境。详见 [环境配置](./vidur-alibabacloud/README_CN.md#-环境配置)。 +> +> 完整场景配置表与输出文件说明请参见 [Vidur-AlibabaCloud README](./vidur-alibabacloud/README_CN.md#四场景配置说明)。 + +# 致谢 + +衷心感谢以下人员和机构对本项目的贡献： + + +- TianHao Fu (Peking University) and [TELOS-syslab](https://github.com/TELOS-syslab/) +- Parth Parikh (KEYSIGHT) +- Sarah-Michelle Hammer & Ziyi Wang (TU-Berlin) +- Xinyue Li (BUPT) +- Tong Chen (Zhejiang University) +- Ming Wang (BUPT) +- Tao Jiang (Institute of Computing Technology, Chinese Academy of Sciences) + +……以及众多来自社区的个人贡献者（详见 [Contributors to aliyun/SimAI](https://github.com/aliyun/SimAI/graphs/contributors)）。 + +同时感谢 Chenning Li（MIT CSAIL）发起了将 SimAI 集成到 [M4](https://github.com/netiken/m4) 的合作——M4 是一个新型创新模拟器。 + +**本项目持续欢迎更多贡献与建议。** + +# 贡献指南 + +欢迎参与贡献！开始前请阅读以下指引： + +| | | +|---|---| +| [贡献指南](./CONTRIBUTING.zh-CN.md) | 如何提交 Issue 和 Pull Request | +| [安全政策](./SECURITY_CN.md) | 如何报告安全漏洞 | +| [行为准则](./CODE_OF_CONDUCT_CN.md) | 社区行为规范 | +| [更新日志](./CHANGELOG_CN.md) | v1.5 起的版本历史 | + +# 联系我们 + +如有任何问题，欢迎发送邮件至：Gang Lu（yunding.lg@alibaba-inc.com）、Feiyang Xue（xuefeiyang.xfy@alibaba-inc.com）或 Qingxu Li（qingxu.lqx@alibaba-inc.com）。 + +欢迎加入 SimAI 社区交流群，左侧为钉钉群，右侧为微信群。 + +
+ SimAI 钉钉群 + SimAI 微信群 +
diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..aa9e066e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,47 @@ +

+ 中文  ｜  English +

+ +# Security Policy + +## Reporting a Vulnerability + +The SimAI team takes security issues seriously. We appreciate your efforts to responsibly disclose any security vulnerabilities you find. + +**Please do NOT report security vulnerabilities through public GitHub issues.** + +Instead, please report them via email to: + +- Gang Lu: yunding.lg@alibaba-inc.com +- Feiyang Xue: xuefeiyang.xfy@alibaba-inc.com +- Qingxu Li: qingxu.lqx@alibaba-inc.com + +Please include the following information in your report: + +- Description of the vulnerability +- Steps to reproduce the issue +- Potential impact +- Suggested fix (if any) + +## Response Timeline + +- We will acknowledge receipt of your vulnerability report within **3 business days**. +- We will provide a more detailed response within **10 business days**, indicating the next steps for handling your report. +- We will keep you informed of the progress towards a fix and full announcement. + +## Supported Versions + +| Version | Supported | +|---------|--------------------| +| 1.5.x | :white_check_mark: | +| < 1.5 | :x: | + +## Disclosure Policy + +When we receive a security bug report, we will: + +1. Confirm the problem and determine the affected versions. +2. Audit code to find any similar problems. +3. Prepare fixes and release them as soon as possible. + +Thank you for helping keep SimAI and its users safe! diff --git a/SECURITY_CN.md b/SECURITY_CN.md new file mode 100644 index 00000000..87c911be --- /dev/null +++ b/SECURITY_CN.md @@ -0,0 +1,47 @@ +

+ 中文  ｜  English +

+ +# 安全政策 + +## 报告漏洞 + +SimAI 团队高度重视安全问题。我们感谢您以负责任的方式披露所发现的安全漏洞。 + +**请勿通过公开的 GitHub Issue 报告安全漏洞。** + +请通过电子邮件将漏洞报告发送至以下联系人： + +- Gang Lu：yunding.lg@alibaba-inc.com +- Feiyang Xue：xuefeiyang.xfy@alibaba-inc.com +- Qingxu Li：qingxu.lqx@alibaba-inc.com + +报告中请包含以下信息： + +- 漏洞描述 +- 复现步骤 +- 潜在影响 +- 修复建议（如有） + +## 响应时间线 + +- 我们将在 **3 个工作日**内确认收到您的漏洞报告。 +- 我们将在 **10 个工作日**内提供更详细的回复，说明后续处理步骤。 +- 我们将持续向您通报修复进展及公告发布情况。 + +## 支持的版本 + +| 版本 | 是否支持 | +|---------|-----------------------| +| 1.5.x | :white_check_mark: | +| < 1.5 | :x: | + +## 披露政策 + +收到安全漏洞报告后，我们将： + +1. 确认问题并确定受影响的版本。 +2. 对代码进行审查，排查类似问题。 +3. 尽快准备并发布修复补丁。 + +感谢您帮助保障 SimAI 及其用户的安全！ diff --git a/docs/SimAI_1.6_Tech_Report.md b/docs/SimAI_1.6_Tech_Report.md new file mode 100644 index 00000000..b00809b7 --- /dev/null +++ b/docs/SimAI_1.6_Tech_Report.md @@ -0,0 +1,429 @@ +

+ 中文  ｜  English +

+ +# SimAI 1.6 Technical Report + +> This report covers all features from SimAI 1.5 as well as the new enhancements introduced in SimAI 1.6. + +## 1. Overview + +**SimAI** is the industry's first full-stack, high-precision **Sim**ulator for **AI** large-scale inference and training, open-sourced by Alibaba Cloud. SimAI provides detailed modeling and simulation of the entire LLM inference and training process, encompassing the framework layer, collective communication layer, and network transport layer, delivering end-to-end performance data. The SimAI paper was accepted by NSDI'25 Spring [1]. + +SimAI 1.6 builds upon SimAI 1.5 with further enhancements, primarily introducing the **GPU Memory Calculation Module** (supporting accurate parameter counting and KV cache management for DeepSeek-V3-671B, Qwen3-MoE-235B, and Qwen3-Next-80B), a **4-Scenario End-to-End Test Suite**, and comprehensive code quality improvements (bilingual documentation, logging system, dead code cleanup, etc.). + +### Component Overview + +``` + |--- AICB (Workload generation & compute profiling) +SimAI --|--- SimCCL (Collective communication algorithm analysis) + |--- astra-sim-alibabacloud (Simulation engine: Analytical / Simulation / Physical) + |--- ns-3-alibabacloud (NS-3 network backend) + |--- vidur-alibabacloud (Multi-request inference scheduling & memory management) +``` + +--- + +## 2. Key Milestones + +The following are the key development events from November 2025 to March 2026: + +| Date | Event | Description | +|------|-------|-------------| +| 2025/11 | AICB PR [#58](https://github.com/aliyun/aicb/pull/58) | AICB adds inference workload generation with prefill/decode phase separation, supporting DeepSeek, Qwen3-MoE, and Qwen3-Next | +| 2025/12 | AICB PR [#60](https://github.com/aliyun/aicb/pull/60) | AICB further update, refining inference workload generation | +| 2025/12 | SimAI PR [#203](https://github.com/aliyun/SimAI/pull/203) | SimAI 1.5 core update: end-to-end inference simulation, PD disaggregation, Vidur scheduling integration, modern model support | +| 2025/12 | ns-3 commit [7e3cb5b](https://github.com/aliyun/ns-3-alibabacloud/commit/7e3cb5b88c99abcb582c5abc3919484a4805111b) | ns-3-alibabacloud README documentation enhancement with detailed NS3 backend modifications | +| 2026/01 | Memory module commits | Completed accurate memory calculation for DeepSeek-V3-671B, Qwen3-Next-80B, and Qwen3-MoE-235B | +| 2026/02 | PD disaggregation memory planning | Implemented independent parameter memory and KV cache budget calculation for Prefill/Decode phases | +| 2026/03 | Code quality improvements | Comprehensive bilingual comments/docs/logs, dead code cleanup, TODO standardization, type annotations | + +--- + +## 3. End-to-End Inference Simulation + +SimAI supports complete multi-request LLM inference simulation with the following core features: + +### 3.1 Prefill-Decode (PD) Disaggregation Architecture + +The inference process is divided into two phases: + +- **Prefill phase**: Processes all input prompt tokens and generates the first output token (compute-intensive) +- **Decode phase**: Autoregressively generates subsequent output tokens one at a time (memory-bandwidth-intensive) + +PD disaggregation allows deploying Prefill and Decode phases on different GPU nodes, enabling: +- Elastic resource allocation (Prefill nodes can be configured with more compute, Decode nodes with more memory) +- Performance isolation (avoiding resource contention between Prefill and Decode) +- Flexible P:D node ratio configuration (via `--replica_config_pd_node_ratio`) + +This design was inspired by [splitwise-sim](https://github.com/Mutinifni/splitwise-sim) [6]. + +### 3.2 Multi-Request Inference Scheduling + +The request scheduling component is adapted from Microsoft's [Vidur](https://github.com/microsoft/vidur) [5] (vidur-alibabacloud), supporting the following scheduling strategies: + +| Scheduler Type | Level | Description | +|---------------|-------|-------------| +| `split_wise` | Global | Global scheduling for PD disaggregation, dispatching requests to Prefill and Decode replicas | +| `lor` | Global | Least Outstanding Requests, dispatching to the least-loaded replica | +| `round_robin` | Global | Round-robin dispatch | +| `sarathi` | Per-replica | Intra-replica batch scheduling | +| `split_wise` | Per-replica | Per-replica scheduling for PD disaggregation | + +### 3.3 Flexible Parallelism + +Supports combinations of multiple parallelism strategies: + +- **Data Parallel (DP)** — via `--cluster_config_num_replicas` +- **Tensor Parallel (TP)** — via `--replica_config_tensor_parallel_size` +- **Pipeline Parallel (PP)** — via `--replica_config_num_pipeline_stages` +- **Expert Parallel (EP)** — via `--replica_config_expert_model_parallel_size` + +Works for both dense and MoE (Mixture-of-Experts) models. + +### 3.4 Multiple Execution-Time Prediction Backends + +| Backend | Description | +|---------|-------------| +| **AICB/AIOB** | Partially supports compute kernels and TP/DP/PP/EP communication size modeling for DeepSeek-V3-671B, Qwen3-MoE-235B, Qwen3-Next-80B | +| **SimAI Simulation** | SimAI NS-3-based full-stack network simulation (currently supports TP) | +| **SimAI Analytical** | SimAI analytical performance model (currently supports TP) | +| **Native Vidur** | Original Vidur backend, supports TP, DP, PP | + +--- + +## 4. Modern Model Support + +SimAI 1.6 supports the following three state-of-the-art MoE large models, with configuration files located in `vidur-alibabacloud/data/hf_configs/`: + +### 4.1 DeepSeek-V3-671B + +| Attribute | Value | +|-----------|-------| +| Total Layers | 61 | +| Attention Type | MLA (Multi-head Latent Attention) | +| Attention Heads | 128 | +| Hidden Size | 7168 | +| KV LoRA Rank | 512 | +| Q LoRA Rank | 1536 | +| QK RoPE Head Dim | 64 | +| QK NoPE Head Dim | 128 | +| V Head Dim | 128 | +| MoE Routed Experts | 256 | +| Experts Per Token | 8 | +| Shared Experts | 1 | +| Dense Layers (first 3) | Fixed activation of 8 routed experts + 1 shared expert | +| Sparse Layers (layers 3-60) | Dynamically select 8 from 256 routed experts + 1 shared expert | + +Configuration file: `data/hf_configs/deepseek_v3_config.json` + +### 4.2 Qwen3-MoE-235B + +| Attribute | Value | +|-----------|-------| +| Total Layers | 94 | +| Attention Type | MHA/GQA | +| Attention Heads | 64 | +| KV Heads | 4 | +| Hidden Size | 4096 | +| Head Dim | 128 | +| MoE Routed Experts | 128 | +| Experts Per Token | 8 | +| MoE Intermediate Size | 1536 | + +Configuration file: `data/hf_configs/qwen3_moe_config.json` + +### 4.3 Qwen3-Next-80B + +| Attribute | Value | +|-----------|-------| +| Total Layers | 48 | +| Attention Type | Hybrid (full + linear attention, alternating every 4 layers) | +| Full Attention Heads | 16 | +| KV Heads | 2 | +| Hidden Size | 2048 | +| Head Dim | 256 | +| Linear Attention Key Heads | 16 | +| Linear Attention Value Heads | 32 | +| MoE Routed Experts | 512 | +| Experts Per Token | 10 | +| MoE Intermediate Size | 512 | + +Configuration file: `data/hf_configs/qwen3-next-80B-A3B_config.json` + +--- + +## 5. GPU Memory Calculation Module + +This is the core new feature in SimAI 1.6. The module provides accurate GPU memory estimation for inference simulation, covering model parameter memory, KV cache memory, and maximum batch size calculation, with separate memory budget computation for Prefill and Decode phases under PD disaggregation. + +### 5.1 Parameter Counting (ParamCounter) + +**File path**: `vidur-alibabacloud/vidur/utils/param_counter.py` + +ParamCounter supports per-layer and per-device parameter counting, returning a triple `(total_params, prefill_params, decode_params)` under PD disaggregation. + +#### MLA Parameters (DeepSeek-V3-671B) + +Per-layer MLA parameter components: + +- **Q LoRA down-projection**: `wq_down = hidden_size * q_lora_rank` = 7168 * 1536 +- **Q LoRA up-projection**: `wq_up = q_lora_rank * num_attention_heads * qk_head_dim` = 1536 * 128 * 192, where `qk_head_dim = qk_nope_head_dim + qk_rope_head_dim = 128 + 64 = 192` +- **KV LoRA down-projection**: `wkv_down = hidden_size * kv_lora_rank` = 7168 * 512 +- **KV LoRA up-projection**: `wkv_up = kv_lora_rank * num_attention_heads * (qk_nope_head_dim + v_head_dim)` = 512 * 128 * 256 +- **Output projection**: `wo = hidden_size * num_attention_heads * v_head_dim` = 7168 * 128 * 128 + +Under FP8 quantization, each parameter element uses 1 byte; under FP16/BF16, each uses 2 bytes. + +References: [3] [4] + +#### MHA/GQA Parameters (Qwen3-MoE-235B) + +Per-layer MHA parameters: + +``` +wq = hidden_size * num_attention_heads * head_dim +wk = hidden_size * num_key_value_heads * head_dim +wv = hidden_size * num_key_value_heads * head_dim +wo = hidden_size * num_attention_heads * head_dim +total = (wq + wk + wv + wo) * bytes_per_element +``` + +#### Linear Attention Parameters (Qwen3-Next-80B) + +Qwen3-Next-80B uses a hybrid attention architecture, alternating between full attention and linear (GDN) attention every 4 layers. Linear attention layers use independent key/value head configurations (`linear_key_head_dim`, `linear_num_key_heads`, etc.). + +#### MoE Expert Parameters + +Per-expert FFN parameters (3 weight matrices W1, W2, W3): + +``` +expert_params = 3 * hidden_size * moe_intermediate_size * bytes_per_element +``` + +#### PD Disaggregation Parameter Calculation + +Under PD disaggregation, the expert parallelism (EP) may differ between Prefill and Decode clusters: + +- **Prefill cluster**: Uses `prefill_world_size` as EP, experts per device = `num_routed_experts / prefill_world_size` +- **Decode cluster**: Uses `decode_world_size` as EP, experts per device = `num_routed_experts / decode_world_size` + +This results in different parameter memory for Prefill and Decode clusters, which in turn affects their respective available KV cache capacity. + +### 5.2 KV Cache Memory Management + +**File path**: `vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py`, `vidur-alibabacloud/vidur/entities/replica.py` + +#### MHA/GQA KV Cache Calculation + +``` +kv_cache_per_token = 2 * num_kv_heads * head_dim * num_layers * bytes_per_element +``` + +The factor of 2 represents the K (Key) and V (Value) caches. + +#### MLA KV Cache Calculation (DeepSeek-V3-671B) + +The MLA architecture uses compressed KV representations. Unlike MHA which stores separate K and V caches, MLA stores a single compressed latent vector (`kv_lora_rank`) that jointly encodes K and V, plus the RoPE position keys (`qk_rope_head_dim`). Per-token KV cache size: + +``` +kv_cache_per_token = (kv_lora_rank + qk_rope_head_dim) * num_layers * bytes_per_element +``` + +Where `kv_lora_rank = 512` and `qk_rope_head_dim = 64`. Compared to MHA's per-token cache of `2 * num_kv_heads * head_dim` = 2 * 128 * 128 = 32768 elements, MLA reduces this to 576 elements — a **~57x** reduction. + +#### Per-Request KV Cache Tracking + +The `Replica` entity (`vidur/entities/replica.py`) maintains the following state: + +- `_allocated_kv_cache_memory`: Currently allocated KV cache memory (bytes) +- `_max_kv_cache_memory`: Maximum KV cache capacity (computed on first call by MemoryPlanner) +- `_kv_cache_allocation_map`: Per-request KV cache allocation mapping + +Supported operations: +- `allocate_request_kv_cache_memory(request, num_blocks, block_size)` — Allocate KV cache for a request +- `release_request_kv_cache_memory(request)` — Release KV cache for a completed request +- `get_remaining_kv_cache_capacity()` — Query remaining KV cache capacity and serviceable request count + +### 5.3 MemoryPlanner + +**File path**: `vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py` + +MemoryPlanner is the central component for memory management, with the following calculation flow: + +1. **Compute available GPU memory**: `available_memory = total_GPU_memory * (1 - memory_margin_fraction)` +2. **Get model parameter memory**: Computed via ParamCounter; under PD disaggregation returns `(total, prefill, decode)` triple +3. **Compute KV cache available memory**: `kv_cache_available = available_memory - param_memory` +4. **Compute maximum concurrent requests**: `max_requests = kv_cache_available / kv_cache_per_request` + +Under PD disaggregation: +- Prefill replicas use `prefill_param_mem` for KV cache budget calculation +- Decode replicas use `decode_param_mem` for KV cache budget calculation + +Includes OOM detection: when parameter memory exceeds available memory, error messages are output with suggestions to increase TP/EP, use larger GPUs, or enable FP8 quantization. + +--- + +## 6. AICB Inference Workload Generation + +[AICB](https://github.com/aliyun/aicb) introduces inference workload generation capabilities (PR [#58](https://github.com/aliyun/aicb/pull/58), [#60](https://github.com/aliyun/aicb/pull/60)), with key features: + +- **Prefill/Decode phase separation**: Generates separate compute and communication workloads for Prefill and Decode phases +- **Compute kernel profiling**: Relies on the following hardware-accelerated libraries (requires Hopper SM90 or Blackwell SM100 GPUs): + - [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) — FP8 matrix multiplication + - [FlashMLA](https://github.com/deepseek-ai/FlashMLA) — MLA attention acceleration + - [FlashInfer](https://github.com/flashinfer-ai/flashinfer) — High-performance inference kernels +- **Communication size modeling**: Supports communication size calculation for TP, DP, PP, EP parallelism strategies +- **Model support**: DeepSeek-V3-671B, Qwen3-MoE-235B, Qwen3-Next-80B + +--- + +## 7. Four-Scenario End-to-End Test Suite + +**File path**: `vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh` + +Provides 4 pre-configured end-to-end test scenarios covering different models, parallelism strategies, and PD disaggregation configurations. + +### Shared Hardware Configuration + +- GPU: H20 (h20_dgx) +- NVLink bandwidth: 1600 Gbps +- RDMA bandwidth: 800 Gbps +- PD P2P bandwidth: 800 Gbps +- Data type: fp8 +- Requests: Poisson QPS=100, 4 requests, fixed prefill=100 / decode=8 tokens + +### Scenario Configuration + +| Scenario | Model | PD Separation | World Size | TP | PP | EP | Global Scheduler | +|----------|-------|---------------|-----------|----|----|-----|-----------------| +| 1 | Qwen3-Next-80B (MoE) | No | 32 (dp=32) | 1 | 1 | 1 | lor | +| 2 | Qwen3-Next-80B (MoE) | Yes (P=2, D=6) | 8 | 1 | 1 | 1 | split_wise | +| 3 | DeepSeek-671B (MoE) | Yes (P=2, D=6) | 8 | 8 | 1 | 8 | split_wise | +| 4 | Qwen3-MoE-235B (MoE) | Yes (P=2, D=6) | 8 | 4 | 1 | 4 | split_wise | + +### Running + +```bash +# Run all 4 scenarios +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all + +# Run a single scenario +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 3 +``` + +For detailed performance data, please run the test suite. Each run produces output files including `request_metrics.csv` (per-request metrics), `chrome_trace.json` (timeline trace), `config.json` (configuration snapshot), and metric files under the `plots/` directory. + +--- + +## 8. Code Quality Improvements + +SimAI 1.6 includes systematic code quality improvements: + +### 8.1 Bilingual Comments and Documentation + +- Added bilingual (Chinese/English) docstrings to all public APIs +- Added bilingual comments to config, scheduler, predictor, and utils modules +- Added bilingual comments to entity modules +- Shell script outputs and Python runtime outputs use bilingual format + +### 8.2 Logging System Improvements + +- Comprehensive replacement of `print` statements with the `logging` module (~12 files) +- Unified log format using parenthetical bilingual style (e.g., `"GPU总内存 (Total GPU mem): 96.00 GB"`) + +### 8.3 Dead Code Cleanup + +- Removed approximately 390 lines of dead code blocks +- Cleaned up personal debug markers + +### 8.4 TODO Standardization + +- Unified to `TODO(author): description` format +- Added missing type annotations + +--- + +## 9. System Architecture + +### Inference Simulation Data Flow + +``` +Request Generator + | Generate synthetic / real-trace requests + v +Global Scheduler + | Dispatch requests to Prefill / Decode replicas + v +Replica Scheduler + | Batch assembly and scheduling + v +Memory Management (MemoryPlanner + Replica) + | KV cache allocation and capacity checking + v +Execution Time Predictor + | AICB / SimAI Simulation / SimAI Analytical / Vidur + v +Metrics Store + | TTFT, TBT, E2E, communication / compute cost + v +Output (request_metrics.csv, chrome_trace.json, plots/) +``` + +--- + +## 10. Quick Start + +### Environment Setup + +#### Option 1: Docker (Recommended) + +```bash +# Build from project root +docker build -t simai:latest . +docker run --gpus all -it --rm simai:latest +``` + +> If using Hopper GPUs, add `ENV FLASH_MLA_DISABLE_SM100=1` to the Dockerfile. + +#### Option 2: Conda + +```bash +cd vidur-alibabacloud +conda env create -p ./env -f ./environment.yml +conda activate vidur +pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ +``` + +### Run 4-Scenario Test Suite + +```bash +# Prerequisites: conda activate vidur +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all +``` + +### Compile and Run SimAI Training Simulation + +```bash +# Compile SimAI-Analytical +./scripts/build.sh -c analytical + +# Run +./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml +``` + +--- + +## 11. References + +[1] SimAI: Unifying Architecture Design and Performance Tuning for Large-Scale Large Language Model Training with Scalability and Precision. NSDI'25 Spring. [[pdf](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf)] + +[2] InferSim — Alibaba. Parameter counting and KV cache estimation. [[GitHub](https://github.com/alibaba/InferSim)] + +[3] DeepSeek V3 Parameter Derivation (Chinese). Zhihu. [[link](https://zhuanlan.zhihu.com/p/21455638257)] + +[4] DeepSeek V3 Parameter Size Analysis. Yang Wenbo. [[link](https://yangwenbo.com/articles/deepseek-v3-parameter-size.html)] + +[5] Vidur: A Large-Scale Simulation Framework For LLM Inference. Microsoft Research. [[GitHub](https://github.com/microsoft/vidur)] + +[6] splitwise-sim — Prefill-Decode Disaggregation Simulation. [[GitHub](https://github.com/Mutinifni/splitwise-sim)] diff --git a/docs/SimAI_1.6_Tech_Report_CN.md b/docs/SimAI_1.6_Tech_Report_CN.md new file mode 100644 index 00000000..228ae90a --- /dev/null +++ b/docs/SimAI_1.6_Tech_Report_CN.md @@ -0,0 +1,429 @@ +

+ 中文  ｜  English +

+ +# SimAI 1.6 技术报告 + +> 本报告涵盖 SimAI 1.5 全部功能及 SimAI 1.6 新增特性。 + +## 1. 概述 + +**SimAI** 是业界首个全栈高精度 AI 大规模推理与训练模拟器（**Sim**ulator for **AI**），由阿里云开源。SimAI 对 LLM 推理与训练全流程进行详细建模和仿真，涵盖框架层、集合通信层、网络传输层等，提供端到端的性能数据。SimAI 论文已被 NSDI'25 Spring 接收 [1]。 + +SimAI 1.6 在 SimAI 1.5 的基础上进一步增强，主要新增了 **GPU 显存计算模块**（支持 DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B 三种 MoE 模型的精确参数量计算与 KV Cache 管理）、**四场景端到端测试套件**，以及全面的代码质量改进（双语文档、日志系统、死代码清理等）。 + +### 组件构成 + +``` + |--- AICB (工作负载生成与计算 profiling) +SimAI --|--- SimCCL (集合通信算法分析) + |--- astra-sim-alibabacloud (仿真引擎：Analytical / Simulation / Physical) + |--- ns-3-alibabacloud (NS-3 网络后端) + |--- vidur-alibabacloud (多请求推理调度与显存管理) +``` + +--- + +## 2. 关键里程碑 + +以下为 2025 年 11 月至 2026 年 3 月的关键开发事件： + +| 时间 | 事件 | 说明 | +|------|------|------| +| 2025/11 | AICB PR [#58](https://github.com/aliyun/aicb/pull/58) | AICB 新增推理工作负载生成能力，区分 prefill/decode 阶段，支持 DeepSeek、Qwen3-MoE、Qwen3-Next | +| 2025/12 | AICB PR [#60](https://github.com/aliyun/aicb/pull/60) | AICB 进一步更新，完善推理工作负载生成 | +| 2025/12 | SimAI PR [#203](https://github.com/aliyun/SimAI/pull/203) | SimAI 1.5 核心更新：端到端推理仿真、PD 分离、Vidur 调度集成、现代模型支持 | +| 2025/12 | ns-3 commit [7e3cb5b](https://github.com/aliyun/ns-3-alibabacloud/commit/7e3cb5b88c99abcb582c5abc3919484a4805111b) | ns-3-alibabacloud README 文档增强，详细说明 NS3 网络后端修改 | +| 2026/01 | 显存模块系列 commit | 完成 DeepSeek-V3-671B、Qwen3-Next-80B、Qwen3-MoE-235B 的精确显存计算 | +| 2026/02 | PD 分离显存规划 | 实现 Prefill/Decode 阶段独立的参数显存与 KV Cache 预算计算 | +| 2026/03 | 代码质量改进 | 双语注释/文档/日志全面改进，死代码清理，TODO 标准化，类型注解补充 | + +--- + +## 3. 端到端推理仿真 + +SimAI 支持完整的多请求 LLM 推理仿真，核心特性如下： + +### 3.1 Prefill–Decode（PD）分离架构 + +推理过程分为两个阶段： + +- **Prefill 阶段**：处理输入 prompt 的全部 token，生成第一个输出 token（计算密集型） +- **Decode 阶段**：逐 token 自回归生成后续输出（访存密集型） + +PD 分离允许将 Prefill 和 Decode 阶段部署在不同的 GPU 节点上，实现： +- 弹性资源分配（Prefill 节点可配置更多计算资源，Decode 节点可配置更多显存） +- 性能隔离（避免 Prefill 和 Decode 之间的资源争用） +- 灵活的 P:D 节点比例配置（通过 `--replica_config_pd_node_ratio` 控制） + +该设计参考了 [splitwise-sim](https://github.com/Mutinifni/splitwise-sim) [6]。 + +### 3.2 多请求推理调度 + +请求调度组件基于微软 [Vidur](https://github.com/microsoft/vidur) [5] 改编（vidur-alibabacloud），支持以下调度策略： + +| 调度器类型 | 级别 | 说明 | +|-----------|------|------| +| `split_wise` | 全局 | PD 分离场景下的全局调度，将请求分配到 Prefill 和 Decode 副本 | +| `lor` | 全局 | Least Outstanding Requests，将请求分配到负载最轻的副本 | +| `round_robin` | 全局 | 轮询分配 | +| `sarathi` | 副本级 | 单副本内的批处理调度 | +| `split_wise` | 副本级 | PD 分离场景下的副本级调度 | + +### 3.3 灵活的并行策略 + +支持多种并行策略的组合： + +- **数据并行（DP）** — 通过 `--cluster_config_num_replicas` 控制 +- **张量并行（TP）** — 通过 `--replica_config_tensor_parallel_size` 控制 +- **流水线并行（PP）** — 通过 `--replica_config_num_pipeline_stages` 控制 +- **专家并行（EP）** — 通过 `--replica_config_expert_model_parallel_size` 控制 + +同时支持 Dense 模型和 MoE（混合专家）模型。 + +### 3.4 多种执行时间预测后端 + +| 后端 | 说明 | +|------|------| +| **AICB/AIOB** | 部分支持 DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B 的计算核与 TP/DP/PP/EP 通信量建模 | +| **SimAI Simulation** | 基于 SimAI NS-3 的网络通信全栈仿真（当前支持 TP） | +| **SimAI Analytical** | SimAI 解析性能模型（当前支持 TP） | +| **Native Vidur** | 原版 Vidur 后端，支持 TP、DP、PP | + +--- + +## 4. 现代模型支持 + +SimAI 1.6 支持以下三种前沿 MoE 大模型，模型配置文件位于 `vidur-alibabacloud/data/hf_configs/`： + +### 4.1 DeepSeek-V3-671B + +| 属性 | 值 | +|------|-----| +| 总层数 | 61 | +| 注意力类型 | MLA（Multi-head Latent Attention） | +| 注意力头数 | 128 | +| 隐藏维度 | 7168 | +| KV LoRA 秩 | 512 | +| Q LoRA 秩 | 1536 | +| QK RoPE 头维度 | 64 | +| QK NoPE 头维度 | 128 | +| V 头维度 | 128 | +| MoE 路由专家数 | 256 | +| 每 token 激活专家数 | 8 | +| 共享专家数 | 1 | +| Dense 层（前 3 层） | 固定激活 8 个路由专家 + 1 个共享专家 | +| Sparse 层（第 3-60 层） | 从 256 个路由专家中动态选择 8 个 + 1 个共享专家 | + +配置文件：`data/hf_configs/deepseek_v3_config.json` + +### 4.2 Qwen3-MoE-235B + +| 属性 | 值 | +|------|-----| +| 总层数 | 94 | +| 注意力类型 | MHA/GQA | +| 注意力头数 | 64 | +| KV 头数 | 4 | +| 隐藏维度 | 4096 | +| 头维度 | 128 | +| MoE 路由专家数 | 128 | +| 每 token 激活专家数 | 8 | +| MoE 中间维度 | 1536 | + +配置文件：`data/hf_configs/qwen3_moe_config.json` + +### 4.3 Qwen3-Next-80B + +| 属性 | 值 | +|------|-----| +| 总层数 | 48 | +| 注意力类型 | 混合（全注意力 + 线性注意力，每 4 层交替） | +| 全注意力头数 | 16 | +| KV 头数 | 2 | +| 隐藏维度 | 2048 | +| 头维度 | 256 | +| 线性注意力键头数 | 16 | +| 线性注意力值头数 | 32 | +| MoE 路由专家数 | 512 | +| 每 token 激活专家数 | 10 | +| MoE 中间维度 | 512 | + +配置文件：`data/hf_configs/qwen3-next-80B-A3B_config.json` + +--- + +## 5. GPU 显存计算模块 + +这是 SimAI 1.6 的核心新增特性。该模块为推理仿真提供精确的 GPU 显存估算，覆盖模型参数显存、KV Cache 显存和最大批处理量计算，并在 PD 分离架构下分别计算 Prefill 和 Decode 阶段的显存预算。 + +### 5.1 参数量计算（ParamCounter） + +**文件路径**：`vidur-alibabacloud/vidur/utils/param_counter.py` + +ParamCounter 支持按层、按设备计算模型参数量，并在 PD 分离架构下返回三元组 `(total_params, prefill_params, decode_params)`。 + +#### MLA 参数量（DeepSeek-V3-671B） + +单层 MLA 参数量由以下部分组成： + +- **Q LoRA 下投影**：`wq_down = hidden_size * q_lora_rank` = 7168 * 1536 +- **Q LoRA 上投影**：`wq_up = q_lora_rank * num_attention_heads * qk_head_dim` = 1536 * 128 * 192，其中 `qk_head_dim = qk_nope_head_dim + qk_rope_head_dim = 128 + 64 = 192` +- **KV LoRA 下投影**：`wkv_down = hidden_size * kv_lora_rank` = 7168 * 512 +- **KV LoRA 上投影**：`wkv_up = kv_lora_rank * num_attention_heads * (qk_nope_head_dim + v_head_dim)` = 512 * 128 * 256 +- **输出投影**：`wo = hidden_size * num_attention_heads * v_head_dim` = 7168 * 128 * 128 + +FP8 量化下每个参数元素占 1 字节；FP16/BF16 下每个占 2 字节。 + +参考：[3] [4] + +#### MHA/GQA 参数量（Qwen3-MoE-235B） + +单层 MHA 参数量： + +``` +wq = hidden_size * num_attention_heads * head_dim +wk = hidden_size * num_key_value_heads * head_dim +wv = hidden_size * num_key_value_heads * head_dim +wo = hidden_size * num_attention_heads * head_dim +total = (wq + wk + wv + wo) * bytes_per_element +``` + +#### 线性注意力参数量（Qwen3-Next-80B） + +Qwen3-Next-80B 采用混合注意力架构，每 4 层交替使用全注意力和线性（GDN）注意力。线性注意力层使用独立的键/值头配置（`linear_key_head_dim`、`linear_num_key_heads` 等）。 + +#### MoE 专家参数量 + +每个专家的 FFN 参数量（3 个权重矩阵 W1、W2、W3）： + +``` +expert_params = 3 * hidden_size * moe_intermediate_size * bytes_per_element +``` + +#### PD 分离下的参数量计算 + +在 PD 分离架构下，Prefill 和 Decode 集群的专家并行度（EP）可能不同： + +- **Prefill 集群**：使用 `prefill_world_size` 作为 EP，每设备加载的专家数 = `num_routed_experts / prefill_world_size` +- **Decode 集群**：使用 `decode_world_size` 作为 EP，每设备加载的专家数 = `num_routed_experts / decode_world_size` + +这导致 Prefill 和 Decode 集群的参数显存不同，进而影响各自可用的 KV Cache 容量。 + +### 5.2 KV Cache 显存管理 + +**文件路径**：`vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py`、`vidur-alibabacloud/vidur/entities/replica.py` + +#### MHA/GQA KV Cache 计算 + +``` +kv_cache_per_token = 2 * num_kv_heads * head_dim * num_layers * bytes_per_element +``` + +其中因子 2 代表 K（Key）和 V（Value）两个缓存。 + +#### MLA KV Cache 计算（DeepSeek-V3-671B） + +MLA 架构使用压缩的 KV 表示。与 MHA 分别存储 K 和 V 缓存不同，MLA 存储一个联合编码 K 和 V 的压缩潜向量（`kv_lora_rank`），外加 RoPE 位置键（`qk_rope_head_dim`）。每 token 的 KV Cache 大小为： + +``` +kv_cache_per_token = (kv_lora_rank + qk_rope_head_dim) * num_layers * bytes_per_element +``` + +其中 `kv_lora_rank = 512`，`qk_rope_head_dim = 64`。相比 MHA 每 token 缓存量 `2 * num_kv_heads * head_dim` = 2 * 128 * 128 = 32768 个元素，MLA 减少至 576 个元素——约 **57 倍**压缩。 + +#### 逐请求 KV Cache 追踪 + +`Replica` 实体（`vidur/entities/replica.py`）维护以下状态： + +- `_allocated_kv_cache_memory`：已分配的 KV Cache 显存（字节） +- `_max_kv_cache_memory`：最大 KV Cache 容量（首次调用时由 MemoryPlanner 计算） +- `_kv_cache_allocation_map`：每请求 KV Cache 分配映射 + +支持的操作： +- `allocate_request_kv_cache_memory(request, num_blocks, block_size)` — 为请求分配 KV Cache +- `release_request_kv_cache_memory(request)` — 释放已完成请求的 KV Cache +- `get_remaining_kv_cache_capacity()` — 查询剩余 KV Cache 容量和可服务请求数 + +### 5.3 MemoryPlanner 显存规划 + +**文件路径**：`vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py` + +MemoryPlanner 是显存管理的核心组件，计算流程如下： + +1. **计算可用 GPU 显存**：`available_memory = total_GPU_memory * (1 - memory_margin_fraction)` +2. **获取模型参数显存**：通过 ParamCounter 计算，PD 分离下返回 `(total, prefill, decode)` 三元组 +3. **计算 KV Cache 可用显存**：`kv_cache_available = available_memory - param_memory` +4. **计算最大并发请求数**：`max_requests = kv_cache_available / kv_cache_per_request` + +在 PD 分离架构下： +- Prefill 副本使用 `prefill_param_mem` 计算 KV Cache 预算 +- Decode 副本使用 `decode_param_mem` 计算 KV Cache 预算 + +包含 OOM 检测：当参数显存超过可用显存时，输出错误信息并建议增加 TP/EP、使用更大 GPU 或启用 FP8 量化。 + +--- + +## 6. AICB 推理工作负载生成 + +[AICB](https://github.com/aliyun/aicb) 新增了推理工作负载生成能力（PR [#58](https://github.com/aliyun/aicb/pull/58)、[#60](https://github.com/aliyun/aicb/pull/60)），主要特性： + +- **Prefill/Decode 阶段分离**：分别生成 Prefill 和 Decode 阶段的计算与通信工作负载 +- **计算核 Profiling**：依赖以下硬件加速库（需要 Hopper SM90 或 Blackwell SM100 GPU）： + - [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) — FP8 矩阵乘法 + - [FlashMLA](https://github.com/deepseek-ai/FlashMLA) — MLA 注意力加速 + - [FlashInfer](https://github.com/flashinfer-ai/flashinfer) — 高性能推理内核 +- **通信量建模**：支持 TP、DP、PP、EP 四种并行策略下的通信量计算 +- **模型支持**：DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B + +--- + +## 7. 四场景端到端测试套件 + +**文件路径**：`vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh` + +提供了 4 个预配置的端到端测试场景，覆盖不同模型、并行策略和 PD 分离配置。 + +### 共用硬件配置 + +- GPU：H20 (h20_dgx) +- NVLink 带宽：1600 Gbps +- RDMA 带宽：800 Gbps +- PD P2P 带宽：800 Gbps +- 数据类型：fp8 +- 请求：Poisson QPS=100，4 个请求，固定 prefill=100 / decode=8 tokens + +### 场景配置表 + +| 场景 | 模型 | PD 分离 | World Size | TP | PP | EP | 全局调度 | +|------|------|---------|-----------|----|----|-----|---------| +| 1 | Qwen3-Next-80B (MoE) | 否 | 32 (dp=32) | 1 | 1 | 1 | lor | +| 2 | Qwen3-Next-80B (MoE) | 是 (P=2, D=6) | 8 | 1 | 1 | 1 | split_wise | +| 3 | DeepSeek-671B (MoE) | 是 (P=2, D=6) | 8 | 8 | 1 | 8 | split_wise | +| 4 | Qwen3-MoE-235B (MoE) | 是 (P=2, D=6) | 8 | 4 | 1 | 4 | split_wise | + +### 运行方式 + +```bash +# 运行全部 4 个场景 +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all + +# 运行单个场景 +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 3 +``` + +详细性能数据请运行测试套件获取。每次运行产生的输出文件包括 `request_metrics.csv`（逐请求指标）、`chrome_trace.json`（时间线追踪）、`config.json`（配置快照）以及 `plots/` 目录下的指标文件。 + +--- + +## 8. 代码质量改进 + +SimAI 1.6 在代码质量方面进行了系统性改进： + +### 8.1 双语注释与文档 + +- 所有公共 API 添加中英双语 docstring +- 配置模块（config）、调度器（scheduler）、预测器（predictor）、工具类（utils）添加双语注释 +- 实体模块（entities）添加双语注释 +- Shell 脚本输出和 Python 运行时输出均为双语格式 + +### 8.2 日志系统改进 + +- 全面将 `print` 语句替换为 `logging` 模块（涉及 ~12 个文件） +- 统一日志格式，使用括号式双语格式（如 `"GPU总内存 (Total GPU mem): 96.00 GB"`） + +### 8.3 死代码清理 + +- 移除约 390 行无效代码块 +- 清理个人调试标记 + +### 8.4 TODO 标准化 + +- 统一为 `TODO(author): description` 格式 +- 补充缺失的类型注解 + +--- + +## 9. 系统架构 + +### 推理仿真数据流 + +``` +请求生成器 (Request Generator) + │ 生成合成/真实 trace 请求 + ▼ +全局调度器 (Global Scheduler) + │ 将请求分配到 Prefill/Decode 副本 + ▼ +副本调度器 (Replica Scheduler) + │ 批处理组装与调度 + ▼ +显存管理 (MemoryPlanner + Replica) + │ KV Cache 分配与容量检查 + ▼ +执行时间预测 (Execution Time Predictor) + │ AICB / SimAI Simulation / SimAI Analytical / Vidur + ▼ +指标收集 (Metrics Store) + │ TTFT, TBT, E2E, 通信/计算开销 + ▼ +输出 (request_metrics.csv, chrome_trace.json, plots/) +``` + +--- + +## 10. 快速开始 + +### 环境搭建 + +#### 方式一：Docker（推荐） + +```bash +# 从项目根目录构建 +docker build -t simai:latest . +docker run --gpus all -it --rm simai:latest +``` + +> 若使用 Hopper GPU，请在 Dockerfile 中添加 `ENV FLASH_MLA_DISABLE_SM100=1`。 + +#### 方式二：Conda + +```bash +cd vidur-alibabacloud +conda env create -p ./env -f ./environment.yml +conda activate vidur +pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ +``` + +### 运行四场景测试 + +```bash +# 前置条件：conda activate vidur +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all +``` + +### 编译与运行 SimAI 训练仿真 + +```bash +# 编译 SimAI-Analytical +./scripts/build.sh -c analytical + +# 运行 +./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml +``` + +--- + +## 11. 参考文献 + +[1] SimAI: Unifying Architecture Design and Performance Tuning for Large-Scale Large Language Model Training with Scalability and Precision. NSDI'25 Spring. [[pdf](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf)] + +[2] InferSim — Alibaba. Parameter counting and KV cache estimation. [[GitHub](https://github.com/alibaba/InferSim)] + +[3] DeepSeek V3 参数推导详解. 知乎. [[link](https://zhuanlan.zhihu.com/p/21455638257)] + +[4] DeepSeek V3 Parameter Size Analysis. Yang Wenbo. [[link](https://yangwenbo.com/articles/deepseek-v3-parameter-size.html)] + +[5] Vidur: A Large-Scale Simulation Framework For LLM Inference. Microsoft Research. [[GitHub](https://github.com/microsoft/vidur)] + +[6] splitwise-sim — Prefill-Decode Disaggregation Simulation. [[GitHub](https://github.com/Mutinifni/splitwise-sim)] diff --git a/docs/en/benchmarking/index.md b/docs/en/benchmarking/index.md new file mode 100644 index 00000000..2431cf17 --- /dev/null +++ b/docs/en/benchmarking/index.md @@ -0,0 +1,33 @@ +# Benchmarking + +This section covers benchmarking and validation approaches for SimAI. + +--- + +## Contents + +| Document | Description | +|----------|-------------| +| [4-Scenario End-to-End Test Suite](test_suite.md) | Pre-configured test scenarios covering different models, parallelism strategies, and PD configurations | + +--- + +## Benchmarking Approaches + +SimAI supports several benchmarking methodologies: + +### Architecture Comparison + +Compare different network architectures (e.g., Spectrum-X vs DCN+) under identical workloads to evaluate their performance characteristics. + +### Algorithm Comparison + +Compare different collective communication algorithms (e.g., RING vs NVLS) to understand their performance trade-offs at various message sizes. + +### Parameter Optimization + +Use SimAI-Analytical for rapid exploration of parallel parameter combinations (TP, PP, EP, DP) to find optimal configurations. + +### Validation Against Real Hardware + +Use AICB physical execution results as ground truth to validate simulation accuracy. diff --git a/docs/en/benchmarking/test_suite.md b/docs/en/benchmarking/test_suite.md new file mode 100644 index 00000000..54a54404 --- /dev/null +++ b/docs/en/benchmarking/test_suite.md @@ -0,0 +1,139 @@ +# 4-Scenario End-to-End Test Suite + +SimAI provides a pre-configured test suite covering 4 representative inference scenarios, enabling quick validation of all supported configurations. + +--- + +## Overview + +The test suite is located at `vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh` and covers different combinations of models, parallelism strategies, and PD disaggregation configurations. + +--- + +## Running + +```bash +# Run all 4 scenarios +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all + +# Run a single scenario +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 + +# Show help +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --help +``` + +> **Prerequisites**: `conda activate vidur` environment must be active. + +--- + +## Shared Hardware Configuration + +All scenarios share the following hardware settings: + +| Parameter | Value | +|-----------|-------| +| GPU | H20 (h20_dgx) | +| NVLink Bandwidth | 1600 Gbps | +| RDMA Bandwidth | 800 Gbps | +| PD P2P Bandwidth | 800 Gbps | +| PD P2P Data Type | fp8 | +| Request Generator | Poisson, QPS=100 | +| Request Count | 4 | +| Prefill Tokens | 100 (fixed) | +| Decode Tokens | 8 (fixed) | + +--- + +## Scenario Configuration + +| Scenario | Model | PD Separation | World Size | TP | PP | EP | Global Scheduler | +|----------|-------|---------------|-----------|----|----|-----|-----------------| +| **1** | Qwen3-Next-80B (MoE) | No | 32 (dp=32) | 1 | 1 | 1 (default) | lor | +| **2** | Qwen3-Next-80B (MoE) | Yes (P=2, D=6) | 8 | 1 | 1 | 1 (default) | split_wise | +| **3** | DeepSeek-671B (MoE) | Yes (P=2, D=6) | 8 | 8 | 1 | 8 | split_wise | +| **4** | Qwen3-MoE-235B (MoE) | Yes (P=2, D=6) | 8 | 4 | 1 | 4 | split_wise | + +### Scenario Details + +- **Scenario 1**: Large-scale DP without PD separation — tests baseline throughput +- **Scenario 2**: Same model with PD separation — tests PD disaggregation overhead +- **Scenario 3**: DeepSeek-671B with large TP/EP — tests MoE with MLA attention +- **Scenario 4**: Qwen3-MoE-235B with moderate TP/EP — tests MHA/GQA attention model + +--- + +## Output + +### Output Directory + +- **Via run_scenarios.sh**: `examples/vidur-ali-scenarios/simulator_output/` +- **Direct python**: `./simulator_output/` + +### Output Files + +``` +// +├── request_metrics.csv # Per-request metrics +├── chrome_trace.json # Chrome DevTools timeline +├── config.json # Configuration snapshot +└── plots/ # Metric CSV/JSON files +``` + +### Logs + +Run logs are saved to `examples/vidur-ali-scenarios/logs/scenario__.log`. + +--- + +## Architecture Comparison Examples + +### RING vs NVLS (SimAI-Simulation) + +```bash +# NVLS topology and run +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py --ro -g 32 -gt H100 -bw 400Gbps -nvbw 1360Gbps +AS_SEND_LAT=12 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator -t 8 -w ./example/microAllReduce.txt \ + -n ./Rail_Opti_SingleToR_32g_8gps_400Gbps_H100 -c ./astra-sim-alibabacloud/inputs/config/SimAI.conf + +# RING topology and run +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py --ro -g 32 -gt H100 -bw 400Gbps -nvbw 1440Gbps +AS_SEND_LAT=2 AS_PXN_ENABLE=1 ./bin/SimAI_simulator -t 8 -w ./example/microAllReduce.txt \ + -n ./Rail_Opti_SingleToR_32g_8gps_400Gbps_H100 -c ./astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +**Results** (busbw in GB/s): + +| Message Size | NVLS | RING | +|-------------|------|------| +| 16M | 148.88 | 141.84 | +| 32M | 178.04 | 153.68 | +| 64M | 197.38 | 160.60 | +| 128M | 208.70 | 163.85 | +| 256M | 214.87 | 165.72 | +| 512M | 218.09 | 166.68 | + +### Spectrum-X vs DCN+ (SimAI-Simulation) + +```bash +# Generate topologies +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py -topo DCN+ -g 256 -psn 64 -bw 400Gbps +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py -topo Spectrum-X -g 256 +``` + +**Results** (busbw in GB/s): + +| Message Size | Spectrum-X | DCN+ SingleToR | +|-------------|------------|----------------| +| 16M | 33.10 | 23.33 | +| 64M | 42.05 | 23.68 | +| 256M | 45.10 | 36.21 | +| 512M | 45.65 | 36.24 | + +--- + +## See Also + +- [Inference Simulation](../user_guide/inference_simulation.md) — Full inference simulation guide +- [vidur-alibabacloud](../components/vidur.md) — Component documentation +- [Result Analysis](../user_guide/result_analysis.md) — Output interpretation diff --git a/docs/en/community/index.md b/docs/en/community/index.md new file mode 100644 index 00000000..f5579139 --- /dev/null +++ b/docs/en/community/index.md @@ -0,0 +1,90 @@ +# Community + +Welcome to the SimAI community! SimAI is built by a growing community of researchers and engineers from Alibaba Cloud and academic institutions worldwide. + +--- + +## Getting Help + +- **GitHub Issues**: [github.com/aliyun/SimAI/issues](https://github.com/aliyun/SimAI/issues) — Bug reports, feature requests, questions +- **Discussions**: Open an issue with "Question:" prefix for general questions +- **Email**: Gang Lu (yunding.lg@alibaba-inc.com), Feiyang Xue (xuefeiyang.xfy@alibaba-inc.com), Qingxu Li (qingxu.lqx@alibaba-inc.com) + +--- + +## Community Chat Groups + +Join the SimAI community via DingTalk or WeChat: + +
+ SimAI DingTalk + SimAI WeChat +
+ +--- + +## Events + +### Upcoming Events + +| Date | Event | Location | Type | +|:----:|:------|:---------|:----:| +| — | — | — | — | + +### Past Events + +| Date | Event | Location | Type | +|:----:|:------|:---------|:----:| +| Dec 30, 2025 | SimAI 1.5 Release | Online | Virtual | +| Jun 4, 2025 | First SimAI Community Workshop | Peking University | On-site | +| May 24, 2025 | 28th Chinasys Workshop — SimAI Talk | Chongqing University | On-site | +| Dec 27, 2024 | SimAI Technical Presentation | Beihang University | On-site | +| Dec 6, 2024 | HKUST Technical Workshop | HKUST(GZ) | On-site | +| Dec 5, 2024 | Bench'24 Conference — SimAI Tutorial | Guangzhou | On-site | +| Nov 26, 2024 | SimAI Community Live Stream (400+ attendees) | Online | Virtual | +| Nov 15, 2024 | Technical Workshop | Thousand Island Lake | On-site | +| Oct 18, 2024 | Guest Lecture — SimAI Tutorial | Fudan University | On-site | +| Sept 24-26, 2024 | CCF HPC China 2024 | Wuhan | Conference | + +--- + +## Citation + +SimAI has been accepted by **NSDI'25 Spring**. If you use SimAI in your research, please cite: + +```bibtex +@inproceedings{simai-nsdi25, + title={SimAI: Unifying Architecture Design and Performance Tuning for Large-Scale Large Language Model Training with Scalability and Precision}, + booktitle={NSDI'25 Spring}, + year={2025} +} +``` + +**Resources:** +- [Paper (PDF)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) +- [Slides](../../docs/SimAI_Intro_Online.pdf) +- [Video](https://n.dingtalk.com/dingding/live-room/index.html?roomId=OF5BkBUXVxmgsK7x&liveUuid=305736cd-aa70-498b-8003-2b471a53decd) + +--- + +## Acknowledgments + +Major contributors: + +- TianHao Fu (Peking University) and [TELOS-syslab](https://github.com/TELOS-syslab/) +- Parth Parikh (KEYSIGHT) +- Sarah-Michelle Hammer & Ziyi Wang (TU-Berlin) +- Xinyue Li (BUPT) +- Tong Chen (Zhejiang University) +- Ming Wang (BUPT) +- Tao Jiang (Institute of Computing Technology, Chinese Academy of Sciences) + +And many other individual contributors — see [Contributors to aliyun/SimAI](https://github.com/aliyun/SimAI/graphs/contributors). + +Special thanks to Chenning Li (MIT CSAIL) for initiating the cooperation on integrating SimAI into [M4](https://github.com/netiken/m4). + +--- + +## Contributing + +We warmly welcome contributions! See our [Contributing Guide](../developer_guide/contributing.md) for details. diff --git a/docs/en/components/aicb.md b/docs/en/components/aicb.md new file mode 100644 index 00000000..b6765545 --- /dev/null +++ b/docs/en/components/aicb.md @@ -0,0 +1,212 @@ +# AICB — AI Communication Benchmark + +**Repository**: [aliyun/aicb](https://github.com/aliyun/aicb) | **Language**: Python + +AICB is a specialized communication benchmarking suite for AI scenarios. It generates realistic communication workloads aligned to real-world LLM training and inference processes. + +--- + +## Introduction + +AICB (Artificial Intelligence Communication Benchmark) produces communication workloads with precise patterns aligned to real-world applications. It supports: + +- Benchmarking and tuning GPU cluster communication systems +- Investigating communication patterns of specific model configurations +- Generating workloads for simulators like SimAI + +--- + +## Benchmark Suite + +AICB provides 10 pre-configured benchmark cases covering typical LLM configurations: + +| ID | Model | Seq Length | Framework | TP | PP | SP | MoE | +|----|-------|-----------|-----------|----|----|-----|-----| +| 1 | LLaMA-7B | 2048 | Megatron | 1 | 1 | - | - | +| 2 | GPT-13B | 2048 | Megatron | 2 | 1 | Yes | - | +| 3 | GPT-22B | 2048 | Megatron | 4 | 1 | - | - | +| 4 | LLaMA-65B | 4096 | Megatron | 8 | 2 | Yes | - | +| 5 | GPT-175B | 2048 | Megatron | 8 | 8 | Yes | - | +| 6 | GPT-175B | 2048 | Megatron | 8 | 8 | - | - | +| 7 | Llama3-405B | 8192 | Megatron | 8 | 16 | Yes | - | +| 8 | LLaMA-7B | 4096 | DeepSpeed | 1 | 1 | - | Zero-2 | +| 9 | LLaMA-65B | 4096 | DeepSpeed | 1 | 1 | - | Zero-3 | +| 10 | Mistral-8x7B | 2048 | Megatron | 2 | 1 | Yes | 8 experts | + +--- + +## Environment Setup + +### Docker + +```bash +docker build -t aicb:v0.0.1 . +docker run --gpus all --net host --shm-size 16g -it --rm aicb:v0.0.1 +``` + +### Local Environment + +Requirements: Python >= 3.8, CUDA >= 11.8, PyTorch >= 2.0.0, NVIDIA APEX + +### NGC Container + +```bash +docker pull nvcr.io/nvidia/pytorch:xx.xx-py3 +docker run --gpus all -it --rm -v /path/to/aicb:/workspace/aicb nvcr.io/nvidia/pytorch:xx.xx-py3 +``` + +> **Note**: Inference workload profiling requires NVIDIA Hopper (SM90) or Blackwell (SM100) GPUs. + +--- + +## Physical Execution on GPU Clusters + +### Environment Variables + +| Parameter | Description | +|-----------|-------------| +| `nnodes` | Number of nodes | +| `node_rank` | Rank of the node | +| `nproc_per_node` | Number of GPUs per node | +| `master_addr` | Master node address | +| `master_port` | Master node port | + +### Running Megatron Workloads + +```bash +sh scripts/megatron_gpt.sh \ + --nnodes 1 --node_rank 0 --nproc_per_node 8 \ + --master_addr localhost --master_port 29500 \ + -m 7 --world_size 8 --tensor_model_parallel_size 2 --pipeline_model_parallel 1 \ + --frame Megatron --global_batch 16 --micro_batch 1 \ + --seq_length 2048 --swiglu --use_flash_attn --aiob_enable +``` + +### Running MoE Workloads + +```bash +sh scripts/megatron_gpt.sh \ + -m moe --world_size 8 --tensor_model_parallel_size 4 \ + --moe_enable --expert_model_parallel_size 1 \ + --num_experts 4 --moe_router_topk 2 \ + --frame Megatron --global_batch 16 --micro_batch 1 \ + --sp --grouped_gemm --aiob_enable --swiglu --use_flash_attn +``` + +### Running DeepSeek Workloads + +```bash +sh scripts/megatron_gpt.sh \ + --frame DeepSeek -m deepseek \ + --tensor_model_parallel_size 4 --moe_enable \ + --expert_model_parallel_size 1 --num_experts 4 \ + --global_batch 4 --micro_batch 1 --world_size 4 \ + --num_layers 10 --sp --swiglu --aiob_enable +``` + +--- + +## Training Workload Generation + +Generate workload files for SimAI simulation: + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --model_name GPT-13B --frame=Megatron \ + --world_size=16 --tensor_model_parallel_size=2 --pipeline_model_parallel=1 \ + --global_batch=16 --micro_batch=1 --num_layers=40 --seq_length=2048 \ + --hidden_size=5120 --epoch_num=1 --num_attention_heads=40 \ + --aiob_enable --use_flash_attn --swiglu +``` + +Output saved in `results/mocked_workload/`. + +--- + +## Inference Workload Generation + +AICB generates inference workloads with prefill/decode phase separation for: + +| Model | Attention | MoE Experts | +|-------|-----------|-------------| +| DeepSeek-V3-671B | MLA | 256 routed + 1 shared | +| Qwen3-MoE-235B | MHA/GQA | 128 routed | +| Qwen3-Next-80B | Hybrid (full + linear) | 512 routed | + +Requires hardware-accelerated libraries: [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM), [FlashMLA](https://github.com/deepseek-ai/FlashMLA), [FlashInfer](https://github.com/flashinfer-ai/flashinfer). + +--- + +## AIOB: Computation Profiling + +AIOB profiles actual GPU computation times and embeds them into workloads: + +- `--aiob_enable` — Profile on current GPU +- `--comp_filepath ` — Use pre-existing profiling data + +Output saved in `results/aiob_outputs/`. + +--- + +## Custom Model Development + +AICB supports creating workloads for custom model architectures using `MockedParam` and `MockedModel` base classes. + +The training process is abstracted into: `init → forward → backward → step` + +Each workload item consists of: +1. **Communication info**: `comm_type`, `comm_group`, `comm_group_size`, `msg_size` +2. **Additional info**: source node (broadcast), compute time +3. **Runtime info**: `elapsed_time`, `algo_bw`, `bus_bw` + +Refer to existing `MockedMegatron` and `MockedDeepSpeed` implementations for examples. + +--- + +## Key Parameters + +| Category | Parameter | Description | +|----------|-----------|-------------| +| Framework | `frame` | Megatron / DeepSpeed / DeepSeek | +| Model | `model_size` | Pre-configured size (7/13/22/175/moe/deepseek) | +| Training | `world_size` | Total GPU count | +| | `global_batch` | Total batch size | +| | `micro_batch` | Micro-batch size | +| | `seq_length` | Sequence length | +| Parallelism | `tensor_model_parallel_size` | TP degree | +| | `pipeline_model_parallel` | PP degree | +| | `expert_model_parallel_size` | EP degree | +| MoE | `moe_enable` | Enable MoE | +| | `num_experts` | Number of experts | +| | `moe_router_topk` | Experts per token | +| DeepSeek | `qk_rope_dim` | RoPE dimension for QK | +| | `kv_lora_rank` | KV compression LoRA dimension | +| | `q_lora_rank` | Q compression LoRA dimension | +| | `n_shared_expert` | Number of shared experts | +| Optimization | `use_flash_attn` | FlashAttention | +| | `swiglu` | SwiGLU activation | +| | `aiob_enable` | AIOB compute profiling | +| | `comp_filepath` | Pre-existing computation file | + +--- + +## Result Output + +### Physical Execution + +- Per-communication logs: type, group, message size, execution time, throughput +- Per-iteration timing analysis +- CSV outputs in `results/comm_logs/` + +### Workload Files + +- Training workloads: `results/mocked_workload/` or `results/workload/` +- AIOB profiles: `results/aiob_outputs/` + +--- + +## See Also + +- [Workload Generation Guide](../user_guide/workload_generation.md) — User-facing workload generation guide +- [Supported Models](../user_guide/supported_models.md) — Full model list +- [Tutorial](https://github.com/aliyun/aicb/blob/master/training/tutorial.md) — Detailed AICB tutorial diff --git a/docs/en/components/astra_sim.md b/docs/en/components/astra_sim.md new file mode 100644 index 00000000..d3685618 --- /dev/null +++ b/docs/en/components/astra_sim.md @@ -0,0 +1,147 @@ +# astra-sim-alibabacloud — Simulation Engine + +**Location**: In-tree (`astra-sim-alibabacloud/`) | **Language**: C++ + +The core simulation engine of SimAI, extended from [astra-sim 1.0](https://github.com/astra-sim/astra-sim/tree/ASTRA-sim-1.0). It supports three operation modes and integrates NCCL algorithms with custom enhancements. + +--- + +## Overview + +astra-sim-alibabacloud serves as the central orchestrator for SimAI simulations. It: + +- Receives workloads from AICB +- Uses SimCCL to decompose collective operations into P2P transfers +- Drives network simulation via NS-3 (simulation mode) or direct RDMA (physical mode) +- Computes timing using busbw parameters (analytical mode) + +--- + +## Three Operation Modes + +### SimAI-Analytical + +Fast analytical simulation using bus bandwidth (busbw) to estimate collective communication times. + +**Build**: `./scripts/build.sh -c analytical` +**Binary**: `bin/SimAI_analytical` + +### SimAI-Simulation + +Full-stack simulation with NS-3 network backend for fine-grained network modeling. + +**Build**: `./scripts/build.sh -c ns3` +**Binary**: `bin/SimAI_simulator` + +### SimAI-Physical + +Physical traffic generation using RDMA on real hardware. + +**Build**: `./scripts/build.sh -c phy` +**Binary**: `bin/SimAI_phynet` + +--- + +## Core Components + +| Component | Description | +|-----------|-------------| +| **AstraComputeAPI** | Manages computation timing and scheduling | +| **MemoryAPI** | Handles memory allocation and tracking | +| **NetworkAPI** | Interface to network backends (NS-3, physical) | +| **MockNcclGroup** | Simulates NCCL communication groups | +| **MockNcclChannel** | Manages individual communication channels | +| **SimAiFlowModelRdma** | RDMA flow model for traffic simulation | + +--- + +## Configuration + +### SimAI.conf + +The main configuration file is located at `astra-sim-alibabacloud/inputs/config/SimAI.conf`. It controls simulation parameters including: + +- Communication algorithms +- Buffer sizes +- Timing parameters +- Network backend settings + +### Environment Variables (Simulation Mode) + +| Variable | Description | Default | +|----------|-------------|---------| +| `AS_LOG_LEVEL` | Log level: DEBUG, INFO, WARNING, ERROR | `INFO` | +| `AS_PXN_ENABLE` | Enable PXN (Proxied NVLINK) | `0` (false) | +| `AS_NVLS_ENABLE` | Enable NVLS (NVLink Sharp) | `0` (false) | +| `AS_SEND_LAT` | Packet sending latency (us) | `6` | +| `AS_NVLSTREE_ENABLE` | Enable NVLS Tree algorithm | `false` | + +### Simulation Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `-t` / `--thread` | Number of threads for acceleration | `1` (recommended: 8-16) | +| `-w` / `--workload` | Path to workload file | Required | +| `-n` / `--network-topo` | Network topology file path | Required (simulation mode) | +| `-c` / `--config` | SimAI configuration file | Required | + +--- + +## Topology Generation + +astra-sim provides 5 topology templates via `gen_Topo_Template.py`: + +### Available Templates + +| Template | Architecture | Description | +|----------|-------------|-------------| +| `Spectrum-X` | NVIDIA Spectrum-X | Rail-optimized, single ToR, single plane | +| `AlibabaHPN` (single plane) | Alibaba HPN 7.0 | Dual ToR, rail-optimized, single plane | +| `AlibabaHPN` (dual plane) | Alibaba HPN 7.0 | Dual ToR, rail-optimized, dual plane | +| `DCN+` (single ToR) | DCN+ | Single ToR, non rail-optimized | +| `DCN+` (dual ToR) | DCN+ | Dual ToR, non rail-optimized | + +### Topology Parameters + +| Level | Parameter | Description | +|-------|-----------|-------------| +| **Global** | `-topo` | Template name | +| | `-g` | Number of GPUs | +| | `--dp` | Enable dual plane | +| | `--ro` | Enable rail-optimized | +| | `--dt` | Enable dual ToR | +| **Intra-Host** | `-gps` | GPUs per server | +| | `-gt` | GPU type (A100/H100) | +| | `-nvbw` | NVLink bandwidth | +| | `-nl` | NVLink latency | +| **Intra-Segment** | `-bw` | NIC to ASW bandwidth | +| | `-asw` | ASW switch count | +| | `-nps` | NICs per switch | +| **Intra-Pod** | `-psn` | PSW switch count | +| | `-apbw` | ASW to PSW bandwidth | + +### Examples + +```bash +# Spectrum-X with 128 GPUs +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +# Dual-Plane AlibabaHPN with 64 GPUs +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo AlibabaHPN --dp -g 64 -asn 16 -psn 16 + +# Dual-ToR DCN+ with 128 GPUs +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo DCN+ --dt -g 128 -asn 2 -psn 8 +``` + +--- + +## See Also + +- [SimAI-Analytical Guide](../user_guide/simai_analytical.md) — Analytical mode usage +- [SimAI-Simulation Guide](../user_guide/simai_simulation.md) — NS-3 simulation usage +- [SimAI-Physical Guide](../user_guide/simai_physical.md) — Physical mode usage +- [NS-3 Component](ns3.md) — Network backend details +- [SimCCL Component](simccl.md) — Collective communication decomposition diff --git a/docs/en/components/index.md b/docs/en/components/index.md new file mode 100644 index 00000000..80890c35 --- /dev/null +++ b/docs/en/components/index.md @@ -0,0 +1,80 @@ +# Components Overview + +SimAI is a modular project composed of 5 core components. Each component can be used independently or combined to achieve different simulation scenarios. + +--- + +## Architecture + +``` + |--- AICB (Workload generation & compute profiling) +SimAI --|--- SimCCL (Collective communication algorithm analysis) + |--- astra-sim-alibabacloud (Simulation engine: Analytical / Simulation / Physical) + |--- ns-3-alibabacloud (NS-3 network backend) + |--- vidur-alibabacloud (Multi-request inference scheduling & memory management) +``` + +--- + +## Component Summary + +| Component | Language | Repository | Description | +|-----------|----------|------------|-------------| +| [AICB](aicb.md) | Python | [aliyun/aicb](https://github.com/aliyun/aicb) | AI Communication Benchmark — workload generation for training and inference | +| [SimCCL](simccl.md) | Python | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | Collective communication to point-to-point transformation | +| [astra-sim-alibabacloud](astra_sim.md) | C++ | In-tree | Core simulation engine supporting 3 modes (Analytical/Simulation/Physical) | +| [ns-3-alibabacloud](ns3.md) | C++ | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | NS-3 network simulator backend with RDMA/datacenter extensions | +| [vidur-alibabacloud](vidur.md) | Python | In-tree | LLM inference simulation with PD disaggregation and request scheduling | + +--- + +## Component Combinations by Scenario + +| Scenario | AICB | SimCCL | astra-sim | ns-3 | vidur | +|----------|------|--------|-----------|------|-------| +| AICB Test Suite (physical GPU) | Required | - | - | - | - | +| Workload Generation | Required | - | - | - | - | +| Collective Comm Analysis | - | Required | - | - | - | +| SimAI-Analytical | Required | - | Required (analytical) | - | - | +| SimAI-Simulation | Required | Required | Required (simulation) | Required | - | +| SimAI-Physical | Required | Required | Required (physical) | - | - | +| Inference Simulation | Required | Required | Required (analytical/simulation) | Optional | Required | + +--- + +## Data Flow + +``` +AICB (Workload Generation) + | + |-- Training workload (.txt) --> astra-sim-alibabacloud + |-- Inference workload -------> vidur-alibabacloud + | +SimCCL (Collective → P2P) + | + |--> astra-sim-alibabacloud (Simulation/Physical mode) + | +astra-sim-alibabacloud (Simulation Engine) + | + |-- Analytical mode: busbw-based estimation + |-- Simulation mode: NS-3 backend + |-- Physical mode: RDMA traffic injection + | +ns-3-alibabacloud (Network Backend) + | + |--> Fine-grained network simulation results + | +vidur-alibabacloud (Inference Scheduling) + | + |--> request_metrics.csv, chrome_trace.json, plots/ +``` + +--- + +## Detailed Component Documentation + +- **[AICB](aicb.md)** — Workload generation, benchmark suite, AIOB compute profiling +- **[SimCCL](simccl.md)** — Collective communication decomposition +- **[astra-sim-alibabacloud](astra_sim.md)** — Core simulation engine, configuration, topology generation +- **[ns-3-alibabacloud](ns3.md)** — RDMA network simulation, CC algorithms, analysis tools +- **[vidur-alibabacloud](vidur.md)** — Inference simulation, PD disaggregation, GPU memory management diff --git a/docs/en/components/ns3.md b/docs/en/components/ns3.md new file mode 100644 index 00000000..ed5c0468 --- /dev/null +++ b/docs/en/components/ns3.md @@ -0,0 +1,175 @@ +# ns-3-alibabacloud — Network Simulation Backend + +**Repository**: [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | **Language**: C++ + +An NS-3-based network simulator acting as the network backend for SimAI, extended with datacenter/RDMA-oriented end-to-end modeling. + +--- + +## Overview + +Compared to upstream [NS-3](https://www.nsnam.org/), ns-3-alibabacloud extends the point-to-point module with comprehensive datacenter networking features: + +- **QBB/PFC + multi-priority queues** — 8 priority queues with PAUSE/RESUME handling +- **ECN + CNP feedback** — Switch-side ECN marking and receiver-side congestion notification +- **RDMA host stack (QP-level)** — Full QP modeling with 5 congestion control algorithms +- **Switch and NVSwitch modeling** — ECMP forwarding, buffer management, PFC logic + +### dev/qp Branch + +The [dev/qp](https://github.com/aliyun/ns-3-alibabacloud/tree/dev/qp) branch includes additional enhancements: + +1. QP logic support with creation/destruction based on actual RDMA logic +2. Per-IP or per-QP NIC CC configuration +3. Optimized Max-Min scheduling logic +4. Decoupled CC module for modularity + +--- + +## Core Modules + +### QBB Net Device (`qbb-net-device`) + +A QBB-capable net device with 8 priorities built on top of `PointToPointNetDevice`. Features: + +- PFC PAUSE/RESUME handling +- `RdmaEgressQueue` with high-priority ACK/NACK queue + round-robin across QPs +- `BEgressQueue` for switch port round-robin +- NVSwitch send path support (NVLS mode) + +**Key attributes**: `QbbEnabled`, `QcnEnabled`, `DynamicThreshold`, `PauseTime`, `NVLS_enable` + +### RDMA Host Stack (`rdma-hw`) + +Host RDMA core implementing: + +- QP create/delete lifecycle +- Packet construction (PPP + IPv4 + UDP + SeqTs headers) +- ACK/NACK/CNP processing +- Per-QP congestion control algorithms +- NVSwitch routing tables + +**Congestion Control Algorithms**: + +| Algorithm | Description | +|-----------|-------------| +| **DCQCN** | Data Center Quantized Congestion Notification | +| **HPCC** | High Precision Congestion Control | +| **TIMELY** | RTT-based congestion control | +| **DCTCP** | Data Center TCP | +| **HPCC-PINT** | HPCC with Probabilistic INT | + +**Protocol Numbers (IPv4 Protocol field)**: + +| Protocol | Number | Description | +|----------|--------|-------------| +| UDP Data | `0x11` | Normal data packets | +| CNP | `0xFF` | Congestion Notification Packet | +| PFC | `0xFE` | Priority Flow Control | +| ACK | `0xFC` | Acknowledgment | +| NACK | `0xFD` | Negative Acknowledgment | + +### Switch Node (`switch-node`) + +Switch pipeline implementing: +- ECMP forwarding (5-tuple hash) +- Admission control via MMU +- PFC pause/resume generation +- ECN marking +- INT/PINT injection for HPCC/HPCC-PINT + +### Switch MMU (`switch-mmu`) + +Switch buffer/MMU model: +- Ingress/egress accounting +- Shared buffer and headroom management +- PFC trigger/resume logic +- ECN marking probability curve (`kmin/kmax/pmax`) + +### NVSwitch Node (`nvswitch-node`) + +NVSwitch model for intra-server GPU communication, paired with NVLS routing logic in `RdmaHw`/`QbbNetDevice`. + +### QP State (`rdma-queue-pair`) + +Per-QP and per-RxQP state management including: +- Window and rate control +- ACKed sequence tracking +- Per-CC algorithm state (DCQCN alpha/targetRate, HPCC hop state, TIMELY RTT, DCTCP alpha/ecnCnt, PINT state) + +--- + +## Analysis Tools + +Located in `ns-3-alibabacloud/analysis/`: + +### FCT Analysis + +```bash +python fct_analysis.py -h # See help for usage +``` + +Reads FCT output files and produces statistics for flow completion time analysis. + +### Trace Reader + +```bash +# Build +make trace_reader + +# Usage +./trace_reader <.tr file> [filter_expr] + +# Filter examples +./trace_reader output.tr "time > 2000010000" +./trace_reader output.tr "sip=0x0b000101&dip=0x0b000201" +``` + +### Trace Output Format + +``` +2000055540 n:338 4:3 100608 Enqu ecn:0 0b00d101 0b012301 10000 100 U 161000 0 3 1048(1000) +``` + +Fields: timestamp, node, port:queue, queue_length, event, ecn, src_ip, dst_ip, src_port, dst_port, pkt_type, seq, tx_time, priority, size(payload) + +--- + +## Headers and Utilities + +| File | Description | +|------|-------------| +| `qbb-header` | ACK/NACK header with optional INT header | +| `cn-header` | CNP header (feedback fields) | +| `pause-header` | PFC pause header | +| `pint` | PINT encode/decode utilities | +| `trace-format.h` | Binary trace record structure for offline analysis | + +--- + +## Extension Guide + +### Adding a New CC Algorithm + +1. **Primary**: `rdma-hw.{h,cc}` — Add `HandleAckX`/`UpdateRateX` methods, dispatch by `m_cc_mode` +2. **Often needed**: `rdma-queue-pair.h` — Add new per-QP state variables +3. **If switch feedback required**: `switch-node.cc` — Add INT/PINT or new markings + +### Changing Switch Behavior + +1. **Primary**: `switch-mmu.{h,cc}` — Modify thresholds, curves, formulas +2. **Marking/injection**: `switch-node.cc::SwitchNotifyDequeue()` +3. **Admission/priority**: `switch-node.cc::SendToDev()` + +### Adding New Control Packets + +1. Create new `*Header` in `model/` (follow `CnHeader`/`PauseHeader` pattern) +2. Add parsing in `QbbNetDevice::Receive()` or `RdmaHw::Receive()` + +--- + +## See Also + +- [SimAI-Simulation Guide](../user_guide/simai_simulation.md) — Full-stack simulation usage +- [astra-sim Component](astra_sim.md) — Simulation engine +- [Extending NS-3 Guide](../developer_guide/extending_ns3.md) — Detailed extension guide diff --git a/docs/en/components/simccl.md b/docs/en/components/simccl.md new file mode 100644 index 00000000..f5712b45 --- /dev/null +++ b/docs/en/components/simccl.md @@ -0,0 +1,82 @@ +# SimCCL — Collective Communication Library + +**Repository**: [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | **Language**: Python/C++ + +SimCCL enables the transformation of collective communication operations into point-to-point communications, serving as a critical bridge between the workload layer and the simulation engine. + +--- + +## Overview + +In distributed LLM training, collective communication operations (AllReduce, AllGather, ReduceScatter, AlltoAll, etc.) are fundamental building blocks. SimCCL breaks down these high-level collective operations into sequences of point-to-point communications that can be precisely simulated by the network backend. + +--- + +## Role in SimAI + +SimCCL sits between AICB (workload generation) and astra-sim-alibabacloud (simulation engine): + +``` +AICB generates workload with collective ops + | + v +SimCCL decomposes collective → point-to-point + | + v +astra-sim sends P2P traffic to NS-3 or physical network +``` + +SimCCL is required for: +- **SimAI-Simulation** — Full-stack NS-3 simulation +- **SimAI-Physical** — Physical RDMA traffic generation +- **Inference Simulation** — When using SimAI Simulation backend + +SimCCL is NOT required for: +- **SimAI-Analytical** — Uses busbw-based estimation directly + +--- + +## Versions + +### Basic Version (mocknccl) + +A basic implementation is currently available in the [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud) repository. Files are prefixed with `mocknccl` and provide fundamental collective-to-P2P conversion. + +### Complete Version + +The full SimCCL library with advanced collective communication algorithms is available in the [SimCCL repository](https://github.com/aliyun/SimCCL). + +--- + +## Supported Collective Operations + +| Operation | Description | +|-----------|-------------| +| AllReduce | Reduce data across all ranks, result available on all ranks | +| AllGather | Gather data from all ranks, result available on all ranks | +| ReduceScatter | Reduce and scatter data across all ranks | +| AlltoAll | All-to-all personalized communication | +| Broadcast | Broadcast from one rank to all others | + +--- + +## Integration with astra-sim + +SimCCL integrates with astra-sim-alibabacloud through the `MockNcclGroup` and `MockNcclChannel` interfaces: + +- **MockNcclGroup**: Manages a group of ranks participating in a collective operation +- **MockNcclChannel**: Handles the actual point-to-point data transfer for a specific channel within a collective operation + +The decomposition considers: +- Network topology (ring, tree, etc.) +- Number of participating ranks +- Message size +- Available communication channels + +--- + +## See Also + +- [Components Overview](index.md) — SimAI component architecture +- [astra-sim Component](astra_sim.md) — Simulation engine that consumes SimCCL output +- [NS-3 Component](ns3.md) — Network backend for P2P simulation diff --git a/docs/en/components/vidur.md b/docs/en/components/vidur.md new file mode 100644 index 00000000..67dc4a79 --- /dev/null +++ b/docs/en/components/vidur.md @@ -0,0 +1,196 @@ +# vidur-alibabacloud + +**vidur-alibabacloud** is the LLM inference simulation component of SimAI, adapted from Microsoft's [Vidur](https://github.com/microsoft/vidur). It provides multi-request inference scheduling, GPU memory management, and Prefill-Decode (PD) disaggregation support. + +- **Repository**: In-tree (`vidur-alibabacloud/`) +- **Language**: Python +- **License**: MIT + +--- + +## Key Features + +- **Prefill-Decode (PD) Separation** — Run prefill and decode stages on different nodes for elastic resource allocation and performance isolation. Inspired by [splitwise-sim](https://github.com/Mutinifni/splitwise-sim). +- **Flexible Parallelism** — Data Parallel (DP), Tensor Parallel (TP), Pipeline Parallel (PP), Expert Parallel (EP) +- **Multiple Execution Backends** — AICB/AIOB, SimAI Simulation (NS-3), SimAI Analytical, Native Vidur +- **Workload Generation & Replay** — Synthetic (fixed/Poisson) or real-trace request replay +- **Fine-Grained Metrics** — TTFT, TBT/TPOT, E2E latency, communication cost, compute cost, scheduling delay + +--- + +## GPU Memory Calculation Module + +This module provides accurate GPU memory estimation for MoE models during inference. + +### Components + +| Component | File | Description | +|-----------|------|-------------| +| **ParamCounter** | `vidur/utils/param_counter.py` | Per-layer and per-device parameter counting for MLA, MHA/GQA, linear attention, and MoE experts. Returns `(total_params, prefill_params, decode_params)` under PD disaggregation | +| **MemoryPlanner** | `vidur/scheduler/utils/memory_planner.py` | Plans GPU memory budget: `available = GPU_mem * (1 - margin) - param_mem`, computes KV cache capacity and max concurrent requests. Includes OOM detection | +| **Per-request KV Cache Tracking** | `vidur/entities/replica.py` | Allocates/releases KV cache memory per request, enabling runtime remaining-capacity queries | + +### Supported Attention Architectures + +| Architecture | Model | Description | +|---|---|---| +| **MLA** (Multi-head Latent Attention) | DeepSeek-V3-671B | LoRA-compressed KV cache (`kv_lora_rank` + `qk_rope_head_dim`), ~57x memory savings vs MHA | +| **MHA / GQA** | Qwen3-MoE-235B | Standard KV cache with `num_kv_heads * head_dim` per token per layer | +| **Hybrid Full + Linear Attention** | Qwen3-Next-80B | Alternates between full attention and linear (GDN) attention every 4 layers | + +--- + +## Supported Models + +| Model | Attention | Experts | Status | +|-------|-----------|---------|--------| +| DeepSeek-V3-671B | MLA | 256 routed + 1 shared | PP/EP adaptation in progress | +| Qwen3-MoE-235B | MHA/GQA | 128 routed | PP/EP adaptation in progress | +| Qwen3-Next-80B | Hybrid | 512 routed | PP/EP adaptation in progress | +| Meta-Llama-3-8B / 70B | MHA | Dense | Supported | +| Llama-2-7b / 70b | MHA | Dense | Supported | +| CodeLlama-34b | MHA | Dense | Supported | +| InternLM-20B | MHA | Dense | Supported | +| Qwen-72B | MHA | Dense | Supported | + +--- + +## Environment Setup + +### Docker (Recommended) + +```bash +docker build -t simai:latest . +docker run --gpus all -it --rm simai:latest +``` + +> Add `ENV FLASH_MLA_DISABLE_SM100=1` to Dockerfile when using Hopper GPUs. + +### Conda + +```bash +cd vidur-alibabacloud +conda env create -p ./env -f ./environment.yml +conda activate vidur +pip install -r requirements.txt +``` + +--- + +## Key Input Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `--replica_config_model_name` | HuggingFace model ID or config path | Required | +| `--cluster_config_num_replicas` | Number of replicas (DP) | 1 | +| `--replica_config_tensor_parallel_size` | TP degree | 1 | +| `--replica_config_num_pipeline_stages` | PP stages | 1 | +| `--replica_config_expert_model_parallel_size` | EP degree | 1 | +| `--replica_config_pd_node_ratio` | P:D node ratio (e.g., `"2:6"`) | `""` (no PD) | +| `--cluster_config_global_scheduler_type` | Global scheduler: `lor` / `round_robin` / `split_wise` | `lor` | +| `--cluster_config_replica_scheduler_type` | Per-replica scheduler: `sarathi` / `split_wise` | `sarathi` | +| `--request_generator_config_type` | `synthetic` / `trace_replay` | `synthetic` | +| `--synthetic_request_generator_config_num_requests` | Number of requests to generate | 100 | +| `--poisson_request_generator_config_qps` | Queries per second (Poisson mode) | 1.0 | +| `--replica_config_device` | GPU type (e.g., `h20_dgx`) | Required | +| `--replica_config_network_device` | Network type | Same as device | +| `--execution_time_predictor_config_type` | Backend: `aicb` / `simai_simulation` / `simai_analytical` / `random_forrest` | `random_forrest` | +| `--nvlink_bandwidth_gbps` | NVLink bandwidth | 1600 | +| `--rdma_bandwidth_gbps` | RDMA bandwidth | 800 | +| `--pd_p2p_bandwidth_gbps` | PD inter-node P2P bandwidth | 800 | +| `--replica_config_fp8_enabled` | Enable FP8 quantization | false | +| `--replica_config_memory_margin_fraction` | GPU memory safety margin | 0.1 | + +--- + +## Output Files + +Each run produces the following outputs: + +| File | Description | +|------|-------------| +| `request_metrics.csv` | Per-request metrics with 17 columns | +| `chrome_trace.json` | Timeline trace for Chrome `chrome://tracing` visualization | +| `config.json` | Configuration snapshot | +| `plots/` | Metric visualization plots | + +### request_metrics.csv Columns + +| Column | Description | +|--------|-------------| +| `request_id` | Unique request identifier | +| `arrived_at` | Request arrival time | +| `scheduled_at` | First schedule time | +| `completed_at` | Request completion time | +| `prefill_completed_at` | Prefill completion time (first token) | +| `num_prefill_tokens` | Number of input tokens | +| `num_decode_tokens` | Number of generated tokens | +| `scheduling_delay` | Wait time before scheduling | +| `e2e_time` | End-to-end latency | +| `e2e_time_normalized` | E2E latency / num_decode_tokens | +| `execution_time` | Actual GPU execution time | +| `preemption_time` | Time spent preempted | +| `num_restarts` | Number of restarts | +| `prefill_e2e_time` | TTFT (Time to First Token) | +| `decode_time_normalized` | Average TBT (Time Between Tokens) | +| `total_comm_cost` | Total communication time | +| `total_compute_cost` | Total compute time | + +--- + +## Simulation Metrics (23 Items) + +The simulator logs the following metrics (see `vidur-alibabacloud/docs/metrics.md` for details): + +1. `request_inter_arrival_delay_histogram` — Request inter-arrival delay distribution +2. `request_num_tokens_histogram` — Token count distribution (prefill + decode) +3. `request_num_restarts_histogram` — Restart count distribution +4. `request_e2e_time_cdf` — End-to-end latency CDF +5. `request_e2e_time_normalised_cdf` — Normalized E2E latency CDF +6. `request_execution_plus_preemption_times_cdf` — Execution + preemption time CDF +7. `request_scheduling_delay_cdf` — Scheduling delay CDF +8. `request_execution_time_cdf` — Pure execution time CDF +9. `request_preempted_time_cdf` — Preemption time CDF +10. `decode_token_execution_plus_preemption_times` — Per-token inter-token delay CDF +11. `batch_num_tokens_cdf` — Batch total token count CDF +12. `batch_sizes_cdf` — Batch size CDF +13. `prefill_time_e2e_cdf` — TTFT CDF +14. `prefill_time_execution_plus_preemption_cdf` — Prefill processing time CDF +15. `prefill_time_execution_plus_preemption_normalized_cdf` — Normalized prefill time CDF +16. `decode_time_execution_plus_preemption_normalized_cdf` — Normalized decode time CDF +17. `request_completions_time_series` — Request completion time series +18. `prefill_completions_time_series` — Prefill completion time series +19. `decode_completions_time_series` — Decode completion time series +20. `replica_{id}_memory_usage_weighted_mean` — Per-replica memory utilization +21. `replica_{id}_stage_{id}_busy_time_percent_weighted_mean` — Per-stage busy time percentage +22. `replica_{id}_stage_{id}_mfu_weighted_mean` — Per-stage MFU +23. `request_arrivals_time_series` — Request arrival time series + +--- + +## 4-Scenario Test Suite + +Run all pre-configured scenarios: + +```bash +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all +# Or a single scenario: +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 3 +``` + +For detailed scenario configuration, see [Benchmarking — Test Suite](../benchmarking/test_suite.md). + +--- + +## Adding New Models + +To add a new model to vidur-alibabacloud, see the [Adding Models Guide](../developer_guide/adding_models.md) and the upstream documentation at `vidur-alibabacloud/docs/profiling.md`. + +--- + +## Related Documentation + +- [Inference Simulation User Guide](../user_guide/inference_simulation.md) — End-to-end inference simulation workflow +- [Result Analysis](../user_guide/result_analysis.md) — How to interpret output files +- [GPU Memory Module Technical Reference](../technical_reference/memory_module.md) — Detailed memory calculation formulas +- [Benchmarking Test Suite](../benchmarking/test_suite.md) — 4-scenario configuration details diff --git a/docs/en/developer_guide/adding_models.md b/docs/en/developer_guide/adding_models.md new file mode 100644 index 00000000..4d1eeb00 --- /dev/null +++ b/docs/en/developer_guide/adding_models.md @@ -0,0 +1,204 @@ +# Adding New Models + +This guide covers how to add new model support to SimAI, including both the Vidur inference simulation side (GPU memory, profiling) and the AICB workload generation side. + +--- + +## Overview + +Adding a new model typically involves two components: + +| Component | What to add | Required hardware | +|-----------|-------------|-------------------| +| **vidur-alibabacloud** | Model config, profiling data (compute + network) | GPU (for profiling only) | +| **AICB** | Workload generation parameters (`MockedParam` / `MockedModel`) | None | + +--- + +## Part 1: Vidur — Model Configuration and Profiling + +### Step 1: Add Model Configuration + +Create a YAML/JSON model config in `vidur-alibabacloud/data/model_configs/` or `vidur-alibabacloud/data/hf_configs/`: + +- Use the model's HuggingFace model ID as filename (e.g., `meta-llama/Llama-2-70b-hf.yml`) +- Reference the model's HuggingFace `config.json` for parameter values +- Ensure the correct parameters are set so the reference transformer model closely resembles the new model + +**Example config parameters:** + +```yaml +num_layers: 80 +hidden_size: 8192 +num_attention_heads: 64 +num_key_value_heads: 8 # For GQA models +head_dim: 128 +intermediate_size: 28672 +vocab_size: 128256 +max_position_embeddings: 8192 +``` + +For MoE models, also include: + +```yaml +num_routed_experts: 256 +num_experts_per_tok: 8 +num_shared_experts: 1 +moe_intermediate_size: 2048 +``` + +### Step 2: Profiling Data Structure + +Profiling data is stored in `vidur-alibabacloud/data/profiling/`: + +``` +profiling/ +├── compute/ +│ ├── a100/ +│ │ └── model-name/ +│ │ ├── mlp.csv +│ │ └── attention.csv +│ └── h100/ +│ └── model-name/ +│ ├── mlp.csv +│ └── attention.csv +└── network/ + ├── a100_pair_nvlink/ + │ ├── allreduce.csv + │ └── send_recv.csv + └── h100_dgx/ + ├── allreduce.csv + └── send_recv.csv +``` + +**Key distinction:** +- **Compute profiling**: Only GPU SKU matters (e.g., `a100`, `h100`), not network topology +- **Network profiling**: Network configuration matters (e.g., `a100_pair_nvlink` vs `a100_dgx`) + +### Step 3: Compute Profiling (MLP) + +Requires actual GPUs. 1 GPU is sufficient even for TP > 1. + +```bash +# Install sarathi-serve (vidur branch) for profiling +# Then run MLP profiling: +python vidur/profiling/mlp/main.py \ + --models your-model/model-name \ + --num_gpus 4 + +# Copy output to data directory: +cp profiling_outputs/mlp//your-model/model-name/mlp.csv \ + data/profiling/compute//your-model/model-name/mlp.csv +``` + +### Step 4: Compute Profiling (Attention) + +```bash +python vidur/profiling/attention/main.py \ + --models your-model/model-name \ + --num_gpus 4 + +# Copy output: +cp profiling_outputs/attention//your-model/model-name/attention.csv \ + data/profiling/compute//your-model/model-name/attention.csv +``` + +### Step 5: Network Profiling (if needed) + +Network profiling is **model-independent** — same data works for all models on the same hardware configuration. + +```bash +# AllReduce profiling (for TP): +python vidur/profiling/collectives/main.py \ + --num_workers_per_node_combinations 1,2,4,8 \ + --collective all_reduce + +# Send/Recv profiling (for PP, requires multi-node): +python vidur/profiling/collectives/main.py \ + --num_workers_per_node_combinations 1,2,4,8 \ + --collective send_recv +``` + +**Available network device profiles:** +- `a100_pair_nvlink` — Azure Standard_NC96ads_A100_v4 (4x A100 PCIe + NVLink pairs) +- `h100_pair_nvlink` — Azure internal (4x H100 NVL + NVLink pairs) +- `a100_dgx` — A100 DGX (8x A100) +- `h100_dgx` — H100 DGX (8x H100) + +--- + +## Part 2: AICB — Workload Generation + +### Custom Model Parameters (MockedParam) + +To add a new model for workload generation in AICB, create a `MockedParam` subclass: + +```python +# In aicb/workload_generator/mocked_params/ +class YourModelParam(MockedParam): + def __init__(self): + super().__init__() + self.num_layers = 80 + self.hidden_size = 8192 + self.num_attention_heads = 64 + self.num_key_value_heads = 8 + self.ffn_hidden_size = 28672 + self.vocab_size = 128256 + self.seq_length = 8192 + # MoE parameters (if applicable) + self.num_experts = 256 + self.topk = 8 + self.moe_intermediate_size = 2048 +``` + +### Custom Model Workflow (MockedModel) + +For full control over the workload generation process, create a `MockedModel` subclass that defines the compute and communication operations for each layer. + +See [AICB Component Documentation](../components/aicb.md#custom-model-development) for detailed examples. + +### Inference Workload Generation + +For inference workloads with prefill/decode separation: + +```bash +# Generate inference workload +python -m aicb.main \ + --model_name your-model-name \ + --workload_type inference \ + --num_prefill_tokens 1024 \ + --num_decode_tokens 128 +``` + +--- + +## Part 3: GPU Memory Module + +If your model uses a non-standard attention architecture, you may need to extend the `ParamCounter` in `vidur/utils/param_counter.py`: + +1. Add attention parameter calculation for your architecture +2. Add KV cache per-token size calculation +3. Test with the MemoryPlanner to verify OOM detection works correctly + +See [GPU Memory Module Technical Reference](../technical_reference/memory_module.md) for calculation formulas. + +--- + +## Verification Checklist + +- [ ] Model config file added to `data/model_configs/` or `data/hf_configs/` +- [ ] Compute profiling data (MLP + attention) added +- [ ] Network profiling data available for target hardware +- [ ] AICB `MockedParam` created (if workload generation needed) +- [ ] GPU memory calculation works correctly (ParamCounter + MemoryPlanner) +- [ ] End-to-end inference simulation produces reasonable results +- [ ] Documentation updated + +--- + +## Related Documentation + +- [vidur-alibabacloud Component](../components/vidur.md) — Full vidur documentation +- [AICB Component](../components/aicb.md) — AICB workload generation +- [GPU Memory Module](../technical_reference/memory_module.md) — Memory calculation formulas +- [Supported Models](../user_guide/supported_models.md) — Current model support status diff --git a/docs/en/developer_guide/architecture.md b/docs/en/developer_guide/architecture.md new file mode 100644 index 00000000..f3536339 --- /dev/null +++ b/docs/en/developer_guide/architecture.md @@ -0,0 +1,176 @@ +# System Architecture + +This document describes SimAI's modular architecture, component interactions, and data flow for both training and inference simulation. + +--- + +## Project Structure + +``` +SimAI/ +├── aicb/ # AI Computation Benchmark — workload generation (Python) +│ ├── workload_generator/ # Generates training/inference workloads +│ └── aicb.py # Main entry point +├── astra-sim-alibabacloud/ # Simulation engine — core simulator (C++) +│ ├── astra-sim/ # Extended from astra-sim 1.0 +│ └── build.sh # Build script +├── ns-3-alibabacloud/ # NS-3 network simulator backend (C++) +├── vidur-alibabacloud/ # LLM inference simulation (Python) +│ ├── vidur/ # Core simulation framework +│ └── setup.py # Python package config +├── SimCCL/ # Collective communication transformation +├── docs/ # Documentation and tutorials +├── example/ # Example workloads and configurations +├── scripts/ # Build and utility scripts +├── results/ # Simulation output directory +├── bin/ # Compiled binary output +└── Dockerfile # Docker container definition +``` + +--- + +## Component Architecture + +``` + |--- AICB (Workload generation & compute profiling) +SimAI --|--- SimCCL (Collective communication algorithm analysis) + |--- astra-sim-alibabacloud (Simulation engine: Analytical / Simulation / Physical) + |--- ns-3-alibabacloud (NS-3 network backend) + |--- vidur-alibabacloud (Multi-request inference scheduling & memory management) +``` + +![SimAI Architecture](../../images/SimAI_Arc.png) + +### Component Responsibilities + +| Component | Role | Language | +|-----------|------|----------| +| **AICB** | Generates training/inference workloads, profiles compute kernels, runs physical benchmarks | Python | +| **SimCCL** | Transforms collective communication operations (AllReduce, AllGather, etc.) into point-to-point communication sets | Python | +| **astra-sim-alibabacloud** | Core simulation engine supporting 3 modes; manages compute/memory/network APIs | C++ | +| **ns-3-alibabacloud** | Packet-level network simulation with RDMA, datacenter topology, and CC algorithms | C++ | +| **vidur-alibabacloud** | Multi-request inference scheduling with PD disaggregation and GPU memory management | Python | + +--- + +## Three Operation Modes + +### SimAI-Analytical + +``` +AICB (workload.txt) → astra-sim (analytical) → busbw estimation → CSV results +``` + +- **Use case**: Fast performance analysis, parallel parameter sweeps +- **Components**: AICB + astra-sim-alibabacloud (analytical mode) +- **Network model**: Bus bandwidth (busbw) abstraction + +### SimAI-Simulation + +``` +AICB (workload.txt) → SimCCL (collective→P2P) → astra-sim (simulation) → NS-3 → detailed traces +``` + +- **Use case**: Full-stack network research, CC algorithm evaluation +- **Components**: AICB + SimCCL + astra-sim-alibabacloud (simulation) + ns-3-alibabacloud +- **Network model**: Packet-level NS-3 simulation + +### SimAI-Physical + +``` +AICB (workload.txt) → SimCCL (collective→P2P) → astra-sim (physical) → RDMA traffic on real NICs +``` + +- **Use case**: NIC behavior study, physical traffic analysis +- **Components**: AICB + SimCCL + astra-sim-alibabacloud (physical) +- **Network model**: Real RDMA traffic via MPI + +--- + +## Inference Simulation Data Flow + +``` +Request Generator + | Generate synthetic / real-trace requests + v +Global Scheduler + | Dispatch requests to Prefill / Decode replicas + v +Replica Scheduler + | Batch assembly and scheduling + v +Memory Management (MemoryPlanner + Replica) + | KV cache allocation and capacity checking + v +Execution Time Predictor + | AICB / SimAI Simulation / SimAI Analytical / Vidur + v +Metrics Store + | TTFT, TBT, E2E, communication / compute cost + v +Output (request_metrics.csv, chrome_trace.json, plots/) +``` + +### Key Inference Components + +| Component | File | Description | +|-----------|------|-------------| +| Request Generator | `vidur/request_generator/` | Generates synthetic or trace-based requests | +| Global Scheduler | `vidur/scheduler/global_scheduler/` | Dispatches requests across replicas (`lor`, `round_robin`, `split_wise`) | +| Replica Scheduler | `vidur/scheduler/replica_scheduler/` | Per-replica batch scheduling (`sarathi`, `split_wise`) | +| MemoryPlanner | `vidur/scheduler/utils/memory_planner.py` | GPU memory budget computation | +| ParamCounter | `vidur/utils/param_counter.py` | Model parameter counting (MLA/MHA/GQA/linear/MoE) | +| Execution Predictor | `vidur/execution_time_predictor/` | Execution time estimation via multiple backends | +| Metrics Store | `vidur/metrics/` | Collects and exports 23 simulation metrics | + +--- + +## Submodule Structure + +SimAI uses Git submodules for its core components: + +| Submodule | Repository | Branch | +|-----------|------------|--------| +| `aicb` | [aliyun/aicb](https://github.com/aliyun/aicb) | master | +| `SimCCL` | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | master | +| `ns-3-alibabacloud` | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | master / dev/qp | +| `astra-sim-alibabacloud` | In-tree | — | +| `vidur-alibabacloud` | In-tree | — | + +**Key rules:** +1. Submodules have independent Git histories +2. The parent repo only tracks the commit hash of each submodule +3. Always initialize after cloning: `git submodule update --init --recursive` + +--- + +## Build System + +### Build Scripts + +```bash +# Analytical mode (fast, busbw-based) +bash scripts/build.sh -c analytical + +# NS-3 simulation mode (full-stack) +bash scripts/build.sh -c ns3 + +# Physical mode (beta, RDMA) +bash scripts/build.sh -c phy +``` + +### Build Outputs + +| Mode | Binary | Location | +|------|--------|----------| +| Analytical | `SimAI_analytical` | `bin/` | +| Simulation | `SimAI_simulator` | `bin/` | +| Physical | `SimAI_physical` | `bin/` | + +--- + +## Related Documentation + +- [Components Overview](../components/index.md) — Detailed documentation for each component +- [Contributing Guide](contributing.md) — How to contribute code +- [Configuration Reference](../technical_reference/configuration.md) — Configuration files and parameters diff --git a/docs/en/developer_guide/contributing.md b/docs/en/developer_guide/contributing.md new file mode 100644 index 00000000..e08b5048 --- /dev/null +++ b/docs/en/developer_guide/contributing.md @@ -0,0 +1,224 @@ +# Contributing to SimAI + +Thank you for your interest in contributing to SimAI! This guide covers the complete development workflow. + +> **Full version**: See [CONTRIBUTING.md](../../../CONTRIBUTING.md) in the project root for the comprehensive guide. + +--- + +## Ways to Contribute + +1. **New features** — Add model support, parallelism strategies, scheduling policies +2. **Bug fixes** — Fix simulation inaccuracies, crashes, or incorrect results +3. **Performance optimization** — Improve simulation speed, memory usage, or scalability +4. **Documentation** — Improve tutorials, add examples, fix errors +5. **Benchmarks & validation** — Add validation against real hardware results +6. **Issue reports** — Report bugs, request features, or share feedback + +--- + +## Development Workflow + +### Step 1: Fork and Clone + +```bash +git clone --recurse-submodules https://github.com/YOUR_USERNAME/SimAI.git +cd SimAI +git remote add upstream https://github.com/aliyun/SimAI.git +``` + +### Step 2: Create a Feature Branch + +```bash +git fetch upstream +git checkout -b feature/your-feature-name upstream/master + +# Branch naming conventions: +# feature/xxx — New features +# fix/xxx — Bug fixes +# docs/xxx — Documentation +# perf/xxx — Performance improvements +# refactor/xxx — Code refactoring +``` + +### Step 3: Develop and Test + +```bash +# For C++ changes, rebuild: +bash scripts/build.sh -c analytical # or ns3 + +# For Python changes: +python -c "from aicb import ..." +``` + +### Step 4: Commit + +```bash +git add -A +git commit -m "feat(aicb): add Llama-4 model workload generation" +``` + +### Step 5: Push and Create PR + +```bash +git push origin feature/your-feature-name +# Then create a Pull Request on GitHub +``` + +--- + +## Commit Message Convention + +Use [Conventional Commits](https://www.conventionalcommits.org/) format: + +``` +(): +``` + +### Types + +| Type | Description | +|------|-------------| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation only | +| `refactor` | Code refactoring | +| `test` | Adding or updating tests | +| `perf` | Performance improvement | +| `chore` | Build process, tooling | + +### Scopes + +`aicb`, `vidur`, `astra-sim`, `ns3`, `simccl`, `docs`, `docker`, `scripts` + +### Examples + +``` +feat(aicb): add DeepSeek-V3 inference workload generation +fix(astra-sim): correct AllReduce latency calculation for ring algorithm +docs: update build instructions for NS-3 mode +perf(vidur): reduce memory allocation in request scheduler +``` + +--- + +## Code Style + +### Python + +- **Formatter**: [black](https://github.com/psf/black) (default settings) +- **Import sorting**: [isort](https://pycqa.github.io/isort/) +- **Linter**: [flake8](https://flake8.pycqa.org/) +- **Max line length**: 120 characters + +```bash +black --line-length 120 your_file.py +isort your_file.py +flake8 your_file.py --max-line-length 120 +``` + +### C++ + +- Follow existing code style in `astra-sim-alibabacloud/` +- 4-space indentation +- `snake_case` for functions and variables +- Comments for non-trivial logic + +### General Rules + +- Write comments in **English** +- All new functions/classes should have docstrings or header comments +- Avoid hardcoded paths; use relative paths or configuration variables +- One feature/fix per PR + +--- + +## Working with Submodules + +SimAI uses Git submodules. Key points: + +| Submodule | Repository | Language | +|-----------|------------|----------| +| `aicb` | [aliyun/aicb](https://github.com/aliyun/aicb) | Python | +| `SimCCL` | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | Python | +| `ns-3-alibabacloud` | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | C++ | +| `astra-sim-alibabacloud` | In-tree | C++ | +| `vidur-alibabacloud` | In-tree | Python | + +### Cross-Submodule Changes + +If your contribution spans multiple submodules: + +1. Make and commit changes in each submodule separately +2. Update the parent repo to point to new submodule commits +3. Create separate PRs for each submodule with independent remotes +4. Reference related PRs in descriptions + +--- + +## Pull Request Guidelines + +### PR Title + +Use the same format as commit messages: `(): ` + +### PR Checklist + +- [ ] Code compiles without errors +- [ ] Existing simulations produce unchanged results (no precision regression) +- [ ] New code has appropriate comments +- [ ] Tests added for new functionality +- [ ] Documentation updated if needed + +--- + +## Pre-Submission Quality Checklist + +```bash +# 1. C++ compilation check +bash scripts/build.sh -c analytical +bash scripts/build.sh -c ns3 + +# 2. Python lint check +black --check --line-length 120 your_changed_files.py +flake8 your_changed_files.py --max-line-length 120 + +# 3. Basic simulation test +cd bin && ./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml + +# 4. Submodule state check +git submodule status +``` + +--- + +## Acceptance Criteria + +| Criterion | Requirement | +|-----------|-------------| +| **Build** | Compiles without errors | +| **Precision** | No existing simulation accuracy degradation | +| **Tests** | Key code paths are covered | +| **Documentation** | New features have comments/doc updates | +| **Style** | Follows code style guidelines | +| **Scope** | Changes are focused and well-explained | + +--- + +## Review Timeline + +1. **Initial review**: 3-5 business days +2. **Feedback**: Constructive comments with actionable suggestions +3. **Iteration**: Address feedback and update PR +4. **Merge**: Approved PRs merged to main branch + +--- + +## Getting Help + +- **Issues**: [GitHub Issues](https://github.com/aliyun/SimAI/issues) +- **Discussions**: Open an issue with "Question:" prefix +- **Documentation**: See [Tutorial](../../../docs/Tutorial.md) for usage guides diff --git a/docs/en/developer_guide/extending_ns3.md b/docs/en/developer_guide/extending_ns3.md new file mode 100644 index 00000000..484465f3 --- /dev/null +++ b/docs/en/developer_guide/extending_ns3.md @@ -0,0 +1,219 @@ +# Extending the NS-3 Network Backend + +This guide covers how to extend `ns-3-alibabacloud` with new congestion control algorithms, switch behaviors, control packets, and NVSwitch features. + +> **Source reference**: See `astra-sim-alibabacloud/extern/network_backend/ns3-interface/README.md` for the detailed module map. + +--- + +## Module Overview + +All key source files are located in `ns-3-alibabacloud/simulation/src/point-to-point/model/`: + +| File | Class | Purpose | +|------|-------|---------| +| `qbb-net-device.{h,cc}` | `QbbNetDevice`, `RdmaEgressQueue` | QBB-capable NIC with 8 priority queues, PFC handling, NVSwitch send path | +| `rdma-hw.{h,cc}` | `RdmaHw` | Host RDMA core: QP management, packet construction, ACK/NACK, CC algorithms | +| `rdma-queue-pair.{h,cc}` | `RdmaQueuePair`, `RdmaRxQueuePair` | Per-QP state (window, rate, CC-specific state) | +| `switch-node.{h,cc}` | `SwitchNode` | Switch pipeline: ECMP forwarding, ECN marking, PFC, INT/PINT injection | +| `switch-mmu.{h,cc}` | `SwitchMmu` | Switch buffer/MMU: ingress/egress accounting, PFC thresholds, ECN curves | +| `nvswitch-node.{h,cc}` | `NVSwitchNode` | NVSwitch model for intra-server GPU communication | +| `rdma-driver.{h,cc}` | `RdmaDriver` | Wiring layer between Node/NICs and RdmaHw | +| `qbb-header.{h,cc}` | — | ACK/NACK header (PG/seq/CNP-flag + INT header) | +| `cn-header.{h,cc}` | — | CNP header (feedback fields) | +| `pause-header.{h,cc}` | — | PFC pause header | +| `pint.{h,cc}` | — | PINT encode/decode utilities | +| `trace-format.h` | `TraceFormat` | Binary trace record structure for offline analysis | + +--- + +## Adding a New Congestion Control Algorithm + +The NS-3 backend supports 5 built-in CC algorithms: **DCQCN**, **HPCC**, **TIMELY**, **DCTCP**, and **HPCC-PINT**. To add a new CC algorithm: + +### Step 1: Define CC Mode + +Add a new `CcMode` value in `rdma-hw.h`: + +```cpp +// Existing modes: 1=DCQCN, 3=HPCC, 7=TIMELY, 8=DCTCP, 10=HPCC-PINT +static const uint32_t CC_MODE_YOUR_ALG = 11; +``` + +### Step 2: Add Per-QP State (if needed) + +In `rdma-queue-pair.h`, add new state variables to `RdmaQueuePair`: + +```cpp +// Your CC algorithm state +double m_your_alg_rate; +double m_your_alg_alpha; +// ... +``` + +### Step 3: Implement Algorithm Logic + +In `rdma-hw.cc`, add two key functions: + +```cpp +void RdmaHw::HandleAckYourAlg(Ptr qp, ...) { + // Process ACK and update rate/window +} + +void RdmaHw::UpdateRateYourAlg(Ptr qp, ...) { + // Rate update logic +} +``` + +### Step 4: Register Dispatch + +Add dispatch cases in `ReceiveAck()` and/or `ReceiveCnp()` in `rdma-hw.cc`: + +```cpp +switch (m_cc_mode) { + // ... existing cases ... + case CC_MODE_YOUR_ALG: + HandleAckYourAlg(qp, ...); + break; +} +``` + +### Step 5: Add Switch Feedback (if needed) + +If your CC algorithm requires switch-side information (like INT/PINT metadata): + +- Modify `switch-node.cc::SwitchNotifyDequeue()` to inject your metadata +- Add header parsing in `RdmaHw::Receive()` or `QbbNetDevice::Receive()` + +--- + +## Modifying Switch Behavior + +### Buffer Management / PFC Thresholds + +**Primary file**: `switch-mmu.{h,cc}` + +Key methods to modify: + +| Method | Purpose | +|--------|---------| +| `ConfigBufferSize()` | Total buffer pool size | +| `ConfigHdrm()` | Headroom allocation | +| `ConfigEcn()` | ECN marking thresholds (`kmin`, `kmax`, `pmax`) | +| `CheckIngressAdmission()` | Ingress admission control | +| `CheckEgressAdmission()` | Egress admission control | +| `GetPfcThreshold()` | PFC trigger threshold formula | + +### ECN Marking / INT Injection + +**File**: `switch-node.cc` + +Modify `SwitchNotifyDequeue()` for: +- ECN marking based on custom queue occupancy formulas +- INT/PINT metadata injection for advanced CC algorithms +- Custom packet tagging + +### Forwarding / ECMP + +**File**: `switch-node.cc` + +Modify for routing changes: +- `GetOutDev()` — Output port selection +- `EcmpHash()` — ECMP hash function (currently 5-tuple) +- `AddTableEntry()` — Routing table management + +--- + +## Introducing New Control Packets + +### Step 1: Create Header + +Create new header files in `model/` following the pattern of `CnHeader` or `PauseHeader`: + +```cpp +// your-header.h +class YourHeader : public Header { +public: + static TypeId GetTypeId(); + // Serialize/Deserialize methods + uint32_t GetSerializedSize() const override; + void Serialize(Buffer::Iterator start) const override; + uint32_t Deserialize(Buffer::Iterator start) override; + + // Your header fields + uint32_t m_your_field; +}; +``` + +### Step 2: Define Protocol Number + +Add a new protocol number (following existing conventions): + +```cpp +// Existing protocol numbers (IPv4 Protocol field): +// UDP data: 0x11 +// CNP: 0xFF +// PFC: 0xFE +// ACK: 0xFC +// NACK: 0xFD +// Your new: 0xFB (example) +``` + +### Step 3: Add Parsing/Dispatch + +Add packet handling in: +- `QbbNetDevice::Receive()` — Device-level parsing +- `RdmaHw::Receive()` — Host stack processing + +--- + +## NVSwitch / NVLS Extensions + +**Files**: `nvswitch-node.{h,cc}`, `qbb-net-device.{h,cc}` (NVLS send path), `rdma-hw.{h,cc}` (NVLS routing) + +The `NVSwitchNode` models intra-server GPU communication via NVSwitch. To extend: + +- **Forwarding**: Similar to `SwitchNode` but without ECN/INT injection +- **NVLS routing**: Modify `RdmaHw::GetNicIdxOfQp()` and `GetNicIdxOfRxQp()` for NVSwitch routing tables +- **QP redistribution**: `RdmaHw::RedistributeQp()` for load balancing across NVSwitch links + +--- + +## Analysis Tools + +The `ns-3-alibabacloud/analysis/` directory contains trace analysis tools: + +| Tool | Purpose | +|------|---------| +| FCT Analysis | Flow Completion Time analysis from simulation traces | +| Trace Reader | Parse binary `TraceFormat` records | +| Bandwidth Analysis | Per-link bandwidth utilization over time | +| Queue Analysis | Queue occupancy and PFC event analysis | +| QP Analysis | Per-QP performance metrics | + +### Trace Format + +The binary trace record structure (`trace-format.h`) captures per-packet events. Use the offline analysis tools to: + +1. Parse trace files from simulation output +2. Compute FCT, throughput, queue depth statistics +3. Identify congestion hotspots and PFC events + +--- + +## dev/qp Branch Enhancements + +The [dev/qp](https://github.com/aliyun/ns-3-alibabacloud/tree/dev/qp) branch includes: + +1. **QP Logic Support** — QP creation/destruction based on actual RDMA logic +2. **NIC CC Configuration** — PerIP or perQP CC settings +3. **Optimized Scheduling** — Max-Min principle for fair resource allocation +4. **Decoupled CC Module** — Improved modularity + +--- + +## Related Documentation + +- [NS-3 Component](../components/ns3.md) — Full NS-3 backend documentation +- [SimAI-Simulation User Guide](../user_guide/simai_simulation.md) — Using NS-3 simulation mode +- [Configuration Reference](../technical_reference/configuration.md) — Topology and configuration files diff --git a/docs/en/developer_guide/index.md b/docs/en/developer_guide/index.md new file mode 100644 index 00000000..ddb9ccbe --- /dev/null +++ b/docs/en/developer_guide/index.md @@ -0,0 +1,25 @@ +# Developer Guide + +Welcome to the SimAI Developer Guide. This section covers the project architecture, contribution workflow, and guides for extending SimAI with new models and network features. + +--- + +## Contents + +| Document | Description | +|----------|-------------| +| [Architecture](architecture.md) | System architecture, data flow, and module interaction | +| [Contributing](contributing.md) | Development workflow, code style, PR guidelines | +| [Adding Models](adding_models.md) | Guide to adding new model support (Vidur profiling + AICB workload) | +| [Extending NS-3](extending_ns3.md) | Guide to extending the NS-3 network backend | + +--- + +## Prerequisites + +- **Python** 3.8+ (3.12 recommended with Docker) +- **CMake** 3.16+ +- **GCC/G++** 9.4+ +- **Git** with submodule support + +See [Installation Guide](../getting_started/installation.md) for setup instructions. diff --git a/docs/en/getting_started/index.md b/docs/en/getting_started/index.md new file mode 100644 index 00000000..46d39f68 --- /dev/null +++ b/docs/en/getting_started/index.md @@ -0,0 +1,25 @@ +# Getting Started + +This section helps you set up SimAI and run your first simulation. + +## Contents + +| Page | Description | +|------|-------------| +| [Installation](installation.md) | How to install SimAI via Docker or from source | +| [Quickstart](quickstart.md) | Run your first SimAI-Analytical, SimAI-Simulation, and Inference simulation | + +## Prerequisites + +- **Python** 3.8+ (3.12 recommended with Docker) +- **CMake** 3.16+ +- **GCC/G++** 9.4+ +- **Git** with submodule support + +For workload generation with AIOB (computation profiling), a **NVIDIA Hopper (SM90)** or **Blackwell (SM100)** GPU is required. + +## Next Steps + +1. Follow the [Installation Guide](installation.md) to set up your environment +2. Run the [Quickstart](quickstart.md) examples to verify your setup +3. Explore the [User Guide](../user_guide/index.md) for detailed usage instructions diff --git a/docs/en/getting_started/installation.md b/docs/en/getting_started/installation.md new file mode 100644 index 00000000..778138b6 --- /dev/null +++ b/docs/en/getting_started/installation.md @@ -0,0 +1,96 @@ +# Installation + +This guide covers how to install SimAI and its dependencies. + +## Option A: Docker (Recommended) + +```bash +# Build the Docker image +docker build -t simai:latest . + +# Run a container with GPU support +docker run --gpus all -it --rm \ + -v $(pwd)/results:/workspace/SimAI/results \ + simai:latest /bin/bash +``` + +> **Note:** If using Hopper GPUs, add `ENV FLASH_MLA_DISABLE_SM100=1` to the Dockerfile. + +## Option B: Build from Source + +The following instructions have been tested on GCC/G++ 9.4.0, Python 3.8.10, Ubuntu 20.04. + +> **Important:** Do not install ninja (it is pre-installed in NGC images and must be removed for SimAI-Simulation compilation). +> ```bash +> apt remove ninja-build && pip uninstall ninja +> ``` + +### Step 1: Clone the Repository + +```bash +git clone https://github.com/aliyun/SimAI.git +cd ./SimAI/ + +# Initialize submodules +git submodule update --init --recursive +# Update to latest commits +git submodule update --remote +``` + +### Step 2: Compile C++ Components + +Choose the mode(s) you need: + +```bash +# SimAI-Analytical (fast, abstracts network details) +./scripts/build.sh -c analytical + +# SimAI-Simulation (full-stack with NS-3 network backend) +./scripts/build.sh -c ns3 + +# SimAI-Physical (beta, requires RDMA environment) +sudo yum install openmpi openmpi-devel +export MPI_INCLUDE_PATH=/usr/include/openmpi-x86_64/ +export MPI_BIN_PATH=/usr/lib64/openmpi/bin/mpic++ +./scripts/build.sh -c phy +``` + +### Step 3: Install Python Dependencies + +```bash +pip install -r aicb/requirements.txt +pip install -r vidur-alibabacloud/requirements.txt +``` + +### Step 4: Verify the Build + +```bash +ls bin/ # Should contain SimAI_analytical and/or SimAI_simulator +``` + +## Option C: Conda Environment (for Inference Simulation) + +```bash +cd vidur-alibabacloud +conda env create -p ./env -f ./environment.yml +conda activate vidur +pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ +``` + +## NGC Container (for Workload Generation) + +For generating workloads with computation profiling (AIOB), we recommend using NGC container images directly: + +```bash +docker pull nvcr.io/nvidia/pytorch:xx.xx-py3 +docker run --gpus all -it --rm \ + -v /path/to/SimAI:/workspace/SimAI \ + nvcr.io/nvidia/pytorch:xx.xx-py3 +``` + +> **Note:** Use PyTorch >= 23.08 NGC images. + +## What's Next + +- [Quickstart Guide](quickstart.md) — Run your first simulation +- [User Guide](../user_guide/index.md) — Detailed usage for each mode diff --git a/docs/en/getting_started/quickstart.md b/docs/en/getting_started/quickstart.md new file mode 100644 index 00000000..985ee2bc --- /dev/null +++ b/docs/en/getting_started/quickstart.md @@ -0,0 +1,85 @@ +# Quickstart + +This guide walks you through running your first simulation with SimAI. + +## 1. SimAI-Analytical + +The fastest way to get started. Abstracts network details using bus bandwidth (busbw). + +```bash +# Run analytical simulation +./bin/SimAI_analytical \ + -w example/workload_analytical.txt \ + -g 9216 \ + -g_p_s 8 \ + -r test- \ + -busbw example/busbw.yaml +``` + +For automatic bus bandwidth calculation: + +```bash +./bin/SimAI_analytical \ + -w ./example/workload_analytical.txt \ + -g 9216 -nv 360 -nic 48.5 \ + -n_p_s 8 -g_p_s 8 -r example- +``` + +For detailed parameter descriptions, see [SimAI-Analytical User Guide](../user_guide/simai_analytical.md). + +## 2. SimAI-Simulation + +Full-stack simulation with NS-3 network backend. + +```bash +# Step 1: Create network topology +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +# Step 2: Run simulation +AS_SEND_LAT=3 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator \ + -t 16 \ + -w ./example/microAllReduce.txt \ + -n ./Spectrum-X_128g_8gps_100Gbps_A100 \ + -c astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +For detailed parameter descriptions, see [SimAI-Simulation User Guide](../user_guide/simai_simulation.md). + +## 3. Multi-Request Inference Simulation + +End-to-end inference simulation using the Vidur framework. + +### Prerequisites + +```bash +# Activate the vidur conda environment +conda activate vidur +``` + +### Run the 4-Scenario Test Suite + +```bash +# Run all 4 scenarios +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all + +# Or run a single scenario +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 +``` + +### Scenarios Overview + +| Scenario | Model | PD Separation | World Size | TP | EP | Scheduler | +|----------|-------|---------------|-----------|----|----|-----------| +| 1 | Qwen3-Next-80B | No | 32 | 1 | 1 | lor | +| 2 | Qwen3-Next-80B | Yes (P=2, D=6) | 8 | 1 | 1 | split_wise | +| 3 | DeepSeek-671B | Yes (P=2, D=6) | 8 | 8 | 8 | split_wise | +| 4 | Qwen3-MoE-235B | Yes (P=2, D=6) | 8 | 4 | 4 | split_wise | + +For detailed information, see [Inference Simulation User Guide](../user_guide/inference_simulation.md). + +## What's Next + +- [User Guide](../user_guide/index.md) — Deep dive into each simulation mode +- [Components](../components/index.md) — Learn about each submodule +- [Benchmarking](../benchmarking/index.md) — Run the full test suite diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 00000000..6953fc17 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,73 @@ +# Welcome to SimAI Documentation + +

+ 中文  ｜  English +

+ +[![License](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE) +[![NSDI'25](https://img.shields.io/badge/NSDI'25-SimAI-blue.svg)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) + +**SimAI** is the industry's first full-stack, high-precision **Sim**ulator for **AI** large-scale **inference** and **training**, open-sourced by Alibaba Cloud. It provides detailed modeling and simulation of the entire LLM training and inference process, encompassing the framework layer, collective communication layer, and network transport layer, delivering end-to-end performance data. + +SimAI enables researchers to: + +- Analyze inference/training process details +- Evaluate the time consumption of AI tasks under specific conditions +- Evaluate E2E performance gains from various algorithmic optimizations (framework parameters, collective communication algorithms, network protocols, congestion control, routing, topology, etc.) + +--- + +## Documentation Overview + +| Section | Description | +|---------|-------------| +| [Getting Started](getting_started/index.md) | Installation, environment setup, and quickstart guide | +| [User Guide](user_guide/index.md) | Detailed usage for SimAI-Analytical, SimAI-Simulation, SimAI-Physical, and Inference Simulation | +| [Components](components/index.md) | In-depth documentation for each submodule: AICB, SimCCL, astra-sim, ns-3, vidur | +| [Technical Reference](technical_reference/index.md) | GPU memory module, CLI parameters, and configuration reference | +| [Benchmarking](benchmarking/index.md) | 4-scenario end-to-end test suite and benchmark results | +| [Developer Guide](developer_guide/index.md) | Architecture, contributing guide, adding models, and extending NS-3 | +| [Community](community/index.md) | Events, contact information, and citation | + +--- + +## Architecture + +``` + |--- AICB (Workload generation & compute profiling) +SimAI --|--- SimCCL (Collective communication algorithm analysis) + |--- astra-sim-alibabacloud (Simulation engine: Analytical / Simulation / Physical) + |--- ns-3-alibabacloud (NS-3 network backend) + |--- vidur-alibabacloud (Multi-request inference scheduling & memory management) +``` + +![SimAI Architecture](../images/SimAI_Arc.png) + +--- + +## Three Operation Modes + +| Mode | Description | Use Cases | +|------|-------------|-----------| +| **SimAI-Analytical** | Fast simulation using bus bandwidth (busbw) to estimate collective communication time | Performance analysis, parallel parameter optimization, scale-up exploration | +| **SimAI-Simulation** | Full-stack simulation with NS-3 network backend for fine-grained network modeling | CC algorithm research, network protocol evaluation, novel architecture design | +| **SimAI-Physical** *(Beta)* | Physical traffic generation on CPU RDMA clusters | NIC behavior study during LLM training | + +--- + +## Supported Models + +- **DeepSeek-V3-671B** — MLA attention, 256 routed experts +- **Qwen3-MoE-235B** — MHA/GQA, 128 routed experts +- **Qwen3-Next-80B** — Hybrid full + linear attention, 512 routed experts +- **Meta-Llama-3-8B / 70B**, **Llama-2-7b / 70b**, **CodeLlama-34b**, **InternLM-20B**, **Qwen-72B** + +--- + +## Quick Links + +- [GitHub Repository](https://github.com/aliyun/SimAI) +- [NSDI'25 Paper (PDF)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) +- [Slides](../../docs/SimAI_Intro_Online.pdf) +- [Technical Report (1.6)](../SimAI_1.6_Tech_Report.md) +- [Contributing Guide](../../CONTRIBUTING.md) diff --git a/docs/en/technical_reference/cli_reference.md b/docs/en/technical_reference/cli_reference.md new file mode 100644 index 00000000..689d2058 --- /dev/null +++ b/docs/en/technical_reference/cli_reference.md @@ -0,0 +1,185 @@ +# CLI Reference + +Complete command-line parameter reference for all SimAI tools. + +--- + +## SimAI-Analytical + +**Binary**: `bin/SimAI_analytical` + +### Required Parameters + +| Flag | Long Form | Description | +|------|-----------|-------------| +| `-w` | `--workload` | Path to workload file | +| `-g` | `--gpus` | Simulation GPU scale | +| `-g_p_s` | `--gpus-per-server` | Scale-up size (GPUs per server) | +| `-r` | `--result` | Output file path and prefix (default: `./results/`) | +| `-busbw` | `--bus-bandwidth` | Path to busbw.yaml file | + +### Optional Parameters + +| Flag | Long Form | Description | +|------|-----------|-------------| +| `-v` | `--visual` | Generate visualization files | +| `-dp_o` | `--dp-overlap-ratio` | DP overlap ratio [0.0-1.0] | +| `-ep_o` | `--ep-overlap-ratio` | EP overlap ratio [0.0-1.0] | +| `-tp_o` | `--tp-overlap-ratio` | TP overlap ratio [0.0-1.0] | +| `-pp_o` | `--pp-overlap-ratio` | PP overlap ratio [0.0-1.0] | + +### Auto Busbw Calculation + +| Flag | Description | +|------|-------------| +| `-nv` | NVLink bandwidth (GB/s) | +| `-nic` | NIC bandwidth (GB/s) | +| `-n_p_s` | NICs per server | + +--- + +## SimAI-Simulation + +**Binary**: `bin/SimAI_simulator` + +### Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `AS_LOG_LEVEL` | Log level: DEBUG/INFO/WARNING/ERROR | `INFO` | +| `AS_PXN_ENABLE` | Enable PXN | `0` | +| `AS_NVLS_ENABLE` | Enable NVLS | `0` | +| `AS_SEND_LAT` | Send latency (us) | `6` | +| `AS_NVLSTREE_ENABLE` | Enable NVLS Tree | `false` | + +### Parameters + +| Flag | Long Form | Description | Default | +|------|-----------|-------------|---------| +| `-t` | `--thread` | Number of threads | `1` | +| `-w` | `--workload` | Path to workload | Required | +| `-n` | `--network-topo` | Topology file path | Required | +| `-c` | `--config` | SimAI.conf path | Required | + +--- + +## SimAI-Physical + +**Binary**: `bin/SimAI_phynet` + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `hostlist` | Path to host IP list | Required | +| `-w` / `--workload` | Workload file path | `./microAllReduce.txt` | +| `-i` / `--gid_index` | GID index for RDMA | `0` | +| `-g` / `--gpus` | Number of GPUs | `8` | + +--- + +## Topology Generator + +**Script**: `astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py` + +| Level | Flag | Description | +|-------|------|-------------| +| Global | `-topo` | Template: Spectrum-X / AlibabaHPN / DCN+ | +| | `-g` | Number of GPUs | +| | `--dp` | Enable dual plane | +| | `--ro` | Enable rail-optimized | +| | `--dt` | Enable dual ToR | +| | `-er` | Error rate | +| Intra-Host | `-gps` | GPUs per server | +| | `-gt` | GPU type (A100/H100) | +| | `-nsps` | NV switches per server | +| | `-nvbw` | NVLink bandwidth | +| | `-nl` | NVLink latency | +| | `-l` | NIC latency | +| Intra-Segment | `-bw` | NIC to ASW bandwidth | +| | `-asw` | ASW switch count | +| | `-nps` | NICs per switch | +| Intra-Pod | `-psn` | PSW switch count | +| | `-apbw` | ASW to PSW bandwidth | +| | `-app` | ASW per PSW | + +--- + +## AICB Workload Generator + +**Script**: `scripts/megatron_workload_with_aiob.sh` or `python -m workload_generator.SimAI_training_workload_generator` + +### Core Parameters + +| Parameter | Description | +|-----------|-------------| +| `--frame` | Framework: Megatron / DeepSpeed / DeepSeek | +| `-m` / `--model_size` | Model size: 7/13/22/175/moe/deepseek | +| `--world_size` | Total GPU count | +| `--global_batch` | Total batch size | +| `--micro_batch` | Micro-batch size | +| `--seq_length` | Sequence length | +| `--epoch_num` | Number of iterations | + +### Parallelism Parameters + +| Parameter | Description | +|-----------|-------------| +| `--tensor_model_parallel_size` | TP degree | +| `--pipeline_model_parallel` | PP degree | +| `--expert_model_parallel_size` | EP degree | +| `--enable_sequence_parallel` | Enable SP | + +### Model Parameters + +| Parameter | Description | +|-----------|-------------| +| `--num_layers` | Transformer layers | +| `--hidden_size` | Hidden size | +| `--num_attention_heads` | Attention heads | +| `--ffn_hidden_size` | FFN hidden size | +| `--vocab_size` | Vocabulary size | + +### MoE Parameters + +| Parameter | Description | +|-----------|-------------| +| `--moe_enable` | Enable MoE | +| `--num_experts` | Number of experts | +| `--moe_router_topk` | Experts per token | +| `--moe_grouped_gemm` | Enable grouped GEMM | + +### DeepSeek Parameters + +| Parameter | Description | +|-----------|-------------| +| `--qk_rope_dim` | RoPE dimension for QK | +| `--qk_nope_dim` | Non-RoPE dimension for QK | +| `--q_lora_rank` | Q LoRA rank | +| `--kv_lora_rank` | KV LoRA rank | +| `--v_head_dim` | V head dimension | +| `--n_shared_expert` | Shared experts per MoE layer | +| `--n_dense_layer` | Dense layers count | + +### Optimization Parameters + +| Parameter | Description | +|-----------|-------------| +| `--use_flash_attn` | FlashAttention | +| `--swiglu` | SwiGLU activation | +| `--aiob_enable` | AIOB computation profiling | +| `--comp_filepath` | Pre-computed times file | + +--- + +## Vidur Inference Simulation + +**Command**: `python -m vidur.main` + +Run `python -m vidur.main -h` for the full parameter list. Key parameters are documented in the [vidur component page](../components/vidur.md). + +--- + +## See Also + +- [Configuration Reference](configuration.md) — Config file formats +- [SimAI-Analytical Guide](../user_guide/simai_analytical.md) — Usage examples +- [AICB Component](../components/aicb.md) — Full parameter details diff --git a/docs/en/technical_reference/configuration.md b/docs/en/technical_reference/configuration.md new file mode 100644 index 00000000..7ad67fb6 --- /dev/null +++ b/docs/en/technical_reference/configuration.md @@ -0,0 +1,163 @@ +# Configuration Reference + +This document covers all configuration files used by SimAI. + +--- + +## SimAI.conf + +**Path**: `astra-sim-alibabacloud/inputs/config/SimAI.conf` + +The main simulation configuration file used by both SimAI-Analytical and SimAI-Simulation modes. It controls communication algorithms, buffer sizes, and timing parameters. + +--- + +## busbw.yaml + +**Path**: `example/busbw.yaml` + +Used by SimAI-Analytical to specify bus bandwidth for different communication groups and collective operations. + +### Format + +```yaml +test +TP: + allreduce,: 300 # AllReduce busbw 300GB/s in TP group + allgather,: 280 + reducescatter,: 280 + alltoall,: 230 +DP: + allreduce,: null # null = not used in this group + allgather,: 380 + reducescatter,: 380 + alltoall,: null +EP: + allreduce,: null + allgather,: 45 + reducescatter,: 45 + alltoall,: 80 +``` + +### Communication Groups + +| Group | Description | +|-------|-------------| +| `TP` | Tensor Parallelism — intra-server NVLink communication | +| `DP` | Data Parallelism — inter-server RDMA communication | +| `EP` | Expert Parallelism — MoE expert communication | + +### Collective Operations + +| Operation | Description | +|-----------|-------------| +| `allreduce` | Reduce + broadcast across all ranks | +| `allgather` | Gather data from all ranks | +| `reducescatter` | Reduce and scatter | +| `alltoall` | All-to-all personalized exchange | + +Set value to `null` for operations not used in a particular group. + +--- + +## Topology Files + +Generated by `gen_Topo_Template.py`, topology files define the network structure for SimAI-Simulation. + +### Generation + +```bash +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps +``` + +The output file is named based on parameters, e.g., `Spectrum-X_128g_8gps_100Gbps_A100`. + +### Template Defaults + +| Template | GPUs | Topo | Bandwidth | GPU Type | +|----------|------|------|-----------|----------| +| Spectrum-X | 4096 | Rail-optimized, single ToR | 400Gbps | H100 | +| AlibabaHPN (single) | 15360 | Rail-optimized, dual ToR | 200Gbps | H100 | +| AlibabaHPN (dual) | 15360 | Rail-optimized, dual ToR, dual plane | 200Gbps | H100 | +| DCN+ (single ToR) | 512 | Non rail-optimized | 400Gbps | A100 | +| DCN+ (dual ToR) | 512 | Non rail-optimized, dual ToR | 200Gbps | H100 | + +--- + +## Model Configuration Files + +### Inference Model Configs + +Located in `vidur-alibabacloud/data/hf_configs/`: + +| Model | Config File | +|-------|------------| +| DeepSeek-V3-671B | `deepseek_v3_config.json` | +| Qwen3-MoE-235B | `qwen3_moe_config.json` | +| Qwen3-Next-80B | `qwen3-next-80B-A3B_config.json` | + +These files follow the HuggingFace `config.json` format and define model architecture parameters. + +### Profiling Data + +Located in `vidur-alibabacloud/data/profiling/`: + +``` +profiling/ +├── compute/ +│ ├── a100/ +│ │ └── / +│ │ ├── mlp.csv +│ │ └── attention.csv +│ └── h100/ +│ └── / +│ ├── mlp.csv +│ └── attention.csv +└── network/ + ├── a100_pair_nvlink/ + │ ├── allreduce.csv + │ └── send_recv.csv + └── h100_dgx/ + ├── allreduce.csv + └── send_recv.csv +``` + +- **Compute profiling**: GPU-type dependent (a100, h100) +- **Network profiling**: Network-configuration dependent (pair_nvlink, dgx) + +--- + +## Workload Files + +### Training Workload Format + +``` +HYBRID_TRANSFORMER_FWD_IN_BCKWD model_parallel_NPU_group: 8 ep: 1 pp: 1 vpp: 8 ga: 1 all_gpus: 32 checkpoints: 0 checkpoint_initiates: 0 +6 +embedding_layer -1 556000 ALLREDUCE 16777216 1 NONE 0 1 NONE 0 1 +... +``` + +Header fields: +- `model_parallel_NPU_group`: TP size +- `ep`: EP size +- `pp`: PP size +- `vpp`: Virtual Pipeline Parallelism +- `ga`: Gradient accumulation +- `all_gpus`: Total GPU count + +### Request Trace Files + +For inference simulation, located in `vidur-alibabacloud/data/processed_traces/`: + +- `splitwise_conv.csv` — Conversational trace +- `sharegpt_8k_filtered_stats_llama2_tokenizer.csv` — ShareGPT trace + +--- + +## See Also + +- [CLI Reference](cli_reference.md) — Command-line parameters +- [SimAI-Analytical Guide](../user_guide/simai_analytical.md) — busbw configuration usage +- [SimAI-Simulation Guide](../user_guide/simai_simulation.md) — Topology configuration usage diff --git a/docs/en/technical_reference/index.md b/docs/en/technical_reference/index.md new file mode 100644 index 00000000..05cbc062 --- /dev/null +++ b/docs/en/technical_reference/index.md @@ -0,0 +1,13 @@ +# Technical Reference + +This section provides detailed technical specifications and reference documentation for SimAI's internal modules, CLI parameters, and configuration files. + +--- + +## Contents + +| Document | Description | +|----------|-------------| +| [GPU Memory Module](memory_module.md) | ParamCounter, KV Cache calculation, and MemoryPlanner | +| [CLI Reference](cli_reference.md) | Complete command-line parameter reference for all modes | +| [Configuration Files](configuration.md) | SimAI.conf, busbw.yaml, topology files, and model configs | diff --git a/docs/en/technical_reference/memory_module.md b/docs/en/technical_reference/memory_module.md new file mode 100644 index 00000000..9fb41c53 --- /dev/null +++ b/docs/en/technical_reference/memory_module.md @@ -0,0 +1,155 @@ +# GPU Memory Calculation Module + +The GPU memory calculation module (introduced in SimAI 1.6) provides accurate GPU memory estimation for inference simulation, covering model parameter memory, KV cache memory, and maximum batch size calculation. + +--- + +## Architecture + +``` +ParamCounter (param_counter.py) + |-- Computes per-layer, per-device parameter counts + |-- Returns (total_params, prefill_params, decode_params) under PD + | +MemoryPlanner (memory_planner.py) + |-- Plans GPU memory budget + |-- Computes KV cache capacity + |-- Detects OOM conditions + | +Replica KV Cache Tracker (replica.py) + |-- Per-request allocation/release + |-- Runtime capacity queries +``` + +--- + +## ParamCounter + +**File**: `vidur-alibabacloud/vidur/utils/param_counter.py` + +### MLA Parameters (DeepSeek-V3-671B) + +Per-layer MLA parameter components: + +| Component | Formula | DeepSeek-V3 Value | +|-----------|---------|-------------------| +| Q LoRA down-projection | `hidden_size * q_lora_rank` | 7168 * 1536 | +| Q LoRA up-projection | `q_lora_rank * num_heads * qk_head_dim` | 1536 * 128 * 192 | +| KV LoRA down-projection | `hidden_size * kv_lora_rank` | 7168 * 512 | +| KV LoRA up-projection | `kv_lora_rank * num_heads * (qk_nope_dim + v_head_dim)` | 512 * 128 * 256 | +| Output projection | `hidden_size * num_heads * v_head_dim` | 7168 * 128 * 128 | + +Where `qk_head_dim = qk_nope_head_dim + qk_rope_head_dim = 128 + 64 = 192` + +### MHA/GQA Parameters (Qwen3-MoE-235B) + +``` +wq = hidden_size * num_attention_heads * head_dim +wk = hidden_size * num_key_value_heads * head_dim +wv = hidden_size * num_key_value_heads * head_dim +wo = hidden_size * num_attention_heads * head_dim +total = (wq + wk + wv + wo) * bytes_per_element +``` + +### Linear Attention Parameters (Qwen3-Next-80B) + +Qwen3-Next-80B uses hybrid attention: full attention and linear (GDN) attention alternating every 4 layers. Linear attention layers use independent `linear_key_head_dim` / `linear_num_key_heads` configurations. + +### MoE Expert Parameters + +Per-expert FFN (3 weight matrices W1, W2, W3): + +``` +expert_params = 3 * hidden_size * moe_intermediate_size * bytes_per_element +``` + +### PD Disaggregation + +Under PD disaggregation, expert parallelism differs between clusters: + +- **Prefill cluster**: `experts_per_device = num_routed_experts / prefill_world_size` +- **Decode cluster**: `experts_per_device = num_routed_experts / decode_world_size` + +Returns triple: `(total_params, prefill_params, decode_params)` + +--- + +## KV Cache Calculation + +### MHA/GQA KV Cache + +``` +kv_cache_per_token = 2 * num_kv_heads * head_dim * num_layers * bytes_per_element +``` + +Factor of 2 = K (Key) + V (Value) caches. + +### MLA KV Cache (DeepSeek-V3-671B) + +MLA uses compressed KV representations — a single latent vector encoding both K and V: + +``` +kv_cache_per_token = (kv_lora_rank + qk_rope_head_dim) * num_layers * bytes_per_element +``` + +Where `kv_lora_rank = 512`, `qk_rope_head_dim = 64`. + +**Comparison**: MHA would need `2 * 128 * 128 = 32768` elements per token. MLA needs only `576` elements — a **~57x reduction**. + +### Per-Request KV Cache Tracking + +The `Replica` entity maintains: + +| State | Description | +|-------|-------------| +| `_allocated_kv_cache_memory` | Currently allocated KV cache (bytes) | +| `_max_kv_cache_memory` | Maximum KV cache capacity | +| `_kv_cache_allocation_map` | Per-request allocation mapping | + +Operations: +- `allocate_request_kv_cache_memory(request, num_blocks, block_size)` +- `release_request_kv_cache_memory(request)` +- `get_remaining_kv_cache_capacity()` + +--- + +## MemoryPlanner + +**File**: `vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py` + +### Calculation Flow + +1. **Available GPU memory**: `available = total_GPU_memory * (1 - memory_margin_fraction)` +2. **Parameter memory**: Via ParamCounter; PD returns `(total, prefill, decode)` +3. **KV cache budget**: `kv_available = available - param_memory` +4. **Max concurrent requests**: `max_requests = kv_available / kv_cache_per_request` + +### PD Disaggregation + +- Prefill replicas: use `prefill_param_mem` for budget +- Decode replicas: use `decode_param_mem` for budget + +### OOM Detection + +When `param_memory > available_memory`, outputs error with suggestions: +- Increase TP/EP size +- Use larger GPU (more VRAM) +- Enable FP8 quantization + +--- + +## Quantization Support + +| Precision | Bytes per Element | Use Case | +|-----------|-------------------|----------| +| FP32 | 4 | Reference | +| FP16/BF16 | 2 | Default inference | +| FP8 | 1 | Reduced memory, supported by ParamCounter | + +--- + +## See Also + +- [vidur-alibabacloud Component](../components/vidur.md) — Full component documentation +- [Supported Models](../user_guide/supported_models.md) — Model specifications +- [SimAI 1.6 Tech Report](../../SimAI_1.6_Tech_Report.md) — Detailed technical report diff --git a/docs/en/user_guide/index.md b/docs/en/user_guide/index.md new file mode 100644 index 00000000..3e95fc10 --- /dev/null +++ b/docs/en/user_guide/index.md @@ -0,0 +1,25 @@ +# User Guide + +This section provides detailed usage instructions for all SimAI operation modes. + +## Contents + +| Page | Description | +|------|-------------| +| [SimAI-Analytical](simai_analytical.md) | Fast analytical simulation using bus bandwidth | +| [SimAI-Simulation](simai_simulation.md) | Full-stack NS-3 network simulation with topology configuration | +| [SimAI-Physical](simai_physical.md) | Physical RDMA traffic generation on real clusters | +| [Inference Simulation](inference_simulation.md) | Multi-request LLM inference simulation with PD disaggregation | +| [Workload Generation](workload_generation.md) | Generate training and inference workloads using AICB | +| [Supported Models](supported_models.md) | Complete list of supported models and configurations | +| [Result Analysis](result_analysis.md) | Analyze and visualize simulation results | + +## Workflow Overview + +A typical SimAI workflow involves three steps: + +1. **Generate workloads** using [AICB](workload_generation.md) — defines the computation and communication patterns +2. **Run simulation** using one of the three modes (Analytical, Simulation, or Physical) +3. **Analyze results** using built-in tools or custom scripts + +For inference simulation, the workflow uses Vidur for request scheduling and memory management, with AICB or SimAI as the execution-time prediction backend. diff --git a/docs/en/user_guide/inference_simulation.md b/docs/en/user_guide/inference_simulation.md new file mode 100644 index 00000000..b99b75fa --- /dev/null +++ b/docs/en/user_guide/inference_simulation.md @@ -0,0 +1,176 @@ +# Multi-Request Inference Simulation + +SimAI supports complete multi-request LLM inference simulation, enabling end-to-end performance evaluation of inference serving systems with support for Prefill-Decode (PD) disaggregation. + +--- + +## Overview + +The inference simulation pipeline combines several SimAI components: + +- **[AICB](../components/aicb.md)** — Generates inference workloads and profiles computation time +- **[vidur-alibabacloud](../components/vidur.md)** — Request scheduling, memory management, and metrics collection +- **[astra-sim-alibabacloud](../components/astra_sim.md)** — Simulation engine (Analytical or Simulation mode) +- **[SimCCL](../components/simccl.md)** — Collective communication transformation + +--- + +## Prefill-Decode (PD) Disaggregation + +The inference process is divided into two distinct phases: + +| Phase | Characteristic | Description | +|-------|---------------|-------------| +| **Prefill** | Compute-intensive | Processes all input prompt tokens and generates the first output token | +| **Decode** | Memory-bandwidth-intensive | Autoregressively generates subsequent output tokens one at a time | + +PD disaggregation allows deploying these phases on different GPU nodes, enabling: + +- **Elastic resource allocation** — Prefill nodes can be configured with more compute, Decode nodes with more memory +- **Performance isolation** — Avoiding resource contention between phases +- **Flexible P:D ratio** — Configurable via `--replica_config_pd_node_ratio` + +--- + +## Request Scheduling + +The scheduling component is adapted from Microsoft's [Vidur](https://github.com/microsoft/vidur), supporting multiple strategies: + +| Scheduler | Level | Description | +|-----------|-------|-------------| +| `split_wise` | Global | PD disaggregation-aware dispatch to Prefill and Decode replicas | +| `lor` | Global | Least Outstanding Requests — dispatch to the least-loaded replica | +| `round_robin` | Global | Round-robin dispatch | +| `sarathi` | Per-replica | Intra-replica batch scheduling | +| `split_wise` | Per-replica | Per-replica scheduling for PD disaggregation | + +--- + +## Parallelism Strategies + +Supports combinations of multiple parallelism strategies: + +| Strategy | Flag | Description | +|----------|------|-------------| +| **Data Parallel (DP)** | `--cluster_config_num_replicas` | Number of replicas | +| **Tensor Parallel (TP)** | `--replica_config_tensor_parallel_size` | Intra-node parallelism | +| **Pipeline Parallel (PP)** | `--replica_config_num_pipeline_stages` | Inter-stage parallelism | +| **Expert Parallel (EP)** | `--replica_config_expert_model_parallel_size` | MoE expert parallelism | + +Works for both dense and MoE (Mixture-of-Experts) models. + +--- + +## Execution-Time Prediction Backends + +| Backend | Flag Value | Description | +|---------|-----------|-------------| +| **AICB/AIOB** | `aicb` | Supports compute kernels and TP/DP/PP/EP communication size for DeepSeek-V3, Qwen3-MoE, Qwen3-Next | +| **SimAI Simulation** | `simai_simulation` | NS-3-based full-stack network simulation (currently supports TP) | +| **SimAI Analytical** | `simai_analytical` | Analytical performance model (currently supports TP) | +| **Native Vidur** | `vidur` | Original Vidur backend, supports TP, DP, PP | + +Set via `--random_forrest_execution_time_predictor_config_backend`. + +--- + +## Quick Start + +### Prerequisites + +- **AICB backend**: SimAI Docker environment with Hopper (SM90) or Blackwell (SM100) GPUs +- **SimAI backends**: Compile SimAI-Analytical or SimAI-Simulation first +- **Vidur backend**: Conda environment with profiling data + +### Run with AICB Backend + +```bash +cd SimAI/vidur-alibabacloud + +python -m vidur.main \ + --replica_config_model_name deepseek-671B \ + --replica_config_tensor_parallel_size 2 \ + --replica_config_expert_model_parallel_size 8 \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 5 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 1024 \ + --fixed_request_length_generator_config_decode_tokens 10 \ + --random_forrest_execution_time_predictor_config_backend aicb +``` + +### Run with SimAI Simulation Backend + +```bash +cd SimAI + +# Compile and generate topology +./scripts/build.sh -c ns3 +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +cd vidur-alibabacloud + +python -m vidur.main \ + --replica_config_model_name meta-llama/Meta-Llama-3-8B \ + --replica_config_tensor_parallel_size 4 \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --random_forrest_execution_time_predictor_config_backend simai_simulation \ + --random_forrest_execution_time_predictor_config_simai_dir ../ \ + --random_forrest_execution_time_predictor_config_simai_simulation_topo ../Spectrum-X_128g_8gps_100Gbps_A100 \ + --random_forrest_execution_time_predictor_config_simai_simulation_config ../astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +### Run the 4-Scenario Test Suite + +```bash +# Run all 4 pre-configured scenarios +bash examples/vidur-ali-scenarios/run_scenarios.sh --all + +# Run a single scenario +bash examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 +``` + +--- + +## 4-Scenario Configuration + +**Shared Hardware**: H20 GPU (h20_dgx), NVLink 1600 Gbps, RDMA 800 Gbps, PD P2P 800 Gbps (fp8) + +| Scenario | Model | PD Separation | World Size | TP | EP | Scheduler | +|----------|-------|---------------|------------|----|----|-----------| +| 1 | Qwen3-Next-80B | No | 32 (dp=32) | 1 | 1 | lor | +| 2 | Qwen3-Next-80B | Yes (P=2, D=6) | 8 | 1 | 1 | split_wise | +| 3 | DeepSeek-671B | Yes (P=2, D=6) | 8 | 8 | 8 | split_wise | +| 4 | Qwen3-MoE-235B | Yes (P=2, D=6) | 8 | 4 | 4 | split_wise | + +--- + +## Output + +Each simulation run produces: + +``` +// +├── request_metrics.csv # Per-request metrics +├── chrome_trace.json # Chrome DevTools timeline trace +├── config.json # Configuration snapshot +└── plots/ # Per-metric CSV/JSON files +``` + +See [Result Analysis](result_analysis.md) for output interpretation. + +--- + +## See Also + +- [vidur-alibabacloud Component](../components/vidur.md) — Full inference simulation documentation +- [Supported Models](supported_models.md) — Model compatibility matrix +- [Result Analysis](result_analysis.md) — Output interpretation guide diff --git a/docs/en/user_guide/result_analysis.md b/docs/en/user_guide/result_analysis.md new file mode 100644 index 00000000..eb4d71e3 --- /dev/null +++ b/docs/en/user_guide/result_analysis.md @@ -0,0 +1,183 @@ +# Result Analysis & Visualization + +This guide covers how to interpret and analyze simulation outputs from all SimAI modes. + +--- + +## SimAI-Analytical Output + +### CSV Output + +Running SimAI-Analytical generates a CSV file in the `results/` directory. The output contains: + +- **Summary row**: Exposure time, computation time (absolute and percentage) for each communication group, and end-to-end iteration time +- **Per-layer rows**: Detailed operation timing for each layer + +Key columns include per-communication-group breakdown (TP, DP, EP, PP) showing time allocation and overlap effects. + +### Visualization + +When running with the `-v` flag, SimAI-Analytical generates additional visualization files showing the timing breakdown across communication groups. + +```bash +# Run with visualization enabled +./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml -v +``` + +--- + +## SimAI-Simulation Output + +SimAI-Simulation (NS-3 mode) generates detailed trace data capturing fine-grained network behavior. The NS-3 backend outputs `.tr` trace files that can be analyzed using the provided analysis tools. + +### Analysis Tools + +Located in `ns-3-alibabacloud/analysis/`: + +| Tool | Description | +|------|-------------| +| `fct_analysis.py` | Flow Completion Time analysis — reads FCT output files and produces statistics | +| `trace_reader` | Parses `.tr` trace files with filtering support | + +### Using trace_reader + +```bash +# Build +cd ns-3-alibabacloud/analysis +make trace_reader + +# Parse trace file +./trace_reader <.tr file> [filter_expr] + +# Examples: +./trace_reader output.tr "time > 2000010000" +./trace_reader output.tr "sip=0x0b000101&dip=0x0b000201" +``` + +### Trace Output Format + +Each line in the trace output follows this format: + +``` +2000055540 n:338 4:3 100608 Enqu ecn:0 0b00d101 0b012301 10000 100 U 161000 0 3 1048(1000) +``` + +Fields: timestamp (ns), node ID, port:queue, queue length (bytes), event type, ECN flag, source IP, destination IP, source port, destination port, packet type, sequence number, TX timestamp, priority group, packet size (payload). + +--- + +## Inference Simulation Output + +### Output Directory Structure + +Each inference simulation run produces: + +``` +// +├── request_metrics.csv # Per-request metrics +├── chrome_trace.json # Chrome DevTools timeline trace +├── config.json # Configuration snapshot +└── plots/ # Per-metric CSV/JSON files + ├── request_e2e_time.csv + ├── prefill_e2e_time.csv + ├── pd_p2p_comm_time.csv + ├── replica_N_memory_usage.json + └── ... +``` + +### request_metrics.csv Columns + +| Column | Meaning | +|--------|---------| +| `arrived_at` | Timestamp when the request entered the system (seconds) | +| `scheduled_at` | Timestamp when the request was first scheduled (seconds) | +| `prefill_completed_at` | Timestamp when Prefill completed and first token generated | +| `decode_arrived_at` | Timestamp when Decode phase started | +| `decode_time` | Duration of Decode phase (seconds) | +| `prefill_replica_id` | Replica ID that executed Prefill (PD mode) | +| `decode_replica_id` | Replica ID that executed Decode (PD mode) | +| `request_num_prefill_tokens` | Number of input tokens (prompt length) | +| `request_num_decode_tokens` | Number of output tokens (generation length) | +| `pd_p2p_comm_size` | P2P communication size from Prefill to Decode node (bytes) | +| `pd_p2p_comm_time` | P2P communication time (seconds) | +| `completed_at` | Request completion timestamp | +| `request_execution_time` | Total execution time excluding delays (seconds) | +| `request_preemption_time` | Wait time due to preemption/bubbles (seconds) | +| `request_scheduling_delay` | Scheduling delay: `scheduled_at - arrived_at` (seconds) | +| `request_e2e_time` | End-to-end latency: `completed_at - arrived_at` (seconds) | +| `prefill_e2e_time` | Time To First Token (TTFT): `prefill_completed_at - arrived_at` (seconds) | +| `tbt` | Time Between Tokens: `decode_time / request_num_decode_tokens` (seconds/token) | + +### Chrome Trace Visualization + +Open `chrome_trace.json` in Chrome DevTools for visual timeline analysis: + +1. Open Chrome browser +2. Navigate to `chrome://tracing` +3. Load the `chrome_trace.json` file + +### Simulation Metrics (23 metrics) + +The simulator records 23 fine-grained metrics: + +| Category | Metrics | +|----------|---------| +| **Request Latency** | E2E time CDF, normalized E2E CDF, execution+preemption CDF | +| **Scheduling** | Scheduling delay CDF | +| **Execution** | Execution time CDF, preemption time CDF | +| **Token-level** | Decode token execution+preemption times, inter-token delay | +| **Batch** | Batch num tokens CDF, batch sizes CDF | +| **Prefill** | Prefill E2E CDF, prefill execution+preemption CDF (normalized) | +| **Decode** | Decode execution+preemption normalized CDF | +| **Time Series** | Request/prefill/decode completions, request arrivals | +| **Per-replica** | Memory usage (weighted mean), busy time %, MFU | + +For detailed metric definitions, see the [vidur metrics documentation](../components/vidur.md). + +--- + +## AICB Physical Execution Output + +### Log Output + +After each communication, AICB prints: +- Communication type and group +- Message size +- Execution time +- Throughput (algbw and busbw) + +### Iteration Summary + +After all communications complete, a summary shows: +- Overall runtime and per-iteration timing +- Per-communication-type statistics (message sizes, frequencies, latency min/max/avg) + +### CSV Output + +Results are saved in `results/comm_logs/`: +- `__log.csv` — Execution log with timing, phase, algbw, busbw per comm_group and comm_type +- `__workload.csv` — Generated workload description + +### Programmatic Analysis + +```python +# Read workload log +from log_analyzer.log import Workload +workload, args = Workload.load("results/comm_logs/megatron_gpt_13B_8n_workload.csv") + +# Read execution log +from log_analyzer.log import Log +log = Log.load("results/comm_logs/megatron_gpt_13B_8n_log.csv") +# log.comm_logs: List[LogItem] +# log.epoch_times: List[int] +# log.comm_log_each_epoch: List[List[LogItem]] +``` + +--- + +## See Also + +- [SimAI-Analytical](simai_analytical.md) — Analytical mode usage +- [SimAI-Simulation](simai_simulation.md) — NS-3 simulation mode usage +- [Inference Simulation](inference_simulation.md) — Inference simulation guide +- [NS-3 Component](../components/ns3.md) — NS-3 analysis tools diff --git a/docs/en/user_guide/simai_analytical.md b/docs/en/user_guide/simai_analytical.md new file mode 100644 index 00000000..94dec88d --- /dev/null +++ b/docs/en/user_guide/simai_analytical.md @@ -0,0 +1,104 @@ +# SimAI-Analytical + +SimAI-Analytical offers fast simulation by abstracting network communication details using bus bandwidth (busbw) to estimate collective communication time. It is ideal for rapid scenario validation and performance analysis. + +## Use Cases + +- **Performance Analysis**: Compare completion times across different models (e.g., impact of expert numbers on MoE training) +- **Parallel Parameter Optimization**: Balance and optimize TP/EP/PP parameters +- **Scale-up Exploration**: Investigate parallel parameter performance across different scale-up domains +- **Scale-out Bandwidth Selection**: Research cost-effective bandwidth configurations + +## Workload Generation + +Generate workloads using [AICB](workload_generation.md): + +```bash +sh ./aicb/scripts/megatron_workload_with_aiob.sh \ + -m 7 --world_size 4096 \ + --tensor_model_parallel_size 2 --pipeline_model_parallel 1 \ + --frame Megatron --global_batch 8192 \ + --micro_batch 1 --seq_length 4096 \ + --swiglu --use_flash_attn --aiob_enable +``` + +This produces a `.txt` workload file containing: +- `model_parallel_NPU_group`: Tensor Parallelism size +- `ep`: Expert model parallelism size +- `pp`: Pipeline model parallelism size +- `vpp`: Virtual Pipeline Parallelism + +> For more details, see [AICB Workload Generation](workload_generation.md) and the [AICB Component Documentation](../components/aicb.md). + +## Busbw Configuration + +SimAI-Analytical uses a `busbw.yaml` file to specify bus bandwidth for different communication groups: + +```yaml +test +TP: + allreduce,: 300 # AllReduce busbw 300GB/s in TP + allgather,: 280 + reducescatter,: 280 + alltoall,: 230 +DP: + allreduce,: null + allgather,: 380 # AllGather busbw 380GB/s in DP + reducescatter,: 380 + alltoall,: null +EP: + allreduce,: null + allgather,: 45 + reducescatter,: 45 + alltoall,: 80 # AlltoAll busbw 80GB/s in EP +``` + +## Running Analytical Simulation + +```bash +./bin/SimAI_analytical \ + -w example/workload_analytical.txt \ + -g 9216 \ + -g_p_s 8 \ + -r test- \ + -busbw example/busbw.yaml +``` + +### Required Parameters + +| Parameter | Long Form | Description | +|:---------:|:----------|:------------| +| `-w` | `--workload` | Path to the workload file | +| `-g` | `--gpus` | Simulation GPU scale | +| `-g_p_s` | `--gpus-per-server` | Scale-up size (GPUs per server) | +| `-r` | `--result` | Output file path and prefix (default: `./results/`) | +| `-busbw` | `--bus-bandwidth` | Path to the busbw file | + +### Optional Parameters + +| Parameter | Long Form | Description | +|:---------:|:----------|:------------| +| `-v` | `--visual` | Generate visualization files | + +### Overlap Ratios + +| Parameter | Long Form | Description | Range | +|:---------:|:----------|:------------|:------| +| `-dp_o` | `--dp-overlap-ratio` | DP overlap ratio | [0.0-1.0] | +| `-ep_o` | `--ep-overlap-ratio` | EP overlap ratio | [0.0-1.0] | +| `-tp_o` | `--tp-overlap-ratio` | TP overlap ratio | [0.0-1.0] | +| `-pp_o` | `--pp-overlap-ratio` | PP overlap ratio | [0.0-1.0] | + +## Result Analysis + +Running SimAI-Analytical generates a CSV output containing: +- Summary row with exposure time, computation time percentages for each communication group, and end-to-end iteration time +- Per-layer operation details + +![Raw Output](../../images/simai_raw.png) + +If you specify `-v`, a visualization file is also generated: + +![Visualization](../../images/simai_visual.png) + +For more on result analysis, see [Result Analysis](result_analysis.md). diff --git a/docs/en/user_guide/simai_physical.md b/docs/en/user_guide/simai_physical.md new file mode 100644 index 00000000..e3481408 --- /dev/null +++ b/docs/en/user_guide/simai_physical.md @@ -0,0 +1,123 @@ +# SimAI-Physical Mode + +> **Status**: Beta — Currently in internal testing phase. + +SimAI-Physical enables physical traffic generation for CPU RDMA cluster environments. This mode generates NCCL-like traffic patterns, allowing in-depth study of NIC behaviors during LLM training. + +--- + +## Overview + +Unlike SimAI-Analytical and SimAI-Simulation which run entirely in software simulation, SimAI-Physical injects real RDMA traffic into a physical network. This enables: + +- Studying actual NIC behavior under realistic LLM training traffic patterns +- Validating network configurations on real hardware +- Benchmarking RDMA performance with representative collective communication workloads + +**Component Combination**: [AICB](../../components/aicb.md) + [SimCCL](../../components/simccl.md) + [astra-sim-alibabacloud](../../components/astra_sim.md) (physical mode) + +--- + +## Prerequisites + +SimAI-Physical uses the RoCEv2 protocol for traffic generation. Before compilation, ensure your environment meets: + +- **RDMA Support**: Working `libibverbs` / RDMA device drivers +- **MPI**: OpenMPI installed and functional +- **Verification**: Successfully run `ib_write_bw` or similar RDMA perftest tools + +--- + +## Compilation + +```bash +# Clone and initialize +git clone https://github.com/aliyun/SimAI.git +cd SimAI/ +git submodule update --init --recursive +git submodule update --remote + +# Install MPI (CentOS/RHEL) +sudo yum install openmpi openmpi-devel + +# Set MPI paths +export MPI_INCLUDE_PATH=/usr/include/openmpi-x86_64/ +export MPI_BIN_PATH=/usr/lib64/openmpi/bin/mpic++ + +# Build SimAI-Physical +./scripts/build.sh -c phy +``` + +--- + +## Workload Generation + +SimAI-Physical uses the same workload format as SimAI-Simulation, generated through [AICB](../../components/aicb.md). See [Workload Generation](workload_generation.md) for details. + +### Example Workload + +``` +HYBRID_TRANSFORMER_FWD_IN_BCKWD model_parallel_NPU_group: 2 ep: 1 pp: 1 vpp: 8 ga: 1 all_gpus: 2 checkpoints: 0 checkpoint_initiates: 0 +10 +mlp_norm -1 1055000 ALLGATHER 1073741824 1055000 NONE 0 1055000 NONE 0 100 +mlp_norm -1 1055000 ALLGATHER 1073741824 1055000 NONE 0 1055000 NONE 0 100 +... +``` + +--- + +## Prepare the Host List + +Prepare an IP list file for the MPI program. The number of IPs should match the number of NICs involved in physical traffic generation (not the number of nodes). + +``` +33.255.199.130 +33.255.199.129 +``` + +--- + +## Running + +### MPI Execution + +```bash +/usr/lib64/openmpi/bin/mpirun -np 2 \ + -host 33.255.199.130,33.255.199.129 \ + --allow-run-as-root \ + -x AS_LOG_LEVEL=0 \ + ./bin/SimAI_phynet ./hostlist -g 2 -w ./example/microAllReduce.txt +``` + +### MPI Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `-np` | Number of processes | Required | +| `-host` | Comma-separated IP list | Required | +| `--allow-run-as-root` | Allow running as root | `FALSE` | + +### SimAI-Physical Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `hostlist` | Path to host IP list file | Required | +| `-w` / `--workload` | Path to workload file | `./microAllReduce.txt` | +| `-i` / `--gid_index` | GID index for RDMA device | `0` | +| `-g` / `--gpus` | Number of GPUs (must match IP count in hostlist) | `8` | + +--- + +## Notes + +- The number of GPUs (`-g`) must be consistent with the number of IPs in the host IP list +- Ensure all nodes have network connectivity and RDMA is properly configured +- SimAI-Physical is currently in beta; some features may change in future releases + +--- + +## See Also + +- [AICB Component](../components/aicb.md) — Workload generation +- [SimCCL Component](../components/simccl.md) — Collective communication transformation +- [astra-sim Component](../components/astra_sim.md) — Simulation engine details diff --git a/docs/en/user_guide/simai_simulation.md b/docs/en/user_guide/simai_simulation.md new file mode 100644 index 00000000..9053d2eb --- /dev/null +++ b/docs/en/user_guide/simai_simulation.md @@ -0,0 +1,113 @@ +# SimAI-Simulation + +SimAI-Simulation provides high-fidelity, full-stack simulation with fine-grained network communication modeling using NS-3 as the network backend. It is designed for detailed research into collective communication algorithms, network protocols, and novel network architectures. + +## Use Cases + +- **Collective Communication Algorithm Research**: Design and optimize traffic patterns for non-switch architectures +- **Network Protocol Research**: Evaluate congestion control, routing mechanisms, and low-level protocols +- **Novel Network Architecture Design**: Explore innovative network topologies and configurations + +## Workload Generation + +Use the same workload as SimAI-Analytical, generated by [AICB](workload_generation.md). + +## Network Topology Configuration + +Before running SimAI-Simulation, you need to generate a topology file recognized by ns-3-alibabacloud. + +### Topology Templates + +SimAI provides 5 templates for common architectures: + +| Template | Description | Default GPUs | +|----------|-------------|-------------| +| `Spectrum-X` | Rail-optimized, single ToR, single plane | 4096 | +| `AlibabaHPN` (Single Plane) | Rail-optimized, dual ToR, single plane | 15360 | +| `AlibabaHPN` (Dual Plane) | Rail-optimized, dual ToR, dual plane | 15360 | +| `DCN+` (Single ToR) | Non rail-optimized, single ToR | 512 | +| `DCN+` (Dual ToR) | Non rail-optimized, dual ToR | 512 | + +![Spectrum-X](../../images/Spectrum-X.jpg) + +### Generating Topology + +```bash +# Spectrum-X with 8 GPUs +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 8 -psn 1 + +# Dual-Plane AlibabaHPN with 64 GPUs +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo AlibabaHPN --dp -g 64 -asn 16 -psn 16 + +# Dual-ToR DCN+ with 128 GPUs +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo DCN+ --dt -g 128 -asn 2 -psn 8 + +# Custom rail-optimized topology +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -g 32 -bw 200Gbps -gt A100 -psn 8 --ro +``` + +### Topology Parameters + +| Level | Parameter | Description | +|-------|-----------|-------------| +| Whole Structure | `-topo` | Template name | +| | `-g` | Number of GPUs | +| | `--dp` | Enable dual plane | +| | `--ro` | Enable rail-optimized | +| | `--dt` | Enable dual NICs and dual ToRs | +| | `-er` | Error rate | +| Intra-Host | `-gps` | GPUs per server | +| | `-gt` | GPU type | +| | `-nvbw` | NVLink bandwidth | +| | `-nl` | NVLink latency | +| | `-l` | NIC latency | +| Intra-Segment | `-bw` | NIC to ASW bandwidth | +| | `-asw` | ASW switch count | +| | `-nps` | NICs per switch | +| Intra-Pod | `-psn` | PSW switch count | +| | `-apbw` | ASW to PSW bandwidth | +| | `-app` | ASW per PSW | + +> For detailed topology parameters and default values per template, see the [astra-sim Component Documentation](../components/astra_sim.md). + +## Running NS-3 Simulation + +```bash +AS_SEND_LAT=3 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator \ + -t 16 \ + -w ./example/microAllReduce.txt \ + -n ./Spectrum-X_8g_8gps_400Gbps_H100 \ + -c astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +### Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `AS_LOG_LEVEL` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` | +| `AS_PXN_ENABLE` | Enable PXN (`0`/`1`) | `0` | +| `AS_NVLS_ENABLE` | Enable NVLS (`0`/`1`) | `0` | +| `AS_SEND_LAT` | Packet sending latency (us) | `6` | +| `AS_NVLSTREE_ENABLE` | Enable NVLSTREE | `false` | + +### Simulation Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `-t` / `--thread` | Number of threads (recommended 8-16) | `1` | +| `-w` / `--workload` | Path to workload file | `./microAllReduce.txt` | +| `-n` / `--network-topo` | Network topology path | None | +| `-c` / `--config` | SimAI configuration file | None | + +## Example: RING vs NVLS Comparison + +See the [Tutorial](../../docs/Tutorial.md#ring-vs-nvls) for a complete comparison of RING and NVLS algorithms across different message sizes. + +## What's Next + +- [NS-3 Component Documentation](../components/ns3.md) — Detailed NS-3 module reference +- [Result Analysis](result_analysis.md) — Analyze simulation output diff --git a/docs/en/user_guide/supported_models.md b/docs/en/user_guide/supported_models.md new file mode 100644 index 00000000..06ebcf59 --- /dev/null +++ b/docs/en/user_guide/supported_models.md @@ -0,0 +1,141 @@ +# Supported Models + +SimAI supports a range of LLM models for both training and inference simulation. + +--- + +## Inference Models (SimAI 1.5+) + +These models are supported for multi-request inference simulation via vidur-alibabacloud, with GPU memory calculation, PD disaggregation, and workload generation support. + +### DeepSeek-V3-671B + +| Attribute | Value | +|-----------|-------| +| **Total Layers** | 61 | +| **Attention Type** | MLA (Multi-head Latent Attention) | +| **Attention Heads** | 128 | +| **Hidden Size** | 7168 | +| **KV LoRA Rank** | 512 | +| **Q LoRA Rank** | 1536 | +| **QK RoPE Head Dim** | 64 | +| **QK NoPE Head Dim** | 128 | +| **V Head Dim** | 128 | +| **MoE Routed Experts** | 256 | +| **Experts Per Token** | 8 | +| **Shared Experts** | 1 | +| **Dense Layers** | First 3 layers (fixed activation of 8 routed + 1 shared expert) | +| **Sparse Layers** | Layers 3-60 (dynamically select 8 from 256 routed + 1 shared expert) | +| **Config File** | `vidur-alibabacloud/data/hf_configs/deepseek_v3_config.json` | + +### Qwen3-MoE-235B + +| Attribute | Value | +|-----------|-------| +| **Total Layers** | 94 | +| **Attention Type** | MHA / GQA | +| **Attention Heads** | 64 | +| **KV Heads** | 4 | +| **Hidden Size** | 4096 | +| **Head Dim** | 128 | +| **MoE Routed Experts** | 128 | +| **Experts Per Token** | 8 | +| **MoE Intermediate Size** | 1536 | +| **Config File** | `vidur-alibabacloud/data/hf_configs/qwen3_moe_config.json` | + +### Qwen3-Next-80B + +| Attribute | Value | +|-----------|-------| +| **Total Layers** | 48 | +| **Attention Type** | Hybrid (full + linear attention, alternating every 4 layers) | +| **Full Attention Heads** | 16 | +| **KV Heads** | 2 | +| **Hidden Size** | 2048 | +| **Head Dim** | 256 | +| **Linear Attention Key Heads** | 16 | +| **Linear Attention Value Heads** | 32 | +| **MoE Routed Experts** | 512 | +| **Experts Per Token** | 10 | +| **MoE Intermediate Size** | 512 | +| **Config File** | `vidur-alibabacloud/data/hf_configs/qwen3-next-80B-A3B_config.json` | + +### Legacy Inference Models (via Vidur Backend) + +These models are supported using the original Vidur profiling-based backend: + +| Model | TP Support | PP Support | +|-------|-----------|-----------| +| meta-llama/Meta-Llama-3-8B | Yes | Yes | +| meta-llama/Meta-Llama-3-70B | Yes | Yes | +| meta-llama/Llama-2-7b-hf | Yes | Yes | +| meta-llama/Llama-2-70b-hf | Yes | Yes | +| codellama/CodeLlama-34b-Instruct-hf | Yes | Yes | +| internlm/internlm-20b | Yes | Yes | +| Qwen/Qwen-72B | Yes | Yes | + +--- + +## Training Models (AICB) + +The following models are supported for training workload generation: + +### AICB Benchmark Suite + +| ID | Model | Seq Length | Framework | TP | PP | SP | MoE | +|----|-------|-----------|-----------|----|----|-----|-----| +| 1 | LLaMA-7B | 2048 | Megatron | 1 | 1 | - | - | +| 2 | GPT-13B | 2048 | Megatron | 2 | 1 | Yes | - | +| 3 | GPT-22B | 2048 | Megatron | 4 | 1 | - | - | +| 4 | LLaMA-65B | 4096 | Megatron | 8 | 2 | Yes | - | +| 5 | GPT-175B | 2048 | Megatron | 8 | 8 | Yes | - | +| 6 | GPT-175B | 2048 | Megatron | 8 | 8 | - | - | +| 7 | Llama3-405B | 8192 | Megatron | 8 | 16 | Yes | - | +| 8 | LLaMA-7B | 4096 | DeepSpeed | 1 | 1 | - | Zero-2 | +| 9 | LLaMA-65B | 4096 | DeepSpeed | 1 | 1 | - | Zero-3 | +| 10 | Mistral-8x7B | 2048 | Megatron | 2 | 1 | Yes | 8 experts | + +### Training Framework Support + +| Framework | Models | AIOB Support | +|-----------|--------|-------------| +| **Megatron** | GPT, LLaMA, MoE | Yes | +| **DeepSpeed** | LLaMA (Zero Stage 1/2/3) | No (fixed times) | +| **DeepSeek** | DeepSeek (16B/236B/671B) | Yes | + +--- + +## Attention Architecture Comparison + +| Architecture | Model | KV Cache Strategy | Memory Efficiency | +|-------------|-------|-------------------|-------------------| +| **MLA** | DeepSeek-V3-671B | Compressed latent vector (`kv_lora_rank` + `qk_rope_head_dim`) | ~57x reduction vs MHA | +| **MHA / GQA** | Qwen3-MoE-235B | Standard KV cache (`num_kv_heads * head_dim`) | Standard | +| **Hybrid Full + Linear** | Qwen3-Next-80B | Full attention layers + linear (GDN) attention alternating every 4 layers | Reduced (linear layers have no KV cache) | + +--- + +## Hardware Requirements + +### Inference Profiling (AICB Backend) + +| Requirement | Details | +|-------------|---------| +| **GPU Architecture** | NVIDIA Hopper (SM90) or Blackwell (SM100) | +| **Reason** | Dependency on DeepGEMM, FlashMLA, FlashInfer | +| **Hopper Note** | Add `ENV FLASH_MLA_DISABLE_SM100=1` to Dockerfile | + +### Training Simulation + +- **SimAI-Analytical**: Any CPU (no GPU required) +- **SimAI-Simulation**: Any CPU (no GPU required) +- **AICB Physical Execution**: Requires GPU cluster with NCCL support + +--- + +## See Also + +- [Inference Simulation](inference_simulation.md) — Multi-request inference guide +- [Workload Generation](workload_generation.md) — AICB workload generation +- [GPU Memory Module](../technical_reference/memory_module.md) — Memory calculation details +- [vidur-alibabacloud](../components/vidur.md) — Inference scheduling component diff --git a/docs/en/user_guide/workload_generation.md b/docs/en/user_guide/workload_generation.md new file mode 100644 index 00000000..e5859b5e --- /dev/null +++ b/docs/en/user_guide/workload_generation.md @@ -0,0 +1,160 @@ +# Workload Generation + +AICB (AI Communication Benchmark) provides workload generation capabilities for both training and inference simulation in SimAI. + +--- + +## Overview + +AICB generates workload description files (`.txt`) that describe the communication and computation patterns of LLM training/inference processes. These workloads are consumed by SimAI's simulation engine. + +Two types of workload generation are supported: + +| Type | Description | Models Supported | +|------|-------------|------------------| +| **Training** | Generates training communication/computation patterns | GPT (7B/13B/22B/175B), LLaMA (7B/65B/405B), DeepSeek (16B/236B/671B), MoE | +| **Inference** | Generates prefill/decode phase workloads | DeepSeek-V3-671B, Qwen3-MoE-235B, Qwen3-Next-80B | + +--- + +## Training Workload Generation + +### Quick Start with Pre-configured Models + +```bash +# Generate workload for Megatron GPT-7B +sh ./scripts/megatron_workload_with_aiob.sh -m 7 \ + --world_size 4096 --tensor_model_parallel_size 4 --pipeline_model_parallel 1 \ + --frame Megatron --global_batch 8192 \ + --micro_batch 1 --seq_length 4096 --swiglu \ + --use_flash_attn --aiob_enable \ + --comp_filepath workload/aiob_inputs/Example.txt +``` + +Available pre-configured model sizes: `7`, `13`, `22`, `175` (GPT/LLaMA), `moe`, `deepseek` (16/236/671). + +### Generating for Different Frameworks + +#### Megatron + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --model_name GPT-13B --frame=Megatron \ + --world_size=16 --tensor_model_parallel_size=2 --pipeline_model_parallel=1 \ + --global_batch=16 --micro_batch=1 --num_layers=40 --seq_length=2048 \ + --hidden_size=5120 --epoch_num=1 --num_attention_heads=40 \ + --aiob_enable --use_flash_attn --swiglu +``` + +#### MoE + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --model_name MoE --frame=Megatron \ + --world_size=32 --tensor_model_parallel_size=4 --pipeline_model_parallel=1 \ + --expert_model_parallel_size=2 --moe_enable --num_experts=8 --moe_router_topk=2 \ + --global_batch=32 --micro_batch=1 --seq_length=2048 \ + --aiob_enable --swiglu --use_flash_attn +``` + +#### DeepSeek + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --frame=DeepSeek \ + --world_size=32 --tensor_model_parallel_size=4 \ + --expert_model_parallel_size=2 --moe_enable --num_experts=4 --moe_router_topk=2 \ + --global_batch=16 --micro_batch=1 --seq_length=4096 \ + --aiob_enable --swiglu -m deepseek +``` + +#### DeepSpeed + +```bash +python -m workload_generator.generate_deepspeed_stage3_workload \ + --world_size=64 --global_batch=64 \ + --num_layers=40 --hidden_size=5120 --seq_length=4096 \ + --zero_stage=3 --reduce_bucket_size=1000000000 +``` + +### Output + +Generated workload files are saved in: +- Training: `results/mocked_workload/` or `results/workload/` + +--- + +## Inference Workload Generation + +SimAI uses AICB to generate inference workloads with prefill/decode phase separation. + +> **Note**: Inference compute profiling requires NVIDIA Hopper (SM90) or Blackwell (SM100) GPUs due to dependencies on [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) and [FlashMLA](https://github.com/deepseek-ai/FlashMLA). + +### Supported Inference Models + +| Model | Attention | MoE Experts | Experts/Token | +|-------|-----------|-------------|---------------| +| DeepSeek-V3-671B | MLA | 256 routed + 1 shared | 8 | +| Qwen3-MoE-235B | MHA/GQA | 128 routed | 8 | +| Qwen3-Next-80B | Hybrid (full + linear) | 512 routed | 10 | + +Inference workloads are automatically generated and consumed by the vidur-alibabacloud scheduling framework. See [Inference Simulation](inference_simulation.md) for end-to-end usage. + +--- + +## AIOB: Computation Time Embedding + +AIOB (AI Operation Benchmark) is a sub-module within AICB that profiles actual GPU computation times and embeds them into workloads. + +### Usage Options + +| Option | Description | +|--------|-------------| +| `--aiob_enable` | Enable AIOB to profile computation times on the current GPU | +| `--comp_filepath ` | Use a pre-existing computation time description file | +| Neither | Use fixed default computation times | + +### Example: Profile and Embed + +```bash +sh scripts/megatron_gpt.sh \ + -m 7 --world_size 8 --tensor_model_parallel_size 2 \ + --frame Megatron --global_batch 16 --micro_batch 1 \ + --seq_length 2048 --swiglu --use_flash_attn --aiob_enable +``` + +Computation description files are saved in `results/aiob_outputs/`. + +--- + +## Key Parameters + +| Category | Parameter | Description | +|----------|-----------|-------------| +| **Framework** | `--frame` | Megatron / DeepSpeed / DeepSeek | +| **Model** | `--model_size` or `-m` | Pre-configured model size | +| **Training** | `--world_size` | Total number of GPUs | +| | `--global_batch` | Total batch size | +| | `--micro_batch` | Micro-batch size | +| | `--seq_length` | Sequence length | +| | `--epoch_num` | Number of iterations | +| **Parallelism** | `--tensor_model_parallel_size` | TP degree | +| | `--pipeline_model_parallel` | PP degree | +| | `--expert_model_parallel_size` | EP degree | +| **MoE** | `--moe_enable` | Enable MoE | +| | `--num_experts` | Number of experts | +| | `--moe_router_topk` | Experts per token | +| **Optimization** | `--use_flash_attn` | Use FlashAttention | +| | `--swiglu` | Use SwiGLU activation | +| | `--aiob_enable` | Enable AIOB computation profiling | +| | `--comp_filepath` | Path to computation time file | + +For the full parameter list, see the [AICB component documentation](../components/aicb.md) or the [CLI Reference](../technical_reference/cli_reference.md). + +--- + +## See Also + +- [AICB Component](../components/aicb.md) — Complete AICB documentation +- [Inference Simulation](inference_simulation.md) — End-to-end inference simulation guide +- [Supported Models](supported_models.md) — Full model compatibility list diff --git a/docs/images/simai_dingtalk.jpg b/docs/images/simai_dingtalk.jpg index ee2d04164d7d7db12ff59a870f65c763f3987767..556d4f2b0c80629487c8d39b007d51da36b7f6ef 100644 GIT binary patch literal 305265 zcmb^Yc|4TgA3uzrSr~-LmL-g>kYq1Q3@K~bT9g*q$rh5`SSlr1B9(+f+N82pnCwa+ zL{ZiXAv0kN#?0>wZST+h{p0()ANQr1>ow;(*E#34KhF~517i@ZH8V0b0tf^E$?y*_ zhQO&^!5*#v?AZf00RY$l8X*E$AO))cJ;eGyv=KrMpjOI}0K|C!^shP=@XowoYb)=p z-jO-T-!;%OIjFxhvnpc>Xj-}Zp7ITF_dO}0wnZ6e?l9ehX0`~g6?(%8xwcCz;bRhb ziXM+*zcxwT5y=?FwwoFn+FRLJ8kz3iwZaJYrNhaSUdXioc>A34w=v!!aqy6x1ZE5% z!8+KA7T|Vp3OH$CWwo2x=I{GT`+vSD-78}Uor=u1{uKY;5j@T=0Zx#4D_GspIl##q z(j@?(Go4QQp8|lDSuP!P>LinfAHeSq2MFo&OxkUg&ScV#tMucQI{R!4VV!!Y5>5vP ze>VWQ+hMuHX(u<>1~&=P%0A8>J^)}PAg$-^?duHb*}kUZKkc~vLpwM) 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

;wN182MrJFv!KWd%|f{ccioaXeD>`F)QZbES2` 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

vZ|D!wHDqH?hijVLx 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

0ec*sB59TNQJ(4@X`7sH-o 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 diff --git a/docs/images/simai_wechat.jpeg b/docs/images/simai_wechat.jpeg index e70c9f02b2a4d0772051b571c3276cc433656ae5..cd75e4a0bc32347445fb0e541719c60fe726d1a6 100644 GIT binary patch literal 268153 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 +- TianHao Fu (Peking University) and [TELOS-syslab](https://github.com/TELOS-syslab/) +- Parth Parikh (KEYSIGHT) +- Sarah-Michelle Hammer & Ziyi Wang (TU-Berlin) +- Xinyue Li (BUPT) +- Tong Chen (Zhejiang University) +- Ming Wang (BUPT) +- Tao Jiang (Institute of Computing Technology, Chinese Academy of Sciences) + +以及其他个人贡献者——详见 [SimAI 贡献者列表](https://github.com/aliyun/SimAI/graphs/contributors)。 + +特别感谢 Chenning Li（MIT CSAIL）发起将 SimAI 集成到 [M4](https://github.com/netiken/m4) 的合作。 + +--- + +## 参与贡献 + +我们热烈欢迎社区贡献！详见 [贡献指南](../developer_guide/contributing.md)。 diff --git a/docs/zh/components/aicb.md b/docs/zh/components/aicb.md new file mode 100644 index 00000000..b0842a18 --- /dev/null +++ b/docs/zh/components/aicb.md @@ -0,0 +1,212 @@ +# AICB — AI 通信基准测试 + +**仓库**: [aliyun/aicb](https://github.com/aliyun/aicb) | **语言**: Python + +AICB 是面向 AI 场景的专用通信基准测试套件。它能生成与真实 LLM 训练和推理流程对齐的通信工作负载。 + +--- + +## 简介 + +AICB（Artificial Intelligence Communication Benchmark）生成与真实应用精准对齐的通信工作负载模式，支持： + +- 基准测试和调优 GPU 集群通信系统 +- 研究特定模型配置的通信模式 +- 为 SimAI 等仿真器生成工作负载 + +--- + +## 基准测试套件 + +AICB 提供 10 个预配置的基准测试案例，覆盖典型 LLM 配置： + +| 编号 | 模型 | 序列长度 | 框架 | TP | PP | SP | MoE | +|----|-------|-----------|-----------|----|----|-----|-----| +| 1 | LLaMA-7B | 2048 | Megatron | 1 | 1 | - | - | +| 2 | GPT-13B | 2048 | Megatron | 2 | 1 | 是 | - | +| 3 | GPT-22B | 2048 | Megatron | 4 | 1 | - | - | +| 4 | LLaMA-65B | 4096 | Megatron | 8 | 2 | 是 | - | +| 5 | GPT-175B | 2048 | Megatron | 8 | 8 | 是 | - | +| 6 | GPT-175B | 2048 | Megatron | 8 | 8 | - | - | +| 7 | Llama3-405B | 8192 | Megatron | 8 | 16 | 是 | - | +| 8 | LLaMA-7B | 4096 | DeepSpeed | 1 | 1 | - | Zero-2 | +| 9 | LLaMA-65B | 4096 | DeepSpeed | 1 | 1 | - | Zero-3 | +| 10 | Mistral-8x7B | 2048 | Megatron | 2 | 1 | 是 | 8 experts | + +--- + +## 环境搭建 + +### Docker + +```bash +docker build -t aicb:v0.0.1 . +docker run --gpus all --net host --shm-size 16g -it --rm aicb:v0.0.1 +``` + +### 本地环境 + +要求：Python >= 3.8、CUDA >= 11.8、PyTorch >= 2.0.0、NVIDIA APEX + +### NGC 容器 + +```bash +docker pull nvcr.io/nvidia/pytorch:xx.xx-py3 +docker run --gpus all -it --rm -v /path/to/aicb:/workspace/aicb nvcr.io/nvidia/pytorch:xx.xx-py3 +``` + +> **注意**：推理工作负载 Profiling 需要 NVIDIA Hopper (SM90) 或 Blackwell (SM100) GPU。 + +--- + +## 物理集群执行 + +### 环境变量 + +| 参数 | 说明 | +|-----------|-------------| +| `nnodes` | 节点数量 | +| `node_rank` | 当前节点编号 | +| `nproc_per_node` | 每节点 GPU 数 | +| `master_addr` | 主节点地址 | +| `master_port` | 主节点端口 | + +### 运行 Megatron 工作负载 + +```bash +sh scripts/megatron_gpt.sh \ + --nnodes 1 --node_rank 0 --nproc_per_node 8 \ + --master_addr localhost --master_port 29500 \ + -m 7 --world_size 8 --tensor_model_parallel_size 2 --pipeline_model_parallel 1 \ + --frame Megatron --global_batch 16 --micro_batch 1 \ + --seq_length 2048 --swiglu --use_flash_attn --aiob_enable +``` + +### 运行 MoE 工作负载 + +```bash +sh scripts/megatron_gpt.sh \ + -m moe --world_size 8 --tensor_model_parallel_size 4 \ + --moe_enable --expert_model_parallel_size 1 \ + --num_experts 4 --moe_router_topk 2 \ + --frame Megatron --global_batch 16 --micro_batch 1 \ + --sp --grouped_gemm --aiob_enable --swiglu --use_flash_attn +``` + +### 运行 DeepSeek 工作负载 + +```bash +sh scripts/megatron_gpt.sh \ + --frame DeepSeek -m deepseek \ + --tensor_model_parallel_size 4 --moe_enable \ + --expert_model_parallel_size 1 --num_experts 4 \ + --global_batch 4 --micro_batch 1 --world_size 4 \ + --num_layers 10 --sp --swiglu --aiob_enable +``` + +--- + +## 训练工作负载生成 + +为 SimAI 仿真生成工作负载文件： + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --model_name GPT-13B --frame=Megatron \ + --world_size=16 --tensor_model_parallel_size=2 --pipeline_model_parallel=1 \ + --global_batch=16 --micro_batch=1 --num_layers=40 --seq_length=2048 \ + --hidden_size=5120 --epoch_num=1 --num_attention_heads=40 \ + --aiob_enable --use_flash_attn --swiglu +``` + +输出保存在 `results/mocked_workload/`。 + +--- + +## 推理工作负载生成 + +AICB 为以下模型生成带 Prefill/Decode 阶段分离的推理工作负载： + +| 模型 | 注意力架构 | MoE 专家数 | +|-------|-----------|-------------| +| DeepSeek-V3-671B | MLA | 256 路由 + 1 共享 | +| Qwen3-MoE-235B | MHA/GQA | 128 路由 | +| Qwen3-Next-80B | 混合（全注意力 + 线性注意力） | 512 路由 | + +需要硬件加速库：[DeepGEMM](https://github.com/deepseek-ai/DeepGEMM)、[FlashMLA](https://github.com/deepseek-ai/FlashMLA)、[FlashInfer](https://github.com/flashinfer-ai/flashinfer)。 + +--- + +## AIOB：计算性能分析 + +AIOB 可采集实际 GPU 计算耗时并嵌入工作负载： + +- `--aiob_enable` — 在当前 GPU 上进行 Profiling +- `--comp_filepath ` — 使用已有 Profiling 数据 + +输出保存在 `results/aiob_outputs/`。 + +--- + +## 自定义模型开发 + +AICB 支持使用 `MockedParam` 和 `MockedModel` 基类为自定义模型架构创建工作负载。 + +训练过程被抽象为：`init → forward → backward → step` + +每条工作负载项包含： +1. **通信信息**：`comm_type`、`comm_group`、`comm_group_size`、`msg_size` +2. **附加信息**：源节点（broadcast 场景）、计算耗时 +3. **运行时信息**：`elapsed_time`、`algo_bw`、`bus_bw` + +可参考现有 `MockedMegatron` 和 `MockedDeepSpeed` 实现。 + +--- + +## 关键参数 + +| 类别 | 参数 | 说明 | +|----------|-----------|-------------| +| 框架 | `frame` | Megatron / DeepSpeed / DeepSeek | +| 模型 | `model_size` | 预配置大小（7/13/22/175/moe/deepseek） | +| 训练 | `world_size` | 总 GPU 数量 | +| | `global_batch` | 总批量大小 | +| | `micro_batch` | 微批量大小 | +| | `seq_length` | 序列长度 | +| 并行策略 | `tensor_model_parallel_size` | TP 度 | +| | `pipeline_model_parallel` | PP 度 | +| | `expert_model_parallel_size` | EP 度 | +| MoE | `moe_enable` | 启用 MoE | +| | `num_experts` | 专家数量 | +| | `moe_router_topk` | 每 Token 专家数 | +| DeepSeek | `qk_rope_dim` | QK 的 RoPE 维度 | +| | `kv_lora_rank` | KV 压缩 LoRA 维度 | +| | `q_lora_rank` | Q 压缩 LoRA 维度 | +| | `n_shared_expert` | 共享专家数 | +| 优化 | `use_flash_attn` | FlashAttention | +| | `swiglu` | SwiGLU 激活函数 | +| | `aiob_enable` | AIOB 计算 Profiling | +| | `comp_filepath` | 预有计算文件 | + +--- + +## 结果输出 + +### 物理执行 + +- 每次通信日志：类型、分组、消息大小、执行时间、吞吐量 +- 每次迭代耗时分析 +- CSV 输出在 `results/comm_logs/` + +### 工作负载文件 + +- 训练工作负载：`results/mocked_workload/` 或 `results/workload/` +- AIOB Profiling：`results/aiob_outputs/` + +--- + +## 相关文档 + +- [工作负载生成指南](../user_guide/workload_generation.md) — 用户指南中的工作负载生成 +- [支持的模型](../user_guide/supported_models.md) — 完整模型列表 +- [Tutorial](https://github.com/aliyun/aicb/blob/master/training/tutorial.md) — AICB 详细教程 diff --git a/docs/zh/components/astra_sim.md b/docs/zh/components/astra_sim.md new file mode 100644 index 00000000..52541430 --- /dev/null +++ b/docs/zh/components/astra_sim.md @@ -0,0 +1,147 @@ +# astra-sim-alibabacloud — 仿真引擎 + +**位置**: 项目内（`astra-sim-alibabacloud/`） | **语言**: C++ + +SimAI 的核心仿真引擎，扩展自 [astra-sim 1.0](https://github.com/astra-sim/astra-sim/tree/ASTRA-sim-1.0)。支持三种运行模式，并集成了 NCCL 算法与自定义增强。 + +--- + +## 概述 + +astra-sim-alibabacloud 是 SimAI 仿真的中央调度器： + +- 接收 AICB 生成的工作负载 +- 使用 SimCCL 将集合操作分解为 P2P 传输 +- 通过 NS-3（仿真模式）或直接 RDMA（物理模式）驱动网络仿真 +- 使用 busbw 参数进行时间计算（分析模式） + +--- + +## 三种运行模式 + +### SimAI-Analytical + +使用总线带宽（busbw）进行快速分析仿真，估算集合通信耗时。 + +**编译**: `./scripts/build.sh -c analytical` +**二进制**: `bin/SimAI_analytical` + +### SimAI-Simulation + +使用 NS-3 网络后端的全栈仿真，实现细粒度网络建模。 + +**编译**: `./scripts/build.sh -c ns3` +**二进制**: `bin/SimAI_simulator` + +### SimAI-Physical + +在真实硬件上使用 RDMA 生成物理流量。 + +**编译**: `./scripts/build.sh -c phy` +**二进制**: `bin/SimAI_phynet` + +--- + +## 核心组件 + +| 组件 | 说明 | +|-----------|-------------| +| **AstraComputeAPI** | 管理计算时序和调度 | +| **MemoryAPI** | 处理内存分配和追踪 | +| **NetworkAPI** | 网络后端接口（NS-3、物理网络） | +| **MockNcclGroup** | 模拟 NCCL 通信组 | +| **MockNcclChannel** | 管理单个通信通道 | +| **SimAiFlowModelRdma** | RDMA 流量模型 | + +--- + +## 配置 + +### SimAI.conf + +主配置文件位于 `astra-sim-alibabacloud/inputs/config/SimAI.conf`，控制以下仿真参数： + +- 通信算法 +- 缓冲区大小 +- 时序参数 +- 网络后端设置 + +### 环境变量（仿真模式） + +| 变量 | 说明 | 默认值 | +|----------|-------------|---------| +| `AS_LOG_LEVEL` | 日志级别：DEBUG、INFO、WARNING、ERROR | `INFO` | +| `AS_PXN_ENABLE` | 启用 PXN（Proxied NVLINK） | `0`（禁用） | +| `AS_NVLS_ENABLE` | 启用 NVLS（NVLink Sharp） | `0`（禁用） | +| `AS_SEND_LAT` | 包发送延迟（us） | `6` | +| `AS_NVLSTREE_ENABLE` | 启用 NVLS Tree 算法 | `false` | + +### 仿真参数 + +| 参数 | 说明 | 默认值 | +|-----------|-------------|---------| +| `-t` / `--thread` | 加速线程数 | `1`（建议 8-16） | +| `-w` / `--workload` | 工作负载文件路径 | 必需 | +| `-n` / `--network-topo` | 网络拓扑文件路径 | 必需（仿真模式） | +| `-c` / `--config` | SimAI 配置文件 | 必需 | + +--- + +## 拓扑生成 + +astra-sim 通过 `gen_Topo_Template.py` 提供 5 种拓扑模板： + +### 可用模板 + +| 模板 | 架构 | 说明 | +|----------|-------------|-------------| +| `Spectrum-X` | NVIDIA Spectrum-X | Rail-optimized，单 ToR，单 Plane | +| `AlibabaHPN`（单 Plane） | Alibaba HPN 7.0 | 双 ToR，Rail-optimized，单 Plane | +| `AlibabaHPN`（双 Plane） | Alibaba HPN 7.0 | 双 ToR，Rail-optimized，双 Plane | +| `DCN+`（单 ToR） | DCN+ | 单 ToR，非 Rail-optimized | +| `DCN+`（双 ToR） | DCN+ | 双 ToR，非 Rail-optimized | + +### 拓扑参数 + +| 层级 | 参数 | 说明 | +|-------|-----------|-------------| +| **全局** | `-topo` | 模板名称 | +| | `-g` | GPU 数量 | +| | `--dp` | 启用双 Plane | +| | `--ro` | 启用 Rail-optimized | +| | `--dt` | 启用双 ToR | +| **服务器内** | `-gps` | 每服务器 GPU 数 | +| | `-gt` | GPU 型号（A100/H100） | +| | `-nvbw` | NVLink 带宽 | +| | `-nl` | NVLink 延迟 | +| **Segment 内** | `-bw` | NIC 到 ASW 带宽 | +| | `-asw` | ASW 交换机数量 | +| | `-nps` | 每交换机 NIC 数 | +| **Pod 内** | `-psn` | PSW 交换机数量 | +| | `-apbw` | ASW 到 PSW 带宽 | + +### 示例 + +```bash +# Spectrum-X 128 GPU +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +# 双 Plane AlibabaHPN 64 GPU +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo AlibabaHPN --dp -g 64 -asn 16 -psn 16 + +# 双 ToR DCN+ 128 GPU +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo DCN+ --dt -g 128 -asn 2 -psn 8 +``` + +--- + +## 相关文档 + +- [SimAI-Analytical 使用指南](../user_guide/simai_analytical.md) — 分析模式使用 +- [SimAI-Simulation 使用指南](../user_guide/simai_simulation.md) — NS-3 仿真使用 +- [SimAI-Physical 使用指南](../user_guide/simai_physical.md) — 物理模式使用 +- [NS-3 组件](ns3.md) — 网络后端详情 +- [SimCCL 组件](simccl.md) — 集合通信分解 diff --git a/docs/zh/components/index.md b/docs/zh/components/index.md new file mode 100644 index 00000000..7635e442 --- /dev/null +++ b/docs/zh/components/index.md @@ -0,0 +1,80 @@ +# 组件概述 + +SimAI 是一个模块化项目，由 5 个核心组件组成。各组件可独立使用，也可组合使用以实现不同的仿真场景。 + +--- + +## 架构 + +``` + |--- AICB （工作负载生成 & 计算性能分析） +SimAI --|--- SimCCL （集合通信算法分析） + |--- astra-sim-alibabacloud （仿真引擎：Analytical / Simulation / Physical） + |--- ns-3-alibabacloud （NS-3 网络后端） + |--- vidur-alibabacloud （多请求推理调度 & 显存管理） +``` + +--- + +## 组件摘要 + +| 组件 | 语言 | 仓库 | 说明 | +|------|------|------|------| +| [AICB](aicb.md) | Python | [aliyun/aicb](https://github.com/aliyun/aicb) | AI 通信基准测试——训练和推理工作负载生成 | +| [SimCCL](simccl.md) | Python | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | 集合通信到点对点通信转换 | +| [astra-sim-alibabacloud](astra_sim.md) | C++ | In-tree | 支持 3 种模式的核心仿真引擎 | +| [ns-3-alibabacloud](ns3.md) | C++ | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | 带 RDMA/数据中心扩展的 NS-3 网络仿真后端 | +| [vidur-alibabacloud](vidur.md) | Python | In-tree | 支持 PD 分离和请求调度的 LLM 推理仿真 | + +--- + +## 场景与组件组合 + +| 场景 | AICB | SimCCL | astra-sim | ns-3 | vidur | +|------|------|--------|-----------|------|-------| +| AICB 测试套件（物理 GPU） | 必需 | - | - | - | - | +| 工作负载生成 | 必需 | - | - | - | - | +| 集合通信分析 | - | 必需 | - | - | - | +| SimAI-Analytical | 必需 | - | 必需（analytical） | - | - | +| SimAI-Simulation | 必需 | 必需 | 必需（simulation） | 必需 | - | +| SimAI-Physical | 必需 | 必需 | 必需（physical） | - | - | +| 推理仿真 | 必需 | 必需 | 必需 | 可选 | 必需 | + +--- + +## 数据流 + +``` +AICB（工作负载生成） + | + |-- 训练工作负载 (.txt) --> astra-sim-alibabacloud + |-- 推理工作负载 -------> vidur-alibabacloud + | +SimCCL（集合 → P2P） + | + |--> astra-sim-alibabacloud（Simulation/Physical 模式） + | +astra-sim-alibabacloud（仿真引擎） + | + |-- Analytical 模式：busbw 估算 + |-- Simulation 模式：NS-3 后端 + |-- Physical 模式：RDMA 流量注入 + | +ns-3-alibabacloud（网络后端） + | + |--> 细粒度网络仿真结果 + | +vidur-alibabacloud（推理调度） + | + |--> request_metrics.csv, chrome_trace.json, plots/ +``` + +--- + +## 组件详细文档 + +- **[AICB](aicb.md)** — 工作负载生成、基准测试套件、AIOB 计算分析 +- **[SimCCL](simccl.md)** — 集合通信分解 +- **[astra-sim-alibabacloud](astra_sim.md)** — 核心仿真引擎、配置、拓扑生成 +- **[ns-3-alibabacloud](ns3.md)** — RDMA 网络仿真、CC 算法、分析工具 +- **[vidur-alibabacloud](vidur.md)** — 推理仿真、PD 分离、GPU 显存管理 diff --git a/docs/zh/components/ns3.md b/docs/zh/components/ns3.md new file mode 100644 index 00000000..d682f568 --- /dev/null +++ b/docs/zh/components/ns3.md @@ -0,0 +1,175 @@ +# ns-3-alibabacloud — 网络仿真后端 + +**仓库**: [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | **语言**: C++ + +基于 NS-3 的网络仿真器，作为 SimAI 的网络后端，扩展了面向数据中心/RDMA 的端到端建模能力。 + +--- + +## 概述 + +相比上游 [NS-3](https://www.nsnam.org/)，ns-3-alibabacloud 在点对点模块上扩展了全面的数据中心网络特性： + +- **QBB/PFC + 多优先级队列** — 8 个优先级队列，支持 PAUSE/RESUME 处理 +- **ECN + CNP 反馈** — 交换机侧 ECN 标记和接收端拥塞通知 +- **RDMA 主机协议栈（QP 级别）** — 完整 QP 建模，支持 5 种拥塞控制算法 +- **交换机和 NVSwitch 建模** — ECMP 转发、缓冲区管理、PFC 逻辑 + +### dev/qp 分支 + +[dev/qp](https://github.com/aliyun/ns-3-alibabacloud/tree/dev/qp) 分支包含额外增强： + +1. 基于实际 RDMA 逻辑的 QP 创建/销毁支持 +2. 按 IP 或按 QP 的 NIC CC 配置 +3. 优化的 Max-Min 调度逻辑 +4. 解耦的 CC 模块，提升模块化程度 + +--- + +## 核心模块 + +### QBB 网络设备（`qbb-net-device`） + +基于 `PointToPointNetDevice` 构建的支持 QBB 的网络设备，具有 8 个优先级。特性： + +- PFC PAUSE/RESUME 处理 +- `RdmaEgressQueue`：高优先级 ACK/NACK 队列 + QP 间轮询 +- `BEgressQueue`：交换机端口轮询 +- NVSwitch 发送路径支持（NVLS 模式） + +**关键属性**: `QbbEnabled`、`QcnEnabled`、`DynamicThreshold`、`PauseTime`、`NVLS_enable` + +### RDMA 主机协议栈（`rdma-hw`） + +主机 RDMA 核心实现： + +- QP 创建/删除生命周期 +- 报文构造（PPP + IPv4 + UDP + SeqTs 头） +- ACK/NACK/CNP 处理 +- 按 QP 的拥塞控制算法 +- NVSwitch 路由表 + +**拥塞控制算法**： + +| 算法 | 说明 | +|-----------|-------------| +| **DCQCN** | 数据中心量化拥塞通知 | +| **HPCC** | 高精度拥塞控制 | +| **TIMELY** | 基于 RTT 的拥塞控制 | +| **DCTCP** | 数据中心 TCP | +| **HPCC-PINT** | HPCC + 概率 INT | + +**协议号（IPv4 Protocol 字段）**： + +| 协议 | 编号 | 说明 | +|----------|--------|-------------| +| UDP 数据 | `0x11` | 普通数据报文 | +| CNP | `0xFF` | 拥塞通知报文 | +| PFC | `0xFE` | 优先级流控 | +| ACK | `0xFC` | 确认报文 | +| NACK | `0xFD` | 否定确认报文 | + +### 交换机节点（`switch-node`） + +交换机流水线实现： +- ECMP 转发（5 元组哈希） +- 通过 MMU 进行准入控制 +- PFC Pause/Resume 生成 +- ECN 标记 +- INT/PINT 注入（用于 HPCC/HPCC-PINT） + +### 交换机 MMU（`switch-mmu`） + +交换机缓冲区/MMU 模型： +- 入口/出口记账 +- 共享缓冲区和 Headroom 管理 +- PFC 触发/恢复逻辑 +- ECN 标记概率曲线（`kmin/kmax/pmax`） + +### NVSwitch 节点（`nvswitch-node`） + +用于服务器内 GPU 通信的 NVSwitch 模型，配合 `RdmaHw`/`QbbNetDevice` 中的 NVLS 路由逻辑。 + +### QP 状态（`rdma-queue-pair`） + +按 QP 和按 RxQP 的状态管理，包括： +- 窗口和速率控制 +- 已确认序列号追踪 +- 按 CC 算法的状态（DCQCN alpha/targetRate、HPCC hop state、TIMELY RTT、DCTCP alpha/ecnCnt、PINT state） + +--- + +## 分析工具 + +位于 `ns-3-alibabacloud/analysis/`： + +### FCT 分析 + +```bash +python fct_analysis.py -h # 查看使用帮助 +``` + +读取 FCT 输出文件，生成流完成时间（FCT）分析统计。 + +### Trace 阅读器 + +```bash +# 编译 +make trace_reader + +# 使用 +./trace_reader <.tr 文件> [过滤表达式] + +# 过滤示例 +./trace_reader output.tr "time > 2000010000" +./trace_reader output.tr "sip=0x0b000101&dip=0x0b000201" +``` + +### Trace 输出格式 + +``` +2000055540 n:338 4:3 100608 Enqu ecn:0 0b00d101 0b012301 10000 100 U 161000 0 3 1048(1000) +``` + +字段：时间戳、节点、端口:队列、队列长度、事件、ECN、源 IP、目的 IP、源端口、目的端口、报文类型、序列号、发送时间、优先级、大小(载荷) + +--- + +## 头部和工具 + +| 文件 | 说明 | +|------|-------------| +| `qbb-header` | ACK/NACK 头（含可选 INT 头） | +| `cn-header` | CNP 头（反馈字段） | +| `pause-header` | PFC Pause 头 | +| `pint` | PINT 编解码工具 | +| `trace-format.h` | 用于离线分析的二进制 Trace 记录结构 | + +--- + +## 扩展指南 + +### 添加新拥塞控制算法 + +1. **主要修改**: `rdma-hw.{h,cc}` — 添加 `HandleAckX`/`UpdateRateX` 方法，按 `m_cc_mode` 分发 +2. **通常需要**: `rdma-queue-pair.h` — 添加新的按 QP 状态变量 +3. **如需交换机反馈**: `switch-node.cc` — 添加 INT/PINT 或新标记 + +### 修改交换机行为 + +1. **主要修改**: `switch-mmu.{h,cc}` — 修改阈值、曲线、公式 +2. **标记/注入**: `switch-node.cc::SwitchNotifyDequeue()` +3. **准入/优先级**: `switch-node.cc::SendToDev()` + +### 添加新控制报文 + +1. 在 `model/` 中创建新 `*Header`（参照 `CnHeader`/`PauseHeader` 模式） +2. 在 `QbbNetDevice::Receive()` 或 `RdmaHw::Receive()` 中添加解析 + +--- + +## 相关文档 + +- [SimAI-Simulation 使用指南](../user_guide/simai_simulation.md) — 全栈仿真使用 +- [astra-sim 组件](astra_sim.md) — 仿真引擎 +- [NS-3 扩展指南](../developer_guide/extending_ns3.md) — 详细扩展指南 diff --git a/docs/zh/components/simccl.md b/docs/zh/components/simccl.md new file mode 100644 index 00000000..cceac180 --- /dev/null +++ b/docs/zh/components/simccl.md @@ -0,0 +1,82 @@ +# SimCCL — 集合通信库 + +**仓库**: [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | **语言**: Python/C++ + +SimCCL 将集合通信操作转换为点对点通信，是工作负载层与仿真引擎之间的关键桥梁。 + +--- + +## 概述 + +在分布式 LLM 训练中，集合通信操作（AllReduce、AllGather、ReduceScatter、AlltoAll 等）是基础构建块。SimCCL 将这些高层集合操作分解为点对点通信序列，以便网络后端精确仿真。 + +--- + +## 在 SimAI 中的角色 + +SimCCL 位于 AICB（工作负载生成）和 astra-sim-alibabacloud（仿真引擎）之间： + +``` +AICB 生成包含集合操作的工作负载 + | + v +SimCCL 分解集合操作 → 点对点通信 + | + v +astra-sim 将 P2P 流量发送到 NS-3 或物理网络 +``` + +SimCCL 在以下场景中**必需**： +- **SimAI-Simulation** — 全栈 NS-3 仿真 +- **SimAI-Physical** — 物理 RDMA 流量生成 +- **推理仿真** — 使用 SimAI Simulation 后端时 + +SimCCL 在以下场景中**不需要**： +- **SimAI-Analytical** — 直接使用 busbw 估算 + +--- + +## 版本 + +### 基础版（mocknccl） + +基础实现目前位于 [astra-sim-alibabacloud](https://github.com/aliyun/SimAI/tree/master/astra-sim-alibabacloud) 仓库中。文件以 `mocknccl` 为前缀，提供基本的集合→P2P 转换功能。 + +### 完整版 + +具备高级集合通信算法的完整 SimCCL 库可在 [SimCCL 仓库](https://github.com/aliyun/SimCCL) 获取。 + +--- + +## 支持的集合操作 + +| 操作 | 说明 | +|-----------|-------------| +| AllReduce | 跨所有 Rank 进行归约，结果在所有 Rank 上可用 | +| AllGather | 从所有 Rank 收集数据，结果在所有 Rank 上可用 | +| ReduceScatter | 跨所有 Rank 进行归约并分发 | +| AlltoAll | 全对全个性化通信 | +| Broadcast | 从一个 Rank 广播到所有其他 Rank | + +--- + +## 与 astra-sim 的集成 + +SimCCL 通过 `MockNcclGroup` 和 `MockNcclChannel` 接口与 astra-sim-alibabacloud 集成： + +- **MockNcclGroup**：管理参与集合操作的一组 Rank +- **MockNcclChannel**：处理集合操作中特定 Channel 的实际点对点数据传输 + +分解过程考虑： +- 网络拓扑（Ring、Tree 等） +- 参与的 Rank 数量 +- 消息大小 +- 可用通信通道 + +--- + +## 相关文档 + +- [组件概述](index.md) — SimAI 组件架构 +- [astra-sim 组件](astra_sim.md) — 消费 SimCCL 输出的仿真引擎 +- [NS-3 组件](ns3.md) — P2P 仿真的网络后端 diff --git a/docs/zh/components/vidur.md b/docs/zh/components/vidur.md new file mode 100644 index 00000000..bc6d2463 --- /dev/null +++ b/docs/zh/components/vidur.md @@ -0,0 +1,194 @@ +# vidur-alibabacloud — LLM 推理仿真 + +**位置**: 项目内（`vidur-alibabacloud/`） | **语言**: Python | **许可**: MIT + +vidur-alibabacloud 是 SimAI 的 LLM 推理仿真组件，改编自微软 [Vidur](https://github.com/microsoft/vidur)。提供多请求推理调度、GPU 显存管理和 Prefill-Decode（PD）分离支持。 + +--- + +## 核心特性 + +- **Prefill-Decode（PD）分离** — 在不同节点上运行 Prefill 和 Decode 阶段，实现弹性资源分配和性能隔离。灵感来自 [splitwise-sim](https://github.com/Mutinifni/splitwise-sim) +- **灵活的并行策略** — 数据并行（DP）、张量并行（TP）、流水线并行（PP）、专家并行（EP） +- **多种执行后端** — AICB/AIOB、SimAI Simulation (NS-3)、SimAI Analytical、原生 Vidur +- **工作负载生成与回放** — 合成请求（固定/泊松分布）或真实 Trace 回放 +- **细粒度指标** — TTFT、TBT/TPOT、端到端延迟、通信开销、计算开销、调度延迟 + +--- + +## GPU 显存计算模块 + +该模块为推理场景下的 MoE 模型提供精确的 GPU 显存估算。 + +### 组件 + +| 组件 | 文件 | 说明 | +|-----------|------|-------------| +| **ParamCounter** | `vidur/utils/param_counter.py` | 按层和按设备的参数计数，支持 MLA、MHA/GQA、线性注意力和 MoE 专家。PD 分离下返回 `(total_params, prefill_params, decode_params)` | +| **MemoryPlanner** | `vidur/scheduler/utils/memory_planner.py` | 规划 GPU 显存预算：`可用 = GPU显存 * (1 - margin) - 参数显存`，计算 KV Cache 容量和最大并发请求数。含 OOM 检测 | +| **按请求 KV Cache 追踪** | `vidur/entities/replica.py` | 按请求分配/释放 KV Cache 显存，支持运行时剩余容量查询 | + +### 支持的注意力架构 + +| 架构 | 模型 | 说明 | +|---|---|---| +| **MLA**（多头潜注意力） | DeepSeek-V3-671B | LoRA 压缩 KV Cache（`kv_lora_rank` + `qk_rope_head_dim`），相比 MHA 节省约 57 倍显存 | +| **MHA / GQA** | Qwen3-MoE-235B | 标准 KV Cache，每 Token 每层 `num_kv_heads * head_dim` | +| **混合全注意力 + 线性注意力** | Qwen3-Next-80B | 全注意力与线性（GDN）注意力每 4 层交替 | + +--- + +## 支持的模型 + +| 模型 | 注意力 | 专家 | 状态 | +|-------|-----------|---------|--------| +| DeepSeek-V3-671B | MLA | 256 路由 + 1 共享 | PP/EP 适配中 | +| Qwen3-MoE-235B | MHA/GQA | 128 路由 | PP/EP 适配中 | +| Qwen3-Next-80B | 混合 | 512 路由 | PP/EP 适配中 | +| Meta-Llama-3-8B / 70B | MHA | 稠密 | 已支持 | +| Llama-2-7b / 70b | MHA | 稠密 | 已支持 | +| CodeLlama-34b | MHA | 稠密 | 已支持 | +| InternLM-20B | MHA | 稠密 | 已支持 | +| Qwen-72B | MHA | 稠密 | 已支持 | + +--- + +## 环境搭建 + +### Docker（推荐） + +```bash +docker build -t simai:latest . +docker run --gpus all -it --rm simai:latest +``` + +> 在 Hopper GPU 上使用时，在 Dockerfile 中添加 `ENV FLASH_MLA_DISABLE_SM100=1`。 + +### Conda + +```bash +cd vidur-alibabacloud +conda env create -p ./env -f ./environment.yml +conda activate vidur +pip install -r requirements.txt +``` + +--- + +## 关键输入参数 + +| 参数 | 说明 | 默认值 | +|-----------|-------------|---------| +| `--replica_config_model_name` | HuggingFace 模型 ID 或配置路径 | 必需 | +| `--cluster_config_num_replicas` | 副本数量（DP） | 1 | +| `--replica_config_tensor_parallel_size` | TP 度 | 1 | +| `--replica_config_num_pipeline_stages` | PP 阶段数 | 1 | +| `--replica_config_expert_model_parallel_size` | EP 度 | 1 | +| `--replica_config_pd_node_ratio` | P:D 节点比例（如 `"2:6"`） | `""`（无 PD） | +| `--cluster_config_global_scheduler_type` | 全局调度器：`lor` / `round_robin` / `split_wise` | `lor` | +| `--cluster_config_replica_scheduler_type` | 副本调度器：`sarathi` / `split_wise` | `sarathi` | +| `--request_generator_config_type` | `synthetic` / `trace_replay` | `synthetic` | +| `--synthetic_request_generator_config_num_requests` | 生成请求数 | 100 | +| `--poisson_request_generator_config_qps` | 每秒请求数（泊松模式） | 1.0 | +| `--replica_config_device` | GPU 型号（如 `h20_dgx`） | 必需 | +| `--replica_config_network_device` | 网络类型 | 与 device 相同 | +| `--execution_time_predictor_config_type` | 后端：`aicb` / `simai_simulation` / `simai_analytical` / `random_forrest` | `random_forrest` | +| `--nvlink_bandwidth_gbps` | NVLink 带宽 | 1600 | +| `--rdma_bandwidth_gbps` | RDMA 带宽 | 800 | +| `--pd_p2p_bandwidth_gbps` | PD 节点间 P2P 带宽 | 800 | +| `--replica_config_fp8_enabled` | 启用 FP8 量化 | false | +| `--replica_config_memory_margin_fraction` | GPU 显存安全余量 | 0.1 | + +--- + +## 输出文件 + +每次运行产生以下输出： + +| 文件 | 说明 | +|------|-------------| +| `request_metrics.csv` | 每请求指标（17 列） | +| `chrome_trace.json` | 时间线 Trace，可在 Chrome `chrome://tracing` 中可视化 | +| `config.json` | 配置快照 | +| `plots/` | 指标可视化图表 | + +### request_metrics.csv 列说明 + +| 列名 | 说明 | +|--------|-------------| +| `request_id` | 请求唯一标识 | +| `arrived_at` | 请求到达时间 | +| `scheduled_at` | 首次调度时间 | +| `completed_at` | 请求完成时间 | +| `prefill_completed_at` | Prefill 完成时间（首 Token） | +| `num_prefill_tokens` | 输入 Token 数 | +| `num_decode_tokens` | 生成 Token 数 | +| `scheduling_delay` | 调度前等待时间 | +| `e2e_time` | 端到端延迟 | +| `e2e_time_normalized` | E2E 延迟 / num_decode_tokens | +| `execution_time` | 实际 GPU 执行时间 | +| `preemption_time` | 被抢占时间 | +| `num_restarts` | 重启次数 | +| `prefill_e2e_time` | TTFT（首 Token 时间） | +| `decode_time_normalized` | 平均 TBT（Token 间隔时间） | +| `total_comm_cost` | 总通信耗时 | +| `total_compute_cost` | 总计算耗时 | + +--- + +## 仿真指标（23 项） + +仿真器记录以下指标（详见 `vidur-alibabacloud/docs/metrics.md`）： + +1. `request_inter_arrival_delay_histogram` — 请求到达间隔分布 +2. `request_num_tokens_histogram` — Token 数量分布（Prefill + Decode） +3. `request_num_restarts_histogram` — 重启次数分布 +4. `request_e2e_time_cdf` — 端到端延迟 CDF +5. `request_e2e_time_normalised_cdf` — 归一化 E2E 延迟 CDF +6. `request_execution_plus_preemption_times_cdf` — 执行 + 抢占时间 CDF +7. `request_scheduling_delay_cdf` — 调度延迟 CDF +8. `request_execution_time_cdf` — 纯执行时间 CDF +9. `request_preempted_time_cdf` — 抢占时间 CDF +10. `decode_token_execution_plus_preemption_times` — 按 Token 的 inter-token 延迟 CDF +11. `batch_num_tokens_cdf` — 批次总 Token 数 CDF +12. `batch_sizes_cdf` — 批次大小 CDF +13. `prefill_time_e2e_cdf` — TTFT CDF +14. `prefill_time_execution_plus_preemption_cdf` — Prefill 处理时间 CDF +15. `prefill_time_execution_plus_preemption_normalized_cdf` — 归一化 Prefill 时间 CDF +16. `decode_time_execution_plus_preemption_normalized_cdf` — 归一化 Decode 时间 CDF +17. `request_completions_time_series` — 请求完成时间序列 +18. `prefill_completions_time_series` — Prefill 完成时间序列 +19. `decode_completions_time_series` — Decode 完成时间序列 +20. `replica_{id}_memory_usage_weighted_mean` — 按副本显存利用率 +21. `replica_{id}_stage_{id}_busy_time_percent_weighted_mean` — 按阶段忙碌时间百分比 +22. `replica_{id}_stage_{id}_mfu_weighted_mean` — 按阶段 MFU +23. `request_arrivals_time_series` — 请求到达时间序列 + +--- + +## 4 场景测试套件 + +运行所有预配置场景： + +```bash +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all +# 或运行单个场景： +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 3 +``` + +场景配置详情请参阅 [基准测试 — 测试套件](../benchmarking/test_suite.md)。 + +--- + +## 添加新模型 + +如需为 vidur-alibabacloud 添加新模型支持，请参阅 [添加新模型指南](../developer_guide/adding_models.md) 和上游文档 `vidur-alibabacloud/docs/profiling.md`。 + +--- + +## 相关文档 + +- [多请求推理仿真](../user_guide/inference_simulation.md) — 端到端推理仿真工作流 +- [结果分析](../user_guide/result_analysis.md) — 输出文件解读 +- [GPU 显存模块技术参考](../technical_reference/memory_module.md) — 详细显存计算公式 +- [基准测试套件](../benchmarking/test_suite.md) — 4 场景配置详情 diff --git a/docs/zh/developer_guide/adding_models.md b/docs/zh/developer_guide/adding_models.md new file mode 100644 index 00000000..92081963 --- /dev/null +++ b/docs/zh/developer_guide/adding_models.md @@ -0,0 +1,204 @@ +# 添加新模型 + +本指南介绍如何为 SimAI 添加新模型支持，包括 Vidur 推理仿真侧（GPU 显存、Profiling）和 AICB 工作负载生成侧。 + +--- + +## 概述 + +添加新模型通常涉及两个组件： + +| 组件 | 需要添加的内容 | 硬件要求 | +|-----------|-------------|-------------------| +| **vidur-alibabacloud** | 模型配置、Profiling 数据（计算 + 网络） | GPU（仅 Profiling 阶段需要） | +| **AICB** | 工作负载生成参数（`MockedParam` / `MockedModel`） | 无 | + +--- + +## 第一部分：Vidur — 模型配置与 Profiling + +### 步骤 1：添加模型配置 + +在 `vidur-alibabacloud/data/model_configs/` 或 `vidur-alibabacloud/data/hf_configs/` 中创建 YAML/JSON 模型配置： + +- 使用模型的 HuggingFace 模型 ID 作为文件名（如 `meta-llama/Llama-2-70b-hf.yml`） +- 参考模型的 HuggingFace `config.json` 获取参数值 +- 确保正确设置参数，使参考 Transformer 模型尽可能接近新模型 + +**配置参数示例：** + +```yaml +num_layers: 80 +hidden_size: 8192 +num_attention_heads: 64 +num_key_value_heads: 8 # GQA 模型 +head_dim: 128 +intermediate_size: 28672 +vocab_size: 128256 +max_position_embeddings: 8192 +``` + +MoE 模型还需包含： + +```yaml +num_routed_experts: 256 +num_experts_per_tok: 8 +num_shared_experts: 1 +moe_intermediate_size: 2048 +``` + +### 步骤 2：Profiling 数据结构 + +Profiling 数据存储在 `vidur-alibabacloud/data/profiling/`： + +``` +profiling/ +├── compute/ +│ ├── a100/ +│ │ └── model-name/ +│ │ ├── mlp.csv +│ │ └── attention.csv +│ └── h100/ +│ └── model-name/ +│ ├── mlp.csv +│ └── attention.csv +└── network/ + ├── a100_pair_nvlink/ + │ ├── allreduce.csv + │ └── send_recv.csv + └── h100_dgx/ + ├── allreduce.csv + └── send_recv.csv +``` + +**关键区别：** +- **计算 Profiling**：仅依赖 GPU 型号（如 `a100`、`h100`），不依赖网络拓扑 +- **网络 Profiling**：依赖网络配置（如 `a100_pair_nvlink` vs `a100_dgx`） + +### 步骤 3：计算 Profiling（MLP） + +需要实际 GPU。TP > 1 时仅需 1 块 GPU 即可。 + +```bash +# 安装 sarathi-serve（vidur 分支）用于 Profiling +# 然后运行 MLP Profiling： +python vidur/profiling/mlp/main.py \ + --models your-model/model-name \ + --num_gpus 4 + +# 将输出复制到数据目录： +cp profiling_outputs/mlp//your-model/model-name/mlp.csv \ + data/profiling/compute//your-model/model-name/mlp.csv +``` + +### 步骤 4：计算 Profiling（Attention） + +```bash +python vidur/profiling/attention/main.py \ + --models your-model/model-name \ + --num_gpus 4 + +# 复制输出： +cp profiling_outputs/attention//your-model/model-name/attention.csv \ + data/profiling/compute//your-model/model-name/attention.csv +``` + +### 步骤 5：网络 Profiling（如需） + +网络 Profiling 是**与模型无关**的——相同硬件配置的数据可用于所有模型。 + +```bash +# AllReduce Profiling（用于 TP）： +python vidur/profiling/collectives/main.py \ + --num_workers_per_node_combinations 1,2,4,8 \ + --collective all_reduce + +# Send/Recv Profiling（用于 PP，需要多节点）： +python vidur/profiling/collectives/main.py \ + --num_workers_per_node_combinations 1,2,4,8 \ + --collective send_recv +``` + +**可用网络设备 Profile：** +- `a100_pair_nvlink` — Azure Standard_NC96ads_A100_v4（4x A100 PCIe + NVLink pairs） +- `h100_pair_nvlink` — Azure 内部（4x H100 NVL + NVLink pairs） +- `a100_dgx` — A100 DGX（8x A100） +- `h100_dgx` — H100 DGX（8x H100） + +--- + +## 第二部分：AICB — 工作负载生成 + +### 自定义模型参数（MockedParam） + +在 AICB 中添加新模型的工作负载生成，需创建 `MockedParam` 子类： + +```python +# 在 aicb/workload_generator/mocked_params/ 中 +class YourModelParam(MockedParam): + def __init__(self): + super().__init__() + self.num_layers = 80 + self.hidden_size = 8192 + self.num_attention_heads = 64 + self.num_key_value_heads = 8 + self.ffn_hidden_size = 28672 + self.vocab_size = 128256 + self.seq_length = 8192 + # MoE 参数（如适用） + self.num_experts = 256 + self.topk = 8 + self.moe_intermediate_size = 2048 +``` + +### 自定义模型工作流（MockedModel） + +如需完全控制工作负载生成过程，可创建 `MockedModel` 子类，定义每层的计算和通信操作。 + +详见 [AICB 组件文档](../components/aicb.md#自定义模型开发)。 + +### 推理工作负载生成 + +生成带 Prefill/Decode 分离的推理工作负载： + +```bash +# 生成推理工作负载 +python -m aicb.main \ + --model_name your-model-name \ + --workload_type inference \ + --num_prefill_tokens 1024 \ + --num_decode_tokens 128 +``` + +--- + +## 第三部分：GPU 显存模块 + +如果您的模型使用非标准注意力架构，可能需要扩展 `vidur/utils/param_counter.py` 中的 `ParamCounter`： + +1. 添加您的架构的注意力参数计算 +2. 添加 KV Cache 每 Token 大小计算 +3. 使用 MemoryPlanner 测试验证 OOM 检测正确工作 + +详见 [GPU 显存模块技术参考](../technical_reference/memory_module.md)。 + +--- + +## 验证清单 + +- [ ] 模型配置文件已添加到 `data/model_configs/` 或 `data/hf_configs/` +- [ ] 计算 Profiling 数据（MLP + Attention）已添加 +- [ ] 目标硬件的网络 Profiling 数据可用 +- [ ] AICB `MockedParam` 已创建（如需工作负载生成） +- [ ] GPU 显存计算正确（ParamCounter + MemoryPlanner） +- [ ] 端到端推理仿真产生合理结果 +- [ ] 文档已更新 + +--- + +## 相关文档 + +- [vidur-alibabacloud 组件](../components/vidur.md) — 完整 vidur 文档 +- [AICB 组件](../components/aicb.md) — AICB 工作负载生成 +- [GPU 显存模块](../technical_reference/memory_module.md) — 显存计算公式 +- [支持的模型](../user_guide/supported_models.md) — 当前模型支持状态 diff --git a/docs/zh/developer_guide/architecture.md b/docs/zh/developer_guide/architecture.md new file mode 100644 index 00000000..702bf80d --- /dev/null +++ b/docs/zh/developer_guide/architecture.md @@ -0,0 +1,176 @@ +# 系统架构 + +本文档描述 SimAI 的模块化架构、组件交互以及训练和推理仿真的数据流。 + +--- + +## 项目结构 + +``` +SimAI/ +├── aicb/ # AI 计算基准——工作负载生成（Python） +│ ├── workload_generator/ # 训练/推理工作负载生成器 +│ └── aicb.py # 主入口 +├── astra-sim-alibabacloud/ # 仿真引擎——核心仿真器（C++） +│ ├── astra-sim/ # 扩展自 astra-sim 1.0 +│ └── build.sh # 编译脚本 +├── ns-3-alibabacloud/ # NS-3 网络仿真后端（C++） +├── vidur-alibabacloud/ # LLM 推理仿真（Python） +│ ├── vidur/ # 核心仿真框架 +│ └── setup.py # Python 包配置 +├── SimCCL/ # 集合通信转换 +├── docs/ # 文档和教程 +├── example/ # 示例工作负载和配置 +├── scripts/ # 编译和工具脚本 +├── results/ # 仿真输出目录 +├── bin/ # 编译二进制输出 +└── Dockerfile # Docker 容器定义 +``` + +--- + +## 组件架构 + +``` + |--- AICB （工作负载生成 & 计算性能分析） +SimAI --|--- SimCCL （集合通信算法分析） + |--- astra-sim-alibabacloud （仿真引擎：Analytical / Simulation / Physical） + |--- ns-3-alibabacloud （NS-3 网络后端） + |--- vidur-alibabacloud （多请求推理调度 & 显存管理） +``` + +![SimAI 架构](../../images/SimAI_Arc.png) + +### 组件职责 + +| 组件 | 角色 | 语言 | +|-----------|------|----------| +| **AICB** | 生成训练/推理工作负载、采集计算内核性能、运行物理基准测试 | Python | +| **SimCCL** | 将集合通信操作（AllReduce、AllGather 等）转换为点对点通信集合 | Python | +| **astra-sim-alibabacloud** | 支持 3 种模式的核心仿真引擎；管理计算/内存/网络 API | C++ | +| **ns-3-alibabacloud** | 带 RDMA、数据中心拓扑和 CC 算法的包级网络仿真 | C++ | +| **vidur-alibabacloud** | 支持 PD 分离和 GPU 显存管理的多请求推理调度 | Python | + +--- + +## 三种运行模式 + +### SimAI-Analytical + +``` +AICB (workload.txt) → astra-sim (analytical) → busbw 估算 → CSV 结果 +``` + +- **适用场景**：快速性能分析、并行参数扫描 +- **组件**：AICB + astra-sim-alibabacloud（分析模式） +- **网络模型**：总线带宽（busbw）抽象 + +### SimAI-Simulation + +``` +AICB (workload.txt) → SimCCL (集合→P2P) → astra-sim (simulation) → NS-3 → 详细 Trace +``` + +- **适用场景**：全栈网络研究、CC 算法评估 +- **组件**：AICB + SimCCL + astra-sim-alibabacloud (simulation) + ns-3-alibabacloud +- **网络模型**：包级 NS-3 仿真 + +### SimAI-Physical + +``` +AICB (workload.txt) → SimCCL (集合→P2P) → astra-sim (physical) → 真实 NIC 上的 RDMA 流量 +``` + +- **适用场景**：NIC 行为研究、物理流量分析 +- **组件**：AICB + SimCCL + astra-sim-alibabacloud（物理模式） +- **网络模型**：通过 MPI 的真实 RDMA 流量 + +--- + +## 推理仿真数据流 + +``` +请求生成器 + | 生成合成/真实 Trace 请求 + v +全局调度器 + | 将请求分发到 Prefill / Decode 副本 + v +副本调度器 + | 批次组装和调度 + v +显存管理（MemoryPlanner + Replica） + | KV Cache 分配和容量检查 + v +执行时间预测器 + | AICB / SimAI Simulation / SimAI Analytical / Vidur + v +指标存储 + | TTFT、TBT、E2E、通信/计算开销 + v +输出（request_metrics.csv, chrome_trace.json, plots/） +``` + +### 推理关键组件 + +| 组件 | 文件 | 说明 | +|-----------|------|-------------| +| 请求生成器 | `vidur/request_generator/` | 生成合成或基于 Trace 的请求 | +| 全局调度器 | `vidur/scheduler/global_scheduler/` | 跨副本分发请求（`lor`、`round_robin`、`split_wise`） | +| 副本调度器 | `vidur/scheduler/replica_scheduler/` | 副本内批次调度（`sarathi`、`split_wise`） | +| MemoryPlanner | `vidur/scheduler/utils/memory_planner.py` | GPU 显存预算计算 | +| ParamCounter | `vidur/utils/param_counter.py` | 模型参数计数（MLA/MHA/GQA/线性/MoE） | +| 执行预测器 | `vidur/execution_time_predictor/` | 通过多种后端估算执行时间 | +| 指标存储 | `vidur/metrics/` | 采集并导出 23 项仿真指标 | + +--- + +## 子模块结构 + +SimAI 使用 Git submodule 管理核心组件： + +| 子模块 | 仓库 | 分支 | +|-----------|------------|--------| +| `aicb` | [aliyun/aicb](https://github.com/aliyun/aicb) | master | +| `SimCCL` | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | master | +| `ns-3-alibabacloud` | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | master / dev/qp | +| `astra-sim-alibabacloud` | 项目内 | — | +| `vidur-alibabacloud` | 项目内 | — | + +**关键规则：** +1. 子模块拥有独立的 Git 历史 +2. 父仓库仅追踪每个子模块的 commit hash +3. 克隆后务必初始化：`git submodule update --init --recursive` + +--- + +## 构建系统 + +### 编译脚本 + +```bash +# 分析模式（快速，基于 busbw） +bash scripts/build.sh -c analytical + +# NS-3 仿真模式（全栈） +bash scripts/build.sh -c ns3 + +# 物理模式（Beta，RDMA） +bash scripts/build.sh -c phy +``` + +### 编译产物 + +| 模式 | 二进制 | 位置 | +|------|--------|----------| +| Analytical | `SimAI_analytical` | `bin/` | +| Simulation | `SimAI_simulator` | `bin/` | +| Physical | `SimAI_physical` | `bin/` | + +--- + +## 相关文档 + +- [组件概述](../components/index.md) — 各组件详细文档 +- [贡献指南](contributing.md) — 如何贡献代码 +- [配置文件参考](../technical_reference/configuration.md) — 配置文件和参数 diff --git a/docs/zh/developer_guide/contributing.md b/docs/zh/developer_guide/contributing.md new file mode 100644 index 00000000..59780065 --- /dev/null +++ b/docs/zh/developer_guide/contributing.md @@ -0,0 +1,224 @@ +# 贡献指南 + +感谢您对 SimAI 项目的关注！本指南介绍完整的开发工作流。 + +> **完整版**：详见项目根目录下的 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。 + +--- + +## 贡献方式 + +1. **新功能** — 添加模型支持、并行策略、调度策略 +2. **Bug 修复** — 修复仿真不准确、崩溃或结果错误 +3. **性能优化** — 提升仿真速度、内存使用或可扩展性 +4. **文档** — 改进教程、添加示例、修正错误 +5. **基准测试与验证** — 添加对比真实硬件的验证结果 +6. **问题报告** — 报告 Bug、请求功能或分享反馈 + +--- + +## 开发工作流 + +### 步骤 1：Fork 和克隆 + +```bash +git clone --recurse-submodules https://github.com/YOUR_USERNAME/SimAI.git +cd SimAI +git remote add upstream https://github.com/aliyun/SimAI.git +``` + +### 步骤 2：创建功能分支 + +```bash +git fetch upstream +git checkout -b feature/your-feature-name upstream/master + +# 分支命名规范： +# feature/xxx — 新功能 +# fix/xxx — Bug 修复 +# docs/xxx — 文档 +# perf/xxx — 性能优化 +# refactor/xxx — 代码重构 +``` + +### 步骤 3：开发和测试 + +```bash +# C++ 修改需重新编译： +bash scripts/build.sh -c analytical # 或 ns3 + +# Python 修改： +python -c "from aicb import ..." +``` + +### 步骤 4：提交 + +```bash +git add -A +git commit -m "feat(aicb): add Llama-4 model workload generation" +``` + +### 步骤 5：推送并创建 PR + +```bash +git push origin feature/your-feature-name +# 然后在 GitHub 上创建 Pull Request +``` + +--- + +## 提交信息规范 + +使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： + +``` +(): +``` + +### 类型 + +| 类型 | 说明 | +|------|-------------| +| `feat` | 新功能 | +| `fix` | Bug 修复 | +| `docs` | 仅文档修改 | +| `refactor` | 代码重构 | +| `test` | 添加或更新测试 | +| `perf` | 性能优化 | +| `chore` | 构建流程、工具 | + +### 范围 + +`aicb`、`vidur`、`astra-sim`、`ns3`、`simccl`、`docs`、`docker`、`scripts` + +### 示例 + +``` +feat(aicb): add DeepSeek-V3 inference workload generation +fix(astra-sim): correct AllReduce latency calculation for ring algorithm +docs: update build instructions for NS-3 mode +perf(vidur): reduce memory allocation in request scheduler +``` + +--- + +## 代码风格 + +### Python + +- **格式化**: [black](https://github.com/psf/black)（默认设置） +- **Import 排序**: [isort](https://pycqa.github.io/isort/) +- **Linter**: [flake8](https://flake8.pycqa.org/) +- **最大行宽**: 120 字符 + +```bash +black --line-length 120 your_file.py +isort your_file.py +flake8 your_file.py --max-line-length 120 +``` + +### C++ + +- 遵循 `astra-sim-alibabacloud/` 中现有代码风格 +- 4 空格缩进 +- 函数和变量使用 `snake_case` +- 非显而易见的逻辑需添加注释 + +### 通用规则 + +- 注释使用**英文**编写 +- 所有新函数/类应有文档字符串或头部注释 +- 避免硬编码路径；使用相对路径或配置变量 +- 每个 PR 只包含一个功能/修复 + +--- + +## 子模块操作 + +SimAI 使用 Git submodule，关键要点： + +| 子模块 | 仓库 | 语言 | +|-----------|------------|----------| +| `aicb` | [aliyun/aicb](https://github.com/aliyun/aicb) | Python | +| `SimCCL` | [aliyun/SimCCL](https://github.com/aliyun/SimCCL) | Python | +| `ns-3-alibabacloud` | [aliyun/ns-3-alibabacloud](https://github.com/aliyun/ns-3-alibabacloud) | C++ | +| `astra-sim-alibabacloud` | 项目内 | C++ | +| `vidur-alibabacloud` | 项目内 | Python | + +### 跨子模块修改 + +如果您的贡献涉及多个子模块： + +1. 在每个子模块中分别进行修改并提交 +2. 更新父仓库指向新的子模块 commit +3. 为有独立远程仓库的子模块创建单独的 PR +4. 在 PR 描述中引用相关 PR + +--- + +## Pull Request 指南 + +### PR 标题 + +使用与 commit message 相同的格式：`(): ` + +### PR 检查清单 + +- [ ] 代码编译无错误 +- [ ] 现有仿真结果不变（无精度退化） +- [ ] 新代码有适当注释 +- [ ] 新功能添加了测试 +- [ ] 必要时更新了文档 + +--- + +## 提交前质量检查 + +```bash +# 1. C++ 编译检查 +bash scripts/build.sh -c analytical +bash scripts/build.sh -c ns3 + +# 2. Python lint 检查 +black --check --line-length 120 your_changed_files.py +flake8 your_changed_files.py --max-line-length 120 + +# 3. 基本仿真测试 +cd bin && ./SimAI_analytical \ + --workload_path=../example/workload_analytical.txt \ + --comm_group_type=TP_GROUP \ + --busbw_path=../example/busbw.yaml + +# 4. 子模块状态检查 +git submodule status +``` + +--- + +## 验收标准 + +| 标准 | 要求 | +|-----------|-------------| +| **编译** | 编译无错误 | +| **精度** | 不降低现有仿真精度 | +| **测试** | 关键代码路径有覆盖 | +| **文档** | 新功能有注释/文档更新 | +| **风格** | 遵循代码风格规范 | +| **范围** | 修改集中且解释清晰 | + +--- + +## 审核时间线 + +1. **初审**：3-5 个工作日 +2. **反馈**：建设性评论和可操作建议 +3. **迭代**：处理反馈并更新 PR +4. **合并**：批准的 PR 合入主分支 + +--- + +## 获取帮助 + +- **Issues**: [GitHub Issues](https://github.com/aliyun/SimAI/issues) +- **讨论**: 创建 Issue 并以 "Question:" 为前缀 +- **文档**: 参见 [Tutorial](../../../docs/Tutorial.md) diff --git a/docs/zh/developer_guide/extending_ns3.md b/docs/zh/developer_guide/extending_ns3.md new file mode 100644 index 00000000..980aee84 --- /dev/null +++ b/docs/zh/developer_guide/extending_ns3.md @@ -0,0 +1,219 @@ +# NS-3 网络后端扩展指南 + +本指南介绍如何扩展 `ns-3-alibabacloud`，包括新增拥塞控制算法、交换机行为、控制报文和 NVSwitch 特性。 + +> **源码参考**：详见 `astra-sim-alibabacloud/extern/network_backend/ns3-interface/README.md` 获取完整模块映射。 + +--- + +## 模块概览 + +所有关键源文件位于 `ns-3-alibabacloud/simulation/src/point-to-point/model/`： + +| 文件 | 类 | 用途 | +|------|-------|---------| +| `qbb-net-device.{h,cc}` | `QbbNetDevice`, `RdmaEgressQueue` | 支持 QBB 的 NIC，8 优先级队列，PFC 处理，NVSwitch 发送路径 | +| `rdma-hw.{h,cc}` | `RdmaHw` | 主机 RDMA 核心：QP 管理、报文构造、ACK/NACK、CC 算法 | +| `rdma-queue-pair.{h,cc}` | `RdmaQueuePair`, `RdmaRxQueuePair` | 按 QP 状态（窗口、速率、CC 特定状态） | +| `switch-node.{h,cc}` | `SwitchNode` | 交换机流水线：ECMP 转发、ECN 标记、PFC、INT/PINT 注入 | +| `switch-mmu.{h,cc}` | `SwitchMmu` | 交换机缓冲区/MMU：入口/出口记账、PFC 阈值、ECN 曲线 | +| `nvswitch-node.{h,cc}` | `NVSwitchNode` | 服务器内 GPU 通信的 NVSwitch 模型 | +| `rdma-driver.{h,cc}` | `RdmaDriver` | Node/NIC 与 RdmaHw 之间的连接层 | +| `qbb-header.{h,cc}` | — | ACK/NACK 头（PG/seq/CNP-flag + INT 头） | +| `cn-header.{h,cc}` | — | CNP 头（反馈字段） | +| `pause-header.{h,cc}` | — | PFC Pause 头 | +| `pint.{h,cc}` | — | PINT 编解码工具 | +| `trace-format.h` | `TraceFormat` | 用于离线分析的二进制 Trace 记录结构 | + +--- + +## 添加新拥塞控制算法 + +NS-3 后端内置 5 种 CC 算法：**DCQCN**、**HPCC**、**TIMELY**、**DCTCP** 和 **HPCC-PINT**。添加新算法步骤： + +### 步骤 1：定义 CC 模式 + +在 `rdma-hw.h` 中添加新的 `CcMode` 值： + +```cpp +// 现有模式：1=DCQCN, 3=HPCC, 7=TIMELY, 8=DCTCP, 10=HPCC-PINT +static const uint32_t CC_MODE_YOUR_ALG = 11; +``` + +### 步骤 2：添加按 QP 状态（如需） + +在 `rdma-queue-pair.h` 中为 `RdmaQueuePair` 添加新状态变量： + +```cpp +// 您的 CC 算法状态 +double m_your_alg_rate; +double m_your_alg_alpha; +// ... +``` + +### 步骤 3：实现算法逻辑 + +在 `rdma-hw.cc` 中添加两个关键函数： + +```cpp +void RdmaHw::HandleAckYourAlg(Ptr qp, ...) { + // 处理 ACK 并更新速率/窗口 +} + +void RdmaHw::UpdateRateYourAlg(Ptr qp, ...) { + // 速率更新逻辑 +} +``` + +### 步骤 4：注册分发 + +在 `rdma-hw.cc` 的 `ReceiveAck()` 和/或 `ReceiveCnp()` 中添加分发： + +```cpp +switch (m_cc_mode) { + // ... 现有 case ... + case CC_MODE_YOUR_ALG: + HandleAckYourAlg(qp, ...); + break; +} +``` + +### 步骤 5：添加交换机反馈（如需） + +如果您的 CC 算法需要交换机侧信息（如 INT/PINT 元数据）： + +- 修改 `switch-node.cc::SwitchNotifyDequeue()` 注入元数据 +- 在 `RdmaHw::Receive()` 或 `QbbNetDevice::Receive()` 中添加头部解析 + +--- + +## 修改交换机行为 + +### 缓冲区管理 / PFC 阈值 + +**主要文件**: `switch-mmu.{h,cc}` + +关键修改方法： + +| 方法 | 用途 | +|--------|---------| +| `ConfigBufferSize()` | 总缓冲池大小 | +| `ConfigHdrm()` | Headroom 分配 | +| `ConfigEcn()` | ECN 标记阈值（`kmin`、`kmax`、`pmax`） | +| `CheckIngressAdmission()` | 入口准入控制 | +| `CheckEgressAdmission()` | 出口准入控制 | +| `GetPfcThreshold()` | PFC 触发阈值公式 | + +### ECN 标记 / INT 注入 + +**文件**: `switch-node.cc` + +修改 `SwitchNotifyDequeue()` 实现： +- 基于自定义队列占用公式的 ECN 标记 +- 用于高级 CC 算法的 INT/PINT 元数据注入 +- 自定义报文标记 + +### 转发 / ECMP + +**文件**: `switch-node.cc` + +路由修改： +- `GetOutDev()` — 输出端口选择 +- `EcmpHash()` — ECMP 哈希函数（当前为 5 元组） +- `AddTableEntry()` — 路由表管理 + +--- + +## 引入新控制报文 + +### 步骤 1：创建头部 + +在 `model/` 中创建新头部文件，参照 `CnHeader` 或 `PauseHeader` 模式： + +```cpp +// your-header.h +class YourHeader : public Header { +public: + static TypeId GetTypeId(); + // 序列化/反序列化方法 + uint32_t GetSerializedSize() const override; + void Serialize(Buffer::Iterator start) const override; + uint32_t Deserialize(Buffer::Iterator start) override; + + // 头部字段 + uint32_t m_your_field; +}; +``` + +### 步骤 2：定义协议号 + +添加新协议号（遵循现有约定）： + +```cpp +// 现有协议号（IPv4 Protocol 字段）： +// UDP 数据: 0x11 +// CNP: 0xFF +// PFC: 0xFE +// ACK: 0xFC +// NACK: 0xFD +// 新协议: 0xFB（示例） +``` + +### 步骤 3：添加解析/分发 + +在以下位置添加报文处理： +- `QbbNetDevice::Receive()` — 设备级解析 +- `RdmaHw::Receive()` — 主机协议栈处理 + +--- + +## NVSwitch / NVLS 扩展 + +**文件**: `nvswitch-node.{h,cc}`、`qbb-net-device.{h,cc}`（NVLS 发送路径）、`rdma-hw.{h,cc}`（NVLS 路由） + +`NVSwitchNode` 模拟通过 NVSwitch 的服务器内 GPU 通信。扩展方式： + +- **转发**：类似 `SwitchNode` 但不包含 ECN/INT 注入 +- **NVLS 路由**：修改 `RdmaHw::GetNicIdxOfQp()` 和 `GetNicIdxOfRxQp()` 以适配 NVSwitch 路由表 +- **QP 重分配**：`RdmaHw::RedistributeQp()` 用于 NVSwitch 链路间负载均衡 + +--- + +## 分析工具 + +`ns-3-alibabacloud/analysis/` 目录包含 Trace 分析工具： + +| 工具 | 用途 | +|------|---------| +| FCT 分析 | 从仿真 Trace 分析流完成时间 | +| Trace 阅读器 | 解析二进制 `TraceFormat` 记录 | +| 带宽分析 | 按链路的带宽利用率随时间变化 | +| 队列分析 | 队列占用和 PFC 事件分析 | +| QP 分析 | 按 QP 的性能指标 | + +### Trace 格式 + +二进制 Trace 记录结构（`trace-format.h`）捕获按报文的事件。使用离线分析工具： + +1. 解析仿真输出的 Trace 文件 +2. 计算 FCT、吞吐量、队列深度统计 +3. 识别拥塞热点和 PFC 事件 + +--- + +## dev/qp 分支增强 + +[dev/qp](https://github.com/aliyun/ns-3-alibabacloud/tree/dev/qp) 分支包含： + +1. **QP 逻辑支持** — 基于实际 RDMA 逻辑的 QP 创建/销毁 +2. **NIC CC 配置** — 按 IP 或按 QP 的 CC 设置 +3. **优化调度** — Max-Min 原则的公平资源分配 +4. **解耦 CC 模块** — 提升模块化程度 + +--- + +## 相关文档 + +- [NS-3 组件](../components/ns3.md) — 完整 NS-3 后端文档 +- [SimAI-Simulation 使用指南](../user_guide/simai_simulation.md) — NS-3 仿真模式使用 +- [配置文件参考](../technical_reference/configuration.md) — 拓扑和配置文件 diff --git a/docs/zh/developer_guide/index.md b/docs/zh/developer_guide/index.md new file mode 100644 index 00000000..f937de50 --- /dev/null +++ b/docs/zh/developer_guide/index.md @@ -0,0 +1,25 @@ +# 开发者指南 + +欢迎来到 SimAI 开发者指南。本节涵盖项目架构、贡献工作流以及扩展 SimAI 的新模型和网络特性指南。 + +--- + +## 目录 + +| 文档 | 说明 | +|----------|-------------| +| [系统架构](architecture.md) | 系统架构、数据流和模块交互 | +| [贡献指南](contributing.md) | 开发工作流、代码风格、PR 指南 | +| [添加新模型](adding_models.md) | 添加新模型支持指南（Vidur profiling + AICB 工作负载） | +| [NS-3 扩展](extending_ns3.md) | NS-3 网络后端扩展指南 | + +--- + +## 前置条件 + +- **Python** 3.8+（Docker 推荐 3.12） +- **CMake** 3.16+ +- **GCC/G++** 9.4+ +- **Git** 支持 submodule + +详见 [安装指南](../getting_started/installation.md)。 diff --git a/docs/zh/getting_started/index.md b/docs/zh/getting_started/index.md new file mode 100644 index 00000000..dc865b17 --- /dev/null +++ b/docs/zh/getting_started/index.md @@ -0,0 +1,25 @@ +# 快速入门 + +本章节帮助你搭建 SimAI 环境并运行第一次仿真。 + +## 目录 + +| 页面 | 说明 | +|------|------| +| [安装指南](installation.md) | 通过 Docker 或源码安装 SimAI | +| [快速开始](quickstart.md) | 运行第一个 SimAI-Analytical、SimAI-Simulation 和推理仿真 | + +## 前置条件 + +- **Python** 3.8+（Docker 镜像中推荐 3.12） +- **CMake** 3.16+ +- **GCC/G++** 9.4+ +- **Git**（支持 submodule） + +若需使用 AIOB（计算性能分析）生成工作负载，则需要 **NVIDIA Hopper (SM90)** 或 **Blackwell (SM100)** GPU。 + +## 下一步 + +1. 按照[安装指南](installation.md)搭建环境 +2. 运行[快速开始](quickstart.md)示例验证安装 +3. 查看[用户指南](../user_guide/index.md)了解详细用法 diff --git a/docs/zh/getting_started/installation.md b/docs/zh/getting_started/installation.md new file mode 100644 index 00000000..bebb2844 --- /dev/null +++ b/docs/zh/getting_started/installation.md @@ -0,0 +1,96 @@ +# 安装指南 + +本指南介绍如何安装 SimAI 及其依赖。 + +## 方式一：Docker（推荐） + +```bash +# 构建 Docker 镜像 +docker build -t simai:latest . + +# 运行容器（带 GPU 支持） +docker run --gpus all -it --rm \ + -v $(pwd)/results:/workspace/SimAI/results \ + simai:latest /bin/bash +``` + +> **注意：** 如使用 Hopper GPU，请在 Dockerfile 中添加 `ENV FLASH_MLA_DISABLE_SM100=1`。 + +## 方式二：从源码编译 + +以下步骤已在 GCC/G++ 9.4.0、Python 3.8.10、Ubuntu 20.04 环境下测试通过。 + +> **重要：** 请勿安装 ninja（NGC 镜像中已预装，需移除以兼容 SimAI-Simulation 编译）。 +> ```bash +> apt remove ninja-build && pip uninstall ninja +> ``` + +### 第一步：克隆仓库 + +```bash +git clone https://github.com/aliyun/SimAI.git +cd ./SimAI/ + +# 初始化子模块 +git submodule update --init --recursive +# 更新到最新提交 +git submodule update --remote +``` + +### 第二步：编译 C++ 组件 + +根据需要选择编译模式： + +```bash +# SimAI-Analytical（快速，抽象网络细节） +./scripts/build.sh -c analytical + +# SimAI-Simulation（使用 NS-3 网络后端的全栈仿真） +./scripts/build.sh -c ns3 + +# SimAI-Physical（Beta，需要 RDMA 环境） +sudo yum install openmpi openmpi-devel +export MPI_INCLUDE_PATH=/usr/include/openmpi-x86_64/ +export MPI_BIN_PATH=/usr/lib64/openmpi/bin/mpic++ +./scripts/build.sh -c phy +``` + +### 第三步：安装 Python 依赖 + +```bash +pip install -r aicb/requirements.txt +pip install -r vidur-alibabacloud/requirements.txt +``` + +### 第四步：验证编译结果 + +```bash +ls bin/ # 应包含 SimAI_analytical 和/或 SimAI_simulator +``` + +## 方式三：Conda 环境（推理仿真专用） + +```bash +cd vidur-alibabacloud +conda env create -p ./env -f ./environment.yml +conda activate vidur +pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ +``` + +## NGC 容器（工作负载生成） + +使用 AIOB 进行计算性能分析生成工作负载时，建议直接使用 NGC 容器镜像： + +```bash +docker pull nvcr.io/nvidia/pytorch:xx.xx-py3 +docker run --gpus all -it --rm \ + -v /path/to/SimAI:/workspace/SimAI \ + nvcr.io/nvidia/pytorch:xx.xx-py3 +``` + +> **注意：** 请使用 PyTorch >= 23.08 版本的 NGC 镜像。 + +## 下一步 + +- [快速开始](quickstart.md) — 运行第一次仿真 +- [用户指南](../user_guide/index.md) — 各模式详细使用方法 diff --git a/docs/zh/getting_started/quickstart.md b/docs/zh/getting_started/quickstart.md new file mode 100644 index 00000000..10e4a374 --- /dev/null +++ b/docs/zh/getting_started/quickstart.md @@ -0,0 +1,85 @@ +# 快速开始 + +本指南帮助你运行第一次 SimAI 仿真。 + +## 1. SimAI-Analytical + +最快的入门方式。使用总线带宽（busbw）抽象网络细节。 + +```bash +# 运行 Analytical 仿真 +./bin/SimAI_analytical \ + -w example/workload_analytical.txt \ + -g 9216 \ + -g_p_s 8 \ + -r test- \ + -busbw example/busbw.yaml +``` + +自动计算总线带宽： + +```bash +./bin/SimAI_analytical \ + -w ./example/workload_analytical.txt \ + -g 9216 -nv 360 -nic 48.5 \ + -n_p_s 8 -g_p_s 8 -r example- +``` + +详细参数说明请参考 [SimAI-Analytical 用户指南](../user_guide/simai_analytical.md)。 + +## 2. SimAI-Simulation + +使用 NS-3 网络后端的全栈仿真。 + +```bash +# 第一步：创建网络拓扑 +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +# 第二步：运行仿真 +AS_SEND_LAT=3 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator \ + -t 16 \ + -w ./example/microAllReduce.txt \ + -n ./Spectrum-X_128g_8gps_100Gbps_A100 \ + -c astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +详细参数说明请参考 [SimAI-Simulation 用户指南](../user_guide/simai_simulation.md)。 + +## 3. 多请求推理仿真 + +使用 Vidur 框架的端到端推理仿真。 + +### 前置条件 + +```bash +# 激活 vidur conda 环境 +conda activate vidur +``` + +### 运行四场景测试套件 + +```bash +# 运行全部 4 个场景 +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --all + +# 或运行单个场景 +bash vidur-alibabacloud/examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 +``` + +### 场景概览 + +| 场景 | 模型 | PD 分离 | World Size | TP | EP | 调度器 | +|------|------|---------|-----------|----|----|--------| +| 1 | Qwen3-Next-80B | 否 | 32 | 1 | 1 | lor | +| 2 | Qwen3-Next-80B | 是（P=2, D=6） | 8 | 1 | 1 | split_wise | +| 3 | DeepSeek-671B | 是（P=2, D=6） | 8 | 8 | 8 | split_wise | +| 4 | Qwen3-MoE-235B | 是（P=2, D=6） | 8 | 4 | 4 | split_wise | + +详细信息请参考[推理仿真用户指南](../user_guide/inference_simulation.md)。 + +## 下一步 + +- [用户指南](../user_guide/index.md) — 深入了解各仿真模式 +- [组件详情](../components/index.md) — 了解各子模块 +- [基准测试](../benchmarking/index.md) — 运行完整测试套件 diff --git a/docs/zh/index.md b/docs/zh/index.md new file mode 100644 index 00000000..9dcc8707 --- /dev/null +++ b/docs/zh/index.md @@ -0,0 +1,73 @@ +# 欢迎使用 SimAI 文档 + +

+ English  ｜  English +

+ +[![License](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE) +[![NSDI'25](https://img.shields.io/badge/NSDI'25-SimAI-blue.svg)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) + +**SimAI** 是阿里云开源的业界首个全栈高精度 AI 大规模**推理**与**训练**仿真器。它提供了对 LLM 训练和推理全流程的详细建模与仿真，涵盖框架层、集合通信层和网络传输层，提供端到端的性能数据。 + +SimAI 使研究人员能够： + +- 分析推理/训练过程细节 +- 评估特定条件下 AI 任务的时间消耗 +- 评估各种算法优化带来的端到端性能提升（框架参数、集合通信算法、网络协议、拥塞控制、路由、拓扑等） + +--- + +## 文档概览 + +| 章节 | 说明 | +|------|------| +| [快速入门](getting_started/index.md) | 安装、环境搭建、快速开始 | +| [用户指南](user_guide/index.md) | SimAI-Analytical、SimAI-Simulation、SimAI-Physical、推理仿真的详细使用方法 | +| [组件详情](components/index.md) | 各子模块详细文档：AICB、SimCCL、astra-sim、ns-3、vidur | +| [技术参考](technical_reference/index.md) | GPU 显存模块、CLI 参数、配置文件参考 | +| [基准测试](benchmarking/index.md) | 四场景端到端测试套件及基准测试结果 | +| [开发者指南](developer_guide/index.md) | 架构、贡献指南、添加模型、扩展 NS-3 | +| [社区](community/index.md) | 活动、联系方式、引用 | + +--- + +## 系统架构 + +``` + |--- AICB （工作负载生成 & 计算性能分析） +SimAI --|--- SimCCL （集合通信算法分析） + |--- astra-sim-alibabacloud （仿真引擎：Analytical / Simulation / Physical） + |--- ns-3-alibabacloud （NS-3 网络后端） + |--- vidur-alibabacloud （多请求推理调度 & 显存管理） +``` + +![SimAI 架构图](../images/SimAI_Arc.png) + +--- + +## 三种运行模式 + +| 模式 | 说明 | 适用场景 | +|------|------|----------| +| **SimAI-Analytical** | 使用总线带宽（busbw）估算集合通信时间的快速仿真 | 性能分析、并行参数优化、scale-up 探索 | +| **SimAI-Simulation** | 使用 NS-3 网络后端的全栈仿真，提供细粒度网络建模 | CC 算法研究、网络协议评估、新架构设计 | +| **SimAI-Physical** *(Beta)* | 在 CPU RDMA 集群上生成物理流量 | NIC 行为研究 | + +--- + +## 支持的模型 + +- **DeepSeek-V3-671B** — MLA 注意力，256 个路由专家 +- **Qwen3-MoE-235B** — MHA/GQA，128 个路由专家 +- **Qwen3-Next-80B** — 混合全注意力 + 线性注意力，512 个路由专家 +- **Meta-Llama-3-8B / 70B**、**Llama-2-7b / 70b**、**CodeLlama-34b**、**InternLM-20B**、**Qwen-72B** + +--- + +## 快速链接 + +- [GitHub 仓库](https://github.com/aliyun/SimAI) +- [NSDI'25 论文 (PDF)](https://ennanzhai.github.io/pub/nsdi25spring-simai.pdf) +- [演示文稿](../../docs/SimAI_Intro_Online.pdf) +- [技术报告 (1.6)](../SimAI_1.6_Tech_Report.md) +- [贡献指南](../../CONTRIBUTING.md) diff --git a/docs/zh/technical_reference/cli_reference.md b/docs/zh/technical_reference/cli_reference.md new file mode 100644 index 00000000..3c1e1ad2 --- /dev/null +++ b/docs/zh/technical_reference/cli_reference.md @@ -0,0 +1,185 @@ +# CLI 参考 + +SimAI 所有工具的完整命令行参数参考。 + +--- + +## SimAI-Analytical + +**二进制**: `bin/SimAI_analytical` + +### 必需参数 + +| 标志 | 长格式 | 说明 | +|------|-----------|-------------| +| `-w` | `--workload` | 工作负载文件路径 | +| `-g` | `--gpus` | 仿真 GPU 规模 | +| `-g_p_s` | `--gpus-per-server` | Scale-up 大小（每服务器 GPU 数） | +| `-r` | `--result` | 输出文件路径和前缀（默认：`./results/`） | +| `-busbw` | `--bus-bandwidth` | busbw.yaml 文件路径 | + +### 可选参数 + +| 标志 | 长格式 | 说明 | +|------|-----------|-------------| +| `-v` | `--visual` | 生成可视化文件 | +| `-dp_o` | `--dp-overlap-ratio` | DP 重叠比例 [0.0-1.0] | +| `-ep_o` | `--ep-overlap-ratio` | EP 重叠比例 [0.0-1.0] | +| `-tp_o` | `--tp-overlap-ratio` | TP 重叠比例 [0.0-1.0] | +| `-pp_o` | `--pp-overlap-ratio` | PP 重叠比例 [0.0-1.0] | + +### 自动 Busbw 计算 + +| 标志 | 说明 | +|------|-------------| +| `-nv` | NVLink 带宽（GB/s） | +| `-nic` | NIC 带宽（GB/s） | +| `-n_p_s` | 每服务器 NIC 数 | + +--- + +## SimAI-Simulation + +**二进制**: `bin/SimAI_simulator` + +### 环境变量 + +| 变量 | 说明 | 默认值 | +|----------|-------------|---------| +| `AS_LOG_LEVEL` | 日志级别：DEBUG/INFO/WARNING/ERROR | `INFO` | +| `AS_PXN_ENABLE` | 启用 PXN | `0` | +| `AS_NVLS_ENABLE` | 启用 NVLS | `0` | +| `AS_SEND_LAT` | 发送延迟（us） | `6` | +| `AS_NVLSTREE_ENABLE` | 启用 NVLS Tree | `false` | + +### 参数 + +| 标志 | 长格式 | 说明 | 默认值 | +|------|-----------|-------------|---------| +| `-t` | `--thread` | 线程数 | `1` | +| `-w` | `--workload` | 工作负载路径 | 必需 | +| `-n` | `--network-topo` | 拓扑文件路径 | 必需 | +| `-c` | `--config` | SimAI.conf 路径 | 必需 | + +--- + +## SimAI-Physical + +**二进制**: `bin/SimAI_phynet` + +| 参数 | 说明 | 默认值 | +|-----------|-------------|---------| +| `hostlist` | 主机 IP 列表路径 | 必需 | +| `-w` / `--workload` | 工作负载文件路径 | `./microAllReduce.txt` | +| `-i` / `--gid_index` | RDMA 的 GID 索引 | `0` | +| `-g` / `--gpus` | GPU 数量 | `8` | + +--- + +## 拓扑生成器 + +**脚本**: `astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py` + +| 层级 | 标志 | 说明 | +|-------|------|-------------| +| 全局 | `-topo` | 模板：Spectrum-X / AlibabaHPN / DCN+ | +| | `-g` | GPU 数量 | +| | `--dp` | 启用双 Plane | +| | `--ro` | 启用 Rail-optimized | +| | `--dt` | 启用双 ToR | +| | `-er` | 错误率 | +| 服务器内 | `-gps` | 每服务器 GPU 数 | +| | `-gt` | GPU 型号（A100/H100） | +| | `-nsps` | 每服务器 NV Switch 数 | +| | `-nvbw` | NVLink 带宽 | +| | `-nl` | NVLink 延迟 | +| | `-l` | NIC 延迟 | +| Segment 内 | `-bw` | NIC 到 ASW 带宽 | +| | `-asw` | ASW 交换机数量 | +| | `-nps` | 每交换机 NIC 数 | +| Pod 内 | `-psn` | PSW 交换机数量 | +| | `-apbw` | ASW 到 PSW 带宽 | +| | `-app` | 每 PSW 的 ASW 数 | + +--- + +## AICB 工作负载生成器 + +**脚本**: `scripts/megatron_workload_with_aiob.sh` 或 `python -m workload_generator.SimAI_training_workload_generator` + +### 核心参数 + +| 参数 | 说明 | +|-----------|-------------| +| `--frame` | 框架：Megatron / DeepSpeed / DeepSeek | +| `-m` / `--model_size` | 模型大小：7/13/22/175/moe/deepseek | +| `--world_size` | 总 GPU 数量 | +| `--global_batch` | 总批量大小 | +| `--micro_batch` | 微批量大小 | +| `--seq_length` | 序列长度 | +| `--epoch_num` | 迭代次数 | + +### 并行参数 + +| 参数 | 说明 | +|-----------|-------------| +| `--tensor_model_parallel_size` | TP 度 | +| `--pipeline_model_parallel` | PP 度 | +| `--expert_model_parallel_size` | EP 度 | +| `--enable_sequence_parallel` | 启用 SP | + +### 模型参数 + +| 参数 | 说明 | +|-----------|-------------| +| `--num_layers` | Transformer 层数 | +| `--hidden_size` | 隐藏层大小 | +| `--num_attention_heads` | 注意力头数 | +| `--ffn_hidden_size` | FFN 隐藏层大小 | +| `--vocab_size` | 词表大小 | + +### MoE 参数 + +| 参数 | 说明 | +|-----------|-------------| +| `--moe_enable` | 启用 MoE | +| `--num_experts` | 专家数量 | +| `--moe_router_topk` | 每 Token 专家数 | +| `--moe_grouped_gemm` | 启用分组 GEMM | + +### DeepSeek 参数 + +| 参数 | 说明 | +|-----------|-------------| +| `--qk_rope_dim` | QK 的 RoPE 维度 | +| `--qk_nope_dim` | QK 的非 RoPE 维度 | +| `--q_lora_rank` | Q LoRA 秩 | +| `--kv_lora_rank` | KV LoRA 秩 | +| `--v_head_dim` | V Head 维度 | +| `--n_shared_expert` | 每 MoE 层共享专家数 | +| `--n_dense_layer` | 稠密层数 | + +### 优化参数 + +| 参数 | 说明 | +|-----------|-------------| +| `--use_flash_attn` | FlashAttention | +| `--swiglu` | SwiGLU 激活函数 | +| `--aiob_enable` | AIOB 计算 Profiling | +| `--comp_filepath` | 预计算时间文件 | + +--- + +## Vidur 推理仿真 + +**命令**: `python -m vidur.main` + +运行 `python -m vidur.main -h` 查看完整参数列表。关键参数见 [vidur 组件页面](../components/vidur.md)。 + +--- + +## 相关文档 + +- [配置文件参考](configuration.md) — 配置文件格式 +- [SimAI-Analytical 指南](../user_guide/simai_analytical.md) — 使用示例 +- [AICB 组件](../components/aicb.md) — 完整参数详情 diff --git a/docs/zh/technical_reference/configuration.md b/docs/zh/technical_reference/configuration.md new file mode 100644 index 00000000..6486f738 --- /dev/null +++ b/docs/zh/technical_reference/configuration.md @@ -0,0 +1,163 @@ +# 配置文件参考 + +本文档涵盖 SimAI 使用的所有配置文件。 + +--- + +## SimAI.conf + +**路径**: `astra-sim-alibabacloud/inputs/config/SimAI.conf` + +SimAI-Analytical 和 SimAI-Simulation 模式共用的主仿真配置文件，控制通信算法、缓冲区大小和时序参数。 + +--- + +## busbw.yaml + +**路径**: `example/busbw.yaml` + +SimAI-Analytical 使用，用于指定不同通信组和集合操作的总线带宽。 + +### 格式 + +```yaml +test +TP: + allreduce,: 300 # TP 组 AllReduce busbw 300GB/s + allgather,: 280 + reducescatter,: 280 + alltoall,: 230 +DP: + allreduce,: null # null = 该组不使用此操作 + allgather,: 380 + reducescatter,: 380 + alltoall,: null +EP: + allreduce,: null + allgather,: 45 + reducescatter,: 45 + alltoall,: 80 +``` + +### 通信组 + +| 组 | 说明 | +|-------|-------------| +| `TP` | 张量并行 — 服务器内 NVLink 通信 | +| `DP` | 数据并行 — 服务器间 RDMA 通信 | +| `EP` | 专家并行 — MoE 专家通信 | + +### 集合操作 + +| 操作 | 说明 | +|-----------|-------------| +| `allreduce` | 归约 + 广播到所有 Rank | +| `allgather` | 从所有 Rank 收集数据 | +| `reducescatter` | 归约并分发 | +| `alltoall` | 全对全个性化交换 | + +对特定组中不使用的操作，将值设为 `null`。 + +--- + +## 拓扑文件 + +由 `gen_Topo_Template.py` 生成，拓扑文件为 SimAI-Simulation 定义网络结构。 + +### 生成 + +```bash +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps +``` + +输出文件以参数命名，如 `Spectrum-X_128g_8gps_100Gbps_A100`。 + +### 模板默认值 + +| 模板 | GPU 数 | 拓扑 | 带宽 | GPU 型号 | +|----------|------|------|-----------|----------| +| Spectrum-X | 4096 | Rail-optimized，单 ToR | 400Gbps | H100 | +| AlibabaHPN（单 Plane） | 15360 | Rail-optimized，双 ToR | 200Gbps | H100 | +| AlibabaHPN（双 Plane） | 15360 | Rail-optimized，双 ToR，双 Plane | 200Gbps | H100 | +| DCN+（单 ToR） | 512 | 非 Rail-optimized | 400Gbps | A100 | +| DCN+（双 ToR） | 512 | 非 Rail-optimized，双 ToR | 200Gbps | H100 | + +--- + +## 模型配置文件 + +### 推理模型配置 + +位于 `vidur-alibabacloud/data/hf_configs/`： + +| 模型 | 配置文件 | +|-------|------------| +| DeepSeek-V3-671B | `deepseek_v3_config.json` | +| Qwen3-MoE-235B | `qwen3_moe_config.json` | +| Qwen3-Next-80B | `qwen3-next-80B-A3B_config.json` | + +这些文件遵循 HuggingFace `config.json` 格式，定义模型架构参数。 + +### Profiling 数据 + +位于 `vidur-alibabacloud/data/profiling/`： + +``` +profiling/ +├── compute/ +│ ├── a100/ +│ │ └── / +│ │ ├── mlp.csv +│ │ └── attention.csv +│ └── h100/ +│ └── / +│ ├── mlp.csv +│ └── attention.csv +└── network/ + ├── a100_pair_nvlink/ + │ ├── allreduce.csv + │ └── send_recv.csv + └── h100_dgx/ + ├── allreduce.csv + └── send_recv.csv +``` + +- **计算 Profiling**：仅依赖 GPU 型号（如 `a100`、`h100`），不依赖网络拓扑 +- **网络 Profiling**：依赖网络配置（如 `a100_pair_nvlink` vs `a100_dgx`） + +--- + +## 工作负载文件 + +### 训练工作负载格式 + +``` +HYBRID_TRANSFORMER_FWD_IN_BCKWD model_parallel_NPU_group: 8 ep: 1 pp: 1 vpp: 8 ga: 1 all_gpus: 32 checkpoints: 0 checkpoint_initiates: 0 +6 +embedding_layer -1 556000 ALLREDUCE 16777216 1 NONE 0 1 NONE 0 1 +... +``` + +头部字段： +- `model_parallel_NPU_group`：TP 大小 +- `ep`：EP 大小 +- `pp`：PP 大小 +- `vpp`：虚拟流水线并行 +- `ga`：梯度累积 +- `all_gpus`：总 GPU 数量 + +### 请求 Trace 文件 + +用于推理仿真，位于 `vidur-alibabacloud/data/processed_traces/`： + +- `splitwise_conv.csv` — 对话式 Trace +- `sharegpt_8k_filtered_stats_llama2_tokenizer.csv` — ShareGPT Trace + +--- + +## 相关文档 + +- [CLI 参考](cli_reference.md) — 命令行参数 +- [SimAI-Analytical 指南](../user_guide/simai_analytical.md) — busbw 配置使用 +- [SimAI-Simulation 指南](../user_guide/simai_simulation.md) — 拓扑配置使用 diff --git a/docs/zh/technical_reference/index.md b/docs/zh/technical_reference/index.md new file mode 100644 index 00000000..78eac060 --- /dev/null +++ b/docs/zh/technical_reference/index.md @@ -0,0 +1,13 @@ +# 技术参考 + +本节提供 SimAI 内部模块、CLI 参数和配置文件的详细技术规格与参考文档。 + +--- + +## 目录 + +| 文档 | 说明 | +|----------|-------------| +| [GPU 显存模块](memory_module.md) | ParamCounter、KV Cache 计算、MemoryPlanner | +| [CLI 参考](cli_reference.md) | 所有模式的完整命令行参数参考 | +| [配置文件参考](configuration.md) | SimAI.conf、busbw.yaml、拓扑文件和模型配置 | diff --git a/docs/zh/technical_reference/memory_module.md b/docs/zh/technical_reference/memory_module.md new file mode 100644 index 00000000..1949621c --- /dev/null +++ b/docs/zh/technical_reference/memory_module.md @@ -0,0 +1,155 @@ +# GPU 显存计算模块 + +GPU 显存计算模块（SimAI 1.6 引入）为推理仿真提供精确的 GPU 显存估算，涵盖模型参数显存、KV Cache 显存和最大批量大小计算。 + +--- + +## 架构 + +``` +ParamCounter (param_counter.py) + |-- 按层、按设备计算参数量 + |-- PD 分离下返回 (total_params, prefill_params, decode_params) + | +MemoryPlanner (memory_planner.py) + |-- 规划 GPU 显存预算 + |-- 计算 KV Cache 容量 + |-- 检测 OOM 条件 + | +Replica KV Cache Tracker (replica.py) + |-- 按请求分配/释放 + |-- 运行时容量查询 +``` + +--- + +## ParamCounter + +**文件**: `vidur-alibabacloud/vidur/utils/param_counter.py` + +### MLA 参数（DeepSeek-V3-671B） + +每层 MLA 参数组成： + +| 组件 | 公式 | DeepSeek-V3 值 | +|-----------|---------|-------------------| +| Q LoRA 下投影 | `hidden_size * q_lora_rank` | 7168 * 1536 | +| Q LoRA 上投影 | `q_lora_rank * num_heads * qk_head_dim` | 1536 * 128 * 192 | +| KV LoRA 下投影 | `hidden_size * kv_lora_rank` | 7168 * 512 | +| KV LoRA 上投影 | `kv_lora_rank * num_heads * (qk_nope_dim + v_head_dim)` | 512 * 128 * 256 | +| 输出投影 | `hidden_size * num_heads * v_head_dim` | 7168 * 128 * 128 | + +其中 `qk_head_dim = qk_nope_head_dim + qk_rope_head_dim = 128 + 64 = 192` + +### MHA/GQA 参数（Qwen3-MoE-235B） + +``` +wq = hidden_size * num_attention_heads * head_dim +wk = hidden_size * num_key_value_heads * head_dim +wv = hidden_size * num_key_value_heads * head_dim +wo = hidden_size * num_attention_heads * head_dim +total = (wq + wk + wv + wo) * bytes_per_element +``` + +### 线性注意力参数（Qwen3-Next-80B） + +Qwen3-Next-80B 使用混合注意力：全注意力和线性（GDN）注意力每 4 层交替。线性注意力层使用独立的 `linear_key_head_dim` / `linear_num_key_heads` 配置。 + +### MoE 专家参数 + +每专家 FFN（3 个权重矩阵 W1、W2、W3）： + +``` +expert_params = 3 * hidden_size * moe_intermediate_size * bytes_per_element +``` + +### PD 分离 + +PD 分离下，专家并行在不同集群间有差异： + +- **Prefill 集群**: `experts_per_device = num_routed_experts / prefill_world_size` +- **Decode 集群**: `experts_per_device = num_routed_experts / decode_world_size` + +返回三元组：`(total_params, prefill_params, decode_params)` + +--- + +## KV Cache 计算 + +### MHA/GQA KV Cache + +``` +kv_cache_per_token = 2 * num_kv_heads * head_dim * num_layers * bytes_per_element +``` + +因子 2 = K（Key）+ V（Value）缓存。 + +### MLA KV Cache（DeepSeek-V3-671B） + +MLA 使用压缩的 KV 表示——单个潜向量同时编码 K 和 V： + +``` +kv_cache_per_token = (kv_lora_rank + qk_rope_head_dim) * num_layers * bytes_per_element +``` + +其中 `kv_lora_rank = 512`、`qk_rope_head_dim = 64`。 + +**对比**：MHA 每 Token 需要 `2 * 128 * 128 = 32768` 个元素。MLA 仅需 `576` 个元素——**约 57 倍压缩**。 + +### 按请求 KV Cache 追踪 + +`Replica` 实体维护： + +| 状态 | 说明 | +|-------|-------------| +| `_allocated_kv_cache_memory` | 当前已分配的 KV Cache（字节） | +| `_max_kv_cache_memory` | 最大 KV Cache 容量 | +| `_kv_cache_allocation_map` | 按请求的分配映射 | + +操作： +- `allocate_request_kv_cache_memory(request, num_blocks, block_size)` +- `release_request_kv_cache_memory(request)` +- `get_remaining_kv_cache_capacity()` + +--- + +## MemoryPlanner + +**文件**: `vidur-alibabacloud/vidur/scheduler/utils/memory_planner.py` + +### 计算流程 + +1. **可用 GPU 显存**: `available = 总GPU显存 * (1 - memory_margin_fraction)` +2. **参数显存**: 通过 ParamCounter 计算；PD 返回 `(total, prefill, decode)` +3. **KV Cache 预算**: `kv_available = available - param_memory` +4. **最大并发请求**: `max_requests = kv_available / kv_cache_per_request` + +### PD 分离 + +- Prefill 副本：使用 `prefill_param_mem` 计算预算 +- Decode 副本：使用 `decode_param_mem` 计算预算 + +### OOM 检测 + +当 `param_memory > available_memory` 时，输出错误并给出建议： +- 增加 TP/EP 度 +- 使用更大 GPU（更多显存） +- 启用 FP8 量化 + +--- + +## 量化支持 + +| 精度 | 每元素字节数 | 使用场景 | +|-----------|-------------------|----------| +| FP32 | 4 | 参考基准 | +| FP16/BF16 | 2 | 默认推理 | +| FP8 | 1 | 降低显存，ParamCounter 支持 | + +--- + +## 相关文档 + +- [vidur-alibabacloud 组件](../components/vidur.md) — 完整组件文档 +- [支持的模型](../user_guide/supported_models.md) — 模型规格 +- [SimAI 1.6 技术报告](../../SimAI_1.6_Tech_Report.md) — 详细技术报告 diff --git a/docs/zh/user_guide/index.md b/docs/zh/user_guide/index.md new file mode 100644 index 00000000..75013786 --- /dev/null +++ b/docs/zh/user_guide/index.md @@ -0,0 +1,25 @@ +# 用户指南 + +本章节提供 SimAI 各运行模式的详细使用说明。 + +## 目录 + +| 页面 | 说明 | +|------|------| +| [SimAI-Analytical](simai_analytical.md) | 使用总线带宽的快速分析仿真 | +| [SimAI-Simulation](simai_simulation.md) | 使用 NS-3 网络后端的全栈仿真与拓扑配置 | +| [SimAI-Physical](simai_physical.md) | 在真实集群上生成物理 RDMA 流量 | +| [推理仿真](inference_simulation.md) | 支持 PD 分离的多请求 LLM 推理仿真 | +| [工作负载生成](workload_generation.md) | 使用 AICB 生成训练和推理工作负载 | +| [支持的模型](supported_models.md) | 支持的模型完整列表及配置 | +| [结果分析](result_analysis.md) | 仿真结果分析与可视化 | + +## 工作流程概览 + +典型的 SimAI 工作流程包含三个步骤： + +1. 使用 [AICB](workload_generation.md) **生成工作负载** — 定义计算和通信模式 +2. 使用三种模式之一（Analytical、Simulation 或 Physical）**运行仿真** +3. 使用内置工具或自定义脚本**分析结果** + +推理仿真的工作流程使用 Vidur 进行请求调度和内存管理，AICB 或 SimAI 作为执行时间预测后端。 diff --git a/docs/zh/user_guide/inference_simulation.md b/docs/zh/user_guide/inference_simulation.md new file mode 100644 index 00000000..c6723ab4 --- /dev/null +++ b/docs/zh/user_guide/inference_simulation.md @@ -0,0 +1,151 @@ +# 多请求推理仿真 + +SimAI 支持完整的多请求 LLM 推理仿真，提供端到端的推理服务系统性能评估，支持 Prefill-Decode (PD) 分离架构。 + +--- + +## 概述 + +推理仿真流水线组合了多个 SimAI 组件： + +- **[AICB](../components/aicb.md)** — 生成推理工作负载和计算时间分析 +- **[vidur-alibabacloud](../components/vidur.md)** — 请求调度、显存管理和指标收集 +- **[astra-sim-alibabacloud](../components/astra_sim.md)** — 仿真引擎（Analytical 或 Simulation 模式） +- **[SimCCL](../components/simccl.md)** — 集合通信转换 + +--- + +## Prefill-Decode (PD) 分离 + +推理过程分为两个阶段： + +| 阶段 | 特征 | 说明 | +|------|------|------| +| **Prefill** | 计算密集 | 处理所有输入 prompt token，生成第一个输出 token | +| **Decode** | 内存带宽密集 | 逐个自回归生成后续输出 token | + +PD 分离允许将这两个阶段部署在不同的 GPU 节点上： + +- **弹性资源分配** — Prefill 节点可配置更多算力，Decode 节点可配置更多显存 +- **性能隔离** — 避免阶段间的资源竞争 +- **灵活 P:D 比例** — 通过 `--replica_config_pd_node_ratio` 配置 + +--- + +## 请求调度 + +调度组件改编自微软 [Vidur](https://github.com/microsoft/vidur)，支持多种策略： + +| 调度器 | 级别 | 说明 | +|--------|------|------| +| `split_wise` | 全局 | PD 分离感知调度，将请求分发到 Prefill 和 Decode 副本 | +| `lor` | 全局 | 最少未完成请求——分发到负载最轻的副本 | +| `round_robin` | 全局 | 轮询分发 | +| `sarathi` | 副本级 | 副本内批量调度 | +| `split_wise` | 副本级 | PD 分离的副本级调度 | + +--- + +## 并行策略 + +支持多种并行策略组合： + +| 策略 | 参数 | 说明 | +|------|------|------| +| **数据并行 (DP)** | `--cluster_config_num_replicas` | 副本数量 | +| **张量并行 (TP)** | `--replica_config_tensor_parallel_size` | 节点内并行 | +| **流水线并行 (PP)** | `--replica_config_num_pipeline_stages` | 阶段间并行 | +| **专家并行 (EP)** | `--replica_config_expert_model_parallel_size` | MoE 专家并行 | + +适用于稠密模型和 MoE（混合专家）模型。 + +--- + +## 执行时间预测后端 + +| 后端 | 参数值 | 说明 | +|------|--------|------| +| **AICB/AIOB** | `aicb` | 支持 DeepSeek-V3、Qwen3-MoE、Qwen3-Next 的计算核和 TP/DP/PP/EP 通信量建模 | +| **SimAI Simulation** | `simai_simulation` | 基于 NS-3 的全栈网络仿真（当前支持 TP） | +| **SimAI Analytical** | `simai_analytical` | 分析性能模型（当前支持 TP） | +| **原生 Vidur** | `vidur` | 原版 Vidur 后端，支持 TP、DP、PP | + +通过 `--random_forrest_execution_time_predictor_config_backend` 设置。 + +--- + +## 快速开始 + +### 前置条件 + +- **AICB 后端**：SimAI Docker 环境 + Hopper (SM90) 或 Blackwell (SM100) GPU +- **SimAI 后端**：先编译 SimAI-Analytical 或 SimAI-Simulation +- **Vidur 后端**：Conda 环境 + profiling 数据 + +### 使用 AICB 后端运行 + +```bash +cd SimAI/vidur-alibabacloud + +python -m vidur.main \ + --replica_config_model_name deepseek-671B \ + --replica_config_tensor_parallel_size 2 \ + --replica_config_expert_model_parallel_size 8 \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 5 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 1024 \ + --fixed_request_length_generator_config_decode_tokens 10 \ + --random_forrest_execution_time_predictor_config_backend aicb +``` + +### 运行四场景测试套件 + +```bash +# 运行全部 4 个预配置场景 +bash examples/vidur-ali-scenarios/run_scenarios.sh --all + +# 运行单个场景 +bash examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 +``` + +--- + +## 四场景配置 + +**共享硬件**：H20 GPU (h20_dgx)，NVLink 1600 Gbps，RDMA 800 Gbps，PD P2P 800 Gbps（fp8） + +| 场景 | 模型 | PD 分离 | World Size | TP | EP | 调度器 | +|------|------|---------|-----------|----|----|--------| +| 1 | Qwen3-Next-80B | 否 | 32 (dp=32) | 1 | 1 | lor | +| 2 | Qwen3-Next-80B | 是（P=2, D=6） | 8 | 1 | 1 | split_wise | +| 3 | DeepSeek-671B | 是（P=2, D=6） | 8 | 8 | 8 | split_wise | +| 4 | Qwen3-MoE-235B | 是（P=2, D=6） | 8 | 4 | 4 | split_wise | + +--- + +## 输出 + +每次仿真运行生成： + +``` +// +├── request_metrics.csv # 逐请求指标 +├── chrome_trace.json # Chrome DevTools 时间线追踪 +├── config.json # 配置快照 +└── plots/ # 各指标 CSV/JSON 文件 +``` + +输出解读请参见[结果分析](result_analysis.md)。 + +--- + +## 相关文档 + +- [vidur-alibabacloud 组件](../components/vidur.md) — 完整推理仿真文档 +- [支持的模型](supported_models.md) — 模型兼容性矩阵 +- [结果分析](result_analysis.md) — 输出解读指南 diff --git a/docs/zh/user_guide/result_analysis.md b/docs/zh/user_guide/result_analysis.md new file mode 100644 index 00000000..cec5ab78 --- /dev/null +++ b/docs/zh/user_guide/result_analysis.md @@ -0,0 +1,183 @@ +# 结果分析与可视化 + +本指南介绍如何解读和分析 SimAI 各模式的仿真输出。 + +--- + +## SimAI-Analytical 输出 + +### CSV 输出 + +运行 SimAI-Analytical 后会在 `results/` 目录生成 CSV 文件，包含： + +- **汇总行**：暴露时间、各通信组的计算时间（绝对值和百分比）、端到端迭代时间 +- **逐层行**：每层的详细操作时间 + +关键列包含各通信组（TP、DP、EP、PP）的分解，展示时间分配和重叠效果。 + +### 可视化 + +使用 `-v` 参数运行时，SimAI-Analytical 会生成额外的可视化文件，展示各通信组的时间分解。 + +```bash +# 启用可视化运行 +./bin/SimAI_analytical -w example/workload_analytical.txt -g 9216 -g_p_s 8 -r test- -busbw example/busbw.yaml -v +``` + +--- + +## SimAI-Simulation 输出 + +SimAI-Simulation（NS-3 模式）生成详细的追踪数据，捕获细粒度的网络行为。NS-3 后端输出 `.tr` 追踪文件，可使用提供的分析工具进行分析。 + +### 分析工具 + +位于 `ns-3-alibabacloud/analysis/`： + +| 工具 | 说明 | +|------|------| +| `fct_analysis.py` | 流完成时间（FCT）分析——读取 FCT 输出文件并生成统计数据 | +| `trace_reader` | 解析 `.tr` 追踪文件，支持过滤 | + +### 使用 trace_reader + +```bash +# 编译 +cd ns-3-alibabacloud/analysis +make trace_reader + +# 解析追踪文件 +./trace_reader <.tr 文件> [过滤表达式] + +# 示例： +./trace_reader output.tr "time > 2000010000" +./trace_reader output.tr "sip=0x0b000101&dip=0x0b000201" +``` + +### 追踪输出格式 + +追踪输出每行格式如下： + +``` +2000055540 n:338 4:3 100608 Enqu ecn:0 0b00d101 0b012301 10000 100 U 161000 0 3 1048(1000) +``` + +字段：时间戳（ns）、节点 ID、端口:队列、队列长度（字节）、事件类型、ECN 标志、源 IP、目的 IP、源端口、目的端口、包类型、序列号、发送时间戳、优先级组、包大小（有效负载）。 + +--- + +## 推理仿真输出 + +### 输出目录结构 + +每次推理仿真运行生成： + +``` +// +├── request_metrics.csv # 逐请求指标 +├── chrome_trace.json # Chrome DevTools 时间线追踪 +├── config.json # 配置快照 +└── plots/ # 各指标 CSV/JSON 文件 + ├── request_e2e_time.csv + ├── prefill_e2e_time.csv + ├── pd_p2p_comm_time.csv + ├── replica_N_memory_usage.json + └── ... +``` + +### request_metrics.csv 列说明 + +| 列名 | 含义 | +|------|------| +| `arrived_at` | 请求进入系统的时间戳（秒） | +| `scheduled_at` | 请求首次被调度的时间戳（秒） | +| `prefill_completed_at` | Prefill 完成并生成第一个 token 的时间戳 | +| `decode_arrived_at` | Decode 阶段开始的时间戳 | +| `decode_time` | Decode 阶段持续时间（秒） | +| `prefill_replica_id` | 执行 Prefill 的副本 ID（PD 模式） | +| `decode_replica_id` | 执行 Decode 的副本 ID（PD 模式） | +| `request_num_prefill_tokens` | 输入 token 数（prompt 长度） | +| `request_num_decode_tokens` | 输出 token 数（生成长度） | +| `pd_p2p_comm_size` | Prefill 到 Decode 节点的 P2P 通信大小（字节） | +| `pd_p2p_comm_time` | P2P 通信时间（秒） | +| `completed_at` | 请求完成时间戳 | +| `request_execution_time` | 总执行时间（不含延迟，秒） | +| `request_preemption_time` | 因抢占/气泡导致的等待时间（秒） | +| `request_scheduling_delay` | 调度延迟：`scheduled_at - arrived_at`（秒） | +| `request_e2e_time` | 端到端延迟：`completed_at - arrived_at`（秒） | +| `prefill_e2e_time` | 首 token 时间（TTFT）：`prefill_completed_at - arrived_at`（秒） | +| `tbt` | token 间时间：`decode_time / request_num_decode_tokens`（秒/token） | + +### Chrome Trace 可视化 + +在 Chrome DevTools 中打开 `chrome_trace.json` 进行可视化时间线分析： + +1. 打开 Chrome 浏览器 +2. 访问 `chrome://tracing` +3. 加载 `chrome_trace.json` 文件 + +### 仿真指标（23 项） + +仿真器记录 23 项细粒度指标： + +| 类别 | 指标 | +|------|------| +| **请求延迟** | E2E 时间 CDF、归一化 E2E CDF、执行+抢占 CDF | +| **调度** | 调度延迟 CDF | +| **执行** | 执行时间 CDF、抢占时间 CDF | +| **Token 级** | Decode token 执行+抢占时间、token 间延迟 | +| **批次** | 批次 token 数 CDF、批次大小 CDF | +| **Prefill** | Prefill E2E CDF、Prefill 执行+抢占 CDF（归一化） | +| **Decode** | Decode 执行+抢占归一化 CDF | +| **时间序列** | 请求/Prefill/Decode 完成、请求到达 | +| **逐副本** | 显存使用（加权均值）、繁忙时间百分比、MFU | + +详细指标定义请参见 [vidur 指标文档](../components/vidur.md)。 + +--- + +## AICB 物理执行输出 + +### 日志输出 + +每次通信后，AICB 输出： +- 通信类型和组 +- 消息大小 +- 执行时间 +- 吞吐量（algbw 和 busbw） + +### 迭代汇总 + +所有通信完成后，汇总显示： +- 总运行时间和每次迭代的时间 +- 按通信类型的统计（消息大小、频率、延迟最小/最大/平均值） + +### CSV 输出 + +结果保存在 `results/comm_logs/`： +- `<模型>_<配置>_log.csv` — 执行日志（包含时间、阶段、algbw、busbw 等） +- `<模型>_<配置>_workload.csv` — 生成的工作负载描述 + +### 编程分析 + +```python +# 读取工作负载日志 +from log_analyzer.log import Workload +workload, args = Workload.load("results/comm_logs/megatron_gpt_13B_8n_workload.csv") + +# 读取执行日志 +from log_analyzer.log import Log +log = Log.load("results/comm_logs/megatron_gpt_13B_8n_log.csv") +# log.comm_logs: List[LogItem] +# log.epoch_times: List[int] +# log.comm_log_each_epoch: List[List[LogItem]] +``` + +--- + +## 相关文档 + +- [SimAI-Analytical](simai_analytical.md) — Analytical 模式用法 +- [SimAI-Simulation](simai_simulation.md) — NS-3 仿真模式用法 +- [推理仿真](inference_simulation.md) — 推理仿真指南 +- [NS-3 组件](../components/ns3.md) — NS-3 分析工具 diff --git a/docs/zh/user_guide/simai_analytical.md b/docs/zh/user_guide/simai_analytical.md new file mode 100644 index 00000000..4f47a85f --- /dev/null +++ b/docs/zh/user_guide/simai_analytical.md @@ -0,0 +1,104 @@ +# SimAI-Analytical + +SimAI-Analytical 通过总线带宽（busbw）抽象网络通信细节来估算集合通信时间，提供快速仿真。适用于快速场景验证和性能分析。 + +## 适用场景 + +- **性能分析**：比较不同模型的完成时间（如专家数对 MoE 训练的影响） +- **并行参数优化**：平衡和优化 TP/EP/PP 参数 +- **Scale-up 探索**：研究不同 scale-up 域下的并行参数性能 +- **Scale-out 带宽选择**：研究高性价比的带宽配置 + +## 工作负载生成 + +使用 [AICB](workload_generation.md) 生成工作负载： + +```bash +sh ./aicb/scripts/megatron_workload_with_aiob.sh \ + -m 7 --world_size 4096 \ + --tensor_model_parallel_size 2 --pipeline_model_parallel 1 \ + --frame Megatron --global_batch 8192 \ + --micro_batch 1 --seq_length 4096 \ + --swiglu --use_flash_attn --aiob_enable +``` + +生成的 `.txt` 工作负载文件包含： +- `model_parallel_NPU_group`：张量并行度 +- `ep`：专家模型并行度 +- `pp`：流水线并行度 +- `vpp`：虚拟流水线并行度 + +> 更多信息参见 [AICB 工作负载生成](workload_generation.md) 和 [AICB 组件文档](../components/aicb.md)。 + +## Busbw 配置 + +SimAI-Analytical 使用 `busbw.yaml` 文件为不同通信组指定总线带宽： + +```yaml +test +TP: + allreduce,: 300 # TP 组内 AllReduce busbw 300GB/s + allgather,: 280 + reducescatter,: 280 + alltoall,: 230 +DP: + allreduce,: null + allgather,: 380 # DP 组内 AllGather busbw 380GB/s + reducescatter,: 380 + alltoall,: null +EP: + allreduce,: null + allgather,: 45 + reducescatter,: 45 + alltoall,: 80 # EP 组内 AlltoAll busbw 80GB/s +``` + +## 运行 Analytical 仿真 + +```bash +./bin/SimAI_analytical \ + -w example/workload_analytical.txt \ + -g 9216 \ + -g_p_s 8 \ + -r test- \ + -busbw example/busbw.yaml +``` + +### 必选参数 + +| 参数 | 长格式 | 说明 | +|:----:|:-------|:-----| +| `-w` | `--workload` | 工作负载文件路径 | +| `-g` | `--gpus` | 仿真 GPU 规模 | +| `-g_p_s` | `--gpus-per-server` | Scale-up 大小（每服务器 GPU 数） | +| `-r` | `--result` | 输出文件路径和前缀（默认：`./results/`） | +| `-busbw` | `--bus-bandwidth` | busbw 文件路径 | + +### 可选参数 + +| 参数 | 长格式 | 说明 | +|:----:|:-------|:-----| +| `-v` | `--visual` | 生成可视化文件 | + +### 重叠比例 + +| 参数 | 长格式 | 说明 | 范围 | +|:----:|:-------|:-----|:-----| +| `-dp_o` | `--dp-overlap-ratio` | DP 重叠比例 | [0.0-1.0] | +| `-ep_o` | `--ep-overlap-ratio` | EP 重叠比例 | [0.0-1.0] | +| `-tp_o` | `--tp-overlap-ratio` | TP 重叠比例 | [0.0-1.0] | +| `-pp_o` | `--pp-overlap-ratio` | PP 重叠比例 | [0.0-1.0] | + +## 结果分析 + +运行 SimAI-Analytical 后生成的 CSV 文件包含： +- 汇总行：暴露时间、各通信组的计算时间百分比、端到端迭代时间 +- 逐层操作详情 + +![原始输出](../../images/simai_raw.png) + +指定 `-v` 参数后还会生成可视化文件： + +![可视化](../../images/simai_visual.png) + +更多结果分析方法请参考[结果分析](result_analysis.md)。 diff --git a/docs/zh/user_guide/simai_physical.md b/docs/zh/user_guide/simai_physical.md new file mode 100644 index 00000000..7a19f651 --- /dev/null +++ b/docs/zh/user_guide/simai_physical.md @@ -0,0 +1,113 @@ +# SimAI-Physical 模式 + +> **状态**：Beta — 目前处于内部测试阶段。 + +SimAI-Physical 在 CPU RDMA 集群环境中生成物理流量。该模式生成类 NCCL 的流量模式，用于深入研究 LLM 训练过程中的 NIC 行为。 + +--- + +## 概述 + +与 SimAI-Analytical 和 SimAI-Simulation 完全在软件中仿真不同，SimAI-Physical 将真实的 RDMA 流量注入物理网络。可用于： + +- 研究真实 LLM 训练流量模式下的 NIC 行为 +- 在真实硬件上验证网络配置 +- 使用典型集合通信工作负载进行 RDMA 性能基准测试 + +**组件组合**：[AICB](../components/aicb.md) + [SimCCL](../components/simccl.md) + [astra-sim-alibabacloud](../components/astra_sim.md)（物理模式） + +--- + +## 前置条件 + +SimAI-Physical 使用 RoCEv2 协议生成流量。编译前请确保： + +- **RDMA 支持**：可用的 `libibverbs` / RDMA 设备驱动 +- **MPI**：已安装并可运行 OpenMPI +- **验证**：能成功运行 `ib_write_bw` 等 RDMA 性能测试工具 + +--- + +## 编译 + +```bash +# 克隆和初始化 +git clone https://github.com/aliyun/SimAI.git +cd SimAI/ +git submodule update --init --recursive +git submodule update --remote + +# 安装 MPI（CentOS/RHEL） +sudo yum install openmpi openmpi-devel + +# 设置 MPI 路径 +export MPI_INCLUDE_PATH=/usr/include/openmpi-x86_64/ +export MPI_BIN_PATH=/usr/lib64/openmpi/bin/mpic++ + +# 编译 SimAI-Physical +./scripts/build.sh -c phy +``` + +--- + +## 工作负载生成 + +SimAI-Physical 使用与 SimAI-Simulation 相同的工作负载格式，通过 [AICB](../components/aicb.md) 生成。详见[工作负载生成](workload_generation.md)。 + +--- + +## 准备主机列表 + +为 MPI 程序准备 IP 列表文件。IP 数量需与参与物理流量生成的 NIC 数量一致（非节点数）。 + +``` +33.255.199.130 +33.255.199.129 +``` + +--- + +## 运行 + +### MPI 执行 + +```bash +/usr/lib64/openmpi/bin/mpirun -np 2 \ + -host 33.255.199.130,33.255.199.129 \ + --allow-run-as-root \ + -x AS_LOG_LEVEL=0 \ + ./bin/SimAI_phynet ./hostlist -g 2 -w ./example/microAllReduce.txt +``` + +### MPI 参数 + +| 参数 | 说明 | 默认值 | +|------|------|--------| +| `-np` | 进程数 | 必填 | +| `-host` | 逗号分隔的 IP 列表 | 必填 | +| `--allow-run-as-root` | 允许以 root 运行 | `FALSE` | + +### SimAI-Physical 参数 + +| 参数 | 说明 | 默认值 | +|------|------|--------| +| `hostlist` | 主机 IP 列表文件路径 | 必填 | +| `-w` / `--workload` | 工作负载文件路径 | `./microAllReduce.txt` | +| `-i` / `--gid_index` | RDMA 设备 GID 索引 | `0` | +| `-g` / `--gpus` | GPU 数量（须与 hostlist 中 IP 数一致） | `8` | + +--- + +## 注意事项 + +- GPU 数量（`-g`）必须与主机 IP 列表中的 IP 数一致 +- 确保所有节点具有网络连通性且 RDMA 已正确配置 +- SimAI-Physical 目前为 Beta 版本；部分功能可能在后续版本中变更 + +--- + +## 相关文档 + +- [AICB 组件](../components/aicb.md) — 工作负载生成 +- [SimCCL 组件](../components/simccl.md) — 集合通信转换 +- [astra-sim 组件](../components/astra_sim.md) — 仿真引擎详情 diff --git a/docs/zh/user_guide/simai_simulation.md b/docs/zh/user_guide/simai_simulation.md new file mode 100644 index 00000000..d6377c60 --- /dev/null +++ b/docs/zh/user_guide/simai_simulation.md @@ -0,0 +1,113 @@ +# SimAI-Simulation + +SimAI-Simulation 使用 NS-3 作为网络后端，提供高保真的全栈仿真和细粒度网络通信建模。适用于集合通信算法、网络协议和新型网络架构的深入研究。 + +## 适用场景 + +- **集合通信算法研究**：设计和优化非交换机架构下的流量模式 +- **网络协议研究**：评估拥塞控制、路由机制和底层协议 +- **新型网络架构设计**：探索创新的网络拓扑和配置 + +## 工作负载生成 + +使用与 SimAI-Analytical 相同的工作负载，由 [AICB](workload_generation.md) 生成。 + +## 网络拓扑配置 + +运行 SimAI-Simulation 之前，需要生成 ns-3-alibabacloud 识别的拓扑文件。 + +### 拓扑模板 + +SimAI 提供 5 种常见架构模板： + +| 模板 | 说明 | 默认 GPU 数 | +|------|------|-------------| +| `Spectrum-X` | Rail-optimized，单 ToR，单 Plane | 4096 | +| `AlibabaHPN`（单 Plane） | Rail-optimized，双 ToR，单 Plane | 15360 | +| `AlibabaHPN`（双 Plane） | Rail-optimized，双 ToR，双 Plane | 15360 | +| `DCN+`（单 ToR） | 非 Rail-optimized，单 ToR | 512 | +| `DCN+`（双 ToR） | 非 Rail-optimized，双 ToR | 512 | + +![Spectrum-X](../../images/Spectrum-X.jpg) + +### 生成拓扑 + +```bash +# 8 GPU 的 Spectrum-X 拓扑 +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 8 -psn 1 + +# 64 GPU 的双 Plane AlibabaHPN 拓扑 +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo AlibabaHPN --dp -g 64 -asn 16 -psn 16 + +# 128 GPU 的双 ToR DCN+ 拓扑 +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo DCN+ --dt -g 128 -asn 2 -psn 8 + +# 自定义 Rail-optimized 拓扑 +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -g 32 -bw 200Gbps -gt A100 -psn 8 --ro +``` + +### 拓扑参数 + +| 层级 | 参数 | 说明 | +|------|------|------| +| 整体结构 | `-topo` | 模板名称 | +| | `-g` | GPU 数量 | +| | `--dp` | 启用双 Plane | +| | `--ro` | 启用 Rail-optimized | +| | `--dt` | 启用双 NIC 和双 ToR | +| | `-er` | 错误率 | +| 服务器内 | `-gps` | 每服务器 GPU 数 | +| | `-gt` | GPU 类型 | +| | `-nvbw` | NVLink 带宽 | +| | `-nl` | NVLink 延迟 | +| | `-l` | NIC 延迟 | +| Segment 内 | `-bw` | NIC 到 ASW 带宽 | +| | `-asw` | ASW 交换机数量 | +| | `-nps` | 每交换机 NIC 数 | +| Pod 内 | `-psn` | PSW 交换机数量 | +| | `-apbw` | ASW 到 PSW 带宽 | +| | `-app` | 每 PSW 的 ASW 数 | + +> 详细拓扑参数和各模板默认值请参见 [astra-sim 组件文档](../components/astra_sim.md)。 + +## 运行 NS-3 仿真 + +```bash +AS_SEND_LAT=3 AS_NVLS_ENABLE=1 ./bin/SimAI_simulator \ + -t 16 \ + -w ./example/microAllReduce.txt \ + -n ./Spectrum-X_8g_8gps_400Gbps_H100 \ + -c astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +### 环境变量 + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `AS_LOG_LEVEL` | 日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR` | `INFO` | +| `AS_PXN_ENABLE` | 启用 PXN（`0`/`1`） | `0` | +| `AS_NVLS_ENABLE` | 启用 NVLS（`0`/`1`） | `0` | +| `AS_SEND_LAT` | 数据包发送延迟（us） | `6` | +| `AS_NVLSTREE_ENABLE` | 启用 NVLSTREE | `false` | + +### 仿真参数 + +| 参数 | 说明 | 默认值 | +|------|------|--------| +| `-t` / `--thread` | 线程数（推荐 8-16） | `1` | +| `-w` / `--workload` | 工作负载文件路径 | `./microAllReduce.txt` | +| `-n` / `--network-topo` | 网络拓扑路径 | 无 | +| `-c` / `--config` | SimAI 配置文件 | 无 | + +## 示例：RING vs NVLS 对比 + +请参阅 [Tutorial](../../docs/Tutorial.md#ring-vs-nvls) 了解 RING 和 NVLS 算法在不同消息大小下的完整对比。 + +## 延伸阅读 + +- [NS-3 组件文档](../components/ns3.md) — NS-3 模块详细参考 +- [结果分析](result_analysis.md) — 仿真输出分析 diff --git a/docs/zh/user_guide/supported_models.md b/docs/zh/user_guide/supported_models.md new file mode 100644 index 00000000..1a6913e2 --- /dev/null +++ b/docs/zh/user_guide/supported_models.md @@ -0,0 +1,133 @@ +# 支持的模型 + +SimAI 支持多种 LLM 模型的训练和推理仿真。 + +--- + +## 推理模型（SimAI 1.5+） + +以下模型通过 vidur-alibabacloud 支持多请求推理仿真，包含 GPU 显存计算、PD 分离和工作负载生成支持。 + +### DeepSeek-V3-671B + +| 属性 | 值 | +|------|------| +| **总层数** | 61 | +| **注意力类型** | MLA（多头潜在注意力） | +| **注意力头数** | 128 | +| **隐藏维度** | 7168 | +| **KV LoRA 秩** | 512 | +| **Q LoRA 秩** | 1536 | +| **QK RoPE Head Dim** | 64 | +| **QK NoPE Head Dim** | 128 | +| **V Head Dim** | 128 | +| **MoE 路由专家数** | 256 | +| **每 token 激活专家数** | 8 | +| **共享专家数** | 1 | +| **稠密层** | 前 3 层（固定激活 8 个路由 + 1 个共享专家） | +| **稀疏层** | 第 3-60 层（从 256 个路由专家中动态选择 8 个 + 1 个共享专家） | +| **配置文件** | `vidur-alibabacloud/data/hf_configs/deepseek_v3_config.json` | + +### Qwen3-MoE-235B + +| 属性 | 值 | +|------|------| +| **总层数** | 94 | +| **注意力类型** | MHA / GQA | +| **注意力头数** | 64 | +| **KV 头数** | 4 | +| **隐藏维度** | 4096 | +| **Head Dim** | 128 | +| **MoE 路由专家数** | 128 | +| **每 token 激活专家数** | 8 | +| **MoE 中间维度** | 1536 | +| **配置文件** | `vidur-alibabacloud/data/hf_configs/qwen3_moe_config.json` | + +### Qwen3-Next-80B + +| 属性 | 值 | +|------|------| +| **总层数** | 48 | +| **注意力类型** | 混合（全注意力 + 线性注意力，每 4 层交替） | +| **全注意力头数** | 16 | +| **KV 头数** | 2 | +| **隐藏维度** | 2048 | +| **Head Dim** | 256 | +| **线性注意力 Key 头数** | 16 | +| **线性注意力 Value 头数** | 32 | +| **MoE 路由专家数** | 512 | +| **每 token 激活专家数** | 10 | +| **MoE 中间维度** | 512 | +| **配置文件** | `vidur-alibabacloud/data/hf_configs/qwen3-next-80B-A3B_config.json` | + +### 传统推理模型（通过 Vidur 后端） + +以下模型使用原版 Vidur 基于 profiling 的后端： + +| 模型 | TP 支持 | PP 支持 | +|------|---------|---------| +| meta-llama/Meta-Llama-3-8B | 是 | 是 | +| meta-llama/Meta-Llama-3-70B | 是 | 是 | +| meta-llama/Llama-2-7b-hf | 是 | 是 | +| meta-llama/Llama-2-70b-hf | 是 | 是 | +| codellama/CodeLlama-34b-Instruct-hf | 是 | 是 | +| internlm/internlm-20b | 是 | 是 | +| Qwen/Qwen-72B | 是 | 是 | + +--- + +## 训练模型（AICB） + +以下模型支持训练工作负载生成： + +### AICB 基准测试套件 + +| ID | 模型 | 序列长度 | 框架 | TP | PP | SP | MoE | +|----|------|----------|------|----|----|-----|-----| +| 1 | LLaMA-7B | 2048 | Megatron | 1 | 1 | - | - | +| 2 | GPT-13B | 2048 | Megatron | 2 | 1 | 是 | - | +| 3 | GPT-22B | 2048 | Megatron | 4 | 1 | - | - | +| 4 | LLaMA-65B | 4096 | Megatron | 8 | 2 | 是 | - | +| 5 | GPT-175B | 2048 | Megatron | 8 | 8 | 是 | - | +| 6 | GPT-175B | 2048 | Megatron | 8 | 8 | - | - | +| 7 | Llama3-405B | 8192 | Megatron | 8 | 16 | 是 | - | +| 8 | LLaMA-7B | 4096 | DeepSpeed | 1 | 1 | - | Zero-2 | +| 9 | LLaMA-65B | 4096 | DeepSpeed | 1 | 1 | - | Zero-3 | +| 10 | Mistral-8x7B | 2048 | Megatron | 2 | 1 | 是 | 8 专家 | + +--- + +## 注意力架构对比 + +| 架构 | 模型 | KV Cache 策略 | 内存效率 | +|------|------|-------------|----------| +| **MLA** | DeepSeek-V3-671B | 压缩潜向量（`kv_lora_rank` + `qk_rope_head_dim`） | 相比 MHA 约 57 倍缩减 | +| **MHA / GQA** | Qwen3-MoE-235B | 标准 KV 缓存（`num_kv_heads * head_dim`） | 标准 | +| **混合全注意力 + 线性注意力** | Qwen3-Next-80B | 全注意力层 + 线性 (GDN) 注意力每 4 层交替 | 减少（线性注意力层无 KV 缓存） | + +--- + +## 硬件要求 + +### 推理性能分析（AICB 后端） + +| 要求 | 详情 | +|------|------| +| **GPU 架构** | NVIDIA Hopper (SM90) 或 Blackwell (SM100) | +| **原因** | 依赖 DeepGEMM、FlashMLA、FlashInfer | +| **Hopper 注意** | 在 Dockerfile 中添加 `ENV FLASH_MLA_DISABLE_SM100=1` | + +### 训练仿真 + +- **SimAI-Analytical**：任意 CPU（无需 GPU） +- **SimAI-Simulation**：任意 CPU（无需 GPU） +- **AICB 物理执行**：需要支持 NCCL 的 GPU 集群 + +--- + +## 相关文档 + +- [推理仿真](inference_simulation.md) — 多请求推理指南 +- [工作负载生成](workload_generation.md) — AICB 工作负载生成 +- [GPU 显存模块](../technical_reference/memory_module.md) — 显存计算详情 +- [vidur-alibabacloud](../components/vidur.md) — 推理调度组件 diff --git a/docs/zh/user_guide/workload_generation.md b/docs/zh/user_guide/workload_generation.md new file mode 100644 index 00000000..95b1eb37 --- /dev/null +++ b/docs/zh/user_guide/workload_generation.md @@ -0,0 +1,160 @@ +# 工作负载生成 + +AICB（AI Communication Benchmark）为 SimAI 的训练和推理仿真提供工作负载生成功能。 + +--- + +## 概述 + +AICB 生成工作负载描述文件（`.txt`），描述 LLM 训练/推理过程的通信和计算模式。这些工作负载由 SimAI 仿真引擎消费。 + +支持两类工作负载生成： + +| 类型 | 说明 | 支持的模型 | +|------|------|-----------| +| **训练** | 生成训练通信/计算模式 | GPT (7B/13B/22B/175B)、LLaMA (7B/65B/405B)、DeepSeek (16B/236B/671B)、MoE | +| **推理** | 生成 prefill/decode 阶段工作负载 | DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B | + +--- + +## 训练工作负载生成 + +### 使用预配置模型快速开始 + +```bash +# 生成 Megatron GPT-7B 工作负载 +sh ./scripts/megatron_workload_with_aiob.sh -m 7 \ + --world_size 4096 --tensor_model_parallel_size 4 --pipeline_model_parallel 1 \ + --frame Megatron --global_batch 8192 \ + --micro_batch 1 --seq_length 4096 --swiglu \ + --use_flash_attn --aiob_enable \ + --comp_filepath workload/aiob_inputs/Example.txt +``` + +可用预配置模型大小：`7`、`13`、`22`、`175`（GPT/LLaMA）、`moe`、`deepseek`（16/236/671）。 + +### 不同框架的生成方法 + +#### Megatron + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --model_name GPT-13B --frame=Megatron \ + --world_size=16 --tensor_model_parallel_size=2 --pipeline_model_parallel=1 \ + --global_batch=16 --micro_batch=1 --num_layers=40 --seq_length=2048 \ + --hidden_size=5120 --epoch_num=1 --num_attention_heads=40 \ + --aiob_enable --use_flash_attn --swiglu +``` + +#### MoE + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --model_name MoE --frame=Megatron \ + --world_size=32 --tensor_model_parallel_size=4 --pipeline_model_parallel=1 \ + --expert_model_parallel_size=2 --moe_enable --num_experts=8 --moe_router_topk=2 \ + --global_batch=32 --micro_batch=1 --seq_length=2048 \ + --aiob_enable --swiglu --use_flash_attn +``` + +#### DeepSeek + +```bash +python -m workload_generator.SimAI_training_workload_generator \ + --frame=DeepSeek \ + --world_size=32 --tensor_model_parallel_size=4 \ + --expert_model_parallel_size=2 --moe_enable --num_experts=4 --moe_router_topk=2 \ + --global_batch=16 --micro_batch=1 --seq_length=4096 \ + --aiob_enable --swiglu -m deepseek +``` + +#### DeepSpeed + +```bash +python -m workload_generator.generate_deepspeed_stage3_workload \ + --world_size=64 --global_batch=64 \ + --num_layers=40 --hidden_size=5120 --seq_length=4096 \ + --zero_stage=3 --reduce_bucket_size=1000000000 +``` + +### 输出 + +生成的工作负载文件保存在： +- 训练：`results/mocked_workload/` 或 `results/workload/` + +--- + +## 推理工作负载生成 + +SimAI 使用 AICB 生成带有 prefill/decode 阶段分离的推理工作负载。 + +> **注意**：推理计算性能分析需要 NVIDIA Hopper (SM90) 或 Blackwell (SM100) GPU，因为依赖 [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) 和 [FlashMLA](https://github.com/deepseek-ai/FlashMLA)。 + +### 支持的推理模型 + +| 模型 | 注意力 | MoE 专家数 | 每 token 激活专家数 | +|------|--------|-----------|-------------------| +| DeepSeek-V3-671B | MLA | 256 路由 + 1 共享 | 8 | +| Qwen3-MoE-235B | MHA/GQA | 128 路由 | 8 | +| Qwen3-Next-80B | 混合（全注意力 + 线性注意力） | 512 路由 | 10 | + +推理工作负载由 vidur-alibabacloud 调度框架自动生成和消费。端到端用法请参见[推理仿真](inference_simulation.md)。 + +--- + +## AIOB：计算时间嵌入 + +AIOB（AI Operation Benchmark）是 AICB 的子模块，用于分析实际 GPU 计算时间并将其嵌入工作负载。 + +### 使用选项 + +| 选项 | 说明 | +|------|------| +| `--aiob_enable` | 启用 AIOB，在当前 GPU 上分析计算时间 | +| `--comp_filepath ` | 使用已有的计算时间描述文件 | +| 均不指定 | 使用固定默认计算时间 | + +### 示例：分析并嵌入 + +```bash +sh scripts/megatron_gpt.sh \ + -m 7 --world_size 8 --tensor_model_parallel_size 2 \ + --frame Megatron --global_batch 16 --micro_batch 1 \ + --seq_length 2048 --swiglu --use_flash_attn --aiob_enable +``` + +计算描述文件保存在 `results/aiob_outputs/`。 + +--- + +## 关键参数 + +| 类别 | 参数 | 说明 | +|------|------|------| +| **框架** | `--frame` | Megatron / DeepSpeed / DeepSeek | +| **模型** | `--model_size` 或 `-m` | 预配置模型大小 | +| **训练** | `--world_size` | GPU 总数 | +| | `--global_batch` | 全局批大小 | +| | `--micro_batch` | 微批大小 | +| | `--seq_length` | 序列长度 | +| | `--epoch_num` | 迭代次数 | +| **并行** | `--tensor_model_parallel_size` | TP 并行度 | +| | `--pipeline_model_parallel` | PP 并行度 | +| | `--expert_model_parallel_size` | EP 并行度 | +| **MoE** | `--moe_enable` | 启用 MoE | +| | `--num_experts` | 专家数量 | +| | `--moe_router_topk` | 每 token 激活专家数 | +| **优化** | `--use_flash_attn` | 使用 FlashAttention | +| | `--swiglu` | 使用 SwiGLU 激活函数 | +| | `--aiob_enable` | 启用 AIOB 计算分析 | +| | `--comp_filepath` | 计算时间文件路径 | + +完整参数列表请参见 [AICB 组件文档](../components/aicb.md) 或 [CLI 参考](../technical_reference/cli_reference.md)。 + +--- + +## 相关文档 + +- [AICB 组件](../components/aicb.md) — 完整 AICB 文档 +- [推理仿真](inference_simulation.md) — 端到端推理仿真指南 +- [支持的模型](supported_models.md) — 完整模型兼容列表 diff --git a/vidur-alibabacloud/README-vidur.md b/vidur-alibabacloud/README-vidur.md index 6f1cd2d0..00c08c04 100644 --- a/vidur-alibabacloud/README-vidur.md +++ b/vidur-alibabacloud/README-vidur.md @@ -164,4 +164,164 @@ This project may contain trademarks or logos for projects, products, or services trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. \ No newline at end of file +Any use of third-party trademarks or logos are subject to those third-party's policies. + +## SimAI / AICB 场景示例（一键运行） + +> 以下命令均在 `vidur-alibabacloud/` 目录下执行，需提前激活 `vidur` conda 环境。 +> 使用 AICB 后端 (`--random_forrest_execution_time_predictor_config_backend aicb`)， +> 设备为 H20 DGX (`h20_dgx`)，请求生成为 Poisson QPS=100，固定长度 prefill=100/decode=8。 +> 所有输入输出文件统一汇聚至 `examples/vidur-ali-scenarios/` 目录： +> - 脚本: `examples/vidur-ali-scenarios/run_scenarios.sh` +> - 运行日志: `examples/vidur-ali-scenarios/logs/scenario__.log` +> - 模拟输出: `examples/vidur-ali-scenarios/simulator_output//` + +### 场景汇总 + +| 场景 | 模型 | ws | TP | PP | EP | PD分离 | 调度器 | +|------|------|----|----|----|-----|--------|--------| +| 1 | Qwen3-Next-80B | 32 | 1 | 1 | 32 | 否 | lor | +| 2 | Qwen3-Next-80B | 8 (P=2,D=6) | 1 | 1 | auto | 是 | split_wise | +| 3 | DeepSeek-671B | 8 (P=2,D=6) | 8 | 1 | 8 | 是 | split_wise | +| 4 | Qwen3-MoE-235B | 8 (P=2,D=6) | 4 | 1 | 4 | 是 | split_wise | + +### 使用方法 + +```sh +# 激活环境 +conda activate vidur + +# 运行单个场景（1~4） +bash examples/vidur-ali-scenarios/run_scenarios.sh --scenario 1 + +# 顺序运行所有场景 +bash examples/vidur-ali-scenarios/run_scenarios.sh --all + +# 查看帮助 +bash examples/vidur-ali-scenarios/run_scenarios.sh --help +``` + +### 分场景命令（手动方式） + +**场景 1: Qwen3-Next-80B 无PD分离 (ws=32, lor)** + +```sh +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype fp8 \ + --replica_config_network_device h20_dgx \ + --replica_config_device h20 \ + --request_generator_config_type synthetic \ + --interval_generator_config_type poisson \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 4 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 100 \ + --fixed_request_length_generator_config_decode_tokens 8 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --random_forrest_execution_time_predictor_config_backend aicb \ + --metrics_config_output_dir examples/vidur-ali-scenarios/simulator_output \ + --cluster_config_num_replicas 32 \ + --replica_config_pd_node_ratio 1 \ + --global_scheduler_config_type lor \ + --replica_scheduler_config_type sarathi \ + --replica_config_model_name qwen3-next-80B \ + --replica_config_tensor_parallel_size 1 \ + --replica_config_num_pipeline_stages 1 +``` + +**场景 2: Qwen3-Next-80B PD分离 (P=2, D=6, split_wise)** + +```sh +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype fp8 \ + --replica_config_network_device h20_dgx \ + --replica_config_device h20 \ + --request_generator_config_type synthetic \ + --interval_generator_config_type poisson \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 4 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 100 \ + --fixed_request_length_generator_config_decode_tokens 8 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --random_forrest_execution_time_predictor_config_backend aicb \ + --metrics_config_output_dir examples/vidur-ali-scenarios/simulator_output \ + --cluster_config_num_replicas 8 \ + --replica_config_pd_node_ratio 0.25 \ + --replica_config_num_prefill_replicas 2 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name qwen3-next-80B \ + --replica_config_tensor_parallel_size 1 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_prefill_tensor_parallel_size 1 \ + --replica_config_prefill_num_pipeline_stages 1 \ + --replica_config_decode_tensor_parallel_size 1 \ + --replica_config_decode_num_pipeline_stages 1 +``` + +**场景 3: DeepSeek-671B PD分离 (tp=8, ep=8, split_wise)** + +```sh +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype fp8 \ + --replica_config_network_device h20_dgx \ + --replica_config_device h20 \ + --request_generator_config_type synthetic \ + --interval_generator_config_type poisson \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 4 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 100 \ + --fixed_request_length_generator_config_decode_tokens 8 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --random_forrest_execution_time_predictor_config_backend aicb \ + --metrics_config_output_dir examples/vidur-ali-scenarios/simulator_output \ + --cluster_config_num_replicas 8 \ + --replica_config_pd_node_ratio 0.25 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name deepseek-671B \ + --replica_config_tensor_parallel_size 8 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 8 +``` + +**场景 4: Qwen3-MoE-235B PD分离 (tp=4, ep=4, split_wise)** + +```sh +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype fp8 \ + --replica_config_network_device h20_dgx \ + --replica_config_device h20 \ + --request_generator_config_type synthetic \ + --interval_generator_config_type poisson \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 4 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 100 \ + --fixed_request_length_generator_config_decode_tokens 8 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --random_forrest_execution_time_predictor_config_backend aicb \ + --metrics_config_output_dir examples/vidur-ali-scenarios/simulator_output \ + --cluster_config_num_replicas 8 \ + --replica_config_pd_node_ratio 0.25 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name qwen3-moe-235B \ + --replica_config_tensor_parallel_size 4 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 4 +``` \ No newline at end of file diff --git a/vidur-alibabacloud/README.md b/vidur-alibabacloud/README.md index 244a1e47..f844bb5a 100644 --- a/vidur-alibabacloud/README.md +++ b/vidur-alibabacloud/README.md @@ -1,64 +1,125 @@ -# README +

+ 中文  ｜  English +

+# Vidur-AlibabaCloud + +[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) + +Vidur ([original](https://github.com/microsoft/vidur)) is a simulation framework for large language model (LLM) inference systems. +**Vidur-AlibabaCloud** (this repository) is a customized version optimized for Alibaba Cloud **SimAI** scenarios. It supports advanced features such as **Prefill–Decode (PD) disaggregation** and includes dedicated adaptations for SOTA LLM models including **DeepSeek-V3-671B**, **Qwen3-MoE-235B**, **Qwen3-Next-80B**, and others. -Vidur ([original](https://github.com/microsoft/vidur)) is a simulation framework for large language model (LLM) inference systems. -**Vidur-AlibabaCloud** (this repository) is a customized version optimized for Alibaba Cloud **SimAI** scenarios. It supports advanced features such as **Prefill–Decode (PD) disaggregation** and includes dedicated adaptations for state-of-the-art (SOTA) LLM models including **DeepSeek-V3-671B**, **Qwen3-MoE-235B**, **Qwen3-Next-80B**, and other models. + +--- + +## Table of Contents + +- [Key Features](#key-features) +- [GPU Memory Calculation](#gpu-memory-calculation) +- [Supported Models](#supported-models) +- [Environment Setup](#-environment-setup) +- [Running Examples](#%EF%B8%8F-running-examples) + - [4-Scenario Configuration](#4-scenario-configuration) + - [Output Files](#output-files) +- [Key Input Parameters](#-key-input-parameter-reference) +- [Key Output Interpretation](#-key-output-interpretation) +- [Known Issues](#%EF%B8%8F-known-issues) +- [Help](#-help) --- ## Key Features -+ **Prefill–Decode (PD) Separation** – Enables running the prefill and decode stages on different nodes, allowing elastic resource allocation and performance isolation. -(Inspired by [splitwise-sim](https://github.com/Mutinifni/splitwise-sim)). -+ **Flexible Parallelism** – Supports: - - **Data Parallel (DP)** - - **Tensor Parallel (TP)** - - **Pipeline Parallel (PP)** - - **Expert Parallel (EP)** (support in progress) -Works for both **dense** and **Mixture-of-Experts (MoE)** models (MoE support in progress). -+ **Multiple Execution-Time Prediction Backends** – Choose from: - - **AICB/AIOB** - Partially supports computation kernels and TP, DP, PP, EP communication size for DeepSeek-V3-671B, Qwen3-Moe-235B, Qwen3-Next-80B - - **SimAi_simulation** – SimAI NS-3-based network simulation (supports TP) - - **SimAi_analytical** – SimAI analytical performance model (supports TP) - - **Native Vidur [original]** – Supports TP, DP, PP -+ **Workload Generation & Replay** – Replay real-world traces or generate synthetic requests using fixed or Poisson distributions. -+ **Fine-Grained Metrics** – Records: - - TTFT – Time to First Token - - TBT / TPOT – Time Between Tokens / Time Per Output Token - - End-to-end latency - - Communication cost - - Computation cost - - Scheduling delay + +- **Prefill–Decode (PD) Separation** — Enables running the prefill and decode stages on different nodes, allowing elastic resource allocation and performance isolation. + (Inspired by [splitwise-sim](https://github.com/Mutinifni/splitwise-sim)) +- **Flexible Parallelism** — Supports: + - **Data Parallel (DP)** + - **Tensor Parallel (TP)** + - **Pipeline Parallel (PP)** + - **Expert Parallel (EP)** (support in progress) + + Works for both **dense** and **Mixture-of-Experts (MoE)** models (MoE support in progress). +- **Multiple Execution-Time Prediction Backends** — Choose from: + - **AICB/AIOB** — Partially supports computation kernels and TP, DP, PP, EP communication size for DeepSeek-V3-671B, Qwen3-MoE-235B, Qwen3-Next-80B + - **SimAI Simulation** — SimAI NS-3-based network simulation (supports TP) + - **SimAI Analytical** — SimAI analytical performance model (supports TP) + - **Native Vidur [original]** — Supports TP, DP, PP +- **Workload Generation & Replay** — Replay real-world traces or generate synthetic requests using fixed or Poisson distributions. +- **Fine-Grained Metrics** — Records: + - TTFT — Time to First Token + - TBT / TPOT — Time Between Tokens / Time Per Output Token + - End-to-end latency + - Communication cost + - Computation cost + - Scheduling delay + +--- + +## GPU Memory Calculation + +This module provides accurate GPU memory estimation for modern MoE (Mixture-of-Experts) models during inference simulation, covering **model parameter memory**, **KV cache memory**, and **maximum batch size** calculation under Prefill–Decode (PD) disaggregation. + +### Supported Attention Architectures + +| Architecture | Model | Description | +|---|---|---| +| **MLA** (Multi-head Latent Attention) | DeepSeek-V3-671B | Uses LoRA-compressed KV cache (`kv_lora_rank` + `qk_rope_head_dim`) for reduced memory footprint | +| **MHA / GQA** (Multi-Head / Grouped-Query Attention) | Qwen3-MoE-235B | Standard KV cache with `num_kv_heads * head_dim` per token per layer | +| **Hybrid Full + Linear Attention** | Qwen3-Next-80B | Alternates between full attention and linear (GDN) attention every 4 layers | + +### Key Components + +- **`ParamCounter`** (`vidur/utils/param_counter.py`) — Computes per-layer and per-device parameter counts for MLA, MHA/GQA, linear attention, and MoE expert weights, with FP8 quantization support. Under PD disaggregation, it returns separate `(total_params, prefill_params, decode_params)` based on `prefill_world_size` / `decode_world_size`. +- **`MemoryPlanner`** (`vidur/scheduler/utils/memory_planner.py`) — Plans GPU memory budget: `available = GPU_mem * (1 - margin) - param_mem`, then computes KV cache capacity and maximum concurrent requests. Includes OOM detection with actionable suggestions. +- **Per-request KV cache tracking** (`vidur/entities/replica.py`) — Allocates and releases KV cache memory on a per-request basis, enabling accurate remaining-capacity queries at runtime. + +### References & Acknowledgments + +The GPU memory calculation module was developed with reference to the following works: + +- [InferSim](https://github.com/alibaba/InferSim) — Parameter counting and KV cache estimation methodology +- [DeepSeek V3 Parameter Size Analysis](https://yangwenbo.com/articles/deepseek-v3-parameter-size.html) — DeepSeek V3 MLA parameter derivation +- [DeepSeek V3 Parameter Derivation (Chinese)](https://zhuanlan.zhihu.com/p/21455638257) — Detailed MLA weight decomposition + +We gratefully acknowledge these resources for providing the foundational analysis that guided our implementation. --- ## Supported Models -+ **DeepSeek-V3-671B** (SimAI PP/EP communication、GPU memory allocation module adaptations in progress) -+ **Qwen3-Moe-235B**, **Qwen3-Next-80B** (SimAI PP/EP communication、GPU memory allocation module adaptations in progress) -+ **meta-llama/Meta-Llama-3-8B** / **Meta-Llama-3-70B** -+ **meta-llama/Llama-2-7b-hf** / **Llama-2-70b-hf** -+ **codellama/CodeLlama-34b-Instruct-hf** -+ **internlm/internlm-20b** -+ **Qwen/Qwen-72B** + +- **DeepSeek-V3-671B** (SimAI PP/EP communication and GPU memory allocation module adaptations in progress) +- **Qwen3-MoE-235B**, **Qwen3-Next-80B** (SimAI PP/EP communication and GPU memory allocation module adaptations in progress) +- **meta-llama/Meta-Llama-3-8B** / **Meta-Llama-3-70B** +- **meta-llama/Llama-2-7b-hf** / **Llama-2-70b-hf** +- **codellama/CodeLlama-34b-Instruct-hf** +- **internlm/internlm-20b** +- **Qwen/Qwen-72B** --- ## 📦 Environment Setup + ### 1. Create Conda Environment + ```bash conda env create -p ./env -f ./environment.yml ``` ### 2. (Optional) Update Dev Dependencies + ```bash conda env update -f environment-dev.yml ``` ### 3. Activate Environment + ```bash conda activate vidur ``` ### 4. Install Python Dependencies (Using Alibaba Cloud PyPI Mirror) + ```bash pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ pip install -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ @@ -66,13 +127,16 @@ pip install -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ --- -## ▶️ Running Example -### Run DeepSeek-671B **with** AICB -**Requirements: **SimAI and AICB Docker environment (see [README](../README.md) for setup instructions). +## ▶️ Running Examples + +### Run DeepSeek-671B with AICB -After setting up the environment, run the following commands: +**Requirements:** SimAI and AICB Docker environment (see [README](../README.md) for setup instructions). + +After setting up the environment, run the following commands: + +#### DeepSeek-671B with AICB (Fixed Length Generator) -#### Run DeepSeek-671B **with** AICB (Fixed Length Generator) ```bash cd SimAI/vidur-alibabacloud @@ -94,10 +158,11 @@ python -m vidur.main --replica_config_pd_p2p_comm_bandwidth 800 \ --replica_config_tensor_parallel_size 2 \ --replica_config_num_pipeline_stages 1 \ --replica_config_expert_model_parallel_size 8 \ - --random_forrest_execution_time_predictor_config_backend aicb + --random_forrest_execution_time_predictor_config_backend aicb ``` -#### Run DeepSeek-671B **with** AICB (Trace Length Generator) +#### DeepSeek-671B with AICB (Trace Length Generator) + ```bash cd SimAI/vidur-alibabacloud @@ -124,11 +189,9 @@ python -m vidur.main \ ``` > ✅ Full parameter descriptions are available via `python -m vidur.main -h`. -> +### Run Llama-3-8B with SimAI Simulation - -### Run Llama-3-8B **with** simai_simulation ```bash cd SimAI @@ -136,8 +199,8 @@ cd SimAI ./scripts/build.sh -c ns3 # Create network topo (Spectrum-X_128g_8gps_100Gbps_A100) -python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps - +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps cd SimAI/vidur-alibabacloud @@ -163,18 +226,16 @@ python -m vidur.main \ --random_forrest_execution_time_predictor_config_backend simai_simulation \ --random_forrest_execution_time_predictor_config_simai_dir ../ \ --random_forrest_execution_time_predictor_config_simai_simulation_topo ../Spectrum-X_128g_8gps_100Gbps_A100 \ - --random_forrest_execution_time_predictor_config_simai_simulation_config ../astra-sim-alibabacloud/inputs/config/SimAI.conf + --random_forrest_execution_time_predictor_config_simai_simulation_config ../astra-sim-alibabacloud/inputs/config/SimAI.conf ``` -> -> +### Run Llama-3-8B with SimAI Analytical -### Run Llama-3-8B **with** simai_analytical ```bash cd SimAI # Compile SimAI-Analytical -$ ./scripts/build.sh -c analytical +./scripts/build.sh -c analytical cd SimAI/vidur-alibabacloud @@ -200,10 +261,8 @@ python -m vidur.main \ --random_forrest_execution_time_predictor_config_backend simai_analytical ``` -> -> +### Run Llama-3-8B with Native Vidur [original] -### Run Llama-3-8B **with** native Vidur [original] ```bash cd SimAI/vidur-alibabacloud @@ -229,125 +288,172 @@ python -m vidur.main \ --random_forrest_execution_time_predictor_config_backend vidur ``` -> -> +### Run 4-Scenario Suite +For a quick validation of all supported configurations, use the bundled test script: +```bash +bash examples/vidur-ali-scenarios/run_scenarios.sh --all +``` + +See `bash examples/vidur-ali-scenarios/run_scenarios.sh --help` for details. + +#### 4-Scenario Configuration + +The following scenarios are pre-configured in `run_scenarios.sh`. All scenarios share the hardware configuration below. + +**Shared Hardware Configuration:** +- GPU: H20 (h20_dgx), NVLink: 1600 Gbps, RDMA: 800 Gbps +- PD P2P bandwidth: 800 Gbps, dtype: fp8 +- Request: Poisson QPS=100, 4 requests, fixed prefill=100 / decode=8 tokens + +| Scenario | Model | PD Separation | World Size | TP | PP | EP | Global Scheduler | +|----------|-------|---------------|------------|----|----|------------|------------------| +| 1 | Qwen3-Next-80B (MoE) | No | 32 (dp=32) | 1 | 1 | 1 (default) | lor | +| 2 | Qwen3-Next-80B (MoE) | Yes (P=2, D=6) | 8 | 1 | 1 | 1 (default) | split_wise | +| 3 | DeepSeek-671B (MoE) | Yes (P=2, D=6) | 8 | 8 | 1 | 8 | split_wise | +| 4 | Qwen3-MoE-235B (MoE) | Yes (P=2, D=6) | 8 | 4 | 1 | 4 | split_wise | + +> **Note:** All four models use Mixture-of-Experts (MoE) architecture. The EP column reflects the explicit `--replica_config_expert_model_parallel_size` value set in the script; scenarios without an explicit EP setting use the default value of 1. + +#### Output Files + +**Output path depends on how you run the simulation:** + +- **`run_scenarios.sh`** --- outputs to `examples/vidur-ali-scenarios/simulator_output/` +- **Direct `python -m vidur.main`** --- outputs to `./simulator_output/` (or the path specified by `--metrics_config_output_dir`) + +Each run produces the following directory: + +``` +// +├── request_metrics.csv # per-request metrics (see Key Output Interpretation) +├── chrome_trace.json # Chrome DevTools timeline trace (open at chrome://tracing) +├── config.json # snapshot of all simulation parameters +└── plots/ # per-metric CSV / JSON files (including but not limited to) + ├── request_e2e_time.csv + ├── prefill_e2e_time.csv + ├── pd_p2p_comm_time.csv + ├── replica_N_memory_usage.json + └── ... +``` + +> **Note:** The exact file list in `plots/` may vary across versions. +> Run-time logs (when using `run_scenarios.sh`) are saved separately to `examples/vidur-ali-scenarios/logs/scenario__.log`. --- ## 🔧 Key Input Parameter Reference + | Parameter | Default | Description | -| --- | --- | --- | -| `--replica_config_pd_p2p_comm_bandwidth` | 800 | Bandwidth (Gbps) for point-to-point communication between Prefill and Decode nodes in PD disaggregation | +|-----------|---------|-------------| +| `--replica_config_pd_p2p_comm_bandwidth` | 800 | Bandwidth (Gbps) for P2P communication between Prefill and Decode nodes in PD disaggregation | | `--replica_config_nvlink_bandwidth` | 1600 | NVLink bandwidth (Gbps) for TP/EP communications | | `--replica_config_rdma_bandwidth` | 800 | RDMA bandwidth (Gbps) for inter-node communication | | `--replica_config_pd_p2p_comm_dtype` | float16 | Data type for PD communication (`float16`, `float32`, etc.) | | `--poisson_request_interval_generator_config_qps` | 0.5 | Queries per second (QPS) for Poisson request generator | | `--synthetic_request_generator_config_num_requests` | 128 | Number of synthetic requests to generate | | `--length_generator_config_type` | fixed | Request length generator type (`fixed`, `trace`, etc.) | -| `--fixed_request_length_generator_config_prefill_tokens` | `2048` | Number of prefill tokens per request (only effective when `--length_generator_config_type=fixed`) | -| `--fixed_request_length_generator_config_decode_tokens` | `512` | Number of decode tokens per request (only effective when `--length_generator_config_type=fixed`) | +| `--fixed_request_length_generator_config_prefill_tokens` | 2048 | Number of prefill tokens per request (only effective when `--length_generator_config_type=fixed`) | +| `--fixed_request_length_generator_config_decode_tokens` | 512 | Number of decode tokens per request (only effective when `--length_generator_config_type=fixed`) | | `--trace_request_length_generator_config_max_tokens` | 4096 | Max tokens when using trace-based length generator | -| `--trace_request_length_generator_config_trace_file` | data/processed_traces/sharegpt_8k_filtered_stats_llama2_tokenizer.csv | Path to trace file for request lengths | +| `--trace_request_length_generator_config_trace_file` | `data/processed_traces/sharegpt_8k_filtered_stats_llama2_tokenizer.csv` | Path to trace file for request lengths | | `--interval_generator_config_type` | poisson | Inter-arrival time generator type | | `--cluster_config_num_replicas` | 1 | Total number of replicas (i.e., data parallelism degree) | -| `--replica_config_pd_node_ratio` | 0.5 | Ratio of P-nodes to （P-nodes + D-nodes） Fraction of replicas allocated as prefill (P) nodes. The remaining replicas are used as decode (D) nodes. For example, 0.5 means half of the replicas are prefill nodes and half are decode nodes (P:D = 1:1). | +| `--replica_config_pd_node_ratio` | 0.5 | Fraction of replicas allocated as prefill (P) nodes. The remaining replicas are used as decode (D) nodes. For example, 0.5 means P:D = 1:1. | | `--global_scheduler_config_type` | round_robin | Global scheduler type (`split_wise`, `round_robin`, etc.) | | `--replica_scheduler_config_type` | sarathi | Per-replica scheduler type | -| `--replica_config_model_name` | meta-llama/Llama-2-7b-hf | Model name (DeepSeek-671B, Qwen3-Moe-235B, Qwen3-Next-80B , etc.)
⚠️ **Note**: Vidur GPU Memory management module is still under adaptation for DeepSeek-671B, Qwen3-Moe-235B, Qwen3-Next-80B | +| `--replica_config_model_name` | meta-llama/Llama-2-7b-hf | Model name (DeepSeek-671B, Qwen3-MoE-235B, Qwen3-Next-80B, etc.) | | `--replica_config_tensor_parallel_size` | 1 | Tensor parallelism size (TP) | | `--replica_config_num_pipeline_stages` | 1 | Number of pipeline stages (PP) | | `--replica_config_expert_model_parallel_size` | 1 | Expert model parallelism size (EP) | -| `--random_forrest_execution_time_predictor_config_backend` | vidur | Backend for execution time prediction
('vidur', 'simai_simulation', 'simai_analytical','aicb', etc.)
⚠️ **Note**: `simai_simulation` and `simai_analytical` currently only model TP communication and do not support pipeline or expert parallelism | -| `--random_forrest_execution_time_predictor_config_simai_dir` | `'../'` | Root directory of the SimAI simulator（default: `../`)
（only effective when `--random_forrest_execution_time_predictor_config_backend simai_simulation`） | -| `--random_forrest_execution_time_predictor_config_simai_simulation_topo` | `'../example/topo'` | Path to SimAI topology file (e.g., `'../Spectrum-X_128g_8gps_100Gbps_A100'`)（only effective when `--random_forrest_execution_time_predictor_config_backend simai_simulation`） | -| `--random_forrest_execution_time_predictor_config_simai_simulation_config` | `'../astra-sim-alibabacloud/inputs/config/SimAI.conf'` | Path to SimAI configuration file (e.g., `'../astra-sim-alibabacloud/inputs/config/SimAI.conf'`)
（only effective when `--random_forrest_execution_time_predictor_config_backend simai_simulation`） | - +| `--random_forrest_execution_time_predictor_config_backend` | vidur | Backend for execution time prediction (`vidur`, `simai_simulation`, `simai_analytical`, `aicb`, etc.). **Note:** `simai_simulation` and `simai_analytical` currently only model TP communication and do not support pipeline or expert parallelism. | +| `--random_forrest_execution_time_predictor_config_simai_dir` | `../` | Root directory of the SimAI simulator (only effective when backend = `simai_simulation`) | +| `--random_forrest_execution_time_predictor_config_simai_simulation_topo` | `../example/topo` | Path to SimAI topology file (only effective when backend = `simai_simulation`) | +| `--random_forrest_execution_time_predictor_config_simai_simulation_config` | `../astra-sim-alibabacloud/inputs/config/SimAI.conf` | Path to SimAI configuration file (only effective when backend = `simai_simulation`) | --- ## 📊 Key Output Interpretation + Simulation results are saved to: -```plain +``` ./simulator_output/YYYY-MM-DD_HH-MM-SS-XXXXXX/request_metrics.csv ``` ### Key Columns in `request_metrics.csv` + | Column | Meaning | -| --- | --- | +|--------|---------| | `arrived_at` / `prefill_arrived_at` | Timestamp when the request entered the system (in seconds). | -| `scheduled_at` | Timestamp when the request was first scheduled by the scheduler and began execution (in seconds). | +| `scheduled_at` | Timestamp when the request was first scheduled and began execution (in seconds). | | `prefill_completed_at` | Timestamp when the Prefill phase completed and the first output token was generated. | -| `decode_arrived_at` | Timestamp when the Decode phase started. In non-PD-Disaggregated setup, this typically equals `prefill_completed_at`. In PD-Disaggregated setup, it is `prefill_completed_at + pd_p2p_comm_time`. | -| `decode_time` | Duration of the Decode phase (in seconds), computed as `completed_at - decode_arrived_at` (equivalently: `request_e2e_time - prefill_e2e_time`). | -| `prefill_replica_id` | Replica ID that executed the Prefill phase (in PD-Disaggregated setup). | -| `decode_replica_id` | Replica ID that executed the Decode phase (in PD-Disaggregated setup). | +| `decode_arrived_at` | Timestamp when the Decode phase started. In non-PD-disaggregated setup, this typically equals `prefill_completed_at`. In PD-disaggregated setup, it is `prefill_completed_at + pd_p2p_comm_time`. | +| `decode_time` | Duration of the Decode phase (in seconds), computed as `completed_at - decode_arrived_at`. | +| `prefill_replica_id` | Replica ID that executed the Prefill phase (in PD-disaggregated setup). | +| `decode_replica_id` | Replica ID that executed the Decode phase (in PD-disaggregated setup). | | `request_num_prefill_tokens` | Number of input tokens (i.e., prompt length). | | `request_num_decode_tokens` | Number of output tokens (i.e., generation length). | -| `pd_p2p_comm_size` | Point-to-point communication size (in bytes) of data transferred from the Prefill node to the Decode node (KV cache, etc.) in PD-Disaggregated setup. | -| `pd_p2p_comm_time` | Point-to-point communication time (in seconds) between Prefill and Decode nodes in PD-Disaggregated setup. | +| `pd_p2p_comm_size` | P2P communication size (in bytes) of data transferred from the Prefill node to the Decode node (KV cache, etc.) in PD-disaggregated setup. | +| `pd_p2p_comm_time` | P2P communication time (in seconds) between Prefill and Decode nodes in PD-disaggregated setup. | | `completed_at` | Timestamp when the request finished processing. | | `request_execution_time` | Total actual execution time (in seconds), excluding delays due to preemption or pipeline bubbles. | | `request_preemption_time` | Time (in seconds) spent waiting due to scheduler preemption, pipeline bubbles, or other non-execution gaps. | | `request_scheduling_delay` | Scheduling delay before execution: `scheduled_at - arrived_at` (in seconds). | | `request_e2e_time` | End-to-end latency: `completed_at - arrived_at` (in seconds). | | `prefill_e2e_time` | Time To First Token (TTFT): `prefill_completed_at - arrived_at` (in seconds). | -| `tbt` | Time Between Tokens (TBT), also known as Time Per Output Token (TPOT). Computed as: `decode_time / request_num_decode_tokens` or equivalently: `(request_e2e_time - prefill_e2e_time) / request_num_decode_tokens` (in seconds/token). | +| `tbt` | Time Between Tokens (TBT), also known as TPOT. Computed as: `decode_time / request_num_decode_tokens` (in seconds/token). | +**Notes:** - **Notes**: +- All time-related fields are in **seconds (s)**, based on monotonic clock or Unix timestamps. +- In non-PD-separated deployments, `prefill_replica_id` and `decode_replica_id` are typically identical. +- If `request_num_decode_tokens = 0`, `tbt` is undefined (may be recorded as `NaN` or `0`). +- TBT is not yet logged in `request_metrics.csv`; it can be computed manually for now. -+ All time-related fields are in **seconds (s)**, based on monotonic clock or Unix timestamps. -+ In non-PD-separated deployments, `prefill_replica_id` and `decode_replica_id` are typically identical. -+ If `request_num_decode_tokens = 0`, `tbt` is undefined (may be recorded as `NaN` or `0`). -+ **TBT is not yet logged in request_metrics.csv; it can be computed manually for now.** +### Sample Row (`request_metrics.csv`) -### Sample Row (request_metrics.csv) -```plain +``` Request Id,request_e2e_time,...,arrived_at,prefill_arrived_at,scheduled_at,prefill_completed_at,decode_arrived_at,completed_at,...,prefill_replica_id,decode_replica_id,pd_p2p_comm_size,pd_p2p_comm_time,... 0,0.03607,...,0.0102006,0.0102006,0.0102006,0.0102265,0.0433997,0.0462744,...,0,2,3561947136,0.0331732,... ``` --- -## ⚠️ Known Issue: Plotting Warning +## ⚠️ Known Issues + +### Plotting Warning + You may see this error at exit: -```plain +``` RuntimeError: Kaleido requires Google Chrome to be installed. ``` -This occurs because the simulator tries to generate PNG plots but lacks Chrome. -✅ **Important**: This **does NOT affect** the generation of `request_metrics.csv`. +This occurs because the simulator tries to generate PNG plots but lacks Chrome. +**Important:** This does **NOT** affect the generation of `request_metrics.csv`. -### Solutions: -1. **Ignore it** – CSV output is unaffected. -2. **Install Chrome**: - -```bash -plotly_get_chrome -``` +**Solutions:** +1. **Ignore it** — CSV output is unaffected. +2. **Install Chrome:** + ```bash + plotly_get_chrome + ``` 3. **Disable plotting** (not recommended): Comment out these lines in `vidur/simulator.py`: - -```python -# self._metric_store.plot() -# logger.info("Metrics written") -``` - -> ⚠️ Disabling plotting will skip all visual outputs and request_metrics.csv. -> + ```python + # self._metric_store.plot() + # logger.info("Metrics written") + ``` + > Disabling plotting will skip all visual outputs and `request_metrics.csv`. --- ## 📚 Help + View all CLI options: ```bash python -m vidur.main -h ``` - ---- - diff --git a/vidur-alibabacloud/README_CN.md b/vidur-alibabacloud/README_CN.md new file mode 100644 index 00000000..372f8303 --- /dev/null +++ b/vidur-alibabacloud/README_CN.md @@ -0,0 +1,458 @@ +

+ 中文  ｜  English +

+ +# Vidur-AlibabaCloud + +[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) + +Vidur（[原版](https://github.com/microsoft/vidur)）是一个大语言模型（LLM）推理系统的模拟框架。 +**Vidur-AlibabaCloud**（本仓库）是针对阿里云 **SimAI** 场景优化的定制版本。支持 **Prefill–Decode（PD）分离**等高级特性，并针对 **DeepSeek-V3-671B**、**Qwen3-MoE-235B**、**Qwen3-Next-80B** 等 SOTA 大模型进行了专门适配。 + +--- + +## 目录 + +- [主要特性](#主要特性) +- [GPU 显存计算模块](#gpu-显存计算模块) +- [支持的模型](#支持的模型) +- [📦 环境配置](#-环境配置) +- [▶️ 运行示例](#️-运行示例) + - [四场景配置说明](#四场景配置说明) + - [输出文件说明](#输出文件说明) +- [🔧 关键输入参数参考](#-关键输入参数参考) +- [📊 输出结果解读](#-输出结果解读) +- [⚠️ 已知问题](#️-已知问题) +- [📚 帮助](#-帮助) + +--- + +## 主要特性 + +- **Prefill–Decode（PD）分离** — 支持 prefill 和 decode 阶段在不同节点运行，实现弹性资源分配和性能隔离。 + （参考 [splitwise-sim](https://github.com/Mutinifni/splitwise-sim)） +- **灵活的并行策略** — 支持： + - **数据并行（DP）** + - **张量并行（TP）** + - **流水线并行（PP）** + - **专家并行（EP）**（适配中） + + 同时支持 **Dense** 模型和 **混合专家（MoE）** 模型（MoE 适配中）。 +- **多种执行时间预测后端** — 可选： + - **AICB/AIOB** — 部分支持 DeepSeek-V3-671B、Qwen3-MoE-235B、Qwen3-Next-80B 的计算核与 TP、DP、PP、EP 通信量建模 + - **SimAI 仿真（Simulation）** — 基于 SimAI NS-3 的网络通信全栈仿真（支持 TP） + - **SimAI 解析（Analytical）** — SimAI 解析性能模型（支持 TP） + - **原版 Vidur [original]** — 支持 TP、DP、PP +- **负载生成与回放** — 支持真实 trace 回放，或使用固定/泊松分布生成合成请求。 +- **细粒度指标** — 记录： + - TTFT — 首 token 时延 + - TBT / TPOT — 相邻 token 时延 / 每输出 token 耗时 + - 端到端延迟 + - 通信开销 + - 计算开销 + - 调度延迟 + +--- + +## GPU 显存计算模块 + +本模块为现代 MoE（混合专家）模型的推理仿真提供精确的 GPU 显存估算，涵盖**模型参数显存**、**KV Cache 显存**以及 Prefill–Decode（PD）分离架构下的**最大批处理量**计算。 + +### 支持的注意力架构 + +| 架构 | 模型 | 说明 | +|---|---|---| +| **MLA**（多头潜在注意力） | DeepSeek-V3-671B | 使用 LoRA 压缩的 KV Cache（`kv_lora_rank` + `qk_rope_head_dim`），显著降低显存占用 | +| **MHA / GQA**（多头 / 分组查询注意力） | Qwen3-MoE-235B | 标准 KV Cache，每 token 每层使用 `num_kv_heads * head_dim` | +| **混合全注意力 + 线性注意力** | Qwen3-Next-80B | 每 4 层交替使用全注意力和线性（GDN）注意力 | + +### 核心组件 + +- **`ParamCounter`**（`vidur/utils/param_counter.py`）— 计算每层和每设备的参数量，支持 MLA、MHA/GQA、线性注意力和 MoE 专家权重，支持 FP8 量化。在 PD 分离架构下，根据 `prefill_world_size` / `decode_world_size` 分别返回 `(total_params, prefill_params, decode_params)` 三元组。 +- **`MemoryPlanner`**（`vidur/scheduler/utils/memory_planner.py`）— 规划 GPU 显存预算：`available = GPU_mem * (1 - margin) - param_mem`，计算 KV Cache 容量和最大并发请求数，包含 OOM 检测与建议输出。 +- **逐请求 KV Cache 追踪**（`vidur/entities/replica.py`）— 按请求粒度分配和释放 KV Cache 显存，支持运行时精确查询剩余容量。 + +### 参考与致谢 + +本 GPU 显存计算模块的开发参考了以下工作： + +- [InferSim](https://github.com/alibaba/InferSim) — 参数量计算与 KV Cache 估算方法论 +- [DeepSeek V3 Parameter Size Analysis](https://yangwenbo.com/articles/deepseek-v3-parameter-size.html) — DeepSeek V3 MLA 参数推导 +- [DeepSeek V3 参数推导详解](https://zhuanlan.zhihu.com/p/21455638257) — MLA 权重分解详细分析 + +衷心感谢以上资源为我们的实现提供了基础性的分析与指导。 + +--- + +## 支持的模型 + +- **DeepSeek-V3-671B**（SimAI PP/EP 通信及 GPU 显存管理模块适配中） +- **Qwen3-MoE-235B**、**Qwen3-Next-80B**（SimAI PP/EP 通信及 GPU 显存管理模块适配中） +- **meta-llama/Meta-Llama-3-8B** / **Meta-Llama-3-70B** +- **meta-llama/Llama-2-7b-hf** / **Llama-2-70b-hf** +- **codellama/CodeLlama-34b-Instruct-hf** +- **internlm/internlm-20b** +- **Qwen/Qwen-72B** + +--- + +## 📦 环境配置 + +### 1. 创建 Conda 环境 + +```bash +conda env create -p ./env -f ./environment.yml +``` + +### 2.（可选）更新开发依赖 + +```bash +conda env update -f environment-dev.yml +``` + +### 3. 激活环境 + +```bash +conda activate vidur +``` + +### 4. 安装 Python 依赖（使用阿里云 PyPI 镜像） + +```bash +pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ +pip install -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ +``` + +--- + +## ▶️ 运行示例 + +### 使用 AICB 运行 DeepSeek-671B + +**前置条件：** 需要 SimAI 和 AICB Docker 环境（参见 [README](../README.md) 了解搭建方法）。 + +完成环境配置后，运行以下命令： + +#### DeepSeek-671B + AICB（固定长度生成器） + +```bash +cd SimAI/vidur-alibabacloud + +python -m vidur.main --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype float32 \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 5 \ + --length_generator_config_type fixed \ + --fixed_request_length_generator_config_prefill_tokens 1024 \ + --fixed_request_length_generator_config_decode_tokens 10 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name deepseek-671B \ + --replica_config_tensor_parallel_size 2 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 8 \ + --random_forrest_execution_time_predictor_config_backend aicb +``` + +#### DeepSeek-671B + AICB（Trace 长度生成器） + +```bash +cd SimAI/vidur-alibabacloud + +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype float32 \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 10 \ + --length_generator_config_type trace \ + --trace_request_length_generator_config_max_tokens 1024 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --interval_generator_config_type poisson \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name deepseek-671B \ + --replica_config_tensor_parallel_size 2 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 8 \ + --random_forrest_execution_time_predictor_config_backend aicb +``` + +> ✅ 完整参数说明可通过 `python -m vidur.main -h` 查看。 + +### 使用 SimAI 仿真运行 Llama-3-8B + +```bash +cd SimAI + +# 编译 SimAI-Simulation（ns3） +./scripts/build.sh -c ns3 + +# 生成网络拓扑（Spectrum-X_128g_8gps_100Gbps_A100） +python3 ./astra-sim-alibabacloud/inputs/topo/gen_Topo_Template.py \ + -topo Spectrum-X -g 128 -gt A100 -bw 100Gbps -nvbw 2400Gbps + +cd SimAI/vidur-alibabacloud + +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype float32 \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 10 \ + --length_generator_config_type trace \ + --trace_request_length_generator_config_max_tokens 2048 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --interval_generator_config_type poisson \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name meta-llama/Meta-Llama-3-8B \ + --replica_config_tensor_parallel_size 4 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 1 \ + --random_forrest_execution_time_predictor_config_backend simai_simulation \ + --random_forrest_execution_time_predictor_config_simai_dir ../ \ + --random_forrest_execution_time_predictor_config_simai_simulation_topo ../Spectrum-X_128g_8gps_100Gbps_A100 \ + --random_forrest_execution_time_predictor_config_simai_simulation_config ../astra-sim-alibabacloud/inputs/config/SimAI.conf +``` + +### 使用 SimAI 解析模型运行 Llama-3-8B + +```bash +cd SimAI + +# 编译 SimAI-Analytical +./scripts/build.sh -c analytical + +cd SimAI/vidur-alibabacloud + +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype float32 \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 10 \ + --length_generator_config_type trace \ + --trace_request_length_generator_config_max_tokens 2048 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --interval_generator_config_type poisson \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name meta-llama/Meta-Llama-3-8B \ + --replica_config_tensor_parallel_size 4 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 1 \ + --random_forrest_execution_time_predictor_config_backend simai_analytical +``` + +### 使用原版 Vidur 运行 Llama-3-8B + +```bash +cd SimAI/vidur-alibabacloud + +python -m vidur.main \ + --replica_config_pd_p2p_comm_bandwidth 800 \ + --replica_config_nvlink_bandwidth 1600 \ + --replica_config_rdma_bandwidth 800 \ + --replica_config_pd_p2p_comm_dtype float32 \ + --poisson_request_interval_generator_config_qps 100 \ + --synthetic_request_generator_config_num_requests 10 \ + --length_generator_config_type trace \ + --trace_request_length_generator_config_max_tokens 2048 \ + --trace_request_length_generator_config_trace_file ./data/processed_traces/splitwise_conv.csv \ + --interval_generator_config_type poisson \ + --cluster_config_num_replicas 4 \ + --replica_config_pd_node_ratio 0.5 \ + --global_scheduler_config_type split_wise \ + --replica_scheduler_config_type split_wise \ + --replica_config_model_name meta-llama/Meta-Llama-3-8B \ + --replica_config_tensor_parallel_size 4 \ + --replica_config_num_pipeline_stages 1 \ + --replica_config_expert_model_parallel_size 1 \ + --random_forrest_execution_time_predictor_config_backend vidur +``` + +### 运行四场景套件 + +使用内置脚本快速验证所有支持的配置： + +```bash +bash examples/vidur-ali-scenarios/run_scenarios.sh --all +``` + +详细信息请运行 `bash examples/vidur-ali-scenarios/run_scenarios.sh --help`。 + +#### 四场景配置说明 + +以下场景已在 `run_scenarios.sh` 中预配置，所有场景共享下方硬件配置。 + +**共用硬件配置：** +- GPU：H20（h20_dgx），NVLink：1600 Gbps，RDMA：800 Gbps +- PD P2P 带宽：800 Gbps，数据类型：fp8 +- 请求生成：Poisson QPS=100，4 requests，固定 prefill=100 / decode=8 tokens + +| 场景 | 模型 | PD 分离 | World Size | TP | PP | EP | 全局调度器 | +|------|------|---------|------------|----|----|------------|------------| +| 1 | Qwen3-Next-80B (MoE) | 无 | 32 (dp=32) | 1 | 1 | 1（默认） | lor | +| 2 | Qwen3-Next-80B (MoE) | 是（P=2, D=6） | 8 | 1 | 1 | 1（默认） | split_wise | +| 3 | DeepSeek-671B (MoE) | 是（P=2, D=6） | 8 | 8 | 1 | 8 | split_wise | +| 4 | Qwen3-MoE-235B (MoE) | 是（P=2, D=6） | 8 | 4 | 1 | 4 | split_wise | + +> **说明：** 四个模型均使用混合专家（MoE）架构。EP 列反映脚本中 `--replica_config_expert_model_parallel_size` 的显式设定值；未显式指定时使用默认值 1。 + +#### 输出文件说明 + +**输出路径取决于运行方式：** + +- **`run_scenarios.sh`** --- 输出到 `examples/vidur-ali-scenarios/simulator_output/` +- **直接 `python -m vidur.main`** --- 输出到 `./simulator_output/`（或通过 `--metrics_config_output_dir` 指定的路径） + +每次运行产生如下目录： + +``` +// +├── request_metrics.csv # 逐请求指标（参见"输出结果解读"） +├── chrome_trace.json # Chrome DevTools 时间轴 trace（可在 chrome://tracing 打开） +├── config.json # 本次仿真的全部参数快照 +└── plots/ # 逐指标 CSV / JSON 文件（包括但不限于） + ├── request_e2e_time.csv + ├── prefill_e2e_time.csv + ├── pd_p2p_comm_time.csv + ├── replica_N_memory_usage.json + └── ... +``` + +> **说明：** `plots/` 中的具体文件列表可能因版本不同而变化。 +> 使用 `run_scenarios.sh` 时，运行日志另存于 `examples/vidur-ali-scenarios/logs/scenario__.log`。 + +--- + +## 🔧 关键输入参数参考 + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `--replica_config_pd_p2p_comm_bandwidth` | 800 | PD 分离中 Prefill 节点与 Decode 节点间 P2P 通信带宽（Gbps） | +| `--replica_config_nvlink_bandwidth` | 1600 | TP/EP 通信使用的 NVLink 带宽（Gbps） | +| `--replica_config_rdma_bandwidth` | 800 | 节点间通信使用的 RDMA 带宽（Gbps） | +| `--replica_config_pd_p2p_comm_dtype` | float16 | PD 通信数据类型（`float16`、`float32` 等） | +| `--poisson_request_interval_generator_config_qps` | 0.5 | 泊松请求生成器的 QPS（每秒请求数） | +| `--synthetic_request_generator_config_num_requests` | 128 | 合成请求总数 | +| `--length_generator_config_type` | fixed | 请求长度生成器类型（`fixed`、`trace` 等） | +| `--fixed_request_length_generator_config_prefill_tokens` | 2048 | 每请求的 prefill token 数（仅在 `--length_generator_config_type=fixed` 时生效） | +| `--fixed_request_length_generator_config_decode_tokens` | 512 | 每请求的 decode token 数（仅在 `--length_generator_config_type=fixed` 时生效） | +| `--trace_request_length_generator_config_max_tokens` | 4096 | 使用 trace 长度生成器时的最大 token 数 | +| `--trace_request_length_generator_config_trace_file` | `data/processed_traces/sharegpt_8k_filtered_stats_llama2_tokenizer.csv` | trace 文件路径 | +| `--interval_generator_config_type` | poisson | 请求到达间隔生成器类型 | +| `--cluster_config_num_replicas` | 1 | replica 总数（即数据并行度） | +| `--replica_config_pd_node_ratio` | 0.5 | 分配为 Prefill（P）节点的 replica 比例，其余为 Decode（D）节点。例如 0.5 表示 P:D = 1:1。 | +| `--global_scheduler_config_type` | round_robin | 全局调度器类型（`split_wise`、`round_robin` 等） | +| `--replica_scheduler_config_type` | sarathi | 单 replica 调度器类型 | +| `--replica_config_model_name` | meta-llama/Llama-2-7b-hf | 模型名称（DeepSeek-671B、Qwen3-MoE-235B、Qwen3-Next-80B 等） | +| `--replica_config_tensor_parallel_size` | 1 | 张量并行大小（TP） | +| `--replica_config_num_pipeline_stages` | 1 | 流水线阶段数（PP） | +| `--replica_config_expert_model_parallel_size` | 1 | 专家并行大小（EP） | +| `--random_forrest_execution_time_predictor_config_backend` | vidur | 执行时间预测后端（`vidur`、`simai_simulation`、`simai_analytical`、`aicb` 等）。**注意：** `simai_simulation` 和 `simai_analytical` 当前仅建模 TP 通信，不支持流水线或专家并行。 | +| `--random_forrest_execution_time_predictor_config_simai_dir` | `../` | SimAI 模拟器根目录（仅在 backend = `simai_simulation` 时生效） | +| `--random_forrest_execution_time_predictor_config_simai_simulation_topo` | `../example/topo` | SimAI 拓扑文件路径（仅在 backend = `simai_simulation` 时生效） | +| `--random_forrest_execution_time_predictor_config_simai_simulation_config` | `../astra-sim-alibabacloud/inputs/config/SimAI.conf` | SimAI 配置文件路径（仅在 backend = `simai_simulation` 时生效） | + +--- + +## 📊 输出结果解读 + +仿真结果保存于： + +``` +./simulator_output/YYYY-MM-DD_HH-MM-SS-XXXXXX/request_metrics.csv +``` + +### `request_metrics.csv` 关键列说明 + +| 列名 | 含义 | +|------|------| +| `arrived_at` / `prefill_arrived_at` | 请求进入系统的时间戳（秒）。 | +| `scheduled_at` | 请求首次被调度并开始执行的时间戳（秒）。 | +| `prefill_completed_at` | Prefill 阶段完成、生成第一个输出 token 的时间戳。 | +| `decode_arrived_at` | Decode 阶段开始的时间戳。非 PD 分离场景下通常等于 `prefill_completed_at`；PD 分离场景下为 `prefill_completed_at + pd_p2p_comm_time`。 | +| `decode_time` | Decode 阶段持续时间（秒），计算公式：`completed_at - decode_arrived_at`。 | +| `prefill_replica_id` | 执行 Prefill 阶段的 replica ID（PD 分离场景下）。 | +| `decode_replica_id` | 执行 Decode 阶段的 replica ID（PD 分离场景下）。 | +| `request_num_prefill_tokens` | 输入 token 数（即 prompt 长度）。 | +| `request_num_decode_tokens` | 输出 token 数（即生成长度）。 | +| `pd_p2p_comm_size` | PD 分离场景下，从 Prefill 节点传输至 Decode 节点的数据量（字节，含 KV Cache 等）。 | +| `pd_p2p_comm_time` | PD 分离场景下，Prefill 节点与 Decode 节点间 P2P 通信耗时（秒）。 | +| `completed_at` | 请求处理完成的时间戳。 | +| `request_execution_time` | 实际执行总时间（秒），不含抢占或流水线气泡导致的等待。 | +| `request_preemption_time` | 因调度器抢占、流水线气泡或其他非执行间隔导致的等待时间（秒）。 | +| `request_scheduling_delay` | 执行前的调度延迟：`scheduled_at - arrived_at`（秒）。 | +| `request_e2e_time` | 端到端延迟：`completed_at - arrived_at`（秒）。 | +| `prefill_e2e_time` | 首 token 时延（TTFT）：`prefill_completed_at - arrived_at`（秒）。 | +| `tbt` | 相邻 token 时延（TBT / TPOT）。计算公式：`decode_time / request_num_decode_tokens`（秒/token）。 | + +**说明：** + +- 所有时间字段单位均为**秒（s）**，基于单调时钟或 Unix 时间戳。 +- 非 PD 分离部署中，`prefill_replica_id` 与 `decode_replica_id` 通常相同。 +- 若 `request_num_decode_tokens = 0`，则 `tbt` 未定义（可能记录为 `NaN` 或 `0`）。 +- `tbt` 暂未写入 `request_metrics.csv`，目前需手动计算。 + +### 示例行（`request_metrics.csv`） + +``` +Request Id,request_e2e_time,...,arrived_at,prefill_arrived_at,scheduled_at,prefill_completed_at,decode_arrived_at,completed_at,...,prefill_replica_id,decode_replica_id,pd_p2p_comm_size,pd_p2p_comm_time,... +0,0.03607,...,0.0102006,0.0102006,0.0102006,0.0102265,0.0433997,0.0462744,...,0,2,3561947136,0.0331732,... +``` + +--- + +## ⚠️ 已知问题 + +### 绘图警告 + +退出时可能出现以下错误： + +``` +RuntimeError: Kaleido requires Google Chrome to be installed. +``` + +这是因为模拟器尝试生成 PNG 图表但缺少 Chrome。 +**重要：** 此问题**不影响** `request_metrics.csv` 的生成。 + +**解决方案：** + +1. **忽略** — CSV 输出不受影响。 +2. **安装 Chrome：** + ```bash + plotly_get_chrome + ``` +3. **禁用绘图**（不推荐）：注释掉 `vidur/simulator.py` 中的以下行： + ```python + # self._metric_store.plot() + # logger.info("Metrics written") + ``` + > 禁用绘图将跳过所有可视化输出及 `request_metrics.csv`。 + +--- + +## 📚 帮助 + +查看所有 CLI 选项： + +```bash +python -m vidur.main -h +``` From 05443a11a34302256aaee4b1ec9b6088daef8acf Mon Sep 17 00:00:00 2001 From: tianhao909 <843101550@qq.com> Date: Wed, 18 Mar 2026 05:23:14 +0000 Subject: [PATCH 2/3] chore: add GitHub community health files (templates, CI, CoC, Security, Changelog) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add GitHub community health and CI configuration files: - Bug report and feature request issue templates (YAML format) - Pull request template with bilingual checklist - Lint CI workflow (lint.yml) for code quality checks - Update .gitignore with build artifact rules 添加 GitHub 社区健康文件与 CI 配置： - Bug 报告和功能请求 Issue 模板（YAML 格式） - Pull Request 模板，含双语检查清单 - 代码质量检查 CI 工作流（lint.yml） - 更新 .gitignore 构建产物规则 Co-authored-by: tianhao909 <843101550@qq.com> Co-authored-by: MXtremist <44829997+MXtremist@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.yml | 87 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 37 +++++++++ .github/pull_request_template.md | 34 +++++++++ .github/workflows/lint.yml | 52 +++++++++++++ .gitignore | 2 + 6 files changed, 220 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/lint.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..1294bccb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,87 @@ +name: Bug Report +description: Submit a bug report to help improve SimAI +title: "[BUG]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + + It would be very helpful if you could provide as much detail as possible. + + - type: textarea + id: bug-description + attributes: + label: Describe the Bug + description: A clear and concise description of what the bug is. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction Details + description: | + Please provide detailed steps to reproduce the issue. + Include the branch names or commit IDs of SimAI/AICB you are using. + placeholder: | + 1. **Branches / Commit IDs**: SimAI branch `master` (commit `abc1234`), AICB branch `master` + 2. Go to '...' + 3. Run `...` + 4. See error: ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? Please include any error messages or logs. + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Please provide details about your environment. + placeholder: | + - OS: Ubuntu 20.04 + - GCC/G++: 9.4.0 + - Python: 3.8.10 + - Docker image (if applicable): ... + - CUDA version (if applicable): ... + - SimAI branch/commit: master / abc1234 + - AICB branch/commit: master / def5678 + validations: + required: true + + - type: textarea + id: usage-scenario + attributes: + label: Usage Scenario (Optional) + description: | + If possible, please describe your usage scenario for SimAI: + - What task or project you are working on + - The underlying goals or business context + + This information will help us collect relevant use cases and optimize the SimAI simulator to better meet your needs. + validations: + required: false + + - type: textarea + id: screenshots + attributes: + label: Screenshots / Logs + description: If applicable, add screenshots or log snippets to help explain your problem. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3b1de558 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: SimAI Documentation + url: https://github.com/aliyun/SimAI/tree/master/docs + about: Refer to the SimAI documentation to help you get started. + - name: SimAI Community (DingTalk / WeChat) + url: https://github.com/aliyun/SimAI#contact-us + about: Join our DingTalk or WeChat community groups for discussion and support. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..c04c204f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,37 @@ +name: Feature Request +description: Suggest an improvement for SimAI +title: "[FEATURE]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thank you for suggesting a feature to improve SimAI! + + - type: textarea + id: feature-description + attributes: + label: Feature Description + description: A clear and concise description of the feature you'd like. + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem / Motivation + description: | + What problem does this feature solve? Why is it needed? + Please describe the use case or scenario where this feature would be helpful. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: | + Have you considered any alternative solutions or workarounds? + Please describe them if applicable. + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..3a65802c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,34 @@ +## Description + + + +## Related Issue + + + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Performance improvement +- [ ] Refactoring (no functional changes) +- [ ] Documentation update +- [ ] Build / CI configuration change + +## Checklist + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guide +- [ ] My code follows the existing code style of this project +- [ ] I have tested my changes locally +- [ ] I have added/updated documentation as needed +- [ ] My changes do not introduce new warnings or errors +- [ ] I have verified that simulation accuracy is not degraded (if applicable) + +## Test Results + + + + +## Additional Notes + + diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000..6490eb32 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,52 @@ +name: Lint + +on: + push: + branches: [master, main] + pull_request: + branches: [master, main] + +jobs: + python-lint: + name: Python Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + + - name: Install linters + run: pip install flake8 + + - name: Run flake8 + run: | + # Stop the build if there are Python syntax errors or undefined names + flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + # Treat all other issues as warnings (non-blocking) + flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + + markdown-lint: + name: Markdown Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: markdownlint + uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: | + README.md + CONTRIBUTING.md + CHANGELOG.md + docs/**/*.md + config: | + { + "default": true, + "MD013": false, + "MD033": false, + "MD041": false + } + continue-on-error: true diff --git a/.gitignore b/.gitignore index e4a9790f..c01ebd14 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,5 @@ test/log/ *.log .cur* .DS_Store +tmp_simai_inference_workload/ +Spectrum-X* From e2ffdfcf5fc20de178f73958fac4795995a24efe Mon Sep 17 00:00:00 2001 From: tianhao909 <843101550@qq.com> Date: Wed, 18 Mar 2026 05:57:26 +0000 Subject: [PATCH 3/3] chore: restore root .gitignore with development rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 恢复根 .gitignore 中的开发规则 Co-authored-by: tianhao909 <843101550@qq.com> Co-authored-by: MXtremist <44829997+MXtremist@users.noreply.github.com> --- .gitignore | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index c01ebd14..b6d67543 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -.vscode +# .vscode astra-sim-alibabacloud/build/simai_analytical/build/ astra-sim-alibabacloud/build/astra_ns3/build/ astra-sim-alibabacloud/extern/ @@ -8,5 +8,16 @@ test/log/ *.log .cur* .DS_Store + +# fth add +*.csv +*.txt tmp_simai_inference_workload/ +aicb/ Spectrum-X* + +fth-test/* + +# Personal dev / fth files +fth.sh +**/fth.sh \ No newline at end of file