OpenAI互換ローカルLLM向け llama.swapモデル切り替えクイックスタート

すぐにvLLM、llama.cpp、そしてその他の多数のスタックを回す必要が出てきます。それぞれのスタックは独自のポートを使います。しかし、下流のすべてのアプリケーションは、/v1 ベースの単一のURLを期待しています。そうでなければ、ポート、プロファイル、使い捨てのスクリプトの入れ替えを繰り返すことになります。llama-swap は、これらのスタックの前段にある /v1 プロキシです。

llama-swap は、OpenAIおよびAnthropic互換の単一のフロントエンドを提供し、YAMLファイルを使用して各 model 名を、適切なアップストリームを起動するコマンドにマッピングします。モデルをリクエストすると、プロキシはそれを起動するか、切り替えます。VRAMが厳しい場合や、複数のモデルを共存させる必要がある場合は、TTLやグループを設定します。このガイドでは、インストール方法、実用的な config.yaml、HTTPインターフェース、そしてストリーミングやリバースプロキシが関わってくる際に生じる障害モードについて説明します。

LLMホスティングオプションのより広範な比較については、2026年のLLMホスティング: ローカル、セルフホスト、クラウドインフラの比較 をご覧ください。

OpenAI互換ローカルLLM APIのためのllama-swapモデルスイッチャー概要

llama-swapは軽量なプロキシサーバーです 。シンプルな運用モデルを前提として構築されています：バイナリは1つ、YAML設定ファイルは1つ、依存関係なし。Goで書かれているため、スタックの残りの部分と同様に単一の静的バイナリとして機能し、Pythonランタイムやデスクトップアプリは不要です。これは、あらゆるOpenAIおよびAnthropic互換のアップストリームの前段に配置されるモデル切り替えレイヤーです。

概念的には、これはローカルLLMスタックで頻繁に生じる非常に実用的な質問に答えるものです：

OpenAI互換クライアントでモデルを切り替えるにはどうすればいいか？
llama-swapを使用すれば、通常の /v1/... リクエストを使い続けられますが、リクエストする model を変更します。llama-swapはその model 値を読み取り、対応するサーバー設定をロードし、「間違った」アップストリームが実行されている場合は、正しいものに置き換えます。

本番環境に近いセットアップにとって重要ないくつかの設計詳細があります：

llama-swapはMITライセンスでテレメトリなしです——実際のプロンプトが通るホストでは、確認する価値があります。
これは、llama.cpp、vLLM、Whisper、stable-diffusion.cpp などのバックエンドのオンデマンド読み込みのために構築されており、単一の推論エンジンに固定されるものではありません。
デフォルトでは（特別なグループ化なし）、1つモデルずつ実行します：別の model をリクエストすると、現在のアップストリームを停止し、正しいものを起動します。1つ以上の常駐モデル、または共存に関するより細かい制御が必要であれば、groups を設定してください。

ほとんどの開発者が役立つと感じるメンタルモデルは以下の通りです：

これが、モデルスイッチャープロキシ が「モデルを実行するだけ」とは異なる理由です。これは、1つ以上の推論サーバーの上位にあるオーケストレーションとルーティングだからです。

llama-swap vs Ollama vs LM Studio vs llama.cpp サーバー

4つの選択肢すべてが「ローカルLLM API」を提供できますが、最適化されるワークフローが異なります。選択する最も速い方法は、ランタイム（モデルのダウンロード＋実行）なのか、ルーター/プロキシ（ランタイム間の切り替え＋オーケストレーション）なのかを決定することです。

llama-swap
llama-swapは、OpenAI互換エンドポイント（/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/modelsを含む）をサポートし、リクエストされたモデルに基づいて正しいアップストリームにリクエストをルーティングする透明なプロキシであることを重視しています。また、/running、/logs/stream、および /ui のWeb UIなど、推論以外の運用エンドポイントも提供します。

Ollama
Ollamaは独自のHTTP API（POST /api/chat、POST /api/generate、およびポート 11434 での標準的なローカルデフォルト）を公開します。
keep_alive は、モデルがロードされた状態を維持する時間を制御し、0 を設定するとすぐにアンロードします。
これは、最小限の設定でモデルを取得してチャットしたいユーザーに適しています。llama-swap は、モデルごとのコマンド、混合バックエンド、そしてすべてのクライアント向けの単一のOpenAI形状URLに適しています——vLLMを llama-server の隣に配置し、モデルごとに異なるフラグを付けるオーケストレーションは、Ollamaが対象とする範囲外です。

