vLLMのGGUF設定を重み、Tokenizer、configに分ける

vLLMでGGUFを読み込むとき、量子化済み重み、Tokenizer、モデル設定を同じものとして扱うと起動エラーの原因を追いにくいです。

3つが同じHugging Face repositoryに置かれている場合でも、vLLMへ渡す役割は別です。

特にGGUF repositoryへconfig.jsonがないとき、--tokenizerだけを指定しても設定エラーは解消しません。

GGUFの対応範囲を先に確認する

GGUFは量子化したモデル重みを保存するfile formatです。

量子化によって重みのサイズを抑えられるため、元の重みをそのまま読み込むより少ないmemoryで推論できる場合があります。

一方、GGUFを使えばvLLMのすべての機能が使えるとは限りません。

vLLMのGGUF公式資料は、対応をexperimentalとして説明し、他機能との互換性に注意を促しています。

また、GGUF対応にはvllm-gguf-pluginが関係するため、pluginの導入方法をvLLMのversionと合わせて確認します。

3つの入力を表にする

入力	主な役割	vLLMでの指定例
GGUF weights	量子化済みのmodel parameter	owner/model-GGUF:Q4_K_M
Tokenizer	token化、語彙、chat template	--tokenizer owner/base-model
Hugging Face config	architecture、layer数、hidden size	--hf-config-path owner/base-model

GGUF weightsは推論で使うparameterを提供します。

Tokenizerは入力文字列をtoken列へ変換し、必要ならchat formatを組み立てます。

Hugging Face configは、weightsをどのmodel architectureとして解釈するかを決めます。

3つは関連するが、同じrepositoryやfileを指す必要はありません。

基本の起動例

GGUF repositoryと元model repositoryを分ける場合は、次のように指定します。

uv pip install vllm-gguf-plugin

vllm serve unsloth/Qwen3-0.6B-GGUF:Q4_K_M \
  --tokenizer Qwen/Qwen3-0.6B \
  --hf-config-path Qwen/Qwen3-0.6B

unsloth/Qwen3-0.6B-GGUF:Q4_K_Mは量子化済みweightsの指定です。

--tokenizer Qwen/Qwen3-0.6Bは元modelのTokenizerとchat設定を使う指定です。

--hf-config-path Qwen/Qwen3-0.6Bはmodel configの取得先を元modelへ向ける指定です。

実際のrepository名、量子化方式、pluginの要否は、配布元とvLLM versionに合わせて置き換えます。

config.jsonエラーを切り分ける

次のようなエラーは、remote GGUF repositoryからHugging Face形式のconfigを取得できないことを示します。

Could not find config.json for remote GGUF model repo.

このとき、--tokenizerの指定だけを確認しても不十分です。

--tokenizerはTokenizerの取得先を指定します。

config.jsonの取得先は指定しません。

設定の取得先を--hf-config-pathで明示します。

vllm serve owner/model-GGUF:Q4_K_M \
  --tokenizer owner/base-model \
  --hf-config-path owner/base-model

対象modelのconfigを自動変換できない場合は、公式資料にあるHugging Face互換configを用意する方法も確認します。

HF_HOMEは取得元ではなくcacheの場所です

HF_HOMEはHugging Face関連のcache保存場所を変える環境変数です。

export HF_HOME="$HOME/src/llm-server/models/huggingface"

この設定はdownloadしたfileの保存先を変えます。

model、Tokenizer、configをどのrepositoryから取得するかは決めません。

取得元はmodel argument、--tokenizer、--hf-config-pathなどのoptionで指定します。

そのため、config.jsonが見つからないときは、cacheの場所よりGGUFと元modelの指定を先に確認します。

Tokenizerを元modelから取得する

vLLMの公式資料は、GGUF側のTokenizerを変換するより元modelのTokenizerを使う構成を案内しています。

GGUFからのTokenizer変換は時間がかかり、modelによっては不安定になり得ます。

元modelと量子化modelの組み合わせを確認した後、次のように指定します。

vllm serve ./Qwen3-0.6B-Q4_K_M.gguf \
  --tokenizer Qwen/Qwen3-0.6B

local GGUF fileでも、Tokenizerを別のHugging Face repositoryから取得できます。

起動前の確認順序

1. GGUFが対象modelの量子化weightsか確認する
2. vLLMとvllm-gguf-pluginの対応versionを確認する
3. 元modelのTokenizerとchat templateを確認する
4. 元modelに必要なconfig.jsonがあるか確認する
5. 必要なら--hf-config-pathを指定する
6. 短いinputで起動しmodel名とTokenizerを確認する
7. 量子化方式とGPU対応を確認する

GGUFの目的がmemory削減でも、Tokenizer、model config、GPU kernelの互換性まで自動解決されるわけではありません。

量子化weightsの選択と、modelを正しく解釈して推論する作業を分けると、起動エラーの原因を追いやすくなります。

参考資料

• GGUF | vLLM
• Quantization | vLLM