uv バイトコードコンパイルによる vLLM 起動時間の短縮

新しい vLLM コンテナは、プリコンパイル済みの Python バイトコードを同梱することで、起動時間を大幅に短縮できます。これにより、実行時のインポート中に発生する繰り返しのコンパイルを回避できます。

ランタイムパッケージをインストールする前に UV_COMPILE_BYTECODE=1 環境フラグを設定することで、uv ビルドツールはビルドプロセス中に Python ソースコードをバイトコードにコンパイルします。この手法により、モデル間で共有されるインポート中に発生するコストのかかる繰り返しコンパイルを回避でき、測定可能な起動時間の短縮につながります。

H100 サーバーでのパフォーマンス向上

プリコンパイル済みバイトコードを同梱した結果、H100 サーバーで実行した際に起動時間が大幅に短縮され、異なるモデルサイズにわたって一貫したパフォーマンス向上が実証されました。

Qwen3-8B と Qwen3-32B の場合、ペアごとの起動時間の中央値はそれぞれ 17.6 秒と 17.8 秒短縮されました。これらの測定は、Xeon Platinum 8480+ / H100 SXM 80GB サーバー上で、バイトコードを同梱したパッケージとキャッシュを削除したパッケージを比較して行われました。これらの時間には、イメージのプルとモデルのダウンロードにかかる時間は含まれていないことに注意してください。

起動時間の短縮率は、32B モデル（13.9%）と比較して 8B モデル（17.6%）の方が大きくなりました。これは、両モデルで共有される Python インポート処理を回避したことと整合的です。

実装と公式サポート

ユーザーは、イメージビルド中にランタイムパッケージをインストールする前に UV_COMPILE_BYTECODE=1 フラグを設定することで、このパフォーマンス改善を実装できます。これにより、ビルドフェーズ中に uv が Python ソースファイルをバイトコードにコンパイルするように指示されます。

公式の vLLM イメージに依存しているユーザーの場合、必要な変更は CUDA ナイトリービルド（例：vllm/vllm-openai:nightly-8cbd5d03006c33185f402249ff2b448efd594986）に含まれています。この機能は、v0.32.0 以降の公式リリースイメージでネイティブにサポートされる予定であり、ユーザーがビルドフラグを手動で設定する必要がなくなります。

起動時間短縮の技術的メカニズム

起動時間が短縮されるのは、Python がデフォルトでソースコードを実行前にコードオブジェクトにコンパイルするためです。有効な .pyc ファイルはこのコンパイル済みコードを保存するため、Python は後続のインポート時にコンパイル手順を省略して直接ロードできます。

pip などの標準的なパッケージマネージャーはインストール中にバイトコードをコンパイルしますが、uv はデフォルトでこの手順をスキップします。イメージにバイトコードが同梱されている場合、Python インタープリターはプリコンパイル済みファイルを即座にロードできます。これにより、サーバー起動 CLI のインポートプロセス中にソースコンパイラ呼び出しに費やされる時間が大幅に削減されます。

診断テストでは、プリコンパイル済みイメージを使用した場合、サーバー起動 CLI のインポート時間は 5,257 回のソースコンパイラ呼び出しからゼロに短縮されました。さらに、Docker 外のスタンドアロンインストールでは、有効なバイトコードにより、計測されたサーバー起動 CLI のインポートが 12.20 秒から 5.01 秒に短縮され、7.19 秒の節約となりました。

クロスハードウェアパフォーマンスの観察

パフォーマンス向上はコンシューマーハードウェアでも観察されましたが、ハードウェアとランタイム環境が異なるため、結果は別途保持されています。

i9-13900HX / RTX 4090 ラップトップでは、Qwen3-0.6B、Qwen3-1.7B、SmolLM2-1.7B を含むマッチドイメージ研究で、ペアごとの中央値の短縮時間は 12.8 秒から 13.5 秒の範囲であり、テストした 18 ペアすべてでプリコンパイルが有利でした。

別の非 Docker インストールでは、インストール済みファイルがすでにメモリに常駐している場合、プリコンパイル済みパッケージキャッシュによりサーバー起動ごとに 9〜12 秒短縮されました。この測定により、ファイルが OS ページキャッシュに保持されている場合でも短縮が確認されました。

実装上の注意点とトレードオフ

バイトコードコンパイルを有効にすることは有益ですが、イメージのビルドとデプロイに関していくつかの考慮事項が生じます。

• イメージサイズ： プリコンパイル済みイメージは、圧縮状態で約 153 MB（またはあるテストでは総サイズの 1.8%）増加します。これは、初期のイメージプルが遅い場合に関連する可能性があります。
• ビルドプロセス： カスタムイメージをビルドする場合、uv コマンドがランタイムパッケージをインストールする前に UV_COMPILE_BYTECODE=1 フラグを設定する必要があります。また、最終イメージを検証し、ランタイム Python の compileall 関数を使用して、不足しているキャッシュを準備する必要があります。
• 短縮の範囲： 主な短縮効果は、インポート中のコンパイラ時間の削減によるものです。モジュールの初期化やその他のセットアップタスクは残り、サーバー起動全体の短縮がコンパイラのみに起因するわけではありません。

詳細な環境、実行順序、および対照条件については、完全な方法と測定結果が補足データで提供されています。