ローカルLLM(vLLM)の簡単な説明

# vLLM 入門ガイド
私自身，ローカルLLMを開発するにあたり，vLLMでつまるところがありましたので，共有できればと思います．
## はじめに
Linux(Debian)環境を想定しています．
vLLM は大規模言語モデル（LLM）を高速・効率的にサーブするためのツールです．本ガイドでは，

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

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

---

## 1. 前提条件

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

---

## 2. 環境構築
### 2.1 Python,Pyenvのセットアップ
```bash
# 必要なパッケージのインストール
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
```
インストールできているかを確認する
```bash
pyenv --version
```

### 2.2 Git LFS のセットアップ

```bash
# 初回のみ
git lfs install
```

### 2.3 環境変数の設定
hugging faceのUserNameと，トークンを取得し設定します．
```bash
export HF_TOKEN = "<YOUR_HF_TOKEN>"
export HF_USER  = "<YOUR_HF_USERNAME>"
```

---

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

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

```bash
git lfs clone https://${HF_USER}:${HF_TOKEN}@huggingface.co/Qwen/Qwen3-32B model/Qwen3-32B
```
私は，modelsディレクトリを作成し，モデルを導入しました．
複数モデルを試す場合は同様に `model/<モデル名>` 以下に配置してください．

---

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

```bash
vllm serve model/Qwen3-32B
```

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

```bash
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 対策

1. 断片化緩和

   ```bash
   export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
   ```

2. シーケンス長の制限

   `--max-model-len 32768` のように下げる

3. 並列度の調整

   パイプライン・テンサー並列度を小さくする

4. 量子化を活用

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

5. GPU 制限

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

---

## 7. Ray 分散実行の注意

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

- リソース不足エラー例：

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

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

- ローカルクラスタ起動：

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

- リモート：

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

---

## 8. OpenWebUI 連携例

```bash
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` でマルチプロセス実行にフォールバックできます

---

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