llama.swap Modelväxlar: Snabbguide för lokala LLM:ar med OpenAI-kompatibilitet

Byt lokala LLM:er med hetbytte utan att ändra klienterna.

Sidinnehåll

Snart balanserar du vLLM, llama.cpp och mer – varje stack på sin egen port. Allt nedströms vill fortfarande ha en enda /v1-bas-URL; annars fortsätter du att flytta runt portar, profiler och engångsscript. llama-swap är /v1-proxyn framför dessa stackar.

llama-swap ger en enda OpenAI- och Anthropic-kompatibel ingångsport, med en YAML-fil som mappar varje model-namn till kommandot som startar rätt uppströms-tjänst. Begär en modell och proxyn startar eller byter till den; konfigurera TTL och grupper när VRAM är begränsad eller flera modeller måste samexistera. Denna guide täcker installationsvägar, en praktisk config.yaml, HTTP-ytan och de feltyper som uppstår när strömning och omvända proxy-lager kommer in i bilden.

llama swap llm infographic För en bredare jämförelse av alternativ för att hosta LLM, se LLM-hosting 2026: Lokalt, Self-Hosted & Moljfrainfrastructure Jämfört

Översikt över llama-swap modellväxlare för OpenAI-kompatibla lokala LLM-API:er

llama-swap är en lättviktig proxyserver byggd kring en enkel driftmodell: en binärfil, en YAML-konfigurationsfil, inga beroenden. Den är skriven i Go, vilket betyder en enda statisk binärfil bredvid resten av stacken – ingen Python-runtime eller skrivbordsapp krävs. Den sitter framför alla OpenAI- och Anthropic-kompatibla uppströms-tjänster som lagret för modellväxling.

Konceptuellt svarar detta på en mycket praktisk fråga som dyker upp i lokala LLM-stackar:

Hur byter jag modeller med en OpenAI-kompatibel klient?
Med llama-swap fortsätter du använda vanliga /v1/...-förfrågningar, men du ändrar model du begär. llama-swap läser det model-värdet, laddar den matchande serverkonfigurationen och om fel uppströms-tjänst körs byter den ut den mot rätt en.

Några design detaljer är viktiga för produktionsliknande uppställningar:

llama-swap är MIT-licensierat med ingen telemetri – fortfarande värt att bekräfta för varje värd som ser verkliga prompts.
Det är byggt för on-demand-laddning av backends som llama.cpp, vLLM, Whisper och stable-diffusion.cpp, inte för att låsa dig till en enda inferensmotor.
Ur lådan (utan speciell gruppindelning) kör det en modell i taget: begär en annan model så stannar den nuvarande uppströms-tjänsten och startar rätt en. För mer än en boende modell eller finare kontroll över samexistens, konfigurerar du groups.

Här är den mentala modellen som de flesta utvecklare finner användbar:

flowchart LR
  C[Din app eller SDK\nOpenAI-kompatibel klient] -->|/v1/chat/completions\nmodel = qwen-coder| LS[llama-swap proxy\nenda slutpunkt]
  LS -->|startar eller vidarebefordrar till| U1[Uppströms server A\nllama-server]
  LS -->|startar eller vidarebefordrar till| U2[Uppströms server B\nvLLM OpenAI server]
  LS --> M[Hanteringsendpunkter\nrunning, unload, events, metrics]

Detta är också varför en modellväxlare-proxy skiljer sig från “bara att köra en modell”: det är orkestrering och routning ovanpå en eller flera inferensservrar.

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

Alla fyra alternativen kan ge dig en “lokal LLM-API”, men de optimerar för olika arbetsflöden. Det snabbaste sättet att välja är att avgöra om du vill ha en runtime (modellnedladdning + exekvering) eller en router/proxy (växling + orkestrering över runtimes).

llama-swap
llama-swap fokuserar på att vara en transparent proxy som stöder OpenAI-kompatibla slutpunkter (inklusive /v1/chat/completions, /v1/completions, /v1/embeddings och /v1/models) och vidarebefordrar förfrågningar till rätt uppströms-tjänst baserat på begärd modell. Den tillhandahåller också icke-inferens operativa slutpunkter som /running, /logs/stream och en webbgränssnitt på /ui.

Ollama
Ollama exponerar sitt eget HTTP-API (POST /api/chat, POST /api/generate och den vanliga lokala standarden på port 11434).
keep_alive styr hur länge en modell förblir laddad, inklusive 0 för att omedelbart avladda.
Det passar användare som vill hämta en modell och chatta med minimal konfiguration. llama-swap passar kommandon per modell, blandade backends och en OpenAI-formad URL för varje klient – att orkestrera vLLM bredvid llama-server med olika flaggor per modell ligger utanför vad Ollama är avsett för.

