llama.swap Modellwechsler: Schnellstart für OpenAI-kompatible lokale LLMs

Lokale LLMs ohne Änderung der Clients austauschen.

Inhaltsverzeichnis

Bald jonglieren Sie mit vLLM, llama.cpp und mehr – jeder Stack auf einem eigenen Port. Alles nachgeschaltete System erwartet dennoch eine einzige /v1-Basis-URL; andernfalls sortieren Sie ständig Ports, Profile und Einmal-Skripte neu. llama-swap ist der /v1-Proxy vor diesen Stacks.

llama-swap bietet eine OpenAI- und Anthropic-kompatible Frontdoor, mit einer YAML-Datei, die jeden model-Namen auf den Befehl abbildet, der den richtigen Upstream startet. Fordern Sie ein Modell an, und der Proxy startet es oder wechselt darauf; konfigurieren Sie TTLs und Gruppen, wenn VRAM knapp ist oder mehrere Modelle koexistieren müssen. Diese Anleitung behandelt Installationspfade, eine praktische config.yaml, die HTTP-Oberfläche und die Fehlermodi, die sich zeigen, sobald Streaming und Reverse-Proxy in das Bild kommen.

llama swap llm infographic Für einen breiteren Vergleich der LLM-Hosting-Optionen siehe LLM-Hosting 2026: Lokal, Self-Hosted & Cloud-Infrastruktur im Vergleich

Überblick über den llama-swap Modell-Switcher für OpenAI-kompatible lokale LLM-APIs

llama-swap ist ein leichtgewichtiger Proxy-Server, der um ein einfaches Betriebsmodell herum aufgebaut ist: eine Binärdatei, eine YAML-Konfigurationsdatei, keine Abhängigkeiten. Es ist in Go geschrieben, was bedeutet, dass es eine einzige statische Binärdatei neben dem Rest des Stacks gibt – keine Python-Laufzeit oder Desktop-App erforderlich. Es sitzt vor jedem OpenAI- und Anthropic-kompatiblen Upstream als Modell-Wechsel-Schicht.

Konzeptionell beantwortet dies eine sehr praktische Frage, die in lokalen LLM-Stacks aufkommt:

Wie wechsele ich Modelle mit einem OpenAI-kompatiblen Client?
Mit llama-swap nutzen Sie weiterhin normale /v1/...-Anfragen, ändern aber das angeforderte model. llama-swap liest diesen model-Wert, lädt die passende Serverkonfiguration und wenn der „falsche" Upstream läuft, wird er durch den richtigen ersetzt.

Einige Design-Details sind für produktionsähnliche Setups wichtig:

llama-swap ist MIT-lizenziert mit keiner Telemetrie – dennoch für jeden Host, der echte Prompts sieht, wert zu bestätigen.
Es ist für das On-Demand-Laden von Backends wie llama.cpp, vLLM, Whisper und stable-diffusion.cpp gebaut, nicht dafür, Sie an einen einzelnen Inferenz-Engine zu binden.
Standardmäßig (ohne spezielle Gruppierung) führt es ein Modell zur gleichen Zeit aus: Fordern Sie ein anderes model an, und es stoppt den aktuellen Upstream und startet den richtigen. Für mehr als ein Resident-Modell oder eine feinere Kontrolle über die Koexistenz konfigurieren Sie groups.

Hier ist das mentale Modell, das die meisten Entwickler hilfreich finden:

flowchart LR
  C[Ihre App oder SDK\nOpenAI-kompatibler Client] -->|/v1/chat/completions\nmodel = qwen-coder| LS[llama-swap Proxy\neinzelnes Endpunkt]
  LS -->|startet oder leitet zu| U1[Upstream Server A\nllama-server]
  LS -->|startet oder leitet zu| U2[Upstream Server B\nvLLM OpenAI Server]
  LS --> M[Management-Endpunkte\nlaufend, entladen, Ereignisse, Metriken]

Deshalb ist ein Modell-Switcher-Proxy auch anders als „nur ein Modell ausführen": Es ist Orchestrierung und Routing auf einem oder mehreren Inferenz-Servern.

llama-swap vs. Ollama vs. LM Studio vs. llama.cpp Server

Alle vier Optionen können Ihnen eine „lokale LLM-API" bieten, aber sie optimieren für unterschiedliche Workflows. Der schnellste Weg zur Auswahl ist, zu entscheiden, ob Sie eine Laufzeit (Modell-Download + Ausführung) oder einen Router/Proxy (Wechseln + Orchestrierung über Laufzeiten hinweg) wollen.

