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でマルチプロセス実行にフォールバックできます
上記ガイドがお役に立てば嬉しいです！
随時更新予定です！