LM Studio
LM Studio är en skrivbordsapp med en lokal API-server från Developer-fliken (localhost eller LAN), inklusive OpenAI-kompatibelt och Anthropic-kompatibelt läge, plus lms server start från terminalen.
Det passar ett GUI-först-flöde: bläddra modeller, klicka, testa. llama-swap passar en server-stil-roll: YAML, processövervakning, blandade uppströms-tjänster, ingen skrivbordssession.

llama.cpp server
llama-server exponerar /v1/completions, /v1/chat/completions, /v1/responses, och det vanliga mönstret är att peka en OpenAI-klient mot den via base_url.
llama.cpp levereras också med ett router-läge: kör llama-server som router, --models-dir, sedan POST /models/load och POST /models/unload för att balansera GGUF-modeller utan en separat proxy.
Om alla modeller sitter under en llama.cpp-router är en extra proxy ofta onödig. När llama.cpp måste sitta bredvid vLLM eller andra OpenAI-formade servrar, tillhandahåller llama-swap en enda /v1-yta och många processer bakom den.

För liknande OpenAI-kompatibla hostningslösningar, se LocalAI QuickStart: Kör OpenAI-kompatibla LLM lokalt eller SGLang QuickStart: Installera, konfigurera och servera LLM via OpenAI-API

Installera llama-swap modellväxlare med Docker, Homebrew, WinGet eller binärer

Linux, macOS och Windows är alla förstklassiga: Docker, Homebrew, WinGet, GitHub-binärer eller källkodskompile. Vanliga val: Docker på headless-servrar, Homebrew eller WinGet på arbetsstationer, fristående binärer när installationsfotavtrycket ska hållas minimalt.

Docker-installation

Dra en bild som matchar din hårdvara. Bilder spånar uppströms-tjänster nära (nightly-builds) och täcker CUDA, Vulkan, Intel, MUSA och CPU – välj den som matchar hur du faktiskt accelererar, inte “senast” av vana.

# Exempel på plattformsdragningar
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

Föredra icke-root-bildsversioner när du kan: mindre att ångra om containergränsen någonsin är fel.

Homebrew-installation

På macOS och Linux, använd tap och installera:

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

WinGet-installation

På Windows:

winget install llama-swap
winget upgrade llama-swap

Förbyggda binärer och releases

GitHub Releases levererar Linux, macOS, Windows och FreeBSD-binärer om du inte vill ha en pakethanterare.
Releasenummer rör sig snabbt (t.ex. v198, v197 kring tidig 2026) – lås en version i automation snarare än att flyta “vad som var där igår”.

Konfigurera llama-swap med config.yaml för modellväxling, TTL och grupper

Allt i llama-swap är konfigurationsdrivet. Den minimala möjliga konfigurationen är helt enkelt en models:-ordlista och ett cmd för varje modell, som ofta startar llama-server med ${PORT} substituerad per modell.

Konfigurationssystemet går mycket längre än bara “starta en process”, och några alternativ är värt att förstå tidigt eftersom de direkt svarar på vanliga FAQ-stilar problem (automatisk avladdning, säkerhet och klienter som litar på /v1/models).

Globala inställningar du faktiskt kommer använda

healthCheckTimeout är hur länge llama-swap väntar för att en modell ska bli hälsosam efter start (standard 120s, minimum 15s). För multi-GB-laddningar på långsamma diskar, öka detta innan du skyller på proxyn.
globalTTL är idle-sekunder innan automatisk avladdning; standard 0 betyder “aldrig avladda” om du inte sätter det – välj explicit TTL för något bortom en leksaksuppsättning så VRAM inte fylls med glömda modeller.
startPort sårar in ${PORT}-makron (standard 5800); tilldelning är deterministisk per alfabetisk modell-ID, vilket är en funktion när du debuggar “vem tog vilken port” och en fälla om du omdöper modeller slarvigt.
includeAliasesInList bestämmer om alias visas som separata rader i /v1/models; slå på om ditt gränssnitt bara erbjuder uppräkna modeller.
apiKeys låser allt som är nåbart utanför localhost: Basic, Bearer eller x-api-key. llama-swap tar bort dessa headers innan vidarebefordring så att uppströms-loggar är mindre troliga att behålla klienthemligheter.

Modell-nivå inställningar som låser upp produktionsergonomi

