Snelstart voor llama.swap Model Switcher voor lokaal met OpenAI-compatibele LLM's

Lokale LLM's zonder cliënten te wijzigen verwisselen.

Inhoud

Binnenkort juggle je vLLM, llama.cpp en meer – elk stack op zijn eigen poort. Alles downstream wil nog steeds één /v1-basis-URL; anders blijf je poorten, profielen en eenmalige scripts shuffelen. llama-swap is de /v1-proxy voor die stacks.

llama-swap biedt één OpenAI- en Anthropic-compatibele ingang, met een YAML-bestand dat elke model-naam koppelt aan het commando dat de juiste upstream opstart. Verzoek een model en de proxy start of wisselt naar die; configureer TTL’s en groepen als VRAM schaars is of meerdere modellen moeten co-existeren. Deze gids dekt installatiepaden, een praktisch config.yaml, het HTTP-oppervlak en de faalmodi die ontstaan zodra streaming en reverse proxies in beeld komen.

llama swap llm infographic Voor een bredere vergelijking van LLM-hostingopties, zie LLM Hosting in 2026: Lokaal, Self-Hosted & Cloud Infrastructuur Vergelijkt

Overzicht van llama-swap model switcher voor OpenAI-compatibele lokale LLM-API’s

llama-swap is een lightweight proxy-server gebouwd rond een eenvoudig operationeel model: één binaire, één YAML-configuratiebestand, geen afhankelijkheden. Het is geschreven in Go, wat betekent dat het een statisch binaire bestand is naast de rest van de stack – geen Python-runtime of desktop-app vereist. Het zit voor elke OpenAI- en Anthropic-compatibele upstream als de model-swapping laag.

Conceptueel beantwoordt dit een zeer praktische vraag die in lokale LLM-stacks opduikt:

Hoe schakel ik modellen met een OpenAI-compatibele client?
Met llama-swap gebruik je gewoon normale /v1/...-aanvragen, maar verander je het model dat je aanvraagt. llama-swap leest die model-waarde, laadt de bijbehorende serverconfiguratie op en als de “foute” upstream draait, wisselt het deze uit voor de juiste.

Enkele ontwerpdetails zijn belangrijk voor productieachtige opstellingen:

llama-swap is MIT-gelicenceerd met geen telemetrie – het blijft de moeite waard om dit te bevestigen voor elke host die echte prompts ontvangt.
Het is gebouwd voor on-demand laden van backends zoals llama.cpp, vLLM, Whisper en stable-diffusion.cpp, niet om je vast te pinnen aan een enkele inferentie-engine.
Standaard (zonder speciale groepering) draait het één model tegelijk: vraag een ander model aan en het stopt de huidige upstream en start de juiste. Voor meer dan één resident model of fijnere controle over co-existentie, configureer groups.

Hier is het mentale model dat de meeste ontwikkelaars nuttig vinden:

flowchart LR
  C[Jouw app of SDK\nOpenAI-compatibele client] -->|/v1/chat/completions\nmodel = qwen-coder| LS[llama-swap proxy\néén endpoint]
  LS -->|start of route naar| U1[Upstream server A\nllama-server]
  LS -->|start of route naar| U2[Upstream server B\nvLLM OpenAI server]
  LS --> M[Management endpoints\ndraait, unload, events, metrics]

Dit is ook waarom een model switcher proxy anders is dan “gewoon een model draaien”: het is orchestratie en routing bovenop een of meer inferentie-servers.

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

Alle vier opties kunnen je een “lokale LLM-API” geven, maar ze optimaliseren voor verschillende workflows. De snelste manier om te kiezen is te beslissen of je een runtime (model downloaden + uitvoeren) of een router/proxy (schakelen + orchestratie over runtimes) wilt.

llama-swap
llama-swap richt zich op het zijn van een transparante proxy die OpenAI-compatibele endpoints ondersteunt (inclusief /v1/chat/completions, /v1/completions, /v1/embeddings en /v1/models) en aanvragen routeert naar de juiste upstream op basis van het aangevraagde model. Het biedt ook niet-inferentiële operationele endpoints zoals /running, /logs/stream en een Web UI op /ui.

Ollama
Ollama exposeert zijn eigen HTTP-API (POST /api/chat, POST /api/generate en de gebruikelijke lokale standaard op poort 11434).
keep_alive regelt hoe lang een model geladen blijft, inclusief 0 om direct te ontladen.
Het past bij gebruikers die een model willen pullen en chatten met minimale bedrading. llama-swap past bij per-model commando’s, gemengde backends en één OpenAI-achtige URL voor elke client – het orchestreert vLLM naast llama-server met verschillende vlaggen per model, wat buiten wat Ollama beoogt valt.

