hyperloom-workload-optimizer

Hyperloom Workload Optimizer

AMD Instinct GPU での Hyperloom 最適化のエントリーポイントです。担当するのはブートストラップです。ワークスペースを確認し、Hyperloom のホイールをインストールして、/hyperloom-setup を実行した後、その実行を担当するスキルに引き継ぎます。

ホイールは、セットアップ完了後のすべてを担当するスキルをインストールします。認証情報と実行モードを扱う hyperloom-setup、ワークロードのプリセットを扱うデモスキル、ランチャーのゲートとモニタリングを扱う inference_optimizer です。これらはランタイムに同梱されるため、インストール済みのバージョンと常に一致します。

このスキルの対象外

• python -m hyperloom.inference_optimizer.cli optimize を自分で実行しないでください。
• GPU の事前チェック、ランチャーのゲート、バックグラウンド起動をここで実装しないでください。Iron Rules や再開パスも含め、これらはインストール済みのスキルが担当します。
• インストール中やセットアップ実行中に、ワークロードの値（モデル、TP/EP、同時実行数、ISL/OSL、精度、目的、予算）を尋ねないでください。これらはセットアップ完了後に、実行スキルで扱います。
• チャット内で手動で最適化しないでください。

前提条件

• ROCm、/dev/kfd、/dev/dri があり、amd-smi または rocm-smi が動作する AMD Instinct GPU ホスト（MI300X / MI325X / MI355X）。
• インストールを実行するマシンに Python 3.10 以降と pip があること。
• LLM の認証情報：Anthropic API へのアクセス、または AMD LLM ゲートウェイ。
• エージェントでワークスペースとして開いた、専用の空のディレクトリ。

インストール前に、現在のシェルが GPU ホスト上にあることを確認してください。セットアップで後から Docker の接続先を別のホストに指定することはできますが、指定するまでは、ここでの処理はすべてエージェントがいるホストで実行されます。

ステップ 1：ワークスペースを確認する

現在のディレクトリがインストール先であり、エージェントのワークスペースでもあります。インストール前に、ここが専用ディレクトリであることをユーザーに確認してください。セットアップにより、このディレクトリ内の .env が作成または更新されます。独断で別のディレクトリに切り替えないでください。また、ユーザーが .env の変更を了承していない限り、既存のプロジェクトにはインストールしないでください。

ステップ 2：Hyperloom のホイールをインストールする

pip install hyperloom-inference-optimizer --target .

ユーザーから特定のバージョンを指定されない限り、最新リリースをインストールしてください。インストール後にディレクトリ内に多数の Python パッケージ用フォルダーができるのは正常です。ユーザーがそれらを確認する必要はありません。

ステップ 3：/hyperloom-setup を実行する

ホイールは、エージェントのスキルディレクトリ（.agents/skills/、.claude/skills/、.cursor/skills/）に hyperloom-setup をインストールします。これを実行してください。

/hyperloom-setup

これは対話形式で、認証情報、USER_DATA_PATH、実行モード（docker を推奨、または baremetal）、Docker の接続先ホスト、ベアメタルでのフレームワークのインストールを扱います。.env を書き込み、最適化を開始する前に停止します。各ワークスペースで一度実行してください。実行スキルはそれらの値を再利用します。

セットアップが独自に質問するようにしてください。質問を先回りしたり、選択肢を言い直したりしないでください。また、API キーをチャットに貼り付けるようユーザーに求めないでください。

インストール後にエージェントのスキル一覧に hyperloom-setup が表示されない場合、エージェントがスキルをスキャンした後にスキルディレクトリが書き込まれています。エージェントを再起動してから、もう一度実行するようユーザーに伝えてください。独自のセットアップ手順で代用しないでください。

ステップ 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 が一覧に表示されない場合：エージェントがスキルをスキャンした後にインストールされた可能性があります。エージェントを再起動し、.claude/skills/hyperloom-setup/ が存在することを確認してください。
• ImportError: libamdhip64.so.7 または libhipblas.so.3：フレームワークの torch ホイールが異なる ROCm ユーザー空間ライブラリを必要としています。ROCM_PATH と LD_LIBRARY_PATH を一致させてください。
• AITER のビルド中に hipDeviceAttributePciChipId が見つからない場合：hipcc が古い ROCm ヘッダーを使用しています。一致する ROCm の bin を PATH の先頭に配置してください。
• セットアップ後に発生する問題（事前確認の失敗、起動、フェーズ、ゲイン）は、インストール済みの実行スキルとオプティマイザースキルの対象です。ここでチェック内容を再現するのではなく、それらのスキルを確認してください。