llama-swap
llama-swap konzentriert sich darauf, ein transparenter Proxy zu sein, der OpenAI-kompatible Endpunkte unterstützt (einschließlich /v1/chat/completions, /v1/completions, /v1/embeddings und /v1/models) und Anfragen basierend auf dem angeforderten Modell an den korrekten Upstream weiterleitet. Es bietet auch nicht-inferenzbezogene Betriebsendpunkte wie /running, /logs/stream und eine Web-Oberfläche unter /ui.

Ollama
Ollama stellt seine eigene HTTP-API zur Verfügung (POST /api/chat, POST /api/generate und das übliche lokale Standard auf Port 11434).
keep_alive steuert, wie lange ein Modell geladen bleibt, einschließlich 0 für sofortiges Entladen.
Es passt für Benutzer, die ein Modell ziehen und chatten wollen, mit minimalem Verkabelungsaufwand. llama-swap passt für modell-spezifische Befehle, gemischte Backends und eine OpenAI-geformte URL für jeden Client – die Orchestrierung von vLLM neben llama-server mit unterschiedlichen Flags pro Modell liegt außerhalb dessen, worauf Ollama abzielt.

LM Studio
LM Studio ist eine Desktop-App mit einem lokalen API-Server vom Developer-Tab (localhost oder LAN), einschließlich OpenAI-kompatibler und Anthropic-kompatibler Modi, sowie lms server start vom Terminal aus.
Es eignet sich für einen GUI-zentrierten Kreislauf: Modelle durchsuchen, klicken, testen. llama-swap eignet sich für eine server-ähnliche Rolle: YAML, Prozessüberwachung, gemischte Upstreams, keine Desktop-Sitzung.

llama.cpp Server
llama-server stellt /v1/completions, /v1/chat/completions, /v1/responses zur Verfügung, und das übliche Muster besteht darin, einen OpenAI-Client darüber auf base_url zu zeigen.
llama.cpp liefert auch einen Router-Modus: Führen Sie llama-server als Router aus, --models-dir, dann POST /models/load und POST /models/unload, um GGUF-Modelle zu jonglieren, ohne einen separaten Proxy. Für einen vollständigen Einrichtungsleitfaden siehe llama-server Router-Modus: Dynamischer Modellwechsel ohne Neustarts.
Wenn jedes Modell unter einem llama.cpp-Router sitzt, ist ein zusätzlicher Proxy oft unnötig. Wenn llama.cpp neben vLLM oder anderen OpenAI-geformten Servern sitzen muss, bietet llama-swap eine einzige /v1-Oberfläche und viele Prozesse dahinter.

Für ähnliche OpenAI-kompatible Hosting-Lösungen siehe LocalAI QuickStart: OpenAI-kompatible LLMs lokal ausführen oder SGLang QuickStart: LLMs über OpenAI-API installieren, konfigurieren und bereitstellen

llama-swap Modell-Switcher mit Docker, Homebrew, WinGet oder Binärdateien installieren

Linux, macOS und Windows sind alle First-Class: Docker, Homebrew, WinGet, GitHub-Binärdateien oder Build aus Quellen. Übliche Optionen: Docker auf headless-Servern, Homebrew oder WinGet auf Workstations, eigenständige Binärdateien, wenn der Installationsfußabdruck minimal bleiben soll.

Docker-Installation

Ziehen Sie ein Image, das Ihrer Hardware entspricht. Images verfolgen Upstreams eng (nächtliche Builds) und decken CUDA, Vulkan, Intel, MUSA und CPU ab – wählen Sie dasjenige, das Ihrer tatsächlichen Beschleunigung entspricht, nicht „latest" aus Gewohnheit.

# Beispiel 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

Bevorzugen Sie die nicht-root Image-Varianten, wann immer möglich: weniger zu bereuen, falls die Container-Grenze jemals falsch ist.

Homebrew-Installation

Auf macOS und Linux, verwenden Sie den Tap und installieren:

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

WinGet-Installation

Auf Windows:

winget install llama-swap
winget upgrade llama-swap

Vorgefertigte Binärdateien und Releases

GitHub Releases liefert Linux, macOS, Windows und FreeBSD Binärdateien, falls Sie keinen Paketmanager wollen.
Versionsnummern bewegen sich schnell (zum Beispiel v198, v197 Anfang 2026) – fixieren Sie eine Version in der Automatisierung, anstatt „was gestern da war" zu schwimmen.

