vllm-sota-humanize-loop

vLLM SOTA Humanize Loop

概要

ユーザーがモデルを指定し、同じ対象環境で再現可能な最高の SGLang または TensorRT-LLM の結果に達するか、それを上回るまで、vLLM のサービング経路を自律的に改善し続けたい場合に、このスキルを使用します。

このワークフローには、永続的に保持する要素が 2 つあります。

1. コードにパッチを適用する前に、一度完了しておく必要がある固定ベースラインフェーズ。
2. ギャップの判断、プロファイリング、必須のレイヤー／カーネルの詳細分析、vLLM へのパッチ適用、任意の NCU エビデンス、および実モデルでの再検証を担う 1 つの Humanize RLCR ループ。

キャンペーンを、ループ前のプロファイリングフェーズと、その後のパッチ適用ループに分割しないでください。固定ベンチマークができたら、Phase 2 のギャップ判断、Phase 3 のプロファイリング、llm-pipeline-analysis、カーネルのエビデンス、およびコード変更はすべて、同じモデルレベルの RLCR ループ内で行います。

ランタイムのルート

このスキルは、Claude Code、Codex、またはその他の互換性のあるスキルランタイムから実行できます。以下の順序で関連するルートを解決してください。

1. Claude Code で実行する場合は、~/.claude/skills のインストール済み Claude Code スキルを優先します。
2. Codex で実行する場合は、${CODEX_HOME:-~/.codex}/skills のインストール済み Codex スキルを優先します。
3. スキルがシンボリックリンクされている場合や、開発用にローカルに保持されている場合は、チェックアウト済みのリポジトリを使用します。

ローカルパスの例：

Humanize runtime: ${CODEX_HOME:-~/.codex}/skills/humanize
ncu-report-skill: ${CODEX_HOME:-~/.codex}/skills/ncu-report-skill/SKILL.md
Model PR history knowledge: <repo>/model-pr-optimization-history

Claude Code のインストールでは、通常、同等のデフォルトは次のとおりです。

Humanize runtime: ~/.claude/skills/humanize
ncu-report-skill: ~/.claude/skills/ncu-report-skill/SKILL.md
Model PR history knowledge: ~/.claude/skills/model-pr-history-knowledge

Humanize ランタイムが見つからない場合は、scripts/setup-rlcr-loop.sh を含むプラグインまたはスキルのディレクトリを探してください。ncu-report-skill が利用できない場合でも、torch-profiler／ソースのエビデンスに基づいてカーネルの編集を進めることはできます。ただし、通常であれば Nsight Compute の診断が必要となるカーネル変更を行う場合は、NCU エビデンスの取得経路がないことをブロッカーとして記録してください。

関連スキル

実際の実行前に、以下を読んでください。

• ../llm-serving-auto-benchmark/SKILL.md
• ../llm-torch-profiler-analysis/SKILL.md
• ../llm-pipeline-analysis/SKILL.md
• ../../model-pr-optimization-history/SKILL.md
• SSH、コンテナー、GPU、およびアーティファクトの規約に関する、該当するホストまたはオペレーターのスキル

ncu-report-skill/SKILL.md を読むのは、アクティブな RLCR ラウンドで CUDA、Triton、CuTe、CUTLASS、TileLang、または torch.compile のカーネル経路を作成または評価しており、Nsight Compute のエビデンスが必要な場合だけです。

契約

モデルレベルの vLLM SOTA リクエストを受けた場合、ベンチマーク、プロファイラー、gen-plan、refine-plan、または Humanize のセットアップコマンドを個別に実行するようユーザーに求めないでください。セットアップは自分で行ってください。

モデル、対象の GPU 環境、または精度／量子化ポリシーが不明で、ローカル設定やアクティブなホストスキルからも推測できない場合に限り、ユーザーに確認してください。

RLCR パッチループの外に置くのは、固定ベンチマークフェーズだけにしてください。フレームワーク横断の固定ベンチマークとモデルの PR 履歴メモが揃ったら、Humanize を開始します。RLCR ループ自体が、ギャップが残っているかどうかを判断し、現在のプロファイラーエビデンスを収集し、レイヤーパイプライン分析を実行して、vLLM にパッチを適用し、再検証する必要があります。