LM Studio
LM Studio is een desktop-app met een lokale API-server vanuit het Developer-tabblad (localhost of LAN), inclusief OpenAI-compatibele en Anthropic-compatibele modi, plus lms server start vanuit de terminal.
Het past bij een GUI-first lus: modellen browsen, klikken, testen. llama-swap past bij een server-achtige rol: YAML, proces-toezicht, gemengde upstreams, geen desktopsessie.

llama.cpp server
llama-server exposeert /v1/completions, /v1/chat/completions, /v1/responses en het gebruikelijke patroon is om een OpenAI-client daarheen te wijzen via base_url.
llama.cpp heeft ook een router-modus: draai llama-server als router, --models-dir, en dan POST /models/load en POST /models/unload om GGUF-modellen te juggle zonder een aparte proxy.
Als elk model onder één llama.cpp-router zit, is een extra proxy vaak niet nodig. Wanneer llama.cpp naast vLLM of andere OpenAI-achtige servers moet zitten, biedt llama-swap één /v1-oppervlak en vele processen daarachter.

Voor vergelijkbare OpenAI-compatibele hostingoplossingen, zie LocalAI QuickStart: Draai OpenAI-Compatibele LLM’s Lokaal of SGLang QuickStart: Installeer, Configureer en Serveer LLM’s via OpenAI API

Installeer llama-swap model switcher met Docker, Homebrew, WinGet of binaire bestanden

Linux, macOS en Windows zijn allemaal eerlijke burgers: Docker, Homebrew, WinGet, GitHub-binaire bestanden of build from source. Gewone keuzes: Docker op headless servers, Homebrew of WinGet op werkstations, standalone binaire bestanden wanneer het installatievoetafdruk minimaal moet blijven.

Docker installatie

Pull een image dat past bij je hardware. Images volgen upstream nauw (nightly builds) en dekken CUDA, Vulkan, Intel, MUSA en CPU – kies degene die past bij hoe je echt accelereert, niet “latest” uit gewoonte.

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

Geef de voorkeur aan de non-root image-varianten als je kunt: minder om op te haken als de containergrens ooit verkeerd is.

Homebrew installatie

Op macOS en Linux, gebruik de tap en installeer:

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

WinGet installatie

Op Windows:

winget install llama-swap
winget upgrade llama-swap

Vooraf gebouwde binaire bestanden en releases

GitHub Releases biedt Linux, macOS, Windows en FreeBSD binaire bestanden als je geen package manager wilt.
Versienummers bewegen snel (bijvoorbeeld v198, v197 rond begin 2026) – pin een versie in automatisering in plaats van te drijven op “wat er gisteren was”.

Configureer llama-swap met config.yaml voor model swapping, TTL en groepen

Alles in llama-swap is configuratie-aangedreven. De minimale levensvatbare configuratie is simpelweg een models:-woordenlijst en een cmd voor elk model, vaak het opstarten van llama-server met ${PORT} gesubstitueerd per model.

Het configuratiesysteem gaat veel verder dan alleen “een proces starten”, en een paar opties zijn de moeite waard om vroeg te begrijpen omdat ze directe antwoorden geven op veelvoorkomende FAQ-stijl problemen (auto-unload, beveiliging en clients die vertrouwen op /v1/models).

Globale instellingen die je daadwerkelijk zult gebruiken

healthCheckTimeout is hoe lang llama-swap wacht tot een model gezond wordt na opstarten (standaard 120s, minimum 15s). Voor multi-GB loads op trage schijven, verhoog dit voordat je de proxy de schuld geeft.
globalTTL is idle seconden voordat auto-unload; standaard 0 betekent “nooit unload” tenzij je het instelt – kies expliciete TTL’s voor alles buiten een toy-opstelling zodat VRAM niet vol raakt met vergeten modellen.
startPort zaait de ${PORT}-macro (standaard 5800); toewijzing is deterministisch op alfabetische model-ID, wat een functie is als je debugt “wie welke poort pakte” en een valkuil als je modellen onzorgvuldig hernoemt.
includeAliasesInList bepaalt of aliases als aparte rijen verschijnen in /v1/models; zet het aan als je UI alleen genummerde modellen biedt.
apiKeys beveiligt alles bereikbaar buiten localhost: Basic, Bearer of x-api-key. llama-swap verwijdert die headers voordat het doorstuurt zodat upstream logs minder waarschijnlijk client-secrets behouden.