LM Studio
LM Studioは、ローカルAPIサーバーを備えたデスクトップアプリです。Developerタブ（localhostまたはLAN）から利用可能で、OpenAI互換およびAnthropic互換モードに加えて、ターミナルからの lms server start もサポートします。
これはGUIファーストのループに適しています：モデルをブラウジングし、クリックし、テストする。llama-swap はサーバースタイルの役割に適しています：YAML、プロセス監督、混合アップストリーム、デスクトップセッションなし。

llama.cpp サーバー
llama-server は /v1/completions、/v1/chat/completions、/v1/responses を公開し、通常は base_url を介してOpenAIクライアントをそこに指向するパターンを取ります。そのサーバーのインストールと、実際に尊重されるフラグについては、llama.cpp クイックスタート を参照してください。
llama.cppはまたルーターモードも同梱しています：llama-server をルーターとして実行し、--models-dir を指定してから、POST /models/load と POST /models/unload を使用して、個別のプロキシなしでGGUFモデルを切り替えます。完全なセットアップガイドについては、llama-server ルーターモード: 再起動なしで動的モデル切り替え をご覧ください。
すべてのモデルが1つの llama.cpp ルーターの下にある場合、追加のプロキシは多くの場合不要です。llama.cppがvLLMやその他のOpenAI形状のサーバーの隣に置かれる必要がある場合、llama-swapは単一の /v1 表面と、その背後にある多数のプロセスを提供します。

同様のOpenAI互換ホスティングソリューションについては、LocalAI クイックスタート: ローカルでOpenAI互換LLMを実行する または SGLang クイックスタート: OpenAI API経由でLLMのインストール、設定、提供 をご覧ください。

Docker、Homebrew、WinGet、またはバイナリでllama-swapモデルスイッチャーをインストール

Linux、macOS、Windowsはすべて第一級市民です：Docker、Homebrew、WinGet、GitHubバイナリ、またはソースからビルド。一般的な選択肢：ヘッドレスサーバーではDocker、ワークステーションではHomebrewまたはWinGet、インストール足痕を最小限に保つべき場合はスタンドアロンバイナリ。

Docker インストール

ハードウェアに適合するイメージを取得します。イメージはアップストリームに密接に追従します（nightlyビルド）し、CUDA、Vulkan、Intel、MUSA、CPUをカバーします——「latest」を習慣として選ぶのではなく、実際にどのようにアクセラレーションするかに適合するものを選択してください。

# Example platform pulls
docker pull ghcr.io/mostlygeek/llama-swap:cuda
docker pull ghcr.io/mostlygeek/llama-swap:vulkan
docker pull ghcr.io/mostlygeek/llama-swap:intel
docker pull ghcr.io/mostlygeek/llama-swap:musa
docker pull ghcr.io/mostlygeek/llama-swap:cpu

可能であれば非ルートイメージのバリアントを優先してください：コンテナの境界が誤っていた場合、後悔するものが少なくなります。

Homebrew インストール

macOSとLinuxでは、タップを追加してインストールします：

brew tap mostlygeek/llama-swap
brew install llama-swap
llama-swap --config path/to/config.yaml --listen localhost:8080

WinGet インストール

Windowsでは：

winget install llama-swap
winget upgrade llama-swap

プリビルドバイナリとリリース

パッケージマネージャーを使いたくない場合は、GitHub ReleasesがLinux、macOS、Windows、FreeBSDバイナリを提供しています。
リリース番号は急速に変わります（例えば v198、v197 は2026年初頭頃）——自動化では「昨日そこにあったもの」をフロートさせるのではなく、バージョンを固定してください。

config.yamlでllama-swapを設定してモデルスワップ、TTL、グループを使用

llama-swapのすべては設定駆動です。最小限の動作する設定は、単に models: 辞書と、各モデルに対する cmd で、通常は ${PORT} がモデルごとに置換されて llama-server を起動します。

