エラー解決

【vLLM】AWQ/GPTQ量子化モデルのサーブ手順と「ValueError: Unknown quantization method」エラー解決法

· 12分で読めます

1. 問題の概要：vLLMで量子化モデルをロードできないエラー

vLLMは、大規模言語モデル(LLM)を高速推論するための強力な推論エンジンです。特に、AWQ(Activation-aware Weight Quantization)やGPTQ(GPT Quantization)などの量子化技術を適用したモデルは、メモリ使用量を大幅に削減し、推論速度を向上させることができます。

しかし、vLLMでこれらの量子化モデルをロードしようとすると、以下のようなエラーが発生し、サーブを開始できないことがよくあります。

ValueError: Unknown quantization method: 'awq'. Must be one of ['fp16', 'fp32', 'bf16'].

または、GPTQモデルでは以下のようなエラーが発生します。

ValueError: The model weights are not quantized.

これらのエラーは、vLLMがモデルの量子化方式を正しく認識できていない、または必要なパラメータが不足しているために発生します。本記事では、この問題の原因と、vLLMでAWQ/GPTQ量子化モデルを正しくサーブするための具体的な手順を解説します。

2. 原因の解説

vLLMが量子化モデルのロードに失敗する主な原因は以下の3つです。

2.1 量子化方式の指定ミス

vLLMは、--quantization (または --quantization-method) パラメータで明示的に量子化方式を指定する必要があります。この指定がない場合、vLLMはデフォルトでFP16などの浮動小数点形式を想定するため、量子化された重みファイルを読み込む際に不一致が生じます。

2.2 モデルファイルの構成の問題

Hugging Face Hubからダウンロードする量子化モデルによっては、vLLMが期待する構成ファイル（config.json）の内容が不完全な場合があります。特に、量子化方式を示すキー（"quantization_config"）が欠落している、または形式が異なっていることが原因です。

2.3 vLLMのバージョン互換性

使用しているvLLMのバージョンが古い場合、最新の量子化方式（特にAWQ）に対応していない可能性があります。また、モデルが特定のライブラリ（autoawq や auto-gptq）の最新バージョンで量子化されている場合、vLLMとの間に互換性問題が生じることがあります。

3. 解決方法：ステップバイステップ手順

以下に、vLLMでAWQおよびGPTQ量子化モデルを正常にサーブするための具体的な手順を説明します。

3.1 環境構築と依存関係のインストール

まず、vLLMと量子化ライブラリを正しくインストールします。AWQとGPTQでは必要なパッケージが異なります。

# vLLMのインストール（最新版を推奨）
pip install vllm

# AWQモデル用の追加ライブラリ
pip install autoawq

# GPTQモデル用の追加ライブラリ
pip install auto-gptq
# または、互換性のために特定のバージョンを指定
# pip install auto-gptq==0.5.1

3.2 AWQ量子化モデルのサーブ手順

TheBlokeなどが提供するAWQ量子化モデル（例：TheBloke/Llama-2-7B-Chat-AWQ）をサーブする場合のコマンド例です。

# 基本的なサーブコマンド
python -m vllm.entrypoints.openai.api_server 
  --model TheBloke/Llama-2-7B-Chat-AWQ 
  --quantization awq 
  --served-model-name llama-2-7b-awq 
  --api-key token-abc123 
  --port 8000

# より詳細なオプションを指定する例
python -m vllm.entrypoints.openai.api_server 
  --model /path/to/local/llama-2-7b-awq 
  --quantization awq 
  --tensor-parallel-size 2 
  --gpu-memory-utilization 0.9 
  --max-model-len 4096

重要なポイント: --quantization awq の指定を忘れないでください。これがないと冒頭のエラーが発生します。

3.3 GPTQ量子化モデルのサーブ手順

GPTQモデル（例：TheBloke/Llama-2-7B-Chat-GPTQ）をサーブする場合も同様に、量子化方式を明示します。