Per modell är cmd det enda obligatoriska fältet.
proxy är standard http://localhost:${PORT} – det är vidarebefordringsmålet för den modellens uppströms-tjänst.
checkEndpoint är standard /health; sätt "none" när backenden har ingen hälsorutt eller kallstart överskrider vad du är villig att vänta på – gör inte att lämna en trasig /health och undra varför ingenting når ready.
ttl: -1 ärver globalTTL, 0 avladdar aldrig, N > 0 avladdar efter N sekunder idle – använd per-modell TTL när en modell ska ligga kvar och en annan ska försvinna snabbt.
aliases och useModelName håller stabila klientvända namn samtidigt som de tillfredsställer uppströms-tjänster som kräver en specifik identifierare.
cmdStop är inte valfritt för containrar: mappa det till docker stop (eller motsvarighet); utan det får du POSIX SIGTERM / Windows taskkill mot vilket PID llama-swap startade – fint för en ren binär, felaktigt för ett containernamn.
concurrencyLimit sätter tak för parallella förfrågningar per modell med HTTP 429 när överskridet – sätt det när du hellre kastar last än att köa för alltid.

groups täcker samexistens (swap, exclusive) och alltid-på-modeller (persistent). Hooks kan förhandsladda vid start; om du förhandsladdar flera modeller samtidigt utan en grupp, förvänta dig att de strider – definiera en grupp först så att förhandsladdning matchar hur du vill att modeller ska dela GPU:n.

Minimal config.yaml-exempel för llama.cpp och vLLM

Detta exempel syftar på att vara “tillräckligt” för att illustrera bästa-praktik-knappar: en standard TTL, explicit hälsokontroll, stabila alias och en grupp som håller en liten “alltid-på”-modell igång medan större chattmodeller växlar.

# config.yaml
healthCheckTimeout: 180
globalTTL: 900            # 15 minuters idle sedan avladda
includeAliasesInList: true
startPort: 5800

# Valfritt men rekommenderat för något bortom lokalt utveckling
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"
    # Använder standardvärden:
    # proxy: http://localhost:${PORT}
    # checkEndpoint: /health
    # ttl: -1 (ärva globalTTL)

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

  vllm-coder:
    # Illustrativt mönster: hantera en containeriserad OpenAI-kompatibel 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                 # aldrig automatisk avladdning (t.ex. behåll på GPU)

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

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

Inget av detta är dekorativt: cmd driver processen, proxy/checkEndpoint/ttl styr routning och livscykel, cmdStop är det som får Docker-baserade uppströms-tjänster att faktiskt stanna, och groups är det som separerar “en stor modell i taget” från “dessa två chattmodeller kan samexistera medan inbäddningsservern förblir fast”.

Kör och byt modeller via OpenAI-kompatibla slutpunkter

När llama-swap körs, interagerar du med den som med vilken annan OpenAI-kompatibel slutpunkt som helst. API-ytan inkluderar kärnslutpunkter som /v1/chat/completions, /v1/completions, /v1/embeddings och /v1/models, och llama-swap använder den begärda model för att bestämma vilken uppströms-tjänst som ska köras och vidarebefordras till.

Ett praktiskt snabbstartsförlopp:

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

# 2) Upptäck tillgängliga modeller
curl http://localhost:8080/v1/models

Modelllistning är en första-klass hanteringsfunktion och inkluderar beteende som sortering per ID, uteslutande av unlisted-modeller och valfritt inkludera alias.

# 3) Gör en chattförfrågan för en specifik modell
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":"Skriv en TypeScript-funktion som försöker fetch med backoff."}]
  }'

Om du nu upprepar anropet med "model": "llama-chat" kommer llama-swap att byta uppströms-processer (om inte din gruppkonfiguration tillåter dem att samexistera) eftersom den extraherar den begärda modellen från förfrågan och laddar rätt serverkonfiguration.

Om du använder en SDK, peka klienten mot http://localhost:8080/v1 – samma trick som att sikta OpenAI-biblioteket för Python mot llama-server, förutom att den stabila URL:n nu är llama-swap och model-fältet väljer uppströms-tjänsten.

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": "Förklara skillnaden mellan mutex och semaforer."}],
)
print(resp.choices[0].message.content)

För att värma en modell innan den första verkliga förfrågan (dölja kallstartslatens), använd /upstream/<model> – den laddar automatiskt om behövt och vidarebefordrar direkt till den uppströms-tjänsten. Ett rakt sätt att säkerställa att vikter är boende innan en benchmark eller skriptad test.

Kontrollera och övervaka llama-swap via hanterings-API-slutpunkter och SSE-händelser

llama-swap är inte bara “en proxy”; den exponerar också operativa kontrollslutpunkter som låter dig bygga verktyg kring modelllivscykel och observabilitet.

