hyperloom-workload-optimizer

Hyperloom 工作负载优化器

这是 AMD Instinct GPU 上 Hyperloom 优化的入口。你的任务是完成引导：确认工作区、安装 Hyperloom wheel、运行 /hyperloom-setup，然后将运行交给负责它的技能。

wheel 会安装负责后续所有工作的技能：负责凭据和运行模式的 hyperloom-setup、负责工作负载预设的演示技能，以及负责启动器门控和监控的 inference_optimizer。这些技能随运行时一起发布，因此始终与已安装的版本匹配。

此技能不负责的事项

• 不要自行运行 python -m hyperloom.inference_optimizer.cli optimize。
• 不要在此处实现 GPU 预检、启动器门控或后台启动。这些工作由已安装的技能负责，包括 Iron Rules 和恢复运行路径。
• 安装期间或设置运行期间，不要询问工作负载值（模型、TP/EP、并发数、ISL/OSL、精度、目标、预算）。这些内容属于运行技能，应在设置完成后处理。
• 不要在聊天中手动优化。

前提条件

• AMD Instinct GPU 主机（MI300X / MI325X / MI355X），配备 ROCm，存在 /dev/kfd 和 /dev/dri，且 amd-smi 或 rocm-smi 可正常运行。
• 运行安装的机器上有 Python 3.10+ 和 pip。
• LLM 凭据：Anthropic API 访问权限或 AMD LLM 网关。
• 一个专用的空目录，并已在 Agent 中作为工作区打开。

安装前，确认当前所在的 shell 位于 GPU 主机上。设置之后可能会将 Docker 指向另一台目标主机；在此之前，所有操作都在 Agent 所在的机器上运行。

步骤 1：确认工作区

当前目录既是安装目标，也是 Agent 工作区。安装前，向用户确认这是一个专用目录：设置会在其中创建或更新 .env。不要自行切换到其他目录；除非用户接受 .env 的更改，否则不要安装到现有项目中。

步骤 2：安装 Hyperloom wheel

pip install hyperloom-inference-optimizer --target .

除非用户要求指定版本，否则安装当前发行版。之后目录中出现许多 Python 软件包文件夹是正常的；用户无需检查它们。

步骤 3：运行 /hyperloom-setup

wheel 会将 hyperloom-setup 安装到 Agent 的技能目录（.agents/skills/、.claude/skills/、.cursor/skills/）。运行它：

/hyperloom-setup

该过程是交互式的，负责凭据、USER_DATA_PATH、运行模式（推荐使用 docker，也可选择 baremetal）、Docker 目标主机以及裸机框架安装。它会写入 .env，并在任何优化开始前停止。每个工作区运行一次即可；运行技能会复用这些值。

让设置过程自行提问。不要抢先回答问题，不要复述其选项列表，也绝不要让用户在聊天中粘贴 API 密钥。

如果安装后 Agent 未列出 hyperloom-setup，说明技能目录是在 Agent 扫描之后写入的。请告知用户重启 Agent，然后再次运行该技能。不要用自行编写的设置步骤替代它。

第 4 步：移交给运行技能

设置过程会以提供运行选项并加载匹配技能作为结束，因此通常只需按提示操作。如果用户直接要求运行，请按名称加载技能并遵循其说明，而不是遵循本技能：

• hyperloom-qwen3-8b-3h — 短时、无内核的 Qwen3-8B 运行；最适合作为首次端到端检查。
• hyperloom-qwen3-14b-fp8-12h — 中等时长的 Qwen3-14B-FP8 运行。
• hyperloom-qwen3-14b-fp8-12h-forge — 在 KernelForge 内核后端上进行的相同运行。
• hyperloom-custom-advanced — 显式指定模型、框架、工作负载、预算和阶段开关。

即使用户提供自己的 MODEL_PATH，预设也会保留其工作负载；不会针对该模型重新调整张量并行、并发数、序列长度、精度和预算。需要更改这些设置时，请使用 hyperloom-custom-advanced。

要恢复已停止的会话，请遵循 .env 中 HYPERLOOM_SKILL_PATH 指定的优化器技能；恢复流程和重新启动仍需通过的门槛由该技能负责。

运行期间的预期情况

优化会在后台运行数小时。不要持续输出日志。

启动前，运行技能会展示计划：解析后的模型路径、运行模式、框架、TP、并发数、ISL/OSL、精度、预算和 USER_DATA_PATH。优化器启动前，请取得用户对该计划的确认——启动后，GPU 将由其独占数小时。启动后，它会报告优化器 PID、运行日志、启动信息 JSON、会话目录、state.json 和首次健康检查结果。

运行期间，每隔约 300 秒报告一次简短状态：进程是否存活、当前阶段、stop_reason、基线和当前最佳吞吐量、累计增益、最新基准测试或候选项决策，以及最相关的日志行。

切勿输出 API 密钥、令牌或自定义标头。

故障排查

• 在工作区中看到许多软件包目录是正常的，这是在 pip install --target . 后的预期结果。
• 未列出 /hyperloom-setup：安装发生在 Agent 扫描技能之后。重启 Agent，并检查 .claude/skills/hyperloom-setup/ 是否存在。
• ImportError: libamdhip64.so.7 或 libhipblas.so.3：框架的 torch wheel 需要不同的 ROCm 用户空间库；请使 ROCM_PATH 和 LD_LIBRARY_PATH 保持一致。
• 构建 AITER 时缺少 hipDeviceAttributePciChipId：hipcc 使用的是较旧的 ROCm 头文件；请将匹配的 ROCm bin 目录放在 PATH 的最前面。
• 设置完成后的所有问题（预检失败、启动、阶段、增益）均由已安装的运行技能和优化器技能负责。请查阅这些技能，而不要在此重复其检查。