OpenBMB/ForgeStencil

ForgeStencil 配备了两个 LLM agent，它们协同工作，将一个 stencil 优化理念 转化为真实软件中经过验证的加速 —— 全程无需人工干预。它已在 **100 个经过端到端验证的应用程序**（石油与天然气、电磁学、 医学成像、CFD、气候、天体物理学、材料学、HPC 基准测试）上运行，实现了 **中位数 1.41× / 几何平均 2.05×** 的端到端加速，所有数据均可 **基于应用程序自带的生产级 GPU 代码进行复现**。 ## 🧭 架构 ``` flowchart LR subgraph KA["Kernel Agent"] direction LR P[Plan] --> C[Code] --> Pr[Profile] --> P end subgraph AA["App Agent"] direction LR H[Locate hotspot] --> F["Forge app-specific operator
(knowledge-base-driven)"] --> V[Verify correctness] --> I[Integrate] end KA -->|optimized operators| LIB[("kernel/
operator library =
knowledge base")] LIB -->|techniques & operators| AA AA -->|"single USE_OURS switch"| HR["Harness:
interleaved measure vs
the app's own GPU code"] HR -->|validated speedup| RES[("results
registry")] ``` ## 📑 目录 [亮点](#-highlights) · [为什么选择 ForgeStencil？](#-why-forgestencil) · [快速开始](#-quick-start) · [结果](#-results-audited) · [工作原理](#-how-it-works) · [仓库布局](#-repository-layout) · [常见问题](#-faq) · [局限性](#-limitations) · [贡献](#-contributing) · [路线图](#-roadmap) · [鸣谢](#-acknowledgments) · [许可证](#-license) · [引用](#-citation) ## ✨ 亮点 - 🤖 **双 agent 循环** — 一个 **Kernel Agent** 负责研究生成 CUDA stencil 算子（计划 → 编码 → 分析），一个 **App Agent** 则在此知识库的基础上锻造特定于应用程序的算子，并将它们集成到真实应用程序中。 - 🔬 **是研究，而不仅仅是代码生成** — 该 agent 会*发现*优化策略（平铺、融合、布局、占用率、主机端重构），而不仅仅是在固定的空间中进行搜索。 - 🏭 **是真实应用程序，而非单纯基准测试** — 基准线是应用程序*自带的生产级 GPU 代码*，而非简化的参考代码。 - 🔒 **可审计的测量协议** — 单一的程序内切换、程序自带的正确性检查、交替执行的中位数、所有标准用例的几何平均值。伪造加速将成为系统级错误。 - 📦 **补丁模式，许可证清洁** — 不捆绑任何第三方源码；每个应用程序都附带来源记录 + 获取脚本 + 我们的集成补丁。 - 🧬 **多架构** — 一个算子库即可通过运行时分发支持 A100 (sm_80)、H100 (sm_90) 和 B200 (sm_100)；特定于架构重新锻造的收益受架构门控限制，因此其他执行路径保持字节一致。参见[跨代研究](#across-gpu-generations-a100--h100--b200)。 - ♻️ **可复现** — 报告的每一个数字都可以从全新的克隆中重新运行（已在 A100 上完成端到端验证）。 ## 🆚 为什么选择 ForgeStencil？ 二十年来，stencil 优化一直被自动化 —— 但仅限于*代码生成*部分。人类依然需要设计优化策略并进行集成。ForgeStencil 实现了策略发现**与**部署的双重自动化。 | 能力 | DSL / 代码生成
(Halide, Devito) | 自动调优器
(AN5D, EBISU, DRStencil) | **ForgeStencil** | |---|:---:|:---:|:---:| | 生成优化的 kernel 代码 | ✅ | ✅ | ✅ | | 发现*全新*的优化策略 | ❌ *(人工设计)* | ⚠️ *(在固定空间内搜索)* | ✅ *(Agent 探索)* | | 部署到真实应用程序中（热点定位 → 锻造 → 集成） | ❌ | ❌ | ✅ | | 在真实程序内部验证正确性 | ❌ | ❌ | ✅ | | 对比应用程序*自有*生产级 GPU 代码的可审计端到端加速 | ❌ | ❌ | ✅ | ## 🚀 快速开始 **环境要求：** NVIDIA GPU（已在 A100-SXM4-80GB, `sm_80` 上验证），CUDA 12.x， C++17 主机编译器，带有 `numpy` + `cupy` 的 Python 3.9+，以及支持 HTTPS 的 `git`（最小化的 conda `git` 可能缺少 `https` 助手 —— 请使用 `/usr/bin/git`）。 ``` git clone forge-stencil && cd forge-stencil python -c "import numpy, cupy; print('deps OK')" # verify install ```