Model-level instellingen die productie-ergonomie ontgrendelen

Per model is cmd het enige vereiste veld.
proxy default naar http://localhost:${PORT} – dat is het forwarding-doel voor dat model’s upstream.
checkEndpoint default naar /health; zet "none" als de backend geen health-route heeft of koude start langer duurt dan je wilt wachten – laat niet een gebroken /health achter en vraag je af waarom niets ready bereikt.
ttl: -1 erf globalTTL, 0 laadt nooit uit, N > 0 laadt uit na N seconden idle – gebruik per-model TTL als één model moet blijven en een ander snel moet verdwijnen.
aliases en useModelName houden stabiele client-facing namen terwijl ze upstreams bevredigen die een specifieke identifier vereisen.
cmdStop is niet-optioneel voor containers: map het naar docker stop (of equivalent); zonder krijg je POSIX SIGTERM / Windows taskkill tegen wat voor PID dan ook dat llama-swap startte – prima voor een blote binaire, verkeerd voor een container-naam.
concurrencyLimit capt parallelle aanvragen per model met HTTP 429 als overschreden – stel het in als je liever load shedt dan eeuwig in de wachtrij staat.

groups dekken co-existentie (swap, exclusive) en altijd-aan modellen (persistent). Hooks kunnen preloaden bij opstart; als je meerdere modellen tegelijk prelaadt zonder een groep, verwacht dat ze vechten – definieer eerst een groep zodat preloading past bij hoe je wilt dat modellen de GPU delen.

Minimale config.yaml voorbeeld voor llama.cpp en vLLM

Dit voorbeeld beoogt “net genoeg” te zijn om beste-praktijk-knoppen te illustreren: een standaard TTL, expliciete health checking, stabiele aliases en een groep die een klein “altijd-aan” model laat draaien terwijl grotere chat-modellen wisselen.

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

# Optioneel maar aanbevolen voor alles buiten localhost ontwikkeling
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"
    # Gebruikt defaults:
    # proxy: http://localhost:${PORT}
    # checkEndpoint: /health
    # ttl: -1 (erf globalTTL)

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

  vllm-coder:
    # Illustratief patroon: beheer een containeriseerde OpenAI-compatibele 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                 # nooit auto-unload (bijv. op GPU houden)

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

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

Dit is allemaal geen versiering: cmd drijft het proces, proxy/checkEndpoint/ttl controleren routing en levenscyclus, cmdStop zorgt ervoor dat Docker-based upstreams daadwerkelijk stoppen, en groups scheiden “één groot model tegelijk” van “deze twee chat-modellen mogen co-existeren terwijl de embedding-server vastzit”.

Draai en wissel modellen via OpenAI-compatibele endpoints

Zodra llama-swap draait, interacteer je ermee als met elke andere OpenAI-compatibele endpoint. Het API-oppervlak bevat kern-endpoints zoals /v1/chat/completions, /v1/completions, /v1/embeddings en /v1/models, en llama-swap gebruikt het aangevraagde model om te beslissen welke upstream te draaien en naar te routeren.

Een praktische quickstart flow:

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

# 2) Ontdek beschikbare modellen
curl http://localhost:8080/v1/models

Model-lijsting is een first-class management-functie en omvat gedrag zoals sorteren op ID, uitsluiten van unlisted modellen en optioneel inclusief aliases.

# 3) Maak een chat completion aanvraag voor een specifiek 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":"Schrijf een TypeScript-functie die fetch met backoff probeert."}]
  }'

Als je nu de oproep herhaalt met "model": "llama-chat", zal llama-swap upstream-processen wisselen (tenzij je groepsconfiguratie toelaat dat ze co-existeren) omdat het het aangevraagde model uit de aanvraag haalt en de juiste serverconfiguratie laadt.

Als je een SDK gebruikt, wijs de client naar http://localhost:8080/v1 – dezelfde truc als het richten van de OpenAI Python-bibliotheek op llama-server, behalve dat de stabiele URL nu llama-swap is en het model-veld de upstream kiest.

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": "Leg het verschil uit tussen mutexes en semaforen."}],
)
print(resp.choices[0].message.content)

Om een model te warmen voor de eerste echte aanvraag (koude-start latentie verbergen), gebruik /upstream/<model> – het laadt automatisch op indien nodig en stuurt direct naar die upstream. Rechtstreekse manier om te waarborgen dat gewichten resident zijn voordat een benchmark of gescript test.

Controleer en monitor llama-swap via management API endpoints en SSE events

llama-swap is niet alleen “een proxy”; het exposeert ook operationele controle-endpoints waarmee je tooling kunt bouwen rond model levenscyclus en observabiliteit.

