llama.swap Modell-Switcher Schnellstart für OpenAI-kompatible lokale LLMs
Hot-Swap lokaler LLMs ohne Änderung der Clients.
In Kürze jonglieren Sie mit vLLM, llama.cpp und mehr – jede Stack auf einem eigenen Port. Alles nachgeschaltete System erwartet dennoch eine einzige /v1-Basis-URL; sonst müssen Sie ständig Ports, Profile und Einweg-Skripte verwalten. 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 dem Befehl zuordnet, der den richtigen Upstream startet. Fordern Sie ein Modell an, und der Proxy startet oder wechselt zu ihm; konfigurieren Sie TTLs und Gruppen, wenn VRAM knapp ist oder mehrere Modelle koexistieren müssen. Dieser Leitfaden behandelt Installationspfade, eine praktische config.yaml, die HTTP-Oberfläche und die Fehlermodi, die auftreten, sobald Streaming und Reverse-Proxying ins Spiel kommen.
Für einen breiteren Vergleich von LLM-Hosting-Optionen siehe LLM-Hosting in 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 leichtgewichtiges Proxy-Server um ein einfaches Betriebsmodell herum aufgebaut: ein Binary, eine YAML-Konfigurationsdatei, keine Abhängigkeiten. Es ist in Go geschrieben, was bedeutet: ein einzelnes statisches Binary neben dem Rest des Stacks – keine Python-Laufzeit oder Desktop-App erforderlich. Es positioniert sich vor jedem OpenAI- und Anthropic-kompatiblen Upstream als Modell-Wechsel-Schicht.
Konzeptionell beantwortet dies eine sehr praktische Frage, die bei lokalen LLM-Stacks auftaucht:
Wie wechsele ich Modelle mit einem OpenAI-kompatiblen Client?
Mit llama-swap verwenden 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, tauscht es ihn gegen den korrekten aus.
Ein paar Design-Details sind für produktionsnahe 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 bedarfsgerechte Laden von Backends wie llama.cpp, vLLM, Whisper und stable-diffusion.cpp gebaut, nicht, um Sie an einen einzigen Inferenz-Engine zu binden.
Standardmäßig (ohne spezielle Gruppierung) läuft es ein Modell zur Zeit: Fordern Sie ein anderes model an, und es stoppt den aktuellen Upstream und startet den richtigen. Für mehr als ein residente Modell oder eine feinere Kontrolle über die Koexistenz konfigurieren Sie groups.
Hier ist das mentale Modell, das die meisten Entwickler nützlich 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 um zu| U1[Upstream Server A\nllama-server]
LS -->|startet oder leitet um zu| U2[Upstream Server B\nvLLM OpenAI Server]
LS --> M[Management-Endpunkte\nlaufend, entladen, Ereignisse, Metriken]
Das ist auch der Grund, warum ein Modell-Switcher-Proxy sich von „einfach ein Modell laufen lassen" unterscheidet: Es ist Orchestrierung und Routing über 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 Arbeitsabläufe. Der schnellste Weg zur Entscheidung ist zu bestimmen, ob Sie eine Laufzeit (Modell-Download + Ausführung) oder einen Router/Proxy (Wechsel + 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 zum korrekten Upstream weiterleitet. Es bietet auch nicht-inferenzbezogene Betriebsendpunkte wie /running, /logs/stream und eine Web-Oberfläche unter /ui.
Ollama
Ollama bietet seine eigene HTTP-API an (POST /api/chat, POST /api/generate und den üblichen lokalen Standard auf Port 11434).
keep_alive steuert, wie lange ein Modell geladen bleibt, inklusive 0 für sofortiges Entladen.
Es passt für Nutzer, die ein Modell ziehen und chatten wollen mit minimalem Aufwand. llama-swap passt für modell-spezifische Befehle, gemischte Backends und eine einzige OpenAI-gestaltete URL für jeden Client – das Orchestrieren von vLLM neben llama-server mit unterschiedlichen Flags pro Modell liegt außerhalb des Ziels von Ollama.
LM Studio
LM Studio ist eine Desktop-App mit einem lokalen API-Server aus dem Developer Reiter (localhost oder LAN), inklusive OpenAI-kompatibler und Anthropic-kompatibler Modi, plus lms server start aus der Terminal.
Es passt für einen GUI-first Zyklus: Modelle durchsuchen, klicken, testen. llama-swap passt für eine Server-artige Rolle: YAML, Prozessüberwachung, gemischte Upstreams, keine Desktop-Sitzung.
llama.cpp server
llama-server bietet /v1/completions, /v1/chat/completions, /v1/responses an, und das übliche Muster ist, einen OpenAI-Client darauf via base_url zu zeigen.
llama.cpp liefert auch einen Router-Modus mit: Starten Sie llama-server als Router, --models-dir, dann POST /models/load und POST /models/unload, um GGUF-Modelle ohne separaten Proxy zu managen.
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-gestalteten Servern stehen 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 betreiben oder SGLang QuickStart: Installieren, Konfigurieren und Bedienen von LLMs über OpenAI API.
llama-swap Modell-Switcher mit Docker, Homebrew, WinGet oder Binaries installieren
Linux, macOS und Windows sind alle First-Class: Docker, Homebrew, WinGet, GitHub Binaries oder Build from Source. Übliche Wahl: Docker auf headless Servern, Homebrew oder WinGet auf Workstations, standalone Binaries, wenn der Installations-Fuß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 Plattform-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, wenn 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
Vor-kompilierte Binaries und Releases
GitHub Releases liefert Linux, macOS, Windows und FreeBSD Binaries, wenn Sie keinen Paketmanager wollen.
Release-Nummern bewegen sich schnell (zum Beispiel v198, v197 um Anfang 2026) – fixieren Sie eine Version in der Automatisierung, statt „was gestern da war" zu schweben.
llama-swap mit config.yaml für Modell-Wechsel, TTL und Gruppen konfigurieren
Alles in llama-swap ist konfigurationsgetrieben. Die minimal lebensfähige Konfiguration ist einfach ein models:-Dictionary und ein cmd für jedes Modell, oft das Starten von llama-server mit ${PORT} pro Modell substituiert.
Das Konfigurationssystem geht viel weiter als nur „einen Prozess starten", und ein paar Optionen sind früh wert, verstanden zu werden, da sie direkt häufige FAQ-artige Probleme beantworten (Auto-Entladen, Sicherheit und Clients, die auf /v1/models angewiesen sind).
Globale Einstellungen, die Sie tatsächlich verwenden werden
healthCheckTimeout ist, wie lange llama-swap wartet, bis ein Modell nach dem Start gesund ist (Standard 120s, Minimum 15s). Für Multi-GB-Laden auf langsamen Festplatten, erhöhen Sie dies, bevor Sie den Proxy beschuldigen.
globalTTL sind inaktive Sekunden vor Auto-Entladen; Standard 0 bedeutet „niemals entladen", es sei denn, Sie setzen es – wählen Sie explizit TTLs für alles außer einem Spielzeug-Setup, damit VRAM nicht mit vergessenen Modellen gefüllt wird.
startPort sämt das ${PORT}-Makro (Standard 5800); Zuweisung ist deterministisch nach alphabetischer Modell-ID, was eine Funktion ist, wenn Sie debuggen „wer welchen Port gekapert hat" und ein Stolperfalle, wenn Sie Modelle unvorsichtig umbenennen.
includeAliasesInList entscheidet, ob Aliase als separate Zeilen in /v1/models erscheinen; schalten Sie es ein, wenn Ihre UI nur modellierte Modelle anbietet.
apiKeys schließt alles ab, das außerhalb von localhost erreichbar ist: Basic, Bearer oder x-api-key. llama-swap entfernt diese Header vor dem Weiterleiten, 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 es auf "none", wenn das Backend keine Health-Route hat oder der Kaltstart länger dauert, als Sie warten wollen – lassen Sie nicht einen kaputten /health und wundern Sie sich, warum nichts ready erreicht.
ttl: -1 erbt globalTTL, 0 entlädt nie, N > 0 entlädt nach N Sekunden Inaktivität – verwenden Sie pro-Modell-TTL, wenn ein Modell verweilen soll und ein anderes schnell verschwinden soll.
aliases und useModelName halten stabile client-seitige Namen, während sie Upstreams erfüllen, die einen spezifischen Identifier benötigen.
cmdStop ist nicht optional für Container: Mappen Sie es auf docker stop (oder Äquivalent); ohne es erhalten Sie POSIX SIGTERM / Windows taskkill gegen welche PID auch immer llama-swap gestartet hat – in Ordnung für ein nacktes Binary, 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 statt ewig in die Warteschlange zu stellen.
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, damit das Vorladen passt, wie Sie wollen, dass Modelle die GPU teilen.
Minimales config.yaml Beispiel für llama.cpp und vLLM
Dieses Beispiel zielt darauf, „genug" zu sein, um bewährte Knöpfe 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 inaktiv 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 # niemals auto-entladen (z.B. auf GPU behalten)
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 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 Kerneendpunkte wie /v1/chat/completions, /v1/completions, /v1/embeddings und /v1/models, und llama-swap verwendet das angeforderte model, um zu entscheiden, welchen Upstream es laufen und weiterleiten soll.
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 ein First-Class Management-Feature und schließt Verhalten wie Sortieren nach ID, Ausschluss von unlisted Modellen und optionales Einschließen von Aliases ein.
# 3) Eine Chat-Vervollständigungsanfrage für ein spezifisches 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 nun 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 die OpenAI Python-Bibliothek auf llama-server auszurichten, außer die stabile URL ist jetzt llama-swap und das model-Feld wählt den Upstream.
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 Mutex und Semaphore."}],
)
print(resp.choices[0].message.content)
Um ein Modell vor der ersten echten Anfrage zu warming (Kaltstart-Latenz zu verbergen), verwenden Sie /upstream/<model> – es lädt automatisch bei Bedarf und leitet direkt zu diesem Upstream weiter. Direkter Weg, um sicherzustellen, dass Gewichte vorhanden 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 bietet auch operative Steuerungs-Endpunkte, die es Ihnen ermöglichen, Tooling um Modelllebenszyklus und Observierbarkeit herum zu bauen.
Prüfen, was läuft
GET /running gibt den Laufzeitstatus für geladene Modelle zurück, inklusive Zustandswerten 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 veralteter 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 zurück benötigt wird, statt auf TTL zu warten – Benchmarks, schnelle Modellwechsel oder nach 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 aktuelle Anfragezahlen einschließen.
curl -N http://localhost:8080/api/events
SSE und Token-Streaming brechen, wenn irgendeine Mittelschicht 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 auch die Pufferung im Proxy – Header sind kein Ersatz für eine korrekte Proxy-Konfiguration.
Metriken und Anfrage-Aufnahmen
GET /api/metrics gibt Token-Nutzungsmetriken zurück, mit im Speicher gehaltenen Retention gesteuert durch metricsMaxInMemory (Standard 1000).
GET /api/captures/<id> kann vollständige Anfrage/Antwort-Aufnahmen abrufen, aber nur wenn captureBuffer > 0 konfiguriert ist.
Logs und Web-Oberfläche
llama-swap bietet /ui für eine Web-Oberfläche und operative Log-Endpunkte wie /logs und /logs/stream für Echtzeit-Überwachung.
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 durchsetzt; die eingebaute Auth ist dazu da, zufällige Clients ehrlich zu halten, nicht für eine öffentliche Multi-Tenant-API.
Fehlerbehebung bei llama-swap Modellwechsel in der Produktion
Die meisten llama-swap-Probleme fallen in eine kleine Menge operativer Kategorien: Streaming durch einen Reverse-Proxy, Health-Checks während Kaltstarts, Ports und Prozesslebenszyklus sowie Authentifizierung.
Streaming bricht hinter nginx oder einem anderen Reverse-Proxy
nginx wird gerne Ihre SSE und gestreamten Vervollständigungen puffern. Deaktivieren Sie proxy_buffering (und proxy_cache) für /api/events und /v1/chat/completions. llama-swap gibt X-Accel-Buffering: no auf SSE aus, was hilft – reparieren Sie den Proxy trotzdem.
Ein Modell wird niemals 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 brauchen, 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 – sonst stoppt llama-swap den Wrapper-Prozess, während der Container im Hintergrund VRAM frisst.
Ich erhalte 401-Antworten nach Aktivierung der Sicherheit
Wenn apiKeys konfiguriert ist, benötigt llama-swap einen gültigen Schlüssel und akzeptiert drei Methoden (Basic Auth, Bearer Token, x-api-key). Es entfernt auch Authentifizierungs-Header vor dem Weiterleiten zum Upstream.
Ich erhalte 429 Too Many Requests
concurrencyLimit gibt 429 zurück, wenn überschritten – per Design. Erhöhen Sie die Obergrenze, wenn Sie sie unterdimensioniert haben, oder senken Sie das Limit, wenn Sie nicht drosseln wollten.
Port-Konflikte oder seltsame Routing-Probleme
Vermeiden Sie hartkodierte Ports in cmd; verwenden Sie ${PORT} und verschieben 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 Wahrheit, /logs/stream, wenn Start undurchsichtig ist, POST /api/models/unload, wenn VRAM jetzt zurück benötigt wird. Dieses Trio deckt die meisten „warum ist die GPU voll"-Sitzungen ab.