🤖 正在使用编码 Agent（例如 Claude Code）？

将此内容粘贴给你的 agent，即可自动设置并运行首个演示：

### 1. 在约 1 分钟内测完一个算子（无需下载应用程序） 查看 ForgeStencil 工作原理最快的方式 —— 构建我们的 kernel 并对其进行测量 （基准测试是可选的；缺失的项会显示为 `null`）： ``` python tools/run.py --stencil star_1 --shape 256 --gpu 0 ```

预期输出

``` [1/1] star_1 256³ ... 0.074 ms [PASS] # our kernel, verified vs NumPy reference === Halide (single-step) === Stencil Shape AMReX(ms) Ours(ms) BL(ms) BL(GC/s) Status star_1 256³ N/A 0.074 0.144 116.63 [PASS] Correctness: ALL PASSED ``` （此处我们的 kernel 耗时 0.074 ms，而 Halide 为 0.144 ms；AMReX/其他 基准是可选的 —— 参见 [`baselines/`](baselines/README.md)。）

### 2. 复现完整的端到端应用程序结果 获取真实的上游代码，应用我们的补丁，并使用应用程序自带的 正确性检查和计时器重新测量： ``` cd applications/haccmk ./vendor.sh # fetch upstream at the recorded version git apply patches/integration.patch # our USE_OURS injection (from this app dir) python ../../harness/run_e2e.py --app haccmk --gpu auto ```

预期输出

``` [e2e] build [orig] ... build [ours] ... [e2e] round 1/7: orig=0.0027s ours=0.0001s [e2e] ... [e2e] app-level correctness: True (builtin check PASS) [e2e] MEASURED end-to-end GEOMEAN speedup over 1 case(s): 36.703x ``` （已在 A100 上通过全新克隆验证。绝对比率会随 GPU/节点 状态变化；正确性保持不变。）