Kontrollera vad som körs
GET /running returnerar körningstillstånd för laddade modeller, inklusive tillståndsvärden som ready, starting, stopping, stopped och shutdown.

curl http://localhost:8080/running

Avladda modeller för att frigöra VRAM
För att avladda allt omedelbart, använd API-versionerade slutpunkten POST /api/models/unload. För att avladda en enskild modell (per ID eller alias), använd POST /api/models/unload/<model>. En legacy GET /unload finns för bakåtkompatibilitet.

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

# avladda en modell
curl -X POST http://localhost:8080/api/models/unload/qwen-coder

Använd dessa slutpunkter när VRAM behövs tillbaka nu istället för att vänta på TTL – benchmarks, snabba modellbyten eller efter att ha laddat en mycket större checkpoint än avsett.

Strömma live-händelser via SSE
GET /api/events etablerar en Server-Sent Events-ström och är designad för realtidsuppdateringar som inkluderar modellstatusförändringar, loggar, metrik och pågående förfråganr.

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

SSE och tokenströmning bryter när någon mellanbox buffrar – inaktivera buffring på nginx (eller din motsvarighet) för /api/events och /v1/chat/completions. llama-swap sätter X-Accel-Buffering: no på SSE; inaktivera buffring i proxyn också – headers är inte ett substitut för en korrekt proxykonfiguration.

Metrik och förfråganfångster
GET /api/metrics returnerar tokenanvändningsmetrik, med minnesbevarande kontrollerat av metricsMaxInMemory (standard 1000).
GET /api/captures/<id> kan hämta fulla förfrågan/svar-fångster, men bara när captureBuffer > 0 är konfigurerat.

Loggar och webbgränssnitt

llama-swap exponerar /ui för ett webbgränssnitt, och operativa loggslutpunkter som /logs och /logs/stream för realtidsövervakning.

llama-swap web UI for switching models

Om du aktiverar apiKeys, anta försvar i djup: /health och delar av /ui förblir nåbara utan nyckel – fint för lokala tillitgränser, inte fint om värdet är på ett delat nätverk. Sätt llama-swap bakom något som genomför din verkliga policy; den inbyggda autentiseringen är för att hålla tillfälliga klienter ärliga, inte för en offentlig multi-tenant-API.

felsökning av llama-swap modellväxling i produktion

De flesta llama-swap-problem faller in i en liten uppsättning operativa kategorier: strömning genom en omvänd proxy, hälsokontroller under kallstart, portar och processlivscykel samt autentisering.

Strömning bryter bakom nginx eller en annan omvänd proxy
nginx kommer gladeligen att buffra bort din SSE och strömmade slutföranden. Inaktivera proxy_buffering (och proxy_cache) för /api/events och /v1/chat/completions. llama-swap emitterar X-Accel-Buffering: no på SSE, vilket hjälper – fixa proxyn ändå.

En modell blir aldrig redo
Standardmässigt är per-modell checkEndpoint /health och måste returnera HTTP 200 för att processen ska betraktas som redo. Du kan sätta checkEndpoint till en annan sökväg eller till "none" för att helt inaktivera hälsokontroller.
Om stora modeller tar längre tid att ladda, öka healthCheckTimeout (standard 120s), eller använd skräddarsydda hälsokontroller för din specifika uppströms-tjänst.

Att byta modeller lämnar en gammal container igång
Om uppströms-tjänsten är Docker eller Podman, sätt cmdStop – annars stannar llama-swap wrapper-processen medan containern fortsätter att äta VRAM i bakgrunden.

Jag får 401-svar efter att ha aktiverat säkerhet
När apiKeys är konfigurerat kräver llama-swap en giltig nyckel och accepterar tre metoder (Basic auth, Bearer-token, x-api-key). Den tar också bort autentiseringsheaders innan vidarebefordring uppströms.

Jag får 429 Too Many Requests
concurrencyLimit returnerar 429 när överskridet – av design. Höj taket om du underprovisionerade det, eller sänk gränsen om du inte menade att strypa.

Portkonflikter eller udda routningsproblem
Undvik hårdkodade portar i cmd; använd ${PORT} och flytta startPort om 5800+ krockar med något annat. Kom ihåg att portar tilldelas i alfabetisk ordning per modell-ID – byt namn på en modell och portmappningen skiftar.

Operativ felsökningschecklista
/running för sanning, /logs/stream när start är opak, POST /api/models/unload när VRAM behövs tillbaka nu. Den triaden täcker de flesta “varför är GPU:n full”-sessioner.