inference-optimisation-skill — ローカルLLMの推論速度を山登り法で最適化するエージェントスキル
sybil-solutions/inference-optimisation-skill
★ 940 ・ Python ・ MIT
概要
inference-optimisation-skill は、ローカル環境で動作する大規模言語モデル(LLM)サーバーの推論パフォーマンスを「山登り法(hill-climbing)」によって段階的に最適化するためのエージェントスキルです。Claude Code をはじめとする自律型エージェントに読み込ませて利用するほか、人間が単独のツール群として利用することも想定されています。
本スキルは単にサーバーの起動フラグを網羅したリストではなく、ハードウェアの理論限界を算出した上で、パラメータを1つずつ変更しながら測定と検証を繰り返す実践的な改善手順を体系化したものです。対象とする領域は、単一および並行環境でのデコード速度、投機的デコード(speculative decoding)、prefill(入力処理)、KVキャッシュサイズ、サーバー起動時間、そして TTFT(Time to First Token: 最初のトークン生成までの時間)など多岐にわたります。メモリ上限の制約を守りつつ、長文コンテキストでの安定性を維持しながら、ローカルLLMサーバーの性能を極限まで引き出したいエンジニアに向いています。
主な特徴
README で示されている本スキルの主な特徴は以下のとおりです。
- 理論上限(Ceiling)に基づく改善目標の設定: ハードウェアの帯域幅や計算能力(FLOPs)、モデル構成から理論的な最大スループットを事前に計算し、物理的に不可能な目標を追う無駄を排除します。
- 厳密な対照実験(A/B/A)と中央値の採用: 推論速度の測定には±5〜10%程度のノイズが生じやすいため、候補設定の測定前後にベースラインの測定を挟み(コントロール)、6サンプル以上の中央値を比較することでドリフト(環境変動)による誤判定を防ぎます。
- ストリームチャンクに依存しない正確な計測: トークン数はストリーミングのチャンク数ではなくサーバーの使用統計(usage stats)から取得し、プロンプト長もトークナイザーの実測値を用いるなど、正確なデータ収集を徹底しています。
- 長文コンテキストとメモリ耐久テストによるゲート管理: 速度向上を達成しても精度や安定性が犠牲にならないよう、長文からの特定文字列抽出(Needle in a Haystack)やフルKVキャッシュ状態での負荷テストを必須の通過条件としています。
- 主要な推論エンジンとハードウェアのノウハウを蓄積: vLLM、SGLang、llama.cpp、ExLlama といったエンジン、および Intel、NVIDIA、Apple、AMD ハードウェアごとの既知の落とし穴(gotchas)や調整レバーがドキュメント化されています。
使い方
本スキルは Claude Code などのエージェント経由で実行する方法と、エージェントを介さずスクリプト群を直接実行する方法が用意されています。
Claude Code での利用手順
リポジトリをクローンし、スキル用ディレクトリを配置します。
git clone https://github.com/sybil-solutions/inference-optimisation-skill
mkdir -p ~/.claude/skills
cp -r inference-optimisation-skill/skills/inference-optimisation ~/.claude/skills/
配置後、Claude Code に対話形式で指示を出します。
- 「hill-climb decode and prefill for the model on :8000 under a 40 GiB cap」(ポート8000で稼働中のモデルに対し、40 GiBのメモリ制限下でデコードとprefillの山登り最適化を実行してほしい)
- 「what’s the theoretical max tok/s for this model on this machine?」(このマシン上のこのモデルにおける理論上の最大トークン毎秒を計算してほしい)
※その他のエージェントの場合は、skills/inference-optimisation/SKILL.md を参照させるか、リポジトリに含まれる PROMPT.md の内容をプロンプトとして利用します。
スクリプト単体でのクイックスタート
エージェントを使わずに Python および Bash スクリプトを手動で実行することも可能です。
S=skills/inference-optimisation
# 理論上限の計算
python3 $S/scripts/ceiling.py $S/examples/ceiling-ornith-b390.json
# 設定ファイルの準備(base_url や model 名を環境に合わせて編集)
mkdir -p configs && cp $S/examples/config-existing-server.json configs/base.json
# 単一実行によるベンチマーク測定
python3 $S/scripts/bench.py run configs/base.json --long 131072
# コントロールを挟んだ A/B テストの直列実行
bash $S/scripts/queue.sh base cand base
# 測定ログ(ledger)のテーブル表示
python3 $S/scripts/bench.py show
技術的なポイント
README から読み取れる本スキルの設計や構成には、実用的な工夫が数多く盛り込まれています。
3つのコンポーネント構成
リポジトリは主に以下の3要素で整理されています。
SKILL.md: 最適化の手順書本体。ハードウェアの把握、理論上限の計算、グラウンドルール、パラメータを試す優先順位、終了判定、クリーンビルドによる検証と公開基準などが定義されています。references/: 必要な場合にのみエージェントが読み込む詳細リファレンス群。ceilings.md: 計算式と具体例。methodology.md: トークン数の誤測定、ユニファイドメモリの計算ミスなどの測定上の罠。levers.md: 実証データに基づいたチューニング項目。gotchas.md: 各推論エンジンやハードウェア固有の注意点。publishing.md: 成果物の固定(ピン留め)と検証ゲートの通過基準。
scripts/: 標準ライブラリの Python と Bash で構成された軽量な検証ハーネス群。外部の特定推論エンジンに依存せず、OpenAI 互換 API サーバー全般を対象にベンチマークを実行できます。
厳格な検証ハーネス(scripts/)
ベンチマークスクリプト bench.py は、単にスループットを測るだけでなく、生成ループの検出、リクエスト失敗の検知、バッテリー駆動時の警告機能などを備えています。また、mem.sh は cgroups では把握しきれないユニファイドメモリ環境(統合GPU)におけるドライバー常駐領域を含めた実メモリフットプリントを計測できるよう設計されています。
実証結果に裏付けられた最適化アプローチ
README には、このスキルが抽出される元となった複数の実測データが掲載されています。たとえば Intel Arc B390 統合GPU(LPDDR5X 64GB)環境では、投機的デコード(MTP: Multi-Token Prediction)を併用した SGLang XPU 環境において、1ユーザーのデコード速度が 43.6 tok/s から 53 tok/s、256K の prefill が 297 tok/s から 628 tok/s に向上し、起動時間も 113秒から 43秒へと短縮された実績が示されています。そのほかにも Intel Arc Pro B70、NVIDIA RTX 3090、4× H200 NVL などの構成で測定された改善結果が記載されています。
投機的デコードに関する原則として、「採択率(acceptance)だけでなく1ステップあたりのコストに着目する」「ドラフトヘッドの語彙削減を検討する」「サンプリング処理をGPU上に維持する」といった、低レイヤのオーバーヘッドを意識した指針が明確に示されています。
注意点
- ライセンス: 本リポジトリのライセンスは MIT License です。
- 対応環境: ベンチマーク対象としては OpenAI 互換のエンドポイントを持つサーバーが想定されています。また、実証例として vLLM、SGLang、llama.cpp、ExLlama などのエンジンや、Intel XPU、NVIDIA CUDA などの環境が挙げられていますが、具体的なサポート範囲や動作要件は各スクリプトやリファレンスを参照する必要があります。
- 結果のばらつきと失敗の記録: 本スキルでも強調されている通り、単一の測定結果はノイズを含みやすいため、測定環境の厳密な統制(AC電源駆動、バックグラウンド処理の停止など)が不可欠です。また、試行したパラメータが失敗に終わった場合もログ(
PLAN.md)に理由を残す運用が推奨されています。
まとめ
inference-optimisation-skill は、ローカルLLMサーバーのチューニングを勘や単なるフラグ設定に頼るのではなく、理論値の算出と対照実験によって科学的に推進するためのエージェントスキルです。Claude Code などのエージェントと協調させながら、あるいは付属のスクリプト群を手動で活用しながら、自身のハードウェア環境に合わせた確実な推論パフォーマンス向上を目指すことができます。