モデル最適化キャンペーンを、1 回のターミナルセッションではなく、永続的な単位として扱ってください。キャンペーンは、実行アーティファクトのルート、チェックポイントファイル、ベンチマーク／プロファイルのアーティファクト、NCU ダイジェスト、および台帳から再開できます。

Phase 0：入力と実行ディレクトリ

以下を収集するか、推測してください。

• モデル ID またはチェックポイントのパス、トークナイザー、精度、量子化、信頼ポリシー、および最大コンテキスト長
• パッチを適用する対象の vLLM チェックアウト
• GPU の種類／数、表示されている GPU ID、コンテナーまたはリモートシェル、CUDA／NCCL のバージョン、およびマルチノードが許可されているかどうか
• 使用可能な場合はデフォルトで vLLM、SGLang、TensorRT-LLM とするフレームワークのセット
• 可能であれば、モデル ID、チェックポイント、またはアクティブな vLLM／SGLang ソースパスから推測したモデルファミリーの履歴スラッグ
• アーティファクトのルート

実行ディレクトリを 1 つ作成します。

runs/YYYYMMDD_<model_slug>_sota_humanize/
  manifest.md
  help/
  benchmark/
  profiles/
  analysis/
    root-cause.md
    layer-pipeline.md
  history/
    model-pr-history-notes.md
  kernel/
    ncu-digests/
  patches/
  humanize/
    model-loop-checkpoint.md
  final_report.md

Hugging Face トークンやその他のシークレットをアーティファクトに保存しないでください。

フェーズ 0.5：モデル PR 履歴ナレッジゲート

固定ベンチマークの実施前、またパッチの計画前に、対象モデルファミリーの model-pr-optimization-history を検索して読みます。

ルール：

• スラッグが不明確な場合は、ナレッジルートから scripts/query.py "<model id or family>" を実行し、最も近いモデルファミリーの履歴を選びます。
• そのファミリーの vLLM 履歴がある場合は、必ず読みます。
• SGLang が比較対象に含まれている場合、後に最有力の競合となった場合、またはソース／トレースから vLLM に不足している高速パスが示唆される場合は、SGLang の履歴も読みます。
• history/model-pr-history-notes.md に、参照したパス、PR 番号、不変のソースヘッド、PR の状態（open、merged、closed-unmerged）、ソースファイル、シンボル、検証の根拠、既知の制限、検証リスク、および各項目が影響する具体的な判断を記録します。
• オープンな PR は候補ベースラインとしてのみ扱います。完全なヘッド SHA を記録し、記録対象のソースヘッドにすでに実装されている動作として説明してはいけません。
• これらのメモは、より優れた vLLM パッチを選ぶためのソースと PR の記録として扱い、それ自体を測定による証拠として扱ってはいけません。

ナレッジルートを利用できない場合は、同じメモファイルに障害を記録し、ベンチマーク／プロファイルの証拠に基づいて続行します。

フェーズ 1：固定公平ベンチマークゲート

このフェーズは必須で、Humanize の開始前にちょうど 1 回だけ実施します。

候補の生成、結果スキーマ、ワークロード、比較の基準として llm-serving-auto-benchmark を使用します。

必須要件：