llama-swap mit config.yaml für Modellwechsel, TTL und Gruppen konfigurieren

Alles in llama-swap ist konfigurationsgesteuert. Die minimal lebensfähige Konfiguration ist einfach ein models:-Dictionary und ein cmd für jedes Modell, das oft llama-server mit ${PORT} pro Modell substituiert startet.

Das Konfigurationssystem geht weit über „einen Prozess starten" hinaus, und einige Optionen sind früh wert zu verstehen, da sie direkte Antworten auf häufige FAQ-artige Probleme geben (Auto-Entladen, Sicherheit und Clients, die auf /v1/models angewiesen sind).

Globale Einstellungen, die Sie tatsächlich verwenden werden

healthCheckTimeout ist die Zeit, die llama-swap wartet, bis ein Modell nach dem Start gesund wird (Standard 120s, Minimum 15s). Für Multi-GB-Laden auf langsamen Festplatten erhöhen Sie dies, bevor Sie den Proxy beschuldigen.
globalTTL ist die Leerlaufsekunden vor Auto-Entladen; Standard 0 bedeutet „niemals entladen", es sei denn, Sie setzen es – wählen Sie explizit TTLs für alles außer einer Spielzeug-Einrichtung, damit VRAM nicht mit vergessenen Modellen gefüllt wird.
startPort seedet den ${PORT}-Makro (Standard 5800); die Zuweisung ist deterministisch nach alphabetischer Modell-ID, was eine Funktion ist, wenn Sie debuggen „wer welchen Port ergriffen hat", und ein Stolperstein, wenn Sie Modelle unvorsichtig umbenennen.
includeAliasesInList entscheidet, ob Aliase als separate Zeilen in /v1/models erscheinen; schalten Sie es ein, wenn Ihre UI nur aufgezählte Modelle anbietet.
apiKeys schließt alles ab, das von localhost aus erreichbar ist: Basic, Bearer oder x-api-key. llama-swap entfernt diese Header vor der Weiterleitung, damit Upstream-Logs weniger wahrscheinlich Client-Geheimnisse behalten.

Modell-spezifische Einstellungen, die Produktions-Ergonomie freischalten

Pro Modell ist cmd das einzige erforderliche Feld.
proxy standardmäßig auf http://localhost:${PORT} – das ist das Weiterleitungsziel für den Upstream dieses Modells.
checkEndpoint standardmäßig auf /health; setzen Sie "none", wenn das Backend keine Health-Route hat oder der Cold-Start länger dauert, als Sie warten möchten – lassen Sie keinen kaputten /health und wundern Sie sich nicht, warum nichts ready wird.
ttl: -1 erbt globalTTL, 0 entlädt nie, N > 0 entlädt nach N Sekunden Leerlauf – verwenden Sie pro-Modell-TTL, wenn ein Modell verweilen und ein anderes schnell verschwinden soll.
aliases und useModelName halten stabile clientseitige Namen, während sie Upstreams befriedigen, die eine spezifische Kennung erfordern.
cmdStop ist nicht optional für Container: mappen Sie es auf docker stop (oder Äquivalent); ohne es erhalten Sie POSIX SIGTERM / Windows taskkill gegen jede PID, die llama-swap gestartet hat – in Ordnung für eine bloße Binärdatei, falsch für einen Container-Namen.
concurrencyLimit begrenzt parallele Anfragen pro Modell mit HTTP 429 bei Überschreitung – setzen Sie es, wenn Sie Last abwerfen wollen, anstatt ewig zu warten.

groups decken Koexistenz (swap, exclusive) und Always-on-Modelle (persistent) ab. Hooks können beim Start vorladen; wenn Sie mehrere Modelle gleichzeitig ohne Gruppe vorladen, erwarten Sie, dass sie kämpfen – definieren Sie zuerst eine Gruppe, sodass das Vorladen damit übereinstimmt, wie Sie wollen, dass Modelle die GPU teilen.

Minimales config.yaml-Beispiel für llama.cpp und vLLM

Dieses Beispiel zielt darauf ab, „genug" zu sein, um Best-Practice-Schalter zu illustrieren: eine Standard-TTL, explizite Health-Checks, stabile Aliase und eine Gruppe, die ein kleines „Always-on"-Modell laufen lässt, während größere Chat-Modelle wechseln.

# config.yaml
healthCheckTimeout: 180
globalTTL: 900            # 15 Minuten Leerlauf dann entladen
includeAliasesInList: true
startPort: 5800

