vLLMでLoRAをリクエスト別に切り替える入門

先に結論

vLLMでは、一つのbase modelへ互換性を確認したLoRA adapterを起動時に読み込み、requestの`model`名だけでbaseとadapter適用後を切り替えられます。最初は動的loadを使わず、公式文書の組み合わせをlocalhostへ固定し、`/v1/models`と同じpromptの2requestで入口を確認します。最初の成功は「品質が上がった」ではなく、baseとLoRAが別model名として見え、両方がerrorなく応答する状態です。

確認日時: 2026年8月13日（Asia/Tokyo）
対象version: vLLM v0.26.0、commit 568afb3。LoRAの操作は2026年8月13日時点のstable公式文書も照合。
検証区分: 公式releaseとdocumentationに基づく机上調査・再現手順です。この制作環境ではvLLM、model、adapterをinstall／downloadしておらず、GPU推論は未実行です。
適用外: baseとadapterの互換性が公式情報やmetadataで確認できない組み合わせ、公開serverでの動的LoRA更新、品質・速度・memoryの保証。

始める前に知っておくこと

LoRA（Low-Rank Adaptation）は、base modelの重みを丸ごと複製せず、小さな追加weightを重ねて振る舞いを変える方法です。vLLMのLoRA対応は、対象model classがSupportsLoRAを実装している場合に使えます。model名が似ているだけでは互換性を判断できません。

この手順では、公式LoRA文書と同じ組み合わせを使います。

base model: meta-llama/Llama-3.2-3B-Instruct
adapter: jeeejeee/llama32-3b-text2sql-spider
server: vLLM v0.26.0を用意した隔離環境
接続先: 127.0.0.1:8000だけ

modelとadapterの取得にはnetwork、保存容量、各repositoryの利用条件への同意が必要です。GPU、driver、CUDAなどvLLM本体の導入条件はplatformで異なるため、先に公式installation guideと自分のaccelerator向け手順を確認します。本番APIの認証や公開方法は既存のvLLM本番API server記事と役割を分け、本稿ではlocalhostで最初の切り替えだけを扱います。

最短手順

1. versionと空きportを確認する

vLLM v0.26.0を有効にしたterminalでversionを記録します。

vllm --version

0.26.0以外なら、同じ結果になると仮定せず、そのversionのLoRA文書とvllm serve --helpを確認します。port 8000を別processが使っている場合は、そのprocessを勝手に停止せず、検証用portを変えて以後のURLも合わせます。

2. adapterを起動時に固定してserverを開始する

vllm serve meta-llama/Llama-3.2-3B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --enable-lora \
  --lora-modules sql-lora=jeeejeee/llama32-3b-text2sql-spider

--enable-loraでLoRA経路を有効にし、--lora-modulesの左側sql-loraをrequestから選ぶmodel名、右側をadapterの場所として登録します。この例は起動時に固定loadする方式です。VLLM_ALLOW_RUNTIME_LORA_UPDATINGは設定しません。

downloadや初回compileには時間がかかる場合があります。server logでerrorが止まり、HTTP serverが起動したことを確認するまで次へ進みません。実際のrepository revision、取得済みsnapshot、container digestは後から再現できるように保存します。

3. baseとLoRAが別model名で見えることを確認する

別terminalからmodel一覧を取得します。

curl --fail-with-body http://127.0.0.1:8000/v1/models

応答のdataにbase modelとsql-loraの両方が含まれることを確認します。HTTP 200だけで合格にせず、idがrequestに使う文字列と一致するかを見ます。

4. 同じpromptでmodel名だけを切り替える

まずbaseへ送ります。

curl --fail-with-body http://127.0.0.1:8000/v1/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "meta-llama/Llama-3.2-3B-Instruct",
    "prompt": "San Francisco is a",
    "max_tokens": 7,
    "temperature": 0
  }'

次にJSONのmodelだけをsql-loraへ変えます。

curl --fail-with-body http://127.0.0.1:8000/v1/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "sql-lora",
    "prompt": "San Francisco is a",
    "max_tokens": 7,
    "temperature": 0
  }'

両方がerrorなく完了し、responseのmodelと選んだ経路を区別できれば最初の動作確認です。短い1promptの出力差だけでadapter品質を判定しません。task品質を評価する場合は、adapterの目的に合う固定test setと期待条件を別に用意します。

つまずきやすい点と戻し方

`sql-lora`がmodel一覧に出ない

server起動logの--enable-lora、--lora-modulesの区切り、adapter取得errorを確認します。別terminalに残った旧serverへ接続していないか、hostとportも確認します。起動commandを一度に変更せず、まず公式例の一adapterへ戻します。

adapterのloadでshapeやmoduleのerrorになる

base model family、revision、adapterのtarget modules、rankが一致しない可能性があります。「同じLlama系だから」と推測で続行せず、adapter cardとmetadataで対応baseを確認します。互換性を確認できなければその組み合わせを中止します。llama.cppのGGUF adapterとはfile形式も実行系も異なるため、llama.cppのLoRA入門のartifactをそのまま指定しません。

memory不足でserverが起動しない

LoRAが小さくてもbase model、KV cache、runtime、adapter領域が必要です。別processを無理に終了せず、serverを停止して小さいbase、短い最大context、少ない同時requestを検討します。設定を変えた場合は同じ条件の比較ではなくなるため、変更値を記録します。

元へ戻す

検証serverをCtrl+Cで停止します。LoRAを使わないbaselineへ戻すには、同じbaseを--enable-loraと--lora-modulesなしで起動します。production設定や既存serverを直接置き換えていなければ、rollbackは検証processを止めるだけです。取得したartifactを削除する前に、再現に必要なrevisionとhashを記録します。

まとめ

vLLMのLoRA切り替えは、起動時にadapterを登録し、requestのmodelへその名前を指定するのが最短です。最初はstatic load、localhost、一adapterへ絞り、/v1/modelsと同一promptでbase／LoRAの経路を確認します。動的load、複数adapter、memory最適化は、基本経路とrollbackを確認してから分けて検証してください。

さらに深く理解する

同じテーマの玄人向け検証記事で、rank、同時adapter数、CPU保持数、request混在率を固定し、memoryとlatencyを測る方法、動的loadをtrusted境界へ閉じる設計を確認できます。

参考資料

vLLM LoRA Adapters公式文書（2026年5月18日更新、2026年8月13日確認）
vLLM v0.26.0 release（commit 568afb3、2026年7月27日公開）
vLLM Security公式文書（2026年8月13日確認）