設定システムは単に「プロセスを開始する」ことをはるかに超えており、いくつかのオプションは、一般的なFAQスタイルの問題（自動アンロード、セキュリティ、および /v1/models に依存するクライアント）に直接答えるため、早期に理解する価値があります。

実際に使用するグローバル設定

healthCheckTimeout は、llama-swapがモデルがヘルス状態になるまで待機する時間です（デフォルト 120秒、最小 15秒）。低速ディスクでの数GBのロードの場合、プロキシを責める前にこれを引き上げてください。
globalTTL は、自動アンロードまでのアイドル秒数です；デフォルトの 0 は設定しない限り「アンロードしない」を意味します——VRAMが忘れられたモデルで埋まらないように、玩具のようなセットアップを超えれば、TTLを明示的に選択してください。
startPort は ${PORT} マクロの種です（デフォルト 5800）；割り当てはモデルIDのアルファベット順で決定的であり、「どのポートを誰が取得したか」をデバッグする際には機能しますが、モデルを無神経に名前変更する足かせにもなります。
includeAliasesInList は、エイリアスが /v1/models で個別の行として表示されるかどうかを決定します；UIが列挙されたモデルのみを提供する場合、これをオンにしてください。
apiKeys はlocalhostから到達可能なものをゲートします：Basic、Bearer、または x-api-key。llama-swapは転送前にこれらのヘッダーを除去するため、アップストリームのログがクライアントのシークレットを保持する可能性が低くなります。

本番環境のエルゴノミクスを解放するモデルレベルの設定

モデルごとに、 cmd は唯一の必須フィールドです。
proxy はデフォルトで http://localhost:${PORT} です——それがそのモデルのアップストリームへの転送先です。
checkEndpoint はデフォルトで /health です；バックエンドにヘルスルーティングがない場合、またはコールドスタートが許容できる待機時間を超える場合は "none" に設定してください——壊れた /health を放置して、なぜ何も ready に達さないのかと疑問を抱くのは避けてください。
ttl： -1 は globalTTL を継承、 0 はアンロードなし、 N > 0 は N秒アイドル後にアンロード——1つのモデルは長く残し、もう1つのモデルはすぐに消す必要がある場合、モデルごとのTTLを使用してください。
aliases と useModelName は、クライアント向けの安定した名前を維持しながら、特定の識別子を要求するアップストリームの要件を満たします。
cmdStop はコンテナに対しては省略不可です：docker stop（または同等のもの）にマッピングしてください；これを設定しないと、llama-swapが起動したPIDに対してPOSIX SIGTERM / Windows taskkillが発行されます——ネイティブバイナリでは問題ありませんが、コンテナ名では誤りです。
concurrencyLimit は、モデルごとの並行リクエスト数を上限とし、超過時にHTTP 429を返します——永久にキューを溜めるよりも負荷を捨てる方が望ましい場合に設定してください。

groups は共存（ swap、 exclusive ）と常駐モデル（ persistent ）をカバーします。フックは起動時にプリロードできます；グループなしで複数のモデルを同時にプリロードすると、彼らが競合すると期待してください——モデルがGPUをどのように共有するか望むようにプリロードが対応するように、まずグループを定義してください。

llama.cpp と vLLM 用の最小構成 config.yaml 例

この例は、ベストプラクティスのノブを示すために「丁度良い」ことを目指しています：デフォルトのTTL、明示的なヘルスチェック、安定したエイリアス、そして大きなチャットモデルがスワップされる間、小さな「常駐」モデルを実行し続けるグループ。

# config.yaml
healthCheckTimeout: 180
globalTTL: 900            # 15 minutes idle then unload
includeAliasesInList: true
startPort: 5800

# Optional but recommended for anything beyond localhost development
apiKeys:
  - "${env.LLAMASWAP_API_KEY}"