# GPTQモデルのサーブ
python -m vllm.entrypoints.openai.api_server 
  --model TheBloke/Llama-2-7B-Chat-GPTQ 
  --quantization gptq 
  --served-model-name llama-2-7b-gptq

# ローカルにダウンロードしたGPTQモデルの場合
python -m vllm.entrypoints.openai.api_server 
  --model /local/path/to/gptq_model 
  --quantization gptq

3.4 よくあるエラーとその対処法

上記手順でもエラーが解消しない場合、以下の対処法を試してください。

ケース1: config.json に量子化設定が含まれていない
モデルディレクトリ内の config.json を確認し、以下のようなAWQ設定が含まれているか確認します。

{
  "quantization_config": {
    "quant_method": "awq",
    "zero_point": true,
    "q_group_size": 128,
    "w_bit": 4,
    "version": "gemm"
  }
}

設定が欠落している場合は、手動で追加するか、正しく設定された別のモデルを使用してください。

ケース2: 「The model weights are not quantized.」エラー（GPTQ）
このエラーは、モデルが実際にはGPTQ量子化されていないか、quantize_config.json ファイルが正しく読み込めていない場合に発生します。以下のコマンドでモデル構造を確認できます。

from transformers import AutoConfig
config = AutoConfig.from_pretrained("/path/to/gptq_model")
print(config.quantization_config)

4. コード例・コマンド例

4.1 サーブ開始後のクライアントからの呼び出し例

vLLMサーバーが起動したら、OpenAI互換のAPIエンドポイントを通じて推論を実行できます。

import openai

# クライアントの設定
client = openai.OpenAI(
    api_key="token-abc123",
    base_url="http://localhost:8000/v1"
)

# チャット補完の実行
response = client.chat.completions.create(
    model="llama-2-7b-awq",  # --served-model-nameで指定した名前
    messages=[
        {"role": "user", "content": "日本の首都はどこですか？"}
    ],
    temperature=0.7,
    max_tokens=100
)

print(response.choices[0].message.content)

4.2 バッチ推論の実行例

vLLMはバッチ推論にも強力です。以下のように複数のリクエストを同時に処理できます。

# バッチリクエストの例
requests = [
    "量子化とは何ですか？",
    "AWQとGPTQの違いを説明してください。",
    "vLLMの利点を教えてください。"
]

responses = []
for prompt in requests:
    response = client.completions.create(
        model="llama-2-7b-awq",
        prompt=prompt,
        max_tokens=50
    )
    responses.append(response.choices[0].text)

for i, (req, resp) in enumerate(zip(requests, responses)):
    print(f"Q{i+1}: {req[:30]}...")
    print(f"A{i+1}: {resp}n")

5. まとめ・補足情報

vLLMでAWQ/GPTQ量子化モデルをサーブする際の最も一般的なエラーは、量子化方式の指定漏れです。--quantization awq または --quantization gptq を明示的にコマンドライン引数に追加することで、ほとんどの問題は解決します。

パフォーマンス最適化のための追加ヒント:

  • GPUメモリ使用率: --gpu-memory-utilization 0.9 を指定することで、GPUメモリの利用率を高め、より大きなバッチサイズを処理できます。
  • テンソル並列処理: 複数GPU環境では --tensor-parallel-size をGPU数に設定することで、推論を高速化できます。
  • モデルのローカルキャッシュ: ネットワーク遅延を避けるため、モデルを事前にダウンロードし、ローカルパスから読み込むことをお勧めします。

トラブルシューティングのチェックリスト:

  1. vLLMと量子化ライブラリのバージョンが互換性があるか確認
  2. --quantization パラメータを正しく指定しているか確認
  3. モデルの config.json に量子化設定が含まれているか確認
  4. 十分なGPUメモリが利用可能か確認（nvidia-smi で確認）
  5. モデルファイルが完全にダウンロードされているか確認

量子化モデルをvLLMで活用することで、同じハードウェアリソースでより大きなモデルを実行したり、推論速度を大幅に向上させたりすることが可能になります。本記事の手順を参考に、効率的なLLM推論環境の構築に役立ててください。

この記事は役に立ちましたか？