# Optional aber empfohlen für alles außer localhost-Entwicklung
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"
    # Verwendet Standards:
    # proxy: http://localhost:${PORT}
    # checkEndpoint: /health
    # ttl: -1 (erbt globalTTL)

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

  vllm-coder:
    # Illustratives Muster: einen containerisierten OpenAI-kompatiblen Server verwalten
    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                 # nie auto-entladen (z.B. auf GPU halten)

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

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

Keines davon ist dekorativ: cmd treibt den Prozess, proxy/checkEndpoint/ttl steuern Routing und Lebenszyklus, cmdStop ist das, was Docker-basierte Upstreams tatsächlich stoppt, und groups sind das, was „ein großes Modell zur gleichen Zeit" von „diese beiden Chat-Modelle können koexistieren, während der Embedding-Server fixiert bleibt" trennt.

Modelle via OpenAI-kompatibler Endpunkte ausführen und wechseln

Sobald llama-swap läuft, interagieren Sie damit wie mit jedem anderen OpenAI-kompatiblen Endpunkt. Die API-Oberfläche umfasst Kernendpunkte wie /v1/chat/completions, /v1/completions, /v1/embeddings und /v1/models, und llama-swap verwendet das angeforderte model, um zu entscheiden, welchen Upstream es ausführt und wohin es leitet.

Ein praktischer Quickstart-Flow:

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

# 2) Verfügbare Modelle entdecken
curl http://localhost:8080/v1/models

Modell-Liste ist eine First-Class-Management-Funktion und enthält Verhalten wie Sortieren nach ID, Ausschließen von unlisted-Modellen und optionales Inkludieren von Aliases.

# 3) Eine Chat-Vervollständigungsanfrage für ein bestimmtes Modell stellen
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":"Schreiben Sie eine TypeScript-Funktion, die fetch mit Backoff wiederholt."}]
  }'

Wenn Sie jetzt den Aufruf mit "model": "llama-chat" wiederholen, wird llama-swap Upstream-Prozesse wechseln (es sei denn, Ihre Gruppenkonfiguration erlaubt Koexistenz), da es das angeforderte Modell aus der Anfrage extrahiert und die passende Serverkonfiguration lädt.

Wenn Sie ein SDK verwenden, zeigen Sie den Client auf http://localhost:8080/v1 – derselbe Trick wie das Zielen der OpenAI Python-Bibliothek auf llama-server, außer dass die stabile URL jetzt llama-swap ist und das model-Feld den Upstream auswählt.

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": "Erklären Sie den Unterschied zwischen Mutexes und Semaphore."}],
)
print(resp.choices[0].message.content)

Um ein Modell zu warming (Aufwärmen) vor der ersten echten Anfrage (um Cold-Start-Latenz zu verbergen), verwenden Sie /upstream/<model> – es lädt automatisch falls nötig und leitet direkt an diesen Upstream weiter. Geradliniger Weg, um sicherzustellen, dass Gewichte resident sind, bevor ein Benchmark oder skriptgestützter Test durchgeführt wird.

llama-swap via Management-API-Endpunkte und SSE-Ereignisse steuern und überwachen

llama-swap ist nicht nur „ein Proxy"; es stellt auch operative Kontrollendpunkte bereit, die es ermöglichen, Werkzeug rund um den Modell-Lebenszyklus und Observability aufzubauen.

Prüfen, was läuft
GET /running gibt den Laufzeitstatus für geladene Modelle zurück, einschließlich Statuswerten wie ready, starting, stopping, stopped und shutdown.

curl http://localhost:8080/running

Modelle entladen, um VRAM freizugeben
Um alles sofort zu entladen, verwenden Sie den API-versionierten Endpunkt POST /api/models/unload. Um ein einzelnes Modell (nach ID oder Alias) zu entladen, verwenden Sie POST /api/models/unload/<model>. Ein veraltetes GET /unload existiert für Rückwärtskompatibilität.

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

# ein Modell entladen
curl -X POST http://localhost:8080/api/models/unload/qwen-coder

Verwenden Sie diese Endpunkte, wenn VRAM jetzt jetzt benötigt wird, anstatt auf TTL zu warten – Benchmarks, schnelle Modellwechsel oder nach dem Laden eines viel größeren Checkpoints als beabsichtigt.

Live-Ereignisse via SSE streamen
GET /api/events etabliert einen Server-Sent-Events-Stream und ist für Echtzeit-Updates konzipiert, die Modellstatusänderungen, Logs, Metriken und in-flight-Anfrageanzahlen enthalten.

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