models:
  llama-chat:
    cmd: |
      llama-server --port ${PORT} --model /models/llama-chat.gguf
      --ctx-size 8192
    aliases:
      - "llama-chat-latest"
    # Uses defaults:
    # proxy: http://localhost:${PORT}
    # checkEndpoint: /health
    # ttl: -1 (inherit globalTTL)

  qwen-coder:
    cmd: |
      llama-server --port ${PORT} --model /models/qwen-coder.gguf
      --ctx-size 8192
    aliases:
      - "qwen-coder-latest"

  vllm-coder:
    # Illustrative pattern: manage a containerised OpenAI-compatible server
    proxy: "http://127.0.0.1:${PORT}"
    cmd: |
      docker run --name ${MODEL_ID} --init --rm -p ${PORT}:8000 vllm/vllm-openai:latest
    cmdStop: docker stop ${MODEL_ID}
    checkEndpoint: "none"
    ttl: 0                 # never auto-unload (e.g. keep on GPU)

groups:
  chat-models:
    swap: true
    exclusive: true
    members: ["llama-chat", "qwen-coder"]

  always-on:
    persistent: true
    swap: false
    exclusive: false
    members: ["vllm-coder"]

これらはどれも装飾的なものではありません： cmd がプロセスを駆動し、 proxy / checkEndpoint / ttl がルーティングとライフサイクルを制御し、 cmdStop がDockerベースのアップストリームを実際に停止させるものになり、 groups は「1つの大きなモデルずつ」を「これら2つのチャットモデルは共存でき、埋め込みサーバーは固定される」と分離するものです。

OpenAI互換エンドポイント経由でモデルを実行およびスワップ

llama-swapが実行されると、他のOpenAI互換エンドポイントと同様に操作します。APIサーフェスは /v1/chat/completions、/v1/completions、/v1/embeddings、/v1/models などのコアエンドポイントを含み、llama-swapはリクエストされた model を使用して、どのアップストリームを実行し、ルーティングするかを決定します。

実用的なクイックスタートフロー：

# 1) Start llama-swap
llama-swap --config ./config.yaml --listen localhost:8080

# 2) Discover available models
curl http://localhost:8080/v1/models

モデルの一覧表示は第一級の管理機能であり、IDによるソート、 unlisted モデルの除外、オプションのエイリアスを含めることなど、動作を含みます。

# 3) Make a chat completion request for a specific model
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${LLAMASWAP_API_KEY}" \
  -d '{
    "model": "qwen-coder",
    "messages": [{"role":"user","content":"Write a TypeScript function that retries fetch with backoff."}]
  }'

次に、 "model": "llama-chat" で同じ呼び出しを繰り返すと、llama-swapはアップストリームプロセスをスワップします（グループ設定が共存を許可しない限り）。これは、リクエストからリクエストされたモデルを抽出し、適切なサーバー設定をロードするからです。

SDKを使用している場合、クライアントを http://localhost:8080/v1 に指向します——OpenAI Pythonライブラリを llama-server に向けるのと同じトリックですが、安定したURLが今ではllama-swapとなり、 model フィールドがアップストリームを選ぶことになります。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-your-llamaswap-key"
)

resp = client.chat.completions.create(
    model="qwen-coder",
    messages=[{"role": "user", "content": "Explain the difference between mutexes and semaphores."}],
)
print(resp.choices[0].message.content)

最初の実際のリクエスト前にモデルをウォームアップし（コールドスタートのレイテンシーを隠す）には、 /upstream/<model> を使用します——必要であれば自動読み込みし、そのアップストリームに直接転送します。ベンチマークやスクリプト化されたテストの前に、重みが常駐することを保証する直截的な方法です。

マネージメントAPIエンドポイントとSSEイベントでllama-swapを制御および監視

llama-swapは単なる「プロキシ」ではなく、モデルライフサイクルと可観測性周りにツールを構築するための運用制御エンドポイントを公開します。

実行中のものを確認
GET /running は、ロードされたモデルのランタイム状態を返し、 ready、 starting、 stopping、 stopped、 shutdown などの状態値を含みます。

curl http://localhost:8080/running

VRAMを解放するためにモデルをアンロード
すべてをすぐにアンロードするには、APIバージョン付きエンドポイント POST /api/models/unload を使用します。単一のモデルをアンロードするには（IDまたはエイリアスで）、 POST /api/models/unload/<model> を使用します。後方互換性のためにレガシーな GET /unload が存在します。

# unload all
curl -X POST http://localhost:8080/api/models/unload

# unload one model
curl -X POST http://localhost:8080/api/models/unload/qwen-coder