## 📊 结果（已审计） 所有数据均直接来自结果注册表 (`results/integration_registry.json`)，并可通过测试框架复现。 我们报告了**完整的分布情况**。 ### 端到端，跨越 100 个经验证的应用程序 | 指标 | 数值 | |---|---| | 端到端中位数加速 | **1.41×** | | 几何平均 | 2.05× | | 范围 | 0.998× – 97.7× | | ≥ 1.05× | 89% | | ≥ 1.20× | 73% | | ≥ 1.50× | 43% | | ≥ 3× | 21% | | ≥ 10× | 7% | ### 算子级性能 **Roofline（独立于基准）。** 经 Nsight Compute 测量，ForgeStencil 的 内存受限型 stencil kernel 达到了 **A100 2039 GB/s 峰值 DRAM 带宽的 74–85%** —— 接近带宽受限型 stencil 的实际硬件上限。 （`box_2` 和 `diamond_ts4` 受限于计算/数据重用，处于不同的状态。） **在相同精度下对比每个形状下的最佳基准。** 在每一个 (stencil, 形状) 组合中，我们都采用*最强*的适用公开结果，进行 **同类别对比**：单步对单步（Halide、Devito），时间分块对 时间分块（EBISU），以及 **fp16 对 fp16** —— 其中 `star_1`/`star_2` 在立方体形状上使用 fp16，Halide 同样以 fp16 运行。 | Stencil（精度） | 用例数 | 对比最佳基准的几何平均 | 领先项 | |---|:---:|:---:|:---:| | `star_1` (7-pt, fp16/fp32) | 9 | 1.63× | 9 / 9† | | `star_2` (13-pt, fp16/fp32) | 7 | 1.92× | 7 / 7 | | `box_1` (27-pt, fp32) | 5 | 3.08× | 5 / 5 | | `box_2` (fp32) | 3 | 4.60× | 3 / 3 | | `diamond_1` (fp32) | 3 | 3.08× | 3 / 3 | | `varcoeff_star_1` (fp32) | 5 | 1.51× | 5 / 5 | | **总体** | **32** | **≈2.16×** | **32 / 32** | 数值为 7 次稳健遍历的中位数；衡量标准由 Halide 和 Devito 共同设定。**关键在于，即便 Halide 以相同的 fp16 精度运行，`star_1`/`star_2` 依然获胜**（fp16 对 fp16：在 8 个立方体形状上提升 **1.75×**） —— 这种优势是真正的*同等精度*下的实现胜利，而不是精度差异造成的假象 （Halide 几乎没有从 fp16 中获益；而我们的 kernel 利用了减半的 带宽）。对于对比 EBISU（时间分块）的时间分块 stencil： `diamond_ts4` 1.82×（胜），`diamond_ts8` 0.73×（负）。†`star_1` 128³ 为 完全持平 (1.00×)；其他所有形状均领先。在通过 [`baselines/vendor_baselines.sh`](baselines/README.md) 获取基准后，使用 `tools/run.py` 进行复现。 ### 跨 GPU 代际（A100 → H100 → B200） 算子库携带了**运行时架构分发**（sm_80 / sm_90 / sm_100）：相同的 `kernel/` 源码会在特定代际的重新锻造胜出时挑选受架构门控的变体，并在其他情况下保持 A100 路径的字节一致性。跨代研究的问题是：*Agent 锻造的 kernel 能否直接迁移， 以及何时重新锻造才有价值？* | 过渡 | 硬件放宽了什么 | 结果 | 重新锻造带来的提升 | |---|---|---|---| | A100 → H100 (带宽 +1.68×) | 计算能力，带宽几乎未变 | kernel 达到**依然带宽饱和**的状态（DRAM 77–90%）→ 近乎最优的迁移 | `box_2` (计算受限)：通过重新调优配置（kernel 路由 + launch bounds）提升 +6–7% | | H100 → B200 (带宽 +2.4×) | 带宽 ≫ 内存发射速率 | kernel **脱离了 roofline**（DRAM 78–90% → 44–65%），B200/H100 的几何平均为 1.51×，而带宽比率为 2.39× | `box_1`：结构性深度预取，@512³ 提升 +7.0% / @1024³ 提升 +5.1% | 相比 Halide 的优势*在多代架构中保持不变*（几何平均值在 A100 上为 2.16× → 在 H100 上为 2.38×）。完整的情况、每轮锻造日志和 原始数据：[`docs/CROSS_GEN_REFORGE.md`](docs/CROSS_GEN_REFORGE.md)、 [`docs/FORGE_LOG_H100.md`](docs/FORGE_LOG_H100.md)、 [`docs/FORGE_LOG_B200.md`](docs/FORGE_LOG_B200.md)、 [`results/cross_gen/`](results/cross_gen/README.md)。 *测量注意事项：B200 的数据来自可抢占的云 pod —— 结果基于同一 pod 内的 A/B 比率；绝对毫秒数取决于节点/时钟。* ### 如何解读端到端数据 **加速比主要反映了上游应用程序拥有的优化空间有多大 —— 而不是单个 kernel 的绝对实力。** - 当应用程序自身的 GPU 代码存在*结构性*瓶颈（过多 微小的 kernel 启动、低占用率、每步进行主机同步）时， 端到端的重构可以带来巨大的收益。示例（标记了获胜来源）： `pathfinder` 97.7×，`bspline_vgh` (QMCPACK B-spline) 58.4×，`haccmk` (HACC 短程力) 36.2× —— 大部分属于*结构性 / 启动融合*带来的胜利。 - 当应用程序*已经过高度调优*（厂商 SDK kernel、手工编写的 supergrid kernel）时，结果通常在 **1.0–1.5×** 之间。示例： `sw4lite` 1.00×（持平），`hpgmg_fv` 1.02×，`cloverleaf` 1.01×。 - 算子级锻造的收益则介于两者之间， gprMax/FDTD Maxwell `2.47×`。 1.0× 的持平结果表明上游代码已经达到了硬件极限， 而我们的集成在保持正确性的同时没有发生性能倒退。 ## 🔧 工作原理 ForgeStencil 绝不捆绑第三方源码。对于每一个集成的应用程序， 它都会提供： ``` applications// ├── PROVENANCE.md # upstream repo URL + sha256 of the exact bytes + result ├── vendor.sh # fetches the upstream source from its original location ├── patches/*.patch # OUR integration diff: adds a USE_OUR_ switch └── e2e/{manifest.json, build.sh} kernel/_ours.cuh # OUR optimized operator ``` 测试框架在**同一个二进制文件中**交替运行（通过单一环境变量切换）原始和优化后的执行路径， 检查程序自身的正确性，读取程序自带的计时器，并报告在应用程序**所有**标准用例上的**几何平均** 加速比。 ### 可审计的测量协议 1. 基准线是应用程序自带且用于生产的 GPU 实现。 2. 原始和优化后的执行路径仅由一个开关决定；原始路径 与上游代码在字节层面完全一致。 3. 正确性来源于程序自身的检查（位精确或其自带容差）。 4. 计时使用程序自带的计时器；原始/优化后的路径在 多轮交替执行并取中位数。 5. 报告的数值是应用程序所有 标准用例上的几何平均值。 如果任何条件不满足，该结果将被标记为**未验证 / 受阻** 并且不予计算。 ## 📁 仓库布局 | 路径 | 内容 | |---|---| | `kernel/` | 算子库 — 优化的 CUDA stencil kernel（`*_ours.cuh`、`stencil_kernel.cu`）以及 Python 分发层。 | | `tools/` | `run.py` — 算子级基准测试驱动（构建我们的 kernel，并与基准进行对比）。 | | `harness/` | 端到端测量协议（`run_e2e.py`、`measure_*.py`、`provenance.py`、`manifest_schema.json`）。 | | `agents/` | Kernel Agent + App Agent 编排循环及其操作规则 — 详见 [`agents/README.md`](agents/README.md)。 | | `applications/` | 100 个按应用划分的复现包（来源 + 获取脚本 + 补丁 + 测试框架配置）。**无上游源码。** 详见 [`applications/README.md`](applications/README.md)。 | | `operator_bench/` | App Agent 工作流使用的按应用划分的算子代理基准测试（`bench_ours.cu`）。 | | `baselines/` | 运行脚本 + `vendor_baselines.sh` 获取第三方 stencil 基准的脚本。**不捆绑基准源码。** 详见 [`baselines/README.md`](baselines/README.md)。 | | `results/` | 已审计的集成结果注册表；`results/cross_gen/` 存放 H100/B200 的跨代测量数据。 | | `docs/` | 研究文档：跨代重新锻造（`CROSS_GEN_REFORGE.md`）+ 提炼后的 H100/B200 每轮锻造日志。 | ## ❓ 常见问题

