vLLMのGGUFサポートは存在しますが、正しいセットアップはvLLMのリリース、GGUFチェックポイント、およびそのトークナイザーによって異なります。現在の安定版ドキュメントでは、別途用意されたvllm-gguf-pluginを使用するよう案内されています。古いチュートリアルでは、ツリー内ローダーが説明されています。まずインストール済みのスタックを特定し、本番ワークロードに移行する前に小規模なモデルを1つ検証してください。
このガイドでは、GGUFチェックポイントを正しく読み込み、提供できるようにすることに焦点を当てます。GGUF、AWQ、GPTQ、FP8の選択については、より広範なvLLM量子化ガイドを参照してください。
現在のvLLM GGUFサポートの意味
GGUFはモデルファイル形式です。.ggufで終わるファイル名であっても、ランタイムが内部のすべてのアーキテクチャ、量子化タイプ、補助コンポーネントをサポートしていることは保証されません。互換性は、ランタイム + プラグイン + モデルアーキテクチャ + 量子化 + トークナイザー + ハードウェアの組み合わせとして扱ってください。
現在のvLLM GGUFドキュメントでは、パフォーマンスおよび機能上の制限がある実験的なパスについて説明されています。Hugging Faceのrepo_id:quant_typeセレクターとローカルファイルの両方が記載されており、元のモデルのトークナイザーを使用することが推奨されています。これは、古いローカルファイルのワークフローを説明するv0.8.4の手順とは異なります。実際に実行するバージョンに対応するドキュメントを使用してください。
| 見つかったもの | 次に確認すること |
|---|---|
| 最新の安定版インストール | GGUFプラグインがvLLMと同じPython環境にインストールされているか |
| 古いコンテナまたは固定されたリリース | そのバージョンのドキュメント。古いローダーと現在のフラグを混在させないこと |
| 別のランタイムで動作するGGUF | vLLMスタックにおけるアーキテクチャ、テンソルマッピング、トークナイザー、必要な機能 |
--omniを使用する例 |
このガイドのテキスト提供パスではなく、vLLM-Omniを使用しているか |
vLLM-Omni GGUFガイドでは、個別のマルチモーダル構成とモデル固有のアダプターについて扱っています。その拡散モデルの例は、テキスト専用vLLMサーバー向けのそのまま使えるコマンドではありません。
1. インストール前に環境を記録する
対象のGPUマシン上にクリーンなテスト環境を用意してください。まず、公式のGPUインストール手順を使用して、ベースとなるvLLMインストールがそのマシンに適合していることを確認します。Pythonパッケージのインストールが成功しただけでは、ドライバーまたはデバイスの互換性は確認できません。
モデルをインポートせずにパッケージのバージョンを記録します。
from importlib.metadata import version, PackageNotFoundError
for package in ("vllm", "vllm-gguf-plugin", "torch", "transformers"):
try:
print(package, version(package))
except PackageNotFoundError:
print(package, "not installed")
NVIDIAホストでは、nvidia-smi、GPUモデル、使用可能なメモリ、コンテナイメージタグまたは環境のロックファイルも記録してください。この記録は、モデルリポジトリのリビジョンおよび量子化名とともに保管します。将来のアップグレードで失敗した場合、これらの詳細があれば、どの依存関係が変わったかを推測するのではなく、既知の2つの環境を比較できます。
2. 提供環境にGGUFプラグインをインストールする
互換性のあるvLLM環境をすでに準備している場合、現在の安定版ドキュメントでは次のパッケージインストールコマンドが案内されています。
uv pip install vllm-gguf-plugin
uvがvllm実行ファイルを含む環境に対して動作していることを確認してください。ある仮想環境にプラグインをインストールし、別の環境からサーバーを起動しても、そのサーバーでプラグインを利用できるようにはなりません。
ソースビルドについては、プラグインリポジトリのインストール手順に従ってください。CUDAまたはROCmツールキットが必要であり、vLLMが使用するPyTorchインストールに対してビルドされます。このため、ドキュメントに記載された編集可能インストールではビルド分離が無効化されています。ビルドが成功するまで無関係なコンパイラフラグを追加するのではなく、選択したリビジョンに対応するリポジトリの手順を使用してください。
プラグインリポジトリには、生成テスト済みのモデルファミリーと量子化方式も掲載されています。最初のカナリアテストの出発点として、これらのテストを使用してください。これらは、すべてのモデルのすべてのGGUF変換が動作する証拠ではありません。
3. 明示的なトークナイザーで小規模チェックポイントを読み込む
次のコマンドでは、プラグインプロジェクトで文書化されている小規模なQwenの例を使用し、ローカル専用リスナーを追加して、APIに予測可能なモデル名を指定します。
vllm serve Qwen/Qwen3-0.6B-GGUF:Q8_0 \
--tokenizer Qwen/Qwen3-0.6B \
--served-model-name gguf-canary \
--host 127.0.0.1 \
--port 8000
これはパフォーマンスベンチマークではなく、互換性のスモークテストです。モデルアセットをダウンロードするため、サポートされるランタイムとデバイスが必要です。小規模なチェックポイントを選択していることを、アプリケーションに推奨されるモデルであると解釈しないでください。
ローカルファイルの場合は、モデルセレクターを実際のGGUFパスに置き換え、対応するベースモデルのトークナイザーを使用してください。提供する前に、ファイルが完全であること、および分割ファイルの処理がインストール済みバージョンでサポートされていることを確認してください。任意のチェックポイントをリネームしても、その形式が変換されるわけではありません。
設定メタデータを解決できない場合、現行ドキュメントでは明示的な設定入力として--hf-config-pathが提供されています。実際にそのチェックポイントのベースアーキテクチャに属する設定を使用してください。便利ではあっても無関係な設定を使うと、明確な読み込み失敗が、診断しにくいテンソルまたは出力エラーに変わる可能性があります。
4. 読み込み、API、出力のチェックを分ける
サーバーが準備完了と報告したら、2つ目のターミナルからモデル一覧を照会します。
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
次に、明示的に提供されている名前に対して小さな補完リクエストを送信します。
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"gguf-canary","prompt":"The capital of France is","max_tokens":16,"temperature":0}'
OpenAI互換サーバーのドキュメントでは、サポートされるエンドポイントとリクエストの動作について説明しています。通常の補完を使うことで、最初のチェックをチャットテンプレートの設定から独立させられます。これに成功したら、実際のチャットテンプレート、構造化出力の要件、ストリーミング、その他のアプリケーション機能を個別にテストしてください。
デプロイ記録では、次の3つの結果を分けて保持してください。
- 読み込み: 重みとトークナイザーが、未サポートのレイヤーまたはテンソルエラーなしで初期化される。
- 提供: 必要なエンドポイントが、提供されているモデル名に対して有効なレスポンスを返す。
- 利用: 出力が、アプリケーション固有の小さな正確性テストセットを満たす。
HTTP 200のレスポンスは、API部分にしか合格していません。空のテキスト、トークンの繰り返し、誤った形式、またはタスクの回答失敗については、引き続き調査が必要です。初期状態ではサーバーをlocalhostにバインドしたままにし、他のクライアントに公開する前に通常の認証およびネットワーク制御を追加してください。
最初に失敗した段階に基づくトラブルシューティング
| 症状 | 最初に確認する項目 | 次に行う制御された変更 |
|---|---|---|
| プラグインまたは量子化方式が認識されない | アクティブなPython環境とインストール済みパッケージのバージョン | クリーンで互換性のある環境で再現する |
| バイナリまたはシンボルエラーでインポートに失敗する | PyTorch、CUDA/ROCm、プラグインビルドの整合性 | プラグインで文書化された手順を使用して再ビルドする |
| モデルまたは量子化セレクターが見つからない | リポジトリのスペル、選択した量子化、権限、ダウンロードの完全性 | プロジェクトで文書化された小規模チェックポイントを試す |
| テンソル名または形状が一致しない | モデルアーキテクチャ、変換元、設定 | 同じベースモデルのサポートされている変換を使用する |
| トークナイザー付近で読み込みが停止する | トークナイザーの識別子とリビジョン | 対応するベースモデルのトークナイザーを明示的に指定する |
| 補完は動作するがチャットが失敗する | チャットテンプレートとアプリケーションのリクエスト形式 | 追加機能を加える前に最小限のチャットリクエストをテストする |
| モデルは読み込めるが、トラフィック下でメモリ不足になる | コンテキスト長、アクティブなリクエスト、ランタイムメモリ、KVキャッシュ | ワークロードの1つの次元を減らし、同じテストを繰り返す |
最初の意味のあるエラーと正確なコマンドを保存してください。モデル、トークナイザー、ドライバー、同時実行数を一度に変更すると、原因を隠したままエラーだけが消える可能性があります。
互換性チェックに合格した後もGGUFを維持するか決定する
重みのストレージまたはメモリが制約である場合、小さいファイルは有用です。しかし、それだけでレイテンシ上の利点があることは示されません。提供形式を選択する前に、同じベースモデルとタスクセットを、サポートされている代替チェックポイントと比較してください。
想定される入力長、出力長、同時リクエストレベルを使用してください。タスク成功率、最初のトークンまでの時間、テールレイテンシ、スループット、ピークメモリを記録します。公式のサービングベンチマークCLIは、制御されたトラフィックを生成できます。そのオプションとデータセットは、インストール済みのバージョンに合わせる必要があります。合成ストレス実行とアプリケーション受け入れテストは異なる問いに答えるため、両方の結果を別々に保持してください。
GGUFで必要な機能または出力が失敗する場合は、まずこの正確なチェックポイントが必要かどうかを検討してください。別の形式がより少ない運用上の不確実性でワークロードを満たせるなら、変換または別のサポート対象ディストリビューションのほうが簡単な選択肢になる可能性があります。ここで量子化に関する完全な調査を繰り返すのではなく、より広範な意思決定支援として形式比較を参照してください。
受け入れ済みワークロードに基づいてクラウドGPU容量を計画する
モデルが上記のチェックに合格したら、テスト済みのメモリおよび同時実行要件に合わせてGPU環境をサイジングします。FlatkeyのCloud GPU Computeは、NVIDIA GPUのレンタルオプションを提供しています。意図するテストについて、利用可能な構成、リージョン、容量、アクセス詳細、レンタル条件を確認してください。このガイドは、例がFlatkeyのレンタル環境でベンチマークされたこと、または特定のカードが常に利用可能であることを主張するものではありません。
短い引き継ぎ資料を用意しましょう。モデルのリビジョン、量子化、ソフトウェアのバージョン、推定ディスク容量、コンテキスト上限、目標同時実行数、受け入れしきい値を含めます。これによりインフラに関する議論が具体的になり、ソフトウェア互換性の問題を、より大きなGPUをレンタルする必要性と誤認せずに済みます。
よくある質問
vLLMはすべてのGGUFモデルをサポートしていますか？
いいえ。アーキテクチャ、量子化、トークナイザー、ハードウェア、機能をまとめて検証してください。ファイル形式のサポートは、その形式で保存されたすべてのモデルに対する普遍的なサポートを意味するものではありません。
古いガイドでは、なぜローカルファイルを渡すよう説明されているのですか？
以前のリリースについて説明している可能性があります。バージョン付きのvLLMドキュメントと現在のプラグインガイダンスでは、異なる読み込み方法が示されている場合があります。インストール済みのスタックに一致する手順を使用してください。
別のモデルのトークナイザーを再利用できますか？
公開元が別の互換性のある選択肢を明示的に文書化している場合を除き、チェックポイントのベースモデルに属するトークナイザーを使用してください。無関係なトークナイザーで起動したサーバーでも、誤った結果を生成する可能性があります。
正常に読み込めれば、本番運用には十分ですか？
いいえ。エンドポイント、タスク品質、機能、現実的な負荷のチェックを完了してください。vLLM GGUFサポートに対する実務的な答えは、単にパッケージのインストールに成功することではなく、再現可能で合格した構成です。
