AMD-AGI/Hyperloom · 上手攻略

  • 仓库：AMD-AGI/Hyperloom
  • 链接：https://github.com/AMD-AGI/Hyperloom
  • 分类：agent / llm-infra（AMD GPU 推理自动调优）
  • 作者：spark
  • 更新：2026-10-17

三证 checklist - [x] GitHub URL 已 fetch（README 直接读取，2026-10-17） - [ ] 顶会 venue+年份：README 仅挂 arXiv 2606.12563（关联论文 Arbor），未声明会议 anchor（⚠️ 待核） - [x] README 子模块 anchor：Why / How it works / Supported features / Get started / Documentation / Developer entry points 均已 fetch - 注：卡片标 "NOASSERTION"，但 README 与 pyproject 均声明 MIT License；以 README/LICENSE 文件为准

是什么

ROCm Hyperloom 是 AMD AGI 团队在 arXiv 2606.12563（Arbor）描述的多 agent 推理调优 harness——专攻 AMD Instinct GPU（MI300X / MI325X / MI355X）上的 LLM 推理工作负载。它不是"再写一个 vLLM/SGLang"，而是一个把已有的 vLLM、SGLang、xDiT 包进"agent 调优 loop"的运行时：

  • Coordinator 跑 Orchestration + Critic 两个角色，按需调用 Specialist；
  • 一轮 session 走完 PRELUDE → ENABLEMENT → FRAMEWORK_AGENT → KERNEL_AGENT → SWEEP → CLOSE 六个阶段；
  • 每轮开始读"Recipe KB"（recipe 知识库），结束写回——同模型/同硬件的下一轮可以 warm-start；
  • Kernel 优化委托给 GEAK 或 KernelForge（仓库自带说明）两个 AMD 后端之一；
  • 所有改动必须通过 Critic + coordinator benchmark 才落到 baseline，否则 revert。

版本：README badge 标 1.1.4，pyproject 声明 Python ≥ 3.10。

解决什么问题

服务端的吞吐 = 硬件容量 / 时延 / 单位成本。手动把 vLLM/SGLang/xDiT 在 AMD GPU 上调优一次要数周、调参专家稀缺；每来一个新模型、一次框架升级、一代新加速卡，又得重做。

直接把这段 loop 交给 LLM 不够：

  • 单次 session 可能数百 turn，要重启多次推理服务、要编辑框架源码；
  • 没有 harness 约束的话，agent 会偏离目标、重复踩坑、可能写出 unsafe patch；
  • agent 自报的加速比不可信，必须由 coordinator 重新实测。

Hyperloom 就是这段 loop 的 harness：把 mission 锚在持久化状态文件里、复用历史 recipe、用 policy gate + Critic + 实测三道闸门决定是否保留改动。

快速安装

仓库用 pyproject.toml（badge 显示 v1.1.4，Python ≥ 3.10）。最小安装与一次 demo：

# 1. 克隆并安装
git clone https://github.com/AMD-AGI/Hyperloom
cd Hyperloom
# 按 pyproject 选择 uv 或 poetry；以 pip 为例
pip install -e .

# 2. 配置凭据（详见 docs/reference/authentication.md）
# 通常是 LLM backend 的 API key（Claude / Codex）+ AMD GPU 驱动栈（ROCm + vLLM/SGLang/xDiT）

# 3. 跑一次 demo
python -m hyperloom optimize

⚠️ 与本机环境强相关：要跑实测必须装好 ROCm 驱动、目标 serving 框架（vLLM/SGLang/xDiT 中至少一个）、以及对应模型权重。README 把 GPU 平台、Framework、Kernel 语言、LLM backend 都列成了 supported features，下手前先对表。

核心用法

1. 一次性优化

python -m hyperloom optimize

默认会启动一轮完整 session：Prelude 测基线、视情况进 Enablement、跑 Framework 与 Kernel 优化、Sweep 重测、按预算决定是否再来一轮。

2. 运维工具

python -m hyperloom session breakdown   # 输出 session_breakdown.json
python -m hyperloom session report      # 输出人类可读报告
python -m hyperloom session backfill    # 回填历史数据
python -m hyperloom session events      # 流式事件
python -m hyperloom session state       # 当前持久化状态

3. Compute-partition 扫描（GPU 分区）

python3 scripts/partition_mode_sweep.py

脚本把同一张卡的 SPX/DPX/QPX/CPX 模式各试一遍，同步预算执行记录吞吐和恢复模式。答案先于 session commit：用来告诉 optimize 这张卡到底想跑什么形态。需要特权（sets the partition mode）。

4. 平台调优审计（CPU 侧）