• 対象環境で各フレームワークがサポートされている場合は、vLLM、SGLang、TensorRT-LLM それぞれの最良のデプロイコマンドを検索します。
• チューニング済みの vLLM を競合のデフォルト設定と比較してはいけません。各フレームワークで、それぞれ独自の範囲内の探索を行います。
• 同じモデル重み、トークナイザー、精度、量子化、GPU の種類／台数、GPU ID、エンドポイントパス、サンプリング設定、SLA を使用します。
• 選択した各フレームワークについて、パッケージのバージョンまたは git コミットと、サーバー／ベンチマークの --help スナップショットを記録します。このスキルで確認済みの 2026-08-23 時点の不変のソースヘッドは、vLLM が bbe8b23e1a2b32a96240b27f63255170d09ef144、SGLang が eec794bce0808ae26cc1dcb84a56b65d2df82af5、TensorRT-LLM が da38c1d2e0dffd073b7dfb6d69e15ee7b45d84a9 です。対象イメージの現在の --help を優先し、オープンな PR を再確認します。また、実行可能なベンチマーク経路が最初から最後まで検証されていない限り、この対象ワークフローに TokenSpeed を追加してはいけません。
• 対象イメージの現在のコマンドを使用します：vllm serve、sglang serve または python -m sglang.launch_server、および trtllm-serve serve --backend pytorch。
• ユーザーが本番ワークロードを明示的に指定しない限り、llm-serving-auto-benchmark のデフォルトの 2 つのデータセットシナリオを使用します：
  • データセット種別 random、num_prompts: 80
  • chat：ランダム入力 1000、出力 1000
  • summarization：ランダム入力 8000、出力 1000
  • 2 つの入出力ペアは直積ではなく、対応するシナリオとして扱います
• 実際の SOTA 判断で、これらのシナリオをより簡単なスモークテスト用データセットに置き換えてはいけません。スモークテストは、フローチェックとして明記した場合に限り許可されます。
• TensorRT-LLM では trtllm-serve serve --backend pytorch を使用します。このスキルでは、PyTorch 以外の TensorRT-LLM サーバーバックエンドを認めません。
• 失敗した候補、スキップした候補、SLA に違反した候補もベンチマーク成果物に含めます。

完了の報告や障害の報告をする前に、今回の実行で開始したサーバー、ベンチマーク、プロファイラー、ダウンローダー、ログ追跡プロセスだけを停止します。今回の実行で明示的に作成したモデルスナップショット、ロック、ミラーディレクトリ、実行固有のキャッシュ項目だけを削除します。実行前後のプロセスと GPU の状態を記録します。他のユーザーのプロセスを強制終了したり、共有モデルキャッシュを削除したりしてはいけません。

以下を作成します：

• benchmark/candidates.jsonl
• benchmark/summary.md
• benchmark/winning-commands.md
• help/ 以下の各フレームワークのヘルプ出力
• 勝者ごとの正確な起動コマンドとベンチマークコマンド

RLCR の範囲外でコードパッチを選択してはいけません。固定の勝者テーブルをモデルループのベースライン入力とします。

フェーズ 2：Humanize プランを作成する

パッチを適用する vLLM チェックアウト内に Humanize プランを作成します。

.humanize/vllm-sota-agent/refined-plan.md

references/refined-plan-template.md を ひな形として使用し、実際のモデル、ワークロード、ベンチマークの勝者、 成果物のルート、モデル PR 履歴に関するメモ、対象の vLLM チェックアウトを 記入します。

プランでは、すべての RLCR ラウンドで次のことを必須とします。

• 固定されたベンチマークのワークロードと SLA を維持する
• モデル固有の vLLM ソースパスを選ぶ前に、history/model-pr-history-notes.md を維持し、参照する
• パッチ適用前に、ループ内でギャップの判断を行う
• vLLM の性能が劣っている場合、または前回のパッチでプロファイル対象のパスが変わった場合は、ループ内で llm-torch-profiler-analysis を実行する
• プロファイラーによるトリアージ後、ソースパス、代表レイヤー、またはカーネルの対象を選ぶ前に、ループ内で llm-pipeline-analysis を実行する
• ベンチマークのパラメーターだけでなく、vLLM のコードにパッチを適用する
• カーネルの編集に Nsight Compute のエビデンスが必要な場合は、同じループ内で ncu-report-skill を使用する
• パッチを受け入れるたびに、実際のモデルでベンチマークとプロファイルを再実行する
• 1 回のパッチでギャップの一部しか解消できない場合は、複数の最小限のパッチを続けて適用する
• 試み、失敗したアイデア、部分的な成果、却下したソースの案、最終的に選択したパッチをすべて成果物に記録する

フェーズ 3：RLCR を開始する

