vLLM 0.23.0で推論サーバーを構築する手順では、完成条件を「起動したこと」だけに置きません。プロセスが起動することではなく、固定したモデル版がAPI経由で応答し、想定負荷でメモリ・速度・品質の基準を守り、異常時に旧版へ戻せることです。ここでは小型言語モデルを単一GPUで配信する検証環境を作り、疎通、負荷試験、品質回帰、監視、停止判断までを一続きで実施します。コマンド中の版と制限値は明示しますが、モデルのコミットSHA、API鍵、合格値は利用組織が確定した値へ置き換えてください。
構築範囲と完了条件を決める
この手順で作るのは、Ubuntu上の単一NVIDIA GPUへ小型言語モデルを読み込み、OpenAI互換のChat Completions APIとして同一ネットワーク内から利用する検証サーバーです。インターネットへ直接公開する構成、複数ノード、LoRAの動的切替、マルチモーダル入力は対象外にします。
先に範囲を限定する理由は、機能を足すほど必要メモリ、認証経路、障害点、品質テストが増え、起動確認だけでは安全性を評価できなくなるためです。
完了判定は六つあります。指定したvLLM版とモデルSHAを記録できること、サーバー再起動後も同じモデル名で応答すること、最大入力と同時数でOOMを起こさないこと、TTFT・TPOT・失敗率が合格値内であること、業務テストの重大誤答が0件であること、旧設定へ決めた時間内に復旧できることです。どれかが未測定なら「構築済み」ではなく「技術検証中」と記録します。
| 要件 | 検証用の設定例 | 本番値の決め方 |
|---|---|---|
| API利用者 | 評価端末2台、担当者3名 | サービスアカウントと送信元を列挙 |
| 入力・出力 | 入力512/4096 tokens、出力128 tokens | 実ログの中央値・p95・許容最大から設定 |
| 同時要求 | 1・4・8で段階試験 | ピーク到着率と待ち時間目標から逆算 |
| 可用性 | 検証時間中99%、手動復旧15分 | 業務停止の損失と運用体制で承認 |
| 品質 | 120件、重大誤答0、要確認率上限を設定 | 業務責任者が正解と重大度を確定 |
表の数値は構成例であり、vLLMやモデルの保証値ではありません。要件票にはデータ機密区分、ログ保存期間、問い合わせ先、停止権限も追加します。業務の最大入力が分からないままmax_model_lenを大きく設定するとKVキャッシュの余地が減り、逆に小さすぎると正規要求を拒否します。インフラ担当だけで値を決めず、業務側が必要範囲と誤りの影響を承認してください。
対応環境とモデル形式を固定する
検証基準は、Ubuntu 24.04 LTS x86_64、Python 3.12、NVIDIA GPU 24GB、RAM 64GB、vLLM 0.23.0のCUDA向けwheelとします。
v0.23.0のGPU導入資料はLinux、Python 3.10～3.13を要件とし、NVIDIAではcompute capability 7.5以上を挙げています。またWindowsはネイティブ対応ではなく、WSLまたはコミュニティ実装を案内しています[2]。
Windows上で同じコマンドを直接実行せず、評価結果にはWSLかLinuxホストかを明記します。
モデル例はQwen/Qwen2.5-1.5B-Instructの公式Safetensorsと公式トークナイザーです。モデルカードでは1.54Bパラメーター、Apache-2.0、Safetensors、チャットテンプレートを確認できます[4]。
ここでは配布ページの最新状態を無条件に使わず、評価開始時に40桁のコミットSHAを取得し、MODEL_REVISIONへ設定します。記事中で実在しないSHAを推測していないため、空欄のまま起動作業へ進めてはいけません。
| 対象 | 保存値 | 確認方法 |
|---|---|---|
| OS | ディストリビューション、kernel、glibc、CPU architecture | OS情報とパッケージ台帳を出力 |
| GPU | 製品名、VRAM、driver、compute capability | GPU管理コマンドと公式仕様を照合 |
| Python環境 | Python、vLLM、PyTorch、CUDA runtimeの版 | 導入後の版表示を保存 |
| モデル | model ID、revision SHA、重み形式、dtype | 配布元とローカルキャッシュを照合 |
| トークナイザー | revision、chat template、特殊token ID | モデルと同じrevisionから取得 |
GGUFはこの手順の入力にしません。量子化GGUFを別エンジンで使う評価と、SafetensorsをvLLMで配信する評価を混ぜると、モデル形式、量子化方式、実装差を切り分けられないからです。
量子化モデルを採用する場合は、vLLM 0.23.0が明示的に対応する方式と対象GPUを公式表で確認し、非量子化候補とは別のリリースIDにします。重み、トークナイザー、config、generation_configを同じrevisionへ揃えることも必須です。
vLLM 0.23.0を隔離環境へ導入する
既存の機械学習環境へ上書きせず、このサーバー専用の仮想環境を作ります。vLLM 0.23.0は2026年6月12日公開の安定リリースとして版を固定します[1]。公式GPU手順はuvによる環境作成と、torch backendを自動選択する導入方法を掲載しています。
ここでは依存関係の再現性を優先し、vLLM本体を0.23.0へ固定し、導入後に完全なパッケージ一覧を保存します。
uv venv --python 3.12 --seed --managed-pythonsource .venv/bin/activateuv pip install "vllm==0.23.0" --torch-backend=autopython -c "import vllm, torch; print('vllm=', vllm.__version__); print('torch=', torch.__version__); print('cuda=', torch.version.cuda)"nvidia-smiuv pip freeze > requirements-vllm-0.23.0.lock.txt
期待する確認結果は、vLLMが0.23.0と表示され、PyTorchからCUDA GPUを認識でき、GPUドライバー側に異常がないことです。CUDA版を記事の記述だけで強制せず、公式wheelとドライバーの互換条件を導入時点で照合します。nightly wheel、mainブランチ、出所不明のコンテナを混ぜると版固定が崩れるため、検証リリースでは使いません。脆弱性対応で依存関係を変更した場合も同じ負荷・品質試験を再実施します。
導入時のログ、コマンド履歴、lockファイルはモデル成果物と別に保管します。複数GPUがある場合は使用するdeviceを明示し、評価中に他の学習処理やデスクトップ処理を載せません。インストール直後に本番ポートを開くのではなく、まずlocalhostだけで版確認を行います。
公式クイックスタートがQwen2.5-1.5B-Instructをvllm serveで起動する例を示していることも、手順整合の確認材料にできます[3]。
制限値を付けてサーバーを起動する
起動前にモデルSHAとAPI鍵を環境変数へ設定します。MODEL_REVISIONは配布元で確認した値、VLLM_API_KEYは秘密管理基盤で発行した十分に長い値に置き換えます。シェル履歴やHTMLへ実鍵を書かないでください。
served-model-nameはクライアントが送る安定名であり、裏側のモデルを入れ替える場合もリリース台帳で対応を追います。初回はhostを127.0.0.1に限定し、ネットワーク公開は認証プロキシとTLSを整えた後に行います。
export MODEL_REVISION="配布元で確認した40桁コミットSHA"export VLLM_API_KEY="秘密管理基盤から読み込んだ検証用API鍵"vllm serve Qwen/Qwen2.5-1.5B-Instruct \ --revision "$MODEL_REVISION" \ --served-model-name local-slm-v1 \ --host 127.0.0.1 \ --port 8000 \ --api-key "$VLLM_API_KEY" \ --dtype bfloat16 \ --max-model-len 4096 \ --max-num-seqs 8 \ --gpu-memory-utilization 0.85
max-model-len 4096は今回の検証上限、max-num-seqs 8は同時処理の上限、gpu-memory-utilization 0.85はGPUメモリ利用率の初期値です。これらは万能な推奨値ではありません。必要入力が4096 tokensを超えるなら、単に上限を広げる前にピークメモリを再計算します。0.85を引き上げてOOMを隠すのではなく、運用監視や断片化の余白を残します。vLLMのメモリ節は、モデル並列、量子化、最大コンテキスト、同時系列数など複数の調整軸を案内しています[9]。
起動ログでは、解決されたモデルrevision、dtype、attention backend、利用GPU、KVキャッシュ容量、最大並列性、待受アドレスを保存します。警告を無視して疎通へ進まず、設定台帳との差を確認します。
OpenAI互換サーバーはCompletions、Chat CompletionsなどのAPIを提供し、API keyも起動引数で設定できます[5]。ただしAPI互換は運用品質や完全な挙動一致を保証する語ではないため、利用するendpointとパラメーターだけを回帰対象にします。
モデル一覧とChat APIを疎通確認する
別の端末を開き、まずモデル一覧を取得します。HTTP 200だけでなく、idがlocal-slm-v1であることを確認してください。次にChat Completionsへ温度0、短い日本語入力、最大出力64 tokensを送り、応答JSON、finish_reason、usage、HTTP status、処理時間を保存します。
API鍵なし、誤ったモデル名、上限超過入力も送って、拒否されるべき要求が拒否されることを確かめます。成功系だけではアクセス制御や入力制限の誤設定を発見できません。
curl -sS http://127.0.0.1:8000/v1/models \ -H "Authorization: Bearer $VLLM_API_KEY"curl -sS http://127.0.0.1:8000/v1/chat/completions \ -H "Authorization: Bearer $VLLM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "local-slm-v1", "messages": [ {"role": "system", "content": "与えられた文章だけを一文で要約してください。"}, {"role": "user", "content": "検証番号A-001。受付日は7月30日、承認者は佐藤です。"} ], "temperature": 0, "max_tokens": 64 }'
| 試験 | 期待結果 | 不一致時の判断 |
|---|---|---|
| 正しい鍵・正しいmodel | 200、本文とusageを返す | ログとリクエストIDを保存して原因調査 |
| 鍵なし | 認証エラーで拒否 | 200なら公開を停止し認証設定を修正 |
| 未知のmodel名 | 対象なしとして拒否 | 別モデルへ暗黙転送するなら設定を見直す |
| 入力上限超過 | 処理せず明確なエラーを返す | 切り詰める実装ならデータ欠落を調査 |
Chat APIはトークナイザー側のchat templateへ依存します。vLLMのオンライン配信資料は、chat templateがないモデルではchat要求がエラーになることを説明しています[6]。任意のテンプレートを急いで追加すると学習時形式とずれ、品質が落ちる可能性があります。まず公式トークナイザーにテンプレートが含まれるか確認し、上書きする場合はそのファイルを版管理し、全品質テストを新しい候補として実施します。
メモリと速度を負荷試験で測る
疎通後は同じモデル設定のまま、入力512 tokens・出力128 tokensの人工データ200件を、同時数1、4、8で順に流します。人工データは速度特性を揃える用途であり、品質判定には使いません。各試験の前にサーバーを同じ状態へ戻し、20件のウォームアップを実行します。
GPU使用量は一秒間隔で採取し、ロード直後、単発実行、最大同時数のピークを区別します。結果には成功件数、失敗件数、実効request rate、入力・出力token数を添えます。
vllm bench serve \ --backend openai-chat \ --base-url http://127.0.0.1:8000 \ --endpoint /v1/chat/completions \ --model local-slm-v1 \ --tokenizer Qwen/Qwen2.5-1.5B-Instruct \ --dataset-name random \ --num-prompts 200 \ --request-rate 2 \ --max-concurrency 8 \ --random-input-len 512 \ --random-output-len 128 \ --percentile-metrics ttft,tpot,itl,e2el \ --metric-percentiles 50,95,99 \ --header "Authorization=Bearer $VLLM_API_KEY"
vLLM 0.23.0のbench serveは、TTFT、TPOT、ITL、E2Eなどのpercentile出力と最大同時数の指定を備えています[7]。TTFTは先頭tokenまで、TPOTは先頭以降の一token当たり、ITLは連続token間隔、E2Eは要求全体の時間として読み分けます。対話ではp95 TTFT、長い生成ではTPOT、バッチではtoken throughputを重視します。平均値だけで合格にすると、一部利用者の長い待ち時間を隠してしまいます。
| 指標 | 同時1 | 同時4 | 同時8 | 合格例 |
|---|---|---|---|---|
| p95 TTFT | 実測を記入 | 実測を記入 | 実測を記入 | 1.5秒以下 |
| p95 TPOT | 実測を記入 | 実測を記入 | 実測を記入 | 45ms以下 |
| 要求失敗率 | 実測を記入 | 実測を記入 | 実測を記入 | 0.5%未満 |
| VRAMピーク | 実測を記入 | 実測を記入 | 実測を記入 | 運用上限以下 |
| 待ち行列最大 | 実測を記入 | 実測を記入 | 実測を記入 | 継続増加しない |
表のしきい値は検証案で、実測結果ではありません。4096 tokens入力でも別試験を行い、短文だけで容量を合格にしないでください。VRAMが物理上限へ近づく、待ち行列が試験終了まで減らない、タイムアウトが連続する場合は、その同時数を不合格にします。
速度を上げるために入力上限や出力上限を変更したなら、同じ候補の追試ではなく設定版を更新し、品質試験もやり直します。
負荷試験の計算式は、要求失敗率を「失敗要求数÷総要求数×100」、実効処理量を「成功要求数÷試験秒数」とします。タイムアウト後に完了した要求を成功へ含めるかは試験前に固定してください。200件中3件が失敗した想定例なら失敗率は1.5％で、表の0.5％未満という提案しきい値には届きません。平均応答時間だけで合格にせず、p95と最大待ち行列も同じ実行記録で確認します。
業務データで品質回帰を行う
推論サーバーはモデル出力へ影響するチャットテンプレート、tokenizer、dtype、サンプリング既定値を含むため、モデル単体で合格済みでも配信経路を通した品質確認が必要です。正解を確定した120件を、抽出30件、分類25件、要約20件、数値・日付20件、否定・例外15件、長文10件へ分けます。
各入力をOpenAI互換APIから送信し、temperature、top_p、max_tokens、seedを固定します。クライアント側の前処理と後処理も本番と同じ版にします。
| 評価群 | 主指標 | 重大な失敗 | 判定責任者 |
|---|---|---|---|
| 項目抽出 | 必須項目完全一致率 | 別人物のID、誤った金額・日付を出力 | 業務データ管理者 |
| 分類 | macro F1、保留率 | 要承認を承認不要へ振り分け | 業務ルール責任者 |
| 要約 | 根拠保持、人手4段階 | 原文に存在しない決定を追加 | 原文作成部門 |
| 数値・否定 | 完全一致、符号保持 | 上限と下限、可と不可を反転 | 品質評価担当 |
| 長文 | 根拠箇所一致、未回答率 | 参照範囲外を確定根拠として使用 | サービス所有者 |
比較対象は、承認済みの直前配信版です。新しいモデルやvLLMへ替えたとき、完全一致率の差だけでなく、以前は正しかった設問が誤りへ変わった件数を確認します。合格案は重大失敗0件、全体正答率の低下1ポイント以内、人手評点3.5/4以上です。正解自体が曖昧だった設問は評価対象から外し、正解定義を更新して全候補へ再実行します。新候補だけに有利な採点修正は禁止します。
品質試験中はHTTP status、request ID、model名、入力hash、出力、token使用量、開始・終了時刻を保存します。ただし機密原文を監視ログへそのまま残すことは避け、評価保管領域と運用メトリクスを分離します。速度に合格しても重大誤答が一件あれば配信を止めます。
逆に品質が同等でも最大負荷で要求が欠落するなら採用できません。品質、容量、速度は総合点で相殺せず、すべて必須条件として扱います。
エラーを原因別に切り分ける
障害対応では「再起動したら直った」で終えず、導入、モデル解決、ロード、API、負荷、品質のどこで崩れたかを分けます。発生時刻、リクエストID、vLLM版、モデルSHA、起動引数、GPU使用量、直前の変更を保存してから復旧します。
起動コマンドをその場で書き換えると再現できなくなるため、設定ファイルの新しい版として変更し、旧版を保持します。下表は代表的な症状と最初の確認点です。
| 症状・メッセージ例 | 主な原因候補 | 切り分け | 停止判断 |
|---|---|---|---|
| CUDA out of memory | 重み、KV領域、同時数、他プロセス | 発生段階を確認し、max-model-lenとmax-num-seqsを要件内で一つずつ下げる | 必須入力・同時数でも再発 |
| No chat template is defined | tokenizerにテンプレートがない | 公式revisionとtokenizer設定を照合 | 学習形式を確認できない独自テンプレートしかない |
| 401または認証拒否 | 鍵欠落、ヘッダー形式、プロキシ設定 | curlで直結試験し、鍵の読込元を確認 | 鍵なし要求が通過する |
| model not found | served名と要求modelが不一致 | /v1/modelsとクライアント設定を照合 | 別モデルへ意図せず転送 |
| maximum context length超過 | 入力と出力予約が上限を超える | tokenizerで事前計数し、切り詰め方針を確認 | 必要情報を黙って欠落させる |
| Windowsでwheel導入失敗 | ネイティブWindowsを使用 | 対応LinuxまたはWSL構成へ移す | 未検証forkだけが解決策 |
| p95遅延が時間とともに増える | 待ち行列、KV逼迫、到着率過多 | running、waiting、KV使用率を同時確認 | SLO超過が二回連続 |
OOMではgpu-memory-utilizationを上げる前に、ロード時か要求処理時かを見ます。ロード時なら重み形式、dtype、GPU分割を確認し、長文負荷だけなら最大入力、最大同時数、KVキャッシュの関係を調整します。入力を短くして通った場合も、本番の必要長を下回るなら解決ではありません。
より小さなモデル、量子化、複数GPU、要求制御を候補として再設計します。設定を変えた後はメモリ試験と品質回帰を双方やり直します。
品質異常はHTTPエラーにならないため、運用上もっとも見逃しやすい障害です。日付だけが欠ける、否定が反転する、JSON構造が時々壊れる場合は、該当リクエストを回帰セットへ追加し、旧版と同じ条件で比較します。
モデルSHA、chat template、推論引数のどれが変わったかを確認し、原因が分からないまま再起動で戻った場合も新規公開は保留します。復旧と原因解消を別の完了条件にしてください。
認証・監視・復旧を運用へ組み込む
検証用のapi-keyは最低限の入口であり、インターネット公開に必要な防御をすべて提供するものではありません。本番ではvLLMを内部アドレスで待ち受けさせ、TLS終端、利用者認証、要求サイズ制限、rate limit、監査ID付与を行うリバースプロキシまたはAPI gatewayの後ろへ置きます。
モデル取得用の資格情報と推論API鍵を分離し、ログへAuthorizationヘッダーを出しません。ネットワーク規則では業務クライアントと監視系だけを許可します。
vLLMの公式メトリクスにはKVキャッシュ使用率、実行中・待機中要求数、E2E待ち時間、inter-token latencyなどがあります[8]。ダッシュボードでは平均よりp95・p99、失敗理由、待ち行列の継続時間を重視します。
提案アラートは、KV使用率90%以上が5分、waitingが10件以上で3分、p95 TTFTが1.5秒超を二窓連続、5xx率1%以上、プロセス再起動発生です。値は負荷試験後に本番要件へ合わせます。
| 観測 | 注意 | 停止 | 担当アクション |
|---|---|---|---|
| KVキャッシュ使用率 | 80%継続 | 95%到達と要求失敗 | 入力長・同時数・到着率を確認 |
| 待機要求数 | 通常帯の2倍 | 増え続けSLO超過 | 流入制御し直前版へ切替 |
| 5xx率 | 0.5%以上 | 1%以上または連続失敗 | 新規要求停止、ログ保全、復旧 |
| 品質サンプル | 軽微差が基準超過 | 重大誤答1件 | 配信停止、影響要求を抽出 |
| モデル識別子 | 台帳との差 | SHA不明・hash不一致 | 隔離して承認版を再展開 |
リリースはblue/greenまたは同等の二系統で行い、旧版をすぐ破棄しません。新系統で疎通、負荷の縮小版、品質の必須設問を通した後、少量の要求だけを流します。停止条件に触れたら新規流入を旧系統へ戻し、処理中要求を扱う方針に従って切り替えます。
モデルキャッシュ、環境lock、起動設定、プロキシ設定、評価票をリリースIDで結び、誰がいつ切り替えたかを監査ログへ残します。
評価票で採用と停止を決める
構築担当者の所感ではなく、業務、性能、セキュリティ、復旧を一枚で判定します。採点前にハードゲートを確認し、一つでも不合格なら総合点を計算せず見送ります。ハードゲートは、モデルとvLLMの版を再現できる、必要入力と同時数でOOMがない、重大誤答0、認証なし要求を拒否、ログから利用版を追跡できる、旧版へ制限時間内に戻せる、の六項目です。
| 評価領域 | 配点 | 満点条件 | 必要証拠 |
|---|---|---|---|
| 業務品質 | 30 | 120件合格、重大差分なし | 設問版、出力、採点記録 |
| 速度・処理量 | 20 | 最大同時数でp95目標内 | bench結果とメトリクス |
| メモリ・安定性 | 15 | ピークが上限内、60分連続成功 | GPU時系列とサーバーログ |
| セキュリティ | 15 | 認証、TLS、権限、秘密管理が承認済み | 構成図と拒否試験 |
| 再現性 | 10 | 別担当者が同じ版を再構築 | lock、SHA、起動設定 |
| 復旧・運用 | 10 | 監視と15分以内の切戻しに合格 | 訓練記録と連絡履歴 |
採用案は85点以上かつ全ハードゲート通過、条件付き採用は70～84点で低リスク入力に限定、69点以下は見送りとします。この境界は編集上の提案なので、組織のリスク基準で承認してください。条件付き採用には対象業務、利用者、最大入力、終了日、再評価日を付けます。点数が高くても重大品質、認証、復旧のいずれかが欠ければ、本番へ進めません。
vLLMサーバーが向かないケース
GPU運用担当を置けない、モデルの利用条件を確認できない、APIへ送るデータ区分が未定、品質正解を作れない、24時間の障害連絡先が必要なのに体制がない場合は、自前配信を始めない方がよいでしょう。要求量が少なく機密制約も弱い業務では、管理サービスの方が保守費を含む総費用を抑える可能性があります。
Windowsネイティブだけが許可された端末へ、非公式実装を本番前提で入れる計画も本手順の対象外です。
停止条件は、重大誤答1件、認証回避、モデルSHA不一致、OOM、要求欠落、p95 SLOの二回連続超過、監視断、ロールバック失敗です。停止権限者が不在でも自動的に新規流入を止める条件と、担当者判断を要する条件を分けます。再開時は原因説明、修正差分、回帰試験、セキュリティ確認、業務責任者承認を必要とし、同じリリースIDを使い回しません。
構築後の次の行動
検証を始める前に、MODEL_REVISION、API鍵の保管先、入力長、同時数、速度目標、120件の正解、停止責任者を埋めます。その後、隔離環境の導入、localhost起動、成功・拒否の疎通、三段階の負荷、品質回帰、切戻し訓練を順番通りに実施します。途中で設定を変えたら、その時点から新しい候補版として必要試験をやり直します。
結果の良い実行だけを残さず、失敗条件と原因も台帳へ記録してください。
本番判定会へ提出するもの
環境台帳、モデルSHA、依存関係lock、起動引数、疎通4パターン、メモリ時系列、benchのp50・p95・p99、120件の品質回帰、認証・入力制限テスト、監視画面、停止条件、切戻し所要時間、100点評価票を提出します。すべての証拠が同じリリースIDへ結び付いていれば、更新後も比較と復旧を繰り返せます。
参考文献・出典
- vLLM Project「Release v0.23.0」（公式リリース、公開日：2026年6月12日、参照日：2026年7月30日）
- vLLM Project「GPU Installation」（公式文書v0.23.0、更新日：2026年5月11日、参照日：2026年7月30日）
- vLLM Project「Quickstart」（公式文書v0.23.0、更新日：2026年5月27日、参照日：2026年7月30日）
- Qwen Team「Qwen2.5-1.5B-Instruct Model Card」（公式モデルカード、シリーズ公開：2024年9月、1.54B・Safetensorsを確認、参照日：2026年7月30日）
- vLLM Project「OpenAI-Compatible Server」（公式文書v0.23.0、更新日：2026年5月19日、参照日：2026年7月30日）
- vLLM Project「Online Serving」（公式文書v0.23.0、更新日：2026年6月2日、参照日：2026年7月30日）
- vLLM Project「vllm bench serve」（公式CLI資料v0.23.0、更新日：2025年12月26日、参照日：2026年7月30日）
- vLLM Project「Production Metrics」（公式監視資料v0.23.0、更新日：2026年2月23日、参照日：2026年7月30日）
- vLLM Project「Conserving Memory」（公式設定資料v0.23.0、更新日：2026年4月28日、参照日：2026年7月30日）
vLLM、PyTorch、GPU driver、モデルrevision、起動引数のどれかを変更した場合は、掲載した合格値を引き継がず、対象環境で負荷試験と品質回帰を再実施してください。
