vllm-deploy-simple

vLLM のシンプルなデプロイ

vLLM をすばやくインストールし、サーバーを起動して、OpenAI 互換 API を検証するためのシンプルなスキルです。

このスキルでできること

このスキルでは、次の作業を効率的に実行できます。

• ハードウェアのバックエンド（NVIDIA CUDA、AMD ROCm、Google TPU、CPU）を検出する
• 適切なバックエンドをサポートする vLLM をインストールする
• モデルとポートを指定して vLLM サーバーを起動する
• OpenAI 互換 API エンドポイントをテストする
• デプロイが正しく動作していることを検証する
• 仮想環境による分離をサポートする

前提条件

• Python 3.10+
• GPU（NVIDIA CUDA、AMD ROCm）（推奨）、TPU、または CPU
• pip または uv パッケージマネージャー
• curl（API テスト用）
• 仮想環境（任意ですが、推奨）

使用方法

venv を作成する

ユーザーが venv のパスを指定していない場合、または現在の環境へのデプロイを求めている場合は、uv を使って現在のフォルダーに Python 3.12 の venv を作成します。uv が見つからない場合は、このパスにフォルダーを作成し、python を使って仮想環境を作成します。

ワークフロー全体を実行する（推奨）

ユーザーが venv のパス、モデル、ポートを指定していない場合は、デフォルトのオプションを使用します。

# Default deployment options (--venv "." --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000 --gpu_memory_utilization 0.8)
scripts/quickstart.sh

カスタムオプションを指定する場合：

# Use custom virtual environment
scripts/quickstart.sh --venv /path/to/venv

# Use custom model and port
scripts/quickstart.sh --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000

# Use custom GPU memory utilization
scripts/quickstart.sh --gpu_memory_utilization 0.6

# Combine all options
scripts/quickstart.sh --venv /path/to/venv --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000 --gpu_memory_utilization 0.8

これにより、次の処理が実行されます。

1. 仮想環境を有効にする（指定されている場合）
2. ハードウェアのバックエンド（CUDA/ROCm/TPU/CPU）を検出する
3. 適切なバックエンドをサポートする vLLM をインストールする
4. vLLM サーバーをバックグラウンドで起動する
5. サーバーの準備ができるまで待機する
6. サンプルリクエストで API をテストする
7. サーバーのステータスを表示する

個別のコマンドを実行する（手順ごとの操作やトラブルシューティングに使用）

vLLM をインストールする：

scripts/quickstart.sh install
# Or with virtual environment
scripts/quickstart.sh install --venv /path/to/venv

サーバーを起動する：

scripts/quickstart.sh start
# Or with custom options
scripts/quickstart.sh start --venv /path/to/venv --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000 --gpu_memory_utilization 0.8

API をテストする：

scripts/quickstart.sh test
# Or with custom port
scripts/quickstart.sh test --port 8000

サーバーを停止する：

scripts/quickstart.sh stop
# Or with virtual environment
scripts/quickstart.sh stop --venv /path/to/venv

サーバーのステータスを確認する：

scripts/quickstart.sh status

サーバーを再起動する：

scripts/quickstart.sh restart
# Or with custom options
scripts/quickstart.sh restart --venv /path/to/venv --port 8000 --gpu_memory_utilization 0.8

設定

このスクリプトでは、次のコマンドラインオプションを使用できます。

scripts/quickstart.sh [command] [OPTIONS]

Commands:
  install  - Install vLLM and dependencies
  start    - Start the vLLM server
  stop     - Stop the vLLM server
  test     - Test the OpenAI-compatible API
  status   - Show server status
  restart  - Restart the server
  all      - Run complete workflow (default)

Options:
  --model MODEL                 Model to use (default: Qwen/Qwen2.5-1.5B-Instruct)
  --port PORT                   Port to run server on (default: 8000)
  --venv VENV_PATH              Virtual environment path (default: .)
  --gpu_memory_utilization VRAM GPU memory utilization (default: 0.8)

ハードウェアバックエンドの検出

スクリプトはハードウェアを自動的に検出し、適切なバージョンの vLLM をインストールします。

• NVIDIA CUDA：nvidia-smi コマンドで検出します
• AMD ROCm：/dev/kfd および /dev/dri デバイスで検出します
• Google TPU：TPU_NAME 環境変数または gcloud コマンドで検出します
• CPU：GPU/TPU が検出されない場合の代替手段です

Google TPU の場合、標準の vllm パッケージではなく、vllm-tpu をインストールします。

API テスト

テストスクリプトは、シンプルなチャット補完リクエストを送信します。

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-1.5B-Instruct",
    "messages": [{"role": "user", "content": "Say hello!"}],
    "max_tokens": 50
  }'

トラブルシューティング

仮想環境が見つからない：

• --venv で指定したパスが存在し、有効な仮想環境であることを確認します
• 有効化スクリプト（Linux/macOS では bin/activate、Windows では Scripts/activate）が存在することを確認します
• uv を確認してインストールし、uv で新しい仮想環境を作成します（推奨）：uv venv /path/to/venv。または pip で作成します：python3 -m venv /path/to/venv

サーバーが起動しない：

• ポートがすでに使用されているか確認します：lsof -i :8000
• GPU が利用可能か確認します（NVIDIA の場合は nvidia-smi、AMD の場合は rocm-smi）
• vLLM のインストールを確認します：python -c "import vllm; print(vllm.__version__)"
• $VENV_PATH/tmp/vllm-server.log にあるサーバーログを確認します

API がエラーを返す：

• モデルの読み込みが完了するまで数秒待ちます
• サーバーログを確認します：cat $VENV_PATH/tmp/vllm-server.log
• サーバーが実行中であることを確認します：scripts/quickstart.sh status

メモリ不足：

• より小さいモデル（例：Qwen2.5-0.5B-Instruct）を使用します
• --gpu-memory-utilization パラメーターの値を下げます
• GPU を多く使用するほかのアプリケーションを終了します

誤ったバックエンドが検出される：

• NVIDIA の場合：nvidia-smi が PATH に含まれていることを確認します
• AMD の場合：ROCm ドライバーが正しくインストールされていることを確認します
• TPU の場合：TPU_NAME 環境変数を設定するか、gcloud をインストールします

注意事項

• サーバーはバックグラウンドで実行され、$VENV_PATH/tmp/vllm-server.log にログが記録されます
• 管理しやすいように、PID は $VENV_PATH/tmp/vllm-server.pid に保存されます
• 初回実行時にモデルがダウンロードされます（Qwen2.5-1.5B-Instruct の場合は約 3GB）
• 2 回目以降の実行では、キャッシュされたモデルが使用されます
• スクリプトは uv が利用可能かどうかを自動的に検出し、利用可能な場合は uv を使用します。利用できない場合は pip にフォールバックします
• 仮想環境を使用すると、システムの Python パッケージから分離できます
• 引数は任意の順序で指定できます（例：scripts/quickstart.sh --port 8080 start --venv /path/to/venv）