これらのエンドポイントは、TTLを待つ代わりにVRAMを今すぐ必要とする場合に使用します——ベンチマーク、クイックなモデル切り替え、または意図せずはるかに大きなチェックポイントをロードした後など。

SSEでライブイベントをストリーミング
GET /api/events はServer-Sent Eventsストリームを確立し、モデル状態の変更、ログ、メトリクス、進行中のリクエスト数を含むリアルタイム更新のために設計されています。

curl -N http://localhost:8080/api/events

SSEとトークンストリーミングは、中間ボックスがバッファリングすると壊れます—— /api/events と /v1/chat/completions に対してnginx（または同等物）でのバッファリングを無効にしてください。llama-swapはSSEに X-Accel-Buffering: no を設定しますが、プロキシでもバッファリングを無効にしてください——ヘッダーは正しいプロキシ設定の代わりにはなりません。

メトリクスとリクエストキャプチャ
GET /api/metrics はトークン使用量メトリクスを返し、メモリ内保留は metricsMaxInMemory （デフォルト1000）で制御されます。
GET /api/captures/<id> は完全なリクエスト/レスポンスキャプチャを取得できますが、 captureBuffer > 0 が設定されている場合のみです。

ログとWeb UI

llama-swapはWebインターフェースのために /ui を公開し、リアルタイム監視のための /logs や /logs/stream などの運用ログエンドポイントを公開します。

apiKeys を有効にした場合、多層防御を前提としてください： /health と /ui の一部はキーなしでも到達可能です——ローカルの信頼境界では問題ありませんが、共有ネットワーク上のホストでは問題があります。llama-swapを、実際のポリシーを強制するものの後ろに配置してください；組み込みの認証は、カジュアルなクライアントを誠実に保つためのものです、パブリックなマルチテナントAPIのためのものではありません。

本番環境でのllama-swapモデル切り替えのトラブルシューティング

llama-swapの問題の大部分は、リバースプロキシを介したストリーミング、コールドスタート時のヘルスチェック、ポートとプロセスライフサイクル、認証という小さな運用カテゴリに収まります。

nginxや他のリバースプロキシの背後でストリーミングが壊れる
nginxは喜んであなたのSSEとストリーミング補完をバッファリングしてしまいます。 /api/events と /v1/chat/completions に対して proxy_buffering （および proxy_cache ）を無効にしてください。llama-swapはSSEに X-Accel-Buffering: no を出力しますが、これは助けになります——それでもプロキシを修正してください。

モデルがreadyにならない
デフォルトでは、モデルごとの checkEndpoint は /health で、プロセスがreadyとみなされるためにはHTTP 200を返す必要があります。 checkEndpoint を別のパスまたは "none" に設定して、ヘルスチェックを完全に無効にできます。
大きなモデルの読み込みに時間がかかる場合、 healthCheckTimeout を増加させる（デフォルト120秒）、または特定のアップストリームに合わせてカスタマイズされたヘルスチェックを使用してください。

モデル切り替え後に古いコンテナが実行されたままになる
アップストリームがDockerまたはPodmanの場合、** cmdStop を設定してください** ——そうしないと、llama-swapはラッパープロセスを停止しますが、コンテナはバックグラウンドでVRAMを食い続けます。

セキュリティを有効にした後に401レスポンスが返る
apiKeys が設定されている場合、llama-swapは有効なキーを要求し、3つの方法（Basic認証、Bearerトークン、 x-api-key ）を受け入れます。また、アップストリームへ転送前に認証ヘッダーを除去します。

429 Too Many Requests が返る
concurrencyLimit は超過時に429を返します——設計通りです。設定が低すぎた場合は上限を引き上げ、スロットリングを意図していない場合は制限を下げてください。

ポート競合や奇妙なルーティング問題
cmd 内でハードコードされたポートを避け、 ${PORT} を使用し、 5800+ が他のものと衝突する場合は startPort を移動してください。ポートはモデルIDのアルファベット順で割り当てられることを覚えておいてください——モデルの名前を変更すると、ポートマッピングがシフトします。

運用デバッグチェックリスト
真実のために /running、起動が不透明なときに /logs/stream、VRAMを今すぐ必要とするときに POST /api/models/unload 。この3点セットが、ほとんどの「なぜGPUがいっぱいなのか」セッションをカバーします。