python3 scripts/platform_audit.py            # 检查 Core Performance Boost / cpufreq governor
sudo python3 scripts/platform_audit_bmc.py --bmc-user <ro>   # 通过 BMC 看 BIOS 端三个旋钮
  • platform_audit.py 退出码：0 达标、1 有旋钮错、2 无法判定（CI 应视为缺覆盖，不当失败处理）；
  • platform_audit_bmc.py 默认拒绝运行；通过 --allow-account-creation 才会临时在 BMC 上 铸一个 ADMINISTRATOR 账号——exit 3 表示这个账号没被关掉或没确认关闭，应当报警；详见脚本 docstring。

5. 选择 kernel 后端

README Supported features 表里 Kernel backends 给的是 GEAK、KernelForge 二选一。README 强调"Only one backend runs per phase"——一次 session 只跑一个后端，避免混跑结果不可比。

6. Recipe KB 的语义

每一行 KB 存：winning 配置、measured throughput、值得记住的 lesson、值得记住的失败。Lookup 顺序放宽字段：model → hardware → framework → model type → architecture → framework version → precision。失败会被写入 prompt context 但不当硬否决——"进入 KB 是严格的"，因为坏 entry 会污染所有未来 session。

7. 关联的内部组件

  • 性能 profiling / 瓶颈分析：TraceLens
  • trace 采集：Magpie
  • 低层 GPU 工具：IntelliKit
  • 长程搜索 + KB：见 Arbor（arXiv 2606.12563）

典型适用场景

  • 新模型上线：在 MI300X/MI325X 上跑一遍 optimize，把 winning 配置写进 KB，下次同硬件同模型直接 warm-start；
  • 框架升级回归：vLLM 升版本时让 Hyperloom 在同一 workload 上重测，自动对比 KB 历史；
  • kernel 候选验证：把 GEAK/KernelForge 给出的 patch 喂进 session，由 Coordinator 重测是否真加速——agent 自报不算数；
  • 多平台移植：在 MI300X 上调好的 recipe 拿去 MI325X/MI355X，KB 字段级 lookup 可以快速 warm-start。

坑与注意

  1. 平台依赖极重：ROCm、目标 serving 框架、目标 GPU 驱动缺一不可；任何一项错版本都可能让 Sweep 阶段静默给出错基线。
  2. Kernel 后端只能选一个：GEAK 与 KernelForge 不能同 session 跑，否则结果不可比；这是 README 显式声明的边界。
  3. Privilege 边界：partition_mode_sweep.py 与 platform_audit_bmc.py 都需要特权；后者默认拒绝运行，启用 --allow-account-creation 会 在 BMC 上临时建管理员账号——务必在生产 BMC 上先评估风险。
  4. 平台审计退出码 ≠ 失败：platform_audit.py 的 exit 2 表示"我读不到 BIOS 那一层"，是 CI 缺覆盖，不是 hyperloom 本身失败；不要把它当 broken pipeline。
  5. Recipe KB 的"污染代价"：一条坏 entry 会延续到未来所有 session；写入 KB 前务必自查 orchestrator 与 critic 的 verdict。
  6. Patch safety gate：risky 源码改动走 isolated worktree → unified-diff gate → policy check → Critic sign-off → coordinator benchmark，任意一环被 reject 都会以"命中所破规则"形式报告——读错误信息要按规则名修复，不要重复 attack。
  7. 三证缺口：与 v3 同样没声明会议 venue；引用 Arbor 前请独立确认是否已被接收。

与同类对比

项目 形态 目标硬件 后端框架 来源 patch 验证
Hyperloom（本） multi-agent harness + Recipe KB AMD Instinct（MI300X/325X/355X） vLLM / SGLang / xDiT Critic + 实测两闸门
vLLM/SGLang/xDiT 原生 serving 框架 NVIDIA 主，AMD 越来越齐 — —
NVIDIA TensorRT-LLM Optimizer / Triton Model Optimizer NVIDIA 专享 NVIDIA TensorRT / Triton 自家实测
KernelBench / AILabsKernel 偏 kernel 评估 静态基准 跨平台 — 静态得分

相对单纯 serving 框架：Hyperloom 不替代 vLLM/SGLang，而是给它们装一个"自动调优的包工头"；相对 NVIDIA 生态的同类工具：Hyperloom 是目前公开仓库里 AMD GPU 端少有的、把 framework + kernel + KB 串起来的工具。

一句话推荐结论

如果你跑的是 AMD Instinct GPU、且有"新模型 / 新框架版本 / 新加速卡"持续上线的工作量，Hyperloom v1.1.1 是当前少有的能在端到端层面闭环"自动调优 + 验证 + 入库"的 harness；下手前先把 ROCm + 至少一个 serving 框架跑通，再用 partition_mode_sweep.py + platform_audit.py 把平台调优打底，最后才上 python -m hyperloom optimize 的完整 session。

引用：Arbor 论文 arXiv 2606.12563（⚠️ 会议 venue 待核）。