vLLMを理解しないままLLMを扱うのは、スポーツでルールを知らずにプレーするようなもの。
本記事では、松尾研 LLM開発コンペ2025 に参加して得た知見をもとに、Transformersとの違いからvLLMの仕組みを解説し、Google Colab（無料）と Ubuntu + RTX3060（ローカル）で Qwen2-0.5B-Instruct を動かす最小手順を紹介します。
背景：松尾研 LLM開発コンペ2025で見えた課題
松尾研 LLM開発コンペ2025 に参加し、チームで LLM の開発・評価 を進める中で、重要な学びがありました。
vLLMの基礎を理解していないと、推論や評価で大きくつまずく場面が多かったことです。
言い換えれば、このvLLMを理解すれば、スループットやチーム連携は格段に向上します。
1. Transformers（前提の整理）
1-1. Transformersとは？
Transformers は Hugging Face 製の LLM 用フレームワーク。事前学習済みモデルを簡単に呼び出し、テキスト生成・翻訳・要約などが可能です。
from transformers import AutoModelForCausalLM, AutoTokenizer
model_name = "Qwen/Qwen2-0.5B-Instruct"
tok = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="auto")
prompt = "What is AI? Answer in one short sentence."
inputs = tok(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=60)
print(tok.decode(outputs[0], skip_special_tokens=True))
1-2. 強みと課題
| 項目 | 内容 |
|---|---|
| 強み | モデル取得～推論が容易／Hubとの統合／多様なモデル対応 |
| 課題 | 逐次処理中心で非効率／GPUアイドルが多い／複数入力で速度低下 |
2. vLLM
2-1. vLLMとは？
vLLM は、大規模言語モデル（LLM）推論を高速化・効率化するために設計された推論エンジンです。
従来の Transformers では、入力ごとに逐次的に処理が行われ、GPUの待機時間（アイドル時間）が多く発生していました。
vLLM はこの非効率性を根本から改善し、複数リクエストを同時に処理しながらGPUを常時フル稼働させることを目指しています。
バックエンドでは、PyTorchやCUDAを直接活用しつつ、モデル管理・メモリスケジューリング・OpenAI互換APIの提供までを一元化しており、研究・業務・評価環境のどれでも同じ仕組みで動かすことができます。
2-2. 3つの中核機能
vLLMの高速化を支えるのは、以下の3つの設計思想です。
| 機能 | 概要 |
|---|---|
| PagedAttention | GPUメモリをページ単位で管理し、必要なページだけを保持。巨大モデルでも効率的に推論可能。 |
| Continuous Batching | リクエストをリアルタイムで束ねて動的に処理。複数ユーザの同時生成を高効率で実行。 |
| OpenAI 互換API |
vllm serve を実行するだけで /v1/completions エンドポイントを自動公開。OpenAI SDKがそのまま使える。 |
これにより、Transformersをそのまま使う場合と比べて、最大3〜5倍のスループット向上が期待できます。
特に、複数の短いプロンプトを同時に処理するRAGや評価系のタスクでは、その効果が顕著に表れます。
3. Transformers vs vLLM
Transformers と vLLM はどちらも LLM の推論を行う仕組みですが、設計思想がまったく異なります。
Transformers は単純で扱いやすい一方、vLLM は高効率・同時処理特化型です。
| 比較項目 | Transformers | vLLM |
|---|---|---|
| 推論単位 | 1つの入力を順番に処理（逐次実行） | 複数入力をリアルタイムで束ねて処理（動的バッチ化） |
| GPU利用効率 | リクエスト待ち時間中はGPUが待機（非効率） | 常に複数リクエストを処理しGPUをフル稼働 |
| メモリ管理 | すべてのトークンをGPU上に保持 | PagedAttentionで必要な部分のみロード（省メモリ） |
| API提供 | 開発者が独自にエンドポイント実装が必要 |
vllm serve だけでOpenAI互換APIを自動提供 |
| スループット（処理速度） | 通常（逐次処理のためボトルネック） | 最大3〜5倍の高速化（連続バッチ処理） |
Transformers は簡単に動かせますが、並列処理やAPI化を考えるとボトルネックが出やすくなります。
vLLM は推論効率とスケーラビリティを重視して設計されており、同じGPUでも「より多く」「より速く」テキストを生成できます。
補足：Hugging Face トークン（HF_TOKEN）の設定方法
Qwen シリーズなど、Hugging Face Hub で「利用同意が必要なモデル」を使う場合は、アクセス用トークン（HF_TOKEN） を設定する必要があります。
このトークンは、Google Colaboratory と Ubuntu のどちらでも共通で使えます。
トークンの取得（共通手順）
- Hugging Face にログイン
- 右上メニュー → Settings → Access Tokens
- 「Create new token」をクリック
- 権限は Read を選択 → コピー（例：
hf_xxxxxxxxxxxxxxx）
⚠️注意：このトークンはあなたの認証情報です。公開ノートブックやGitHubに直接書かないようにしてください。
Google Colaboratoryでの設定
Colab の「シークレット」機能を使えば、追加コードなしでも自動的に環境変数が設定されます。
- 左側メニューの「鍵マーク（シークレット）」
- 「新しいシークレットを追加」
- キー：HF_TOKEN
- 値：コピーしたトークン
Ubuntu / WSL2 環境での設定
方法A：環境変数を直接設定（推奨）
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxx
方法B：.env ファイルを用意（uv など対応ツール使用時）
プロジェクト直下に .env ファイルを作成：
echo "HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxx" > .env
uv run や dotenv 対応ライブラリを使用すると自動ロードされます。
.env は .gitignore に登録しておきましょう。
4. Google Colaboratoryで試す（Qwen 2-0.5B）
4-1. セットアップ
- メニューから「ランタイム → ランタイムのタイプを変更」
- 「ハードウェア アクセラレータ」を GPU に設定
!pip -q install vllm openai
!nvidia-smi
T4 などのGPUが表示されればOK。
4-2. 単一推論
from vllm import LLM, SamplingParams
llm = LLM(
model="Qwen/Qwen2-0.5B-Instruct",
dtype="float32",
max_model_len=1024,
gpu_memory_utilization=0.70,
)
out = llm.generate(
["What is AI? Answer in one short sentence."],
SamplingParams(max_tokens=512, temperature=0.2)
)
print(out[0].outputs[0].text.strip())
4-3. 複数プロンプト同時推論
prompts = [
"What is AI? Answer in one short sentence.",
"Why do plants need sunlight? Answer simply."
]
outs = llm.generate(prompts, SamplingParams(max_tokens=100, temperature=0.2))
for i, o in enumerate(outs):
print(f"Q{i+1}:", prompts[i])
print("A :", o.outputs[0].text.strip(), "\n")
複数プロンプトを渡すと Continuous Batching が働き、処理時間が短縮されます。
5. Ubuntu + RTX3060で動かす
5-0. 事前チェック（GPU・ドライバ）
- NVIDIAドライバが入り、nvidia-smi でGPUが見えること
- CUDA Toolkit は必須ではありません（PyTorchの cu121 ビルドが同梱のCUDAランタイムを使用）
nvidia-smi
5-1. uv でプロジェクト＆仮想環境を作る
uv は「高速な Python パッケージ＆環境マネージャ」です。プロジェクト直下に .venv を作り、依存は pyproject.toml に記録されます。
# uv インストール（未導入なら）
curl -LsSf https://astral.sh/uv/install.sh | sh
# プロジェクト作成
uv init vllm-demo
cd vllm-demo
以後、仮想環境の有効化は uv run ... でOK（手動でのactivateは不要）。
手動で仮想環境を有効化したい場合：
source .venv/bin/activate # activate environment
deactivate # deactivate environment
5-2. 依存インストール（PyTorch/cu121 + vLLM）
RTX3060（Ampere）は cu121（CUDA 12.1）ビルドが安定です。
uv add torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
uv add vllm openai
GPUがPythonから使えるか確認。仮想環境内で動いていることを保証するため、uv run を付けます。
uv run python -c "import torch;print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
# 例）True NVIDIA GeForce RTX 3060
5-3. vLLM サーバ起動（仮想環境で）
サーバは必ず uv run で起動します。
uv run vllm serve Qwen/Qwen2-0.5B-Instruct \
--dtype float32 \
--max-model-len 1024 \
--gpu-memory-utilization 0.70 \
--port 8000
別ターミナルを開かず 同一シェルで動かしたい人向けTips：
uv run vllm serve ... &でバックグラウンド化、tail -f nohup.out等でログ監視。
5-4. クライアントから叩く（OpenAI SDK互換）
Python（同じ仮想環境から）
# client.py
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
resp = client.completions.create(
model="Qwen/Qwen2-0.5B-Instruct",
prompt="What is AI? Answer in one short sentence.",
max_tokens=512
)
print(resp.choices[0].text.strip())
実行：
uv run python client.py
curl
curl -s http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{
"model":"Qwen/Qwen2-0.5B-Instruct",
"prompt":"What is AI? Answer in one short sentence.",
"max_tokens":512
}' | jq -r '.choices[0].text'
謝辞
本プロジェクトを通じて、貴重な学びと経験を得ることができました。
松尾研LLM開発コンペ2025の運営関係者および支援者の皆様に、心より感謝申し上げます。
また、チームねこの皆さんと共に学び、成長できたことに心から感謝します。
本プロジェクトは、国立研究開発法人新エネルギー・産業技術総合開発機構(以下「NEDO」)の「日本語版医療特化型LLMの社会実装に向けた安全性検証・実証」における基盤モデルの開発プロジェクトの一環として行われます。