Controleer wat er draait
GET /running geeft runtime-state voor geladen modellen, inclusief state-waarden zoals ready, starting, stopping, stopped en shutdown.

curl http://localhost:8080/running

Ontlaad modellen om VRAM vrij te maken
Om alles direct te ontladen, gebruik het API-versie-geëindigde endpoint POST /api/models/unload. Om één model te ontladen (op ID of alias), gebruik POST /api/models/unload/<model>. Een legacy GET /unload bestaat voor backwards compatibiliteit.

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

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

Gebruik deze endpoints als VRAM nu nu nodig is in plaats van te wachten op TTL – benchmarks, snelle modelwissels, of na het laden van een veel groter checkpoint dan beoogd.

Stream live events via SSE
GET /api/events vestigt een Server-Sent Events stream en is ontworpen voor real-time updates die modelstatusveranderingen, logs, metrics en in-flight aanvraag-aantallen bevatten.

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

SSE en token streaming breken als elke middle box buffer – schakel buffering uit op nginx (of je equivalent) voor /api/events en /v1/chat/completions. llama-swap zet X-Accel-Buffering: no op SSE; schakel buffering in de proxy ook uit – headers zijn geen vervanging voor een correcte proxy-configuratie.

Metrics en aanvraag-captures
GET /api/metrics geeft token-gebruiks-metrics terug, met in-memory retentie gecontroleerd door metricsMaxInMemory (standaard 1000).
GET /api/captures/<id> kan volledige aanvraag/antwoord-captures ophalen, maar alleen als captureBuffer > 0 is geconfigureerd.

Logs en de Web UI

llama-swap exposeert /ui voor een web-interface, en operationele log-endpoints zoals /logs en /logs/stream voor real-time monitoring.

llama-swap web UI voor het wisselen van modellen

Als je apiKeys inschakelt, neem dan verdediging in diepte aan: /health en stukjes van /ui blijven bereikbaar zonder een sleutel – prima voor lokale vertrouwensgrenzen, niet prima als de host op een gedeeld netwerk zit. Zet llama-swap achter iets dat je echte beleid afdwingt; de ingebouwde auth is om informele clients eerlijk te houden, niet voor een publieke multi-tenant API.

Probleemoplossing voor llama-swap model wisselen in productie

De meeste llama-swap problemen vallen in een klein aantal operationele categorieën: streaming via een reverse proxy, health checks tijdens koude starts, poorten en proces levenscyclus, en authenticatie.

Streaming breekt achter nginx of een andere reverse proxy
nginx zal je SSE en gestreamde completions blijmoedig bufferen. Schakel proxy_buffering (en proxy_cache) uit voor /api/events en /v1/chat/completions. llama-swap emiteert X-Accel-Buffering: no op SSE, wat helpt – fix de proxy toch.

Een model wordt nooit ready
Standaard is per-model checkEndpoint /health en moet HTTP 200 teruggeven voor het proces om als ready te worden beschouwd. Je kunt checkEndpoint op een ander pad of op "none" zetten om health checks volledig uit te schakelen.
Als grote modellen langer nodig hebben om te laden, verhoog healthCheckTimeout (standaard 120s), of gebruik op maat gemaakte health checks voor je specifieke upstream.

Modellen wisselen laat een oude container draaien
Als de upstream Docker of Podman is, zet cmdStop – anders stopt llama-swap het wrapper-proces terwijl de container VRAM blijft consumeren in de achtergrond.

Ik krijg 401 responses na het inschakelen van beveiliging
Wanneer apiKeys is geconfigureerd, vereist llama-swap een geldige sleutel en accepteert drie methoden (Basic auth, Bearer token, x-api-key). Het verwijdert ook authenticatie-headers voordat het upstream doorstuurt.

Ik krijg 429 Too Many Requests
concurrencyLimit geeft 429 terug als overschreden – per ontwerp. Verhoog de limiet als je het te laag hebt ingesteld, of verlaag de limiet als je niet van plan was te throttlen.

Poortconflicten of vreemde routingproblemen
Vermijd hard-coded poorten in cmd; gebruik ${PORT} en verplaats startPort als 5800+ botst met iets anders. Onthoud dat poorten worden toegewezen in alfabetische volgorde per model-ID – hernoem een model en de poorttoewijzing verschuift.

Operationele debug-checklist
/running voor de waarheid, /logs/stream als opstarten onduidelijk is, POST /api/models/unload als VRAM nu nu nodig is. Dat trio dekt de meeste “waarom is de GPU vol” sessies.