SSE und Token-Streaming brechen, wenn irgendeine Zwischenbox puffert – deaktivieren Sie Pufferung auf nginx (oder Ihrem Äquivalent) für /api/events und /v1/chat/completions. llama-swap setzt X-Accel-Buffering: no auf SSE; deaktivieren Sie die Pufferung auch im Proxy – Header sind kein Ersatz für eine korrekte Proxy-Konfiguration.

Metriken und Anfrage-Aufzeichnungen
GET /api/metrics gibt Token-Nutzungs-Metriken zurück, mit im-Speicher-Beibehaltung gesteuert durch metricsMaxInMemory (Standard 1000).
GET /api/captures/<id> kann vollständige Anfrage/Antwort-Aufzeichnungen abrufen, aber nur wenn captureBuffer > 0 konfiguriert ist.

Logs und die Web-Oberfläche

llama-swap stellt /ui für eine Weboberfläche bereit und operative Log-Endpunkte wie /logs und /logs/stream für Echtzeit-Überwachung.

llama-swap web UI for switching models

Wenn Sie apiKeys aktivieren, gehen Sie von Verteidigung in der Tiefe aus: /health und Teile von /ui bleiben ohne Schlüssel erreichbar – in Ordnung für lokale Vertrauensgrenzen, nicht in Ordnung, wenn der Host in einem geteilten Netzwerk ist. Stellen Sie llama-swap hinter etwas, das Ihre echte Politik erzwingt; die integrierte Auth dient dazu, zufällige Clients ehrlich zu halten, nicht für eine öffentliche Multi-Tenant-API.

Fehlerbehebung bei llama-swap Modellwechseln in der Produktion

Die meisten llama-swap-Probleme fallen in eine kleine Menge operativer Kategorien: Streaming durch einen Reverse-Proxy, Health-Checks während Cold-Starts, Ports und Prozess-Lebenszyklus sowie Authentifizierung.

Streaming bricht hinter nginx oder einem anderen Reverse-Proxy
nginx puffert Ihre SSE und gestreamten Vervollständigungen gerne weg. Deaktivieren Sie proxy_buffering (und proxy_cache) für /api/events und /v1/chat/completions. llama-swap emittiert X-Accel-Buffering: no auf SSE, was hilft – reparieren Sie den Proxy trotzdem.

Ein Modell wird nie bereit
Standardmäßig ist pro-Modell checkEndpoint /health und muss HTTP 200 zurückgeben, damit der Prozess als bereit gilt. Sie können checkEndpoint auf einen anderen Pfad oder auf "none" setzen, um Health-Checks vollständig zu deaktivieren.
Wenn große Modelle länger zum Laden benötigen, erhöhen Sie healthCheckTimeout (Standard 120s), oder verwenden Sie maßgeschneiderte Health-Checks für Ihren spezifischen Upstream.

Wechseln von Modellen lässt einen alten Container laufen
Wenn der Upstream Docker oder Podman ist, setzen Sie cmdStop – andernfalls stoppt llama-swap den Wrapper-Prozess, während der Container im Hintergrund VRAM frisst.

Ich bekomme 401-Antworten nach Aktivierung der Sicherheit
Wenn apiKeys konfiguriert ist, erfordert llama-swap einen gültigen Schlüssel und akzeptiert drei Methoden (Basic-Auth, Bearer-Token, x-api-key). Es entfernt auch Authentifizierungs-Header vor der Weiterleitung an den Upstream.

Ich bekomme 429 Too Many Requests
concurrencyLimit gibt 429 zurück, wenn überschritten – per Design. Erhöhen Sie die Obergrenze, wenn Sie sie unterprovisioniert haben, oder senken Sie die Grenze, wenn Sie nicht drosseln wollten.

Port-Konflikte oder seltsame Routing-Probleme
Vermeiden Sie hartkodierte Ports in cmd; verwenden Sie ${PORT} und bewegen Sie startPort, wenn 5800+ mit etwas anderem kollidiert. Denken Sie daran, dass Ports in alphabetischer Reihenfolge nach Modell-ID zugewiesen werden – benennen Sie ein Modell um, und die Port-Zuordnung verschiebt sich.

Operative Debugging-Checkliste
/running für die Wahrheit, /logs/stream, wenn der Start undurchsichtig ist, POST /api/models/unload, wenn VRAM jetzt zurück benötigt wird. Diese drei decken die meisten „warum ist die GPU voll"-Sitzungen ab.

Abonnieren

Neue Beiträge zu Systemen, Infrastruktur und KI-Engineering.