vLLM チェックアウトから Humanize を開始する前に、次のことを確認します。

• vLLM チェックアウトが、少なくとも 1 つのコミットを含む Git リポジトリであり、Gitignore されている Humanize のランタイム状態のみを除いて、作業ツリーがクリーンであること。
• .humanize* が Gitignore されており、RLCR の状態、ラウンドの概要、ローカルのチェックポイントが誤ってステージされないこと。
• 対象のレビュー用ベースブランチがローカルに存在すること。Humanize の自動検出で曖昧になる場合は、--base-branch <branch> を渡してください。
• vLLM チェックアウト内に、アクティブな .humanize/rlcr/*/state.md が既に存在する場合、新しいループを開始しないこと。先に古いモデルループを再開、完了、またはキャンセルしてください。

vLLM チェックアウトから、次を実行します。

"$HUMANIZE_RUNTIME_ROOT/scripts/setup-rlcr-loop.sh" \
  .humanize/vllm-sota-agent/refined-plan.md --yolo

クライアント／プラグイン環境で HUMANIZE_RUNTIME_ROOT が設定されていない場合は、まずインストール済みの Humanize ランタイムを特定して設定します。Codex では通常 ${CODEX_HOME:-~/.codex}/skills/humanize、Claude Code では通常 ~/.claude/skills/humanize またはプラグインが提供する Humanize ランタイムです。セットアップが 0 以外で終了した場合は、停止してエラーを報告してください。ゲートを回避してはいけません。

セットアップが成功したら、次の手順を実行します。

1. find .humanize/rlcr -maxdepth 2 -name state.md -print を実行して、アクティブな状態ファイルを見つけます。
2. 状態ファイルが存在し、current_round: 0 を含み、--yolo を使用する場合は ask_codex_question: false を含むことを確認します。
3. .humanize/rlcr/<timestamp>/round-0-prompt.md が存在し、生成された Round Contract Setup の指示を含むことを確認します。
4. .humanize/rlcr/<timestamp>/round-0-prompt.md を読みます。
5. 現在のラウンドを実行します。
6. vLLM の変更をコミットします。
7. 必須の Humanize ラウンド概要を作成します。
8. 通常どおり停止して、ネイティブの Humanize Stop フックでレビューできるようにします。

アクティブな状態ファイルがない場合、または round-0-prompt.md が見つからない場合は、停止して RLCR が正しく開始されなかったことを報告します。Humanize ループ外で vLLM のパッチ作業を続けてはいけません。フックが終了をブロックした場合は、生成された次のラウンドのプロンプトに正確に従ってください。

各 RLCR ラウンドの内部

ギャップの判断

各ラウンドの開始時に、固定された各シナリオについて、現在の vLLM と SLA を満たす最良のフレームワークとのギャップを計算します。

デフォルトの安定したノイズしきい値として 1% を使用します。現在の結果が +/-1% 以内である場合は、パッチを選ぶ前に、勝者のコマンドを十分な回数再実行し、ギャップが安定しているかを判断します。

vLLM が最良のフレームワークより 1% を超えて遅い場合、他のフレームワークが SLA を満たしているのに vLLM が満たしていない場合、または固定ワークロードで残るギャップを説明できるプロファイル済みのボトルネックがある場合に限り、パッチを適用します。

vLLM がすでに最良であるか、安定したしきい値内で同等である場合は、最終レポートを作成し、通常の Humanize レビュープロセスに従って停止します。

必須のプロファイリング

vLLM の性能が劣る場合は、現在最良の vLLM コマンドと、最有力の競合コマンドを llm-torch-profiler-analysis でプロファイリングします。

ルール：

• vLLM の性能が劣る場合は、必ず vLLM をプロファイリングします。
• 少なくとも現在最良のフレームワークを必ずプロファイリングします。
• 安定した結果で SGLang と TensorRT-LLM の両方が vLLM を 1% 超上回る場合は、両方をプロファイリングします。
• プロファイラーのデフォルト値ではなく、低速ベンチマークシナリオの長さを使用します。
  • プリフィルのプロファイル：低速の入力長 → 出力トークン数 1
  • デコードのプロファイル：入力トークン数 1 → 低速の出力長
• 混合データセットまたは本番データセットでは、ベンチマーク成果物にすでに記録されている、代表的な最も遅い p50 または p95 のバケットを使用します。
• フレームワークが対応している場合は、プリフィルとデコードの証跡を別々に取得または分析します。

プロファイリングした各フレームワークについて、同じ 3 つのテーブルを保存します。

• カーネルテーブル
• オーバーラップの機会テーブル
• 融合パターンテーブル

次に analysis/root-cause.md を作成または更新し、フレームワーク間の現在の比較を記述します。どのステージが遅いのか、どのテーブルの行がその原因を示しているのか、どの vLLM のソースパスまたはカーネル群がパッチ対象として妥当なのかを記載します。

現在の性能差についてこのレポートが存在するまで、vLLM にパッチを適用しないでください。

レイヤーパイプラインの詳細分析

各 RLCR ラウンドで、プロファイラーによるトリアージの後、パッチ対象を選ぶ前に llm-pipeline-analysis を実行します。

レポートには以下を記載する必要があります。

• 選択したフォワードパスと、それが代表例として適切な理由
• 関連するレイヤータイプ。特に MoE、ハッシュレイヤー、compress_ratios などの異種レイヤー
• パッチ対象の代表的なレイヤー
• それらの代表的なレイヤーで負荷の高い上位カーネル
• 調査に必要な Perfetto の時間範囲

プロファイリング済みの vLLM トレースと、提供されたモデル設定を使用します。選択したフォワードパス、レイヤータイプごとのタイミングテーブル、代表的なレイヤー、負荷の高い上位カーネル、および調査に使用した Perfetto の時間範囲を記載した analysis/layer-pipeline.md を作成します。そのラウンドのこのレポートが存在するまで、vLLM のパッチを選ばないでください。

カーネルのエビデンスに基づく支援

ncu-report-skill は、アクティブな RLCR ラウンドで具体的なカーネルまたは小規模なカーネルファミリーのパッチを作成しており、次の編集を選択または検証するうえで torch-profiler のエビデンスだけでは不十分な場合に限り使用してください。

カーネルレベルの支援が許可されるのは、以下のすべてを満たす場合のみです。

• 必要な再実行／プロファイラーチェック後も、固定されたベンチマークシナリオで vLLM が最良のフレームワークより 1% を超えて遅れています。
• 遅いステージについて、カーネルテーブルに累積 GPU 時間の割合が 1% 以上の、具体的な vLLM カーネルまたは対象範囲を絞ったカーネルファミリーがあります。共有実装が 1% を超える集約ファミリーに影響する場合を除き、単独で割合が 1% 未満のカーネルにカーネル専門家の労力を費やさないでください。
• llm-pipeline-analysis により、現在のラウンドで代表的なレイヤー／フォワードパスと上位のホットカーネルが特定されています。
• 提案するカーネルの対象には、明確な正しさの参照基準、モデル実行から得た代表的な形状／データ型／レイアウト、および候補をアクティブな vLLM サービングコードに組み込む手段があります。

対象となる各カーネルについて、次の手順に従ってください。

1. ncu-report-skill/SKILL.md を読み、ハーネスの構築、ncu による収集、レポートの解析、ストールの診断、エビデンスに基づく次の編集の選択について、記載された Nsight Compute のワークフローに従ってください。
2. NCU の出力は kernel/ncu-digests/<version>/ またはホストで同等のアーティファクトルートに保存してください。各ダイジェストではベースラインと候補を比較し、具体的な次の編集をちょうど1つ記載して締めくくってください。
3. vLLM のチェックアウトで vLLM カーネルまたは呼び出し経路に直接パッチを適用し、利用可能であれば対象を絞った正しさの確認とマイクロベンチマークのカバレッジを追加してください。CUDA および C++ のカーネルコードは csrc/ に、Triton カーネルと attention／量子化ラッパーは vllm/ に、torch.compile によって駆動される経路は vllm/compilation/ にあります。
4. 元のプロファイラー行を生成したアクティブなモデルサービング経路に候補を組み込んでください。
5. 候補の正しさを確認した後、同じ実モデルのベンチマークとプロファイリングを再実行してください。マイクロベンチマークまたは NCU での改善だけでは成功とはみなされません。

対象を絞ったハーネスがない場合は、モデルから得た形状／データ型／レイアウトを維持する、最小限のハーネスを構築してください。ホストで NCU を実行できない場合は、ブロッカーをダイジェストのパスに記録し、利用可能な torch-profiler、レイヤーパイプライン、およびソースのエビデンスに基づいて次の編集を決めてください。

カーネルの対象について、スタンドアロンの .humanize/rlcr セッションを開始しないでください。カーネル作業はアクティブなモデル RLCR ループ内で行ってください。

モデルループのチェックポイント

ラウンドが承認されるたびに、以下を記載して humanize/model-loop-checkpoint.md を更新してください。

• 元のモデル、トークナイザー、精度、量子化、ハードウェア、ワークロード、SLA、アーティファクトルート、ベンチマークで勝利したコマンド
• 現在の vLLM ブランチ、コミット、適用済みパッチ、実行したテスト、現在最良の vLLM ベンチマーク行
• 残っている性能差、プロファイラー行、モデル PR 履歴のメモ、レイヤーパイプラインのメモ、NCU ダイジェストのパス、却下したソースの案、次に予定している vLLM パッチ

このチェックポイントは、同じモデルレベルのワークフロー内でキャンペーンを再開するためのものです。ベンチマーク／プロファイルの来歴を失わずにキャンペーンを再開できるだけのコンテキストを記録します。

ループ台帳

ホストの慣例に応じて、これらのファイルを実行アーティファクトルートまたは vLLM のチェックアウトに保存してください。

humanize/attempt-ledger.md
humanize/optimization-ledger.md
humanize/source-idea-ledger.md
humanize/lineage.jsonl
humanize/profile-digests/

すべてのパッチ試行について試行行を記録してください。正しく、測定された改善があるパッチのみ、最適化行を記録してください。ソースに関する案には、プロファイラー行、レイヤーパイプラインのエビデンス、使用した場合は NCU レポートのパス、コードの来歴を含めてください。後続のラウンドで同じソースを再読せずに済むようにするためです。モデル PR 履歴のエビデンスがパッチに影響した場合は、vLLM、SGLang、TensorRT-LLM、および NCU のソースに関する案と併せて記録してください。

連続する2ラウンドで、直前の vLLM ベスト結果に対する幾何平均の改善が 1% 未満だった場合は、再び編集する前にコードを優先した調査の範囲を広げてください。文章だけの記事よりも、vLLM、SGLang、TensorRT-LLM のコードや PR のエビデンス、および関連するカーネルのソースガイドを優先してください。

停止条件

次のいずれかに該当した場合にのみ停止してください。

• 固定ワークロードにおいて、vLLM が SLA を満たした SGLang／TensorRT-LLM の最良結果を上回った。
• 反復実行後、安定した 1% のしきい値以内で vLLM が同等となった。
• 残る差が vLLM の外部要因によるものだと証明された。たとえば、ハードウェアサポートが利用できない、フレームワーク依存関係が不足している、TensorRT-LLM の PyTorch バックエンドが未サポートである、公平に読み込めないモデルウェイトがある、などです。
• プロファイルの証拠から、残るホットパスがすでに関連するハードウェアまたはアルゴリズム上の限界に近く、リスクの低い vLLM パッチが残っていないことが示された。

最終レポートには、固定ベンチマーク表、パッチ適用後のベンチマーク表、すべての勝者のコマンド、モデル PR 履歴のパス、プロファイルのパス、使用した場合はレイヤーパイプラインのパス、使用した場合は NCU ダイジェストのパス、vLLM の変更ファイル、テスト、および vLLM が対象環境で SOTA に到達したかどうかを含める必要があります。