vendor.sh 失败并提示 "remote-https is not a git command"

你的 `git` 是一个没有 HTTPS 远程助手的极简 conda 版本。请使用 系统自带的 git：`PATH=/usr/bin:$PATH ./vendor.sh`，或者 `conda install -c conda-forge git`。

上游克隆超时 / 断开连接

外部 git 连接可能不稳定。`vendor.sh` 会自动重试；只需重新运行即可。 对于大型代码库，预热 DNS/代理会有所帮助。在可能的情况下，获取操作均为浅克隆。

我测出的加速比与 README / 注册表中的不同

绝对加速取决于 GPU 型号、时钟频率和节点负载（共享的繁忙 节点会推高基准线）。**正确性是不变的**；*比率* 在空闲且锁定频率的 A100 上是可以复现的。使用 `nvidia-smi -lgc ` 锁定频率，并在无负载的 GPU 上运行以获得严谨的数据。

如何选择 GPU？

`run_e2e.py --gpu auto` 会选择最空闲的 GPU；`tools/run.py --gpu ` 接受一个 显式的索引。使用 `nvidia-smi` 查找空闲设备。

我需要构建基准 / AMReX 才能获得结果吗？

不需要。`tools/run.py` 会优雅降级 —— 缺失的基准会显示为 `null`，并且 使用 NumPy 的 CPU 参考进行正确性验证。只有在需要 对比数据时才需获取基准。

## 🚧 局限性 - **每种架构的验证覆盖率。** 算子库携带了 A100 (`sm_80`)、H100 (`sm_90`) 和 B200 (`sm_100`) 的运行时分发，并在所有这三种架构上测量了算子级结果（参见 [跨代研究](#across-gpu-generations-a100--h100--b200)）。 100 个端到端应用程序包均在 A100 上进行了验证；在 H100/B200 上重新运行它们已列入路线图。 - **加速比 ≠ kernel 实力。** 端到端的大幅提升通常反映了上游应用存在结构性优化空间，而非普遍更快的 kernel；面对 已经调优过的代码，结果通常在 1.0–1.5× 之间。 - **纯 CPU 的上游。** 少数应用程序没有 GPU 版本；这些属于跨架构 对比（由硬件主导），并被标记为*研究*，绝非*已验证*。 - **LLM 非确定性。** 这些 agent 由 LLM 驱动；特定运行路径并非 位级可复现，尽管*测量到的产物*（补丁、结果）是可复现的。 - **正确性采用的是程序自身的检查。** 如果应用程序自带的自检较弱， 我们的正确性保证也仅限于该检查的力度。 - **负责任的使用。** ForgeStencil 仅优化性能；它保留了 应用程序的数值语义，并且绝不在程序自身的 正确性容差范围之外改变科学计算输出。 ## 🎯 路线图 - [x] 跨代研究 — A100 → H100 → B200 算子级测量 + 重新锻造（[文档](docs/CROSS_GEN_REFORGE.md)） - [x] 算子级 Roofline / 可达带宽分析（Nsight Compute，[结果](results/cross_gen/README.md)) - [ ] 在 H100/B200 上重新进行端到端应用程序验证 - [ ] 扩充按用例划分的算子基准 - [ ] 发布 Agent 自主性与成本指标（每个应用的迭代次数、干预次数、token 数） - [ ] 更多应用程序集成（由社区驱动 —— 提交 issue 以提出建议） - [x] 双语 README (English / 中文) 优先级由社区需求决定 —— [提交 issue](../../issues) 发表你的看法。 ## 📄 许可证 Apache-2.0（宽松许可，包含专利授权）— 详见 [`LICENSE`](LICENSE)。 ForgeStencil **不会**重新分发第三方的上游源代码；关于如何引用上游应用程序 和基准测试，请参阅 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md)。 ## 📚 引用 如果您在研究中使用了 ForgeStencil，请引用它（参见 [`CITATION.cff`](CITATION.cff))：

BibTeX

``` @software{forgestencil, title = {ForgeStencil: Autonomous Agents for Stencil Optimization and Deployment}, author = {The ForgeStencil Authors}, year = {2026}, url = {https://github.com/OpenBMB/ForgeStencil} } ```

标签：AI智能体, CUDA, Vectored Exception Handling, 人工智能, 代码优化, 用户模式Hook绕过, 科学计算, 逆向工具, 高性能计算