vLLM 入門ガイド

私自身，ローカルLLMを開発するにあたり，vLLMでつまるところがありましたので，共有できればと思います．

はじめに

Linux(Debian)環境を想定しています．
vLLM は大規模言語モデル（LLM）を高速・効率的にサーブするためのツールです．本ガイドでは，

環境構築
モデルのダウンロード
基本的な実行方法
主要パラメータの解説
メモリ不足・OOM 対策
Ray 分散実行の注意点
OpenWebUI 連携

までを段階的に整理しています．初心者の方もまずは一歩ずつお試しください！

1. 前提条件

GPU（CUDA 対応ドライバ／NVIDIAのグラボ）
Python，pyenvを使える状態にする
Git LFS
Hugging Face アカウント（トークン取得済み）

2. 環境構築

2.1 Python,Pyenvのセットアップ

# 必要なパッケージのインストール
sudo apt install build-essential curl wget zip git libssl-dev libbz2-dev libffi-dev liblzma-dev libreadline-dev libsqlite3-dev tk-dev

# pyenvのリポジトリをクローンする
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

~/.bashrcに下記の内容を追記する

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

インストールできているかを確認する

pyenv --version

2.2 Git LFS のセットアップ

# 初回のみ
git lfs install

2.3 環境変数の設定

hugging faceのUserNameと，トークンを取得し設定します．

export HF_TOKEN = "<YOUR_HF_TOKEN>"
export HF_USER  = "<YOUR_HF_USERNAME>"

3. モデルのダウンロード

Hugging Face から任意のモデルをクローンします．例として Qwen3-32B をダウンロード：

git lfs clone https://${HF_USER}:${HF_TOKEN}@huggingface.co/Qwen/Qwen3-32B model/Qwen3-32B

私は，modelsディレクトリを作成し，モデルを導入しました．
複数モデルを試す場合は同様に model/<モデル名> 以下に配置してください．

4. 基本的な実行コマンド

vllm serve model/Qwen3-32B

実行後は別ターミナルで GPU 使用状況をモニタリング：

watch -n1 nvidia-smi

5. パラメータ解説

オプション	説明	デフォルト
`--pipeline-parallel-size`	パイプライン並列度．モデル層を分割して複数 GPU で実行できる．モデルが大きく，１GPUに収まらない場合に使う．メモリ負荷分散が目的？	1
`--tensor-parallel-size`	テンサー並列度．各層をさらに分散して高速化計算負荷の分散が目的？	1
`--cpu-offload-gb`	GPU メモリ不足時にオフロードする CPU メモリ量 (GB)	0
`--gpu-memory-utilization`	vLLM が GPU メモリを確保する割合 (0～1)	0.8
`--max-model-len`	最大シーケンス長（KV キャッシュサイズに影響）	モデル依存
`--quantization`	FP8 または bitsandbytes による量子化方式	なし
`--enforce-eager`	CUDA Graph キャプチャを無効化し同期実行モードに	オフ
`--no-enable-chunked-prefill`	チャンクドプリフィルを無効化しメモリ断片化を軽減	オフ

注意: 必要GPU台数の計算
--pipeline-parallel-size × --tensor-parallel-size = 4 × 4 = 16台 のGPUを要求します

6. メモリ不足・OOM 対策

断片化緩和

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

シーケンス長の制限

--max-model-len 32768 のように下げる
並列度の調整

パイプライン・テンサー並列度を小さくする
量子化を活用

--quantization bitsandbytes（事前に pip install bitsandbytes）

GPU 制限

export CUDA_VISIBLE_DEVICES=0,1   # 使用する GPU を指定

7. Ray 分散実行の注意

Ray クラスタ起動前に CUDA_VISIBLE_DEVICES を適切に設定してください．設定されているGPUがRayにて使用されることになります．

リソース不足エラー例：

ValueError: Cannot provide a placement group of placement_group_specs=[...] within 1800 seconds

→ GPU 台数を確認し --pipeline-parallel-size を調整

ローカルクラスタ起動：

ray start --head --port=6379
ray status

リモート：

export RAY_ADDRESS="<HEAD_NODE_IP>:6379"
ray status --address $RAY_ADDRESS

8. OpenWebUI 連携例

docker run -d -p 3000:8080 \
  --name open-webui \
  -v open-webui:/app/backend/data \
  -e OPENAI_API_BASE_URL=http://<vllm_HOST>:<vllm_PORT>/v1 \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Tips

モデルごとに最適な並列度・キャッシュサイズ設定は変わるので，小刻みにパラメータを調整して様子を見ましょう
watch nvidia-smi でリアルタイムに GPU メモリと利用率を監視するとチューニングが捗ります
Docker + NVIDIA Container Toolkit を組み合わせて安定的に GPU を扱いましょう
Ray を使わない場合は --distributed-executor-backend=mp でマルチプロセス実行にフォールバックできます

上記ガイドがお役に立てば嬉しいです！
随時更新予定です！