LiteLLM proxy tracker: load balancing en fallback-gedrag

Door Ivo Donker — samengesteld met AI-ondersteuning (Claude & Gemini)

Status tracker: Focus op proxy routing-architecturen, rate-limit buffering via Redis, streaming connection drops tijdens provider fallbacks en cost-aware routeringspatronen voor ontwikkelaars met een eigen stack.

In complexe AI-architecturen is inferentie allang niet meer gekoppeld aan één enkele API-sleutel bij één leverancier. Wie meerdere agents tegelijkertijd laat draaien of productieworkflows ondersteunt, loopt onvermijdelijk tegen rate limits (HTTP 429), upstream timeouts (HTTP 504) en plotselinge providerstoringen aan. LiteLLM Proxy heeft zich gevestigd als een veelgebruikte opensource API-gateway om een uniforme OpenAI-compatibele interface te leggen over tientallen modelproviders.

Toch blijkt in de praktijk dat het configureren van een proxy eenvoudiger klinkt dan het beheersen van het dynamische runtime-gedrag. Load balancing tussen heterogene backends, het correct doorgeven van context limits en het opvangen van haperende streaming responses vereisen diepgaande kennis van de onderliggende router. In deze tracker analyseren we hoe load balancing en fallback cascades zich conceptueel gedragen onder zware belasting, waar de structurele zwaktes zitten en hoe parameters in productiesetups moeten worden ingeregeld om dataverlies en onnodige vertragingen te voorkomen.

De routing-strategieën van LiteLLM onder de motorkap

LiteLLM Proxy biedt verschillende ingebouwde routing-algoritmen via de parameter routing_strategy. De keuze van deze strategie bepaalt fundamenteel hoe inkomende requests worden verdeeld over de geconfigureerde endpoints binnen een modelgroep. De eenvoudigste implementatie is simple-shuffle, wat neerkomt op een willekeurige selectie zonder rekening te houden met eerdere belasting of responstijden.

Voor productieomgevingen waarin piekbelastingen en wisselende providercondities optreden, zijn er drie geavanceerdere benaderingen beschikbaar:

least-busy: Stuurt het verzoek naar het endpoint dat op dat moment het minste aantal actieve open verbindingen heeft. Dit voorkomt dat een trage endpoint overspoeld raakt met wachtende verbindingen, maar vereist nauwkeurige lokale state tracking.
latency-based-routing: Kiest dynamisch het endpoint met de laagste gemiddelde responstijd over een glijdend venster. Dit is geschikt wanneer dezelfde modellen worden gehost over verschillende regio's of cloudproviders met wisselende netwerklatentie.
usage-based-routing-v2: Houdt in een centrale Redis-laag bij hoeveel tokens per minuut (TPM) en requests per minuut (RPM) er naar elk endpoint zijn gestuurd, en balanceert verzoeken zodanig dat rate limits bij upstream providers proportioneel worden vermeden.

Om te begrijpen hoe deze routering zich vertaalt naar kostenbeheersing bij grootschalige operaties, biedt het raadplegen van de doorlopende prijskaart per miljoen tokens een helder referentiekader voor de financiële impact van providerkeuzes. Een balancer zonder contextuele limieten kan immers ongemerkt verkeer doorsluizen naar een aanzienlijk duurder fallback-model.

Configuratie: RPM, TPM en gewogen eindpunten

Wanneer meerdere API-keys van dezelfde provider of verschillende deployments (zoals Azure OpenAI naast OpenAI Direct) worden samengevoegd, moeten de endpoints expliciet worden voorzien van capaciteitslimieten. LiteLLM gebruikt deze metadata om proactief te throttlen of verzoeken af te buigen voordat de upstream provider een HTTP 429 genereert.

Hieronder staat een typische configuratie waarin een modelgroep wordt verdeeld over Azure, OpenAI en een lokaal gehost vLLM-cluster:

model_list:
  - model_name: gpt-4o-productie
    litellm_params:
      model: azure/gpt-4o-eastus
      api_base: https://instance-east.openai.azure.com/
      api_key: os.environ/AZURE_EAST_KEY
      rpm: 2400
      tpm: 180000
  - model_name: gpt-4o-productie
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_PROD_KEY
      rpm: 5000
      tpm: 450000
  - model_name: gpt-4o-productie
    litellm_params:
      model: hosted_vllm/meta-llama/Llama-3.3-70B-Instruct
      api_base: http://vllm-cluster.internal:8000/v1
      api_key: none
      rpm: 1200
      tpm: 90000

router_settings:
  routing_strategy: usage-based-routing-v2
  redis_host: redis-cluster.internal
  redis_port: 6379
  redis_password: os.environ/REDIS_AUTH
  enable_pre_call_checks: true

De parameter enable_pre_call_checks: true dwingt de router af om vóór verzending in Redis te controleren of het geschatte tokenverbruik past binnen het resterende TPM-venster van het geselecteerde endpoint. Hierdoor wordt het risico op overbelasting van individuele API-keys sterk verkleind.

Voor ontwikkelaars die optimalisaties zoeken in prompt-overhead en payload-reductie, sluiten de technieken uit het artikel over bewezen token-besparing uit de community direct aan op het effectief benutten van deze strakke TPM-budgetten.

Fallback cascades: volgorde, foutcodes en cooldown-mechanismen

Een robuuste fallback-architectuur vangt niet alleen capaciteitsproblemen op, maar reageert ook op infrastructurele en functionele fouten zoals netwerkuitval en modelonbeschikbaarheid. LiteLLM hanteert een tweetraps benadering: retries op hetzelfde model (indien er meerdere endpoints zijn) gevolgd door een fallback naar een alternatieve modelgroep.

De fallback-volgorde wordt gedefinieerd in de configuratie via fallbacks. Een cruciaal aspect hierbij is de cooldown-tijd: zodra een endpoint faalt met een 5xx- of 429-fout, markeert LiteLLM dit endpoint als inactief voor een instelbare periode via cooldown_time.

Foutcode	Trigger-oorzaak	Standaard LiteLLM actie	Aanbevolen mitigatie
`HTTP 429`	Upstream Rate Limit (RPM/TPM bereikt)	Zet endpoint op cooldown; switch naar volgende sleutel of fallback-model	Schakel `usage-based-routing-v2` in met Redis
`HTTP 504 / Timeout`	Upstream inferentie duurt te lang	Retry afhankelijk van `num_retries`, daarna fallback	Stel `request_timeout` scherp in op basis van serviceniveau
`HTTP 400 (Context Length)`	Prompt overschrijdt contextvenster	Geen retry op zelfde model; faalt tenzij fallback groter venster heeft	Definieer fallback naar een model met een ruimer contextvenster
`HTTP 400 (Content Filter)`	Veiligheidsfilter geactiveerd bij provider	Wordt gezien als client error; triggert standaard geen fallback	Configureer expliciete error mappings indien fallback gewenst is

Wanneer een fout optreedt die wél een fallback triggert, doorloopt de proxy de geconfigureerde lijst. Als de primaire tier (bijvoorbeeld Claude 3.5 Sonnet) niet bereikbaar is, schakelt de router door naar een alternatief endpoint zoals GPT-4o, en in uiterste nood naar een lokaal open-weight model.

Wie zijn eigen architectuur wil vergelijken met algemene routeringspatronen kan de gids over meerdere modellen orkestreren via routing en fallback raadplegen om de verschillen tussen gateway-level routing en applicatie-level routing scherp te krijgen.

De architectuur van state-beheer: Redis vs. in-memory

LiteLLM Proxy kan draaien in een stateless modus waarbij elke worker zijn eigen statistieken in-memory bijhoudt, of in een gedistribueerde modus met Redis als centrale state store. In productie met meerdere workers of geclusterde containers is een centrale Redis-instantie noodzakelijk om consistente beslissingen te kunnen nemen.

Zonder Redis treedt het split-brain probleem op: instantie A weet niet dat instantie B zojuist een grote promptbatch naar hetzelfde endpoint heeft gestuurd. Beide instanties veronderstellen dat ze binnen hun TPM-limiet opereren, waardoor ze gelijktijdig verzoeken doorsturen en alsnog tegen upstream rate limits aanlopen. Redis synchroniseert drie essentiële tabellen:

Token buckets: Voor het bijhouden van actueel RPM- en TPM-verbruik per model-alias en per API-sleutel.
Cooldown registers: Een gedeelde status van endpoints die tijdelijk buiten gebruik zijn gesteld wegens foutmeldingen.
Latency matrices: Gemiddelde responstijden ten behoeve van latency-based routing.

Daarnaast speelt caching een grote rol in het ontlasten van de routeringslaag. Door semantische of exacte response caching direct in Redis te activeren, hoeven identieke prompts niet opnieuw te worden doorgezet naar de providers. Voor geavanceerde scenario's waarin multi-agent systemen repeterende queries uitvoeren, biedt het artikel over caching-architecturen voor multi-agent loops diepgaande strategieën om Redis hiervoor optimaal in te zetten.

Streaming responses en het fallback-dilemma

Het combineren van Server-Sent Events (SSE) streaming met automatische fallbacks is een van de meest complexe uitdagingen binnen LLM-infrastructuur. Het probleem ontstaat zodra de proxy de HTTP 200-headers en de eerste streaming chunks (zoals de role en de eerste tokens) al heeft doorgestuurd naar de client.

Als de upstream provider halverwege het genereren crasht, de verbinding verbreekt of een timeout genereert, kan LiteLLM de verbinding niet zomaar opnieuw starten op een fallback-model zonder dat de client corrupte data ontvangt. De client heeft immers al een gedeeltelijke datastroom ontvangen.

Er zijn twee manieren om met deze beperking om te gaan:

Directe streaming zonder buffering: Maximale snelheid en minimale vertraging tot het eerste token (TTFT). Faalt het endpoint halverwege de stream, dan verbreekt de verbinding met een foutmelding. De client-applicatie moet in dat geval zelf detecteren dat de stream onvolledig was en een retry initiëren.
Bufferen van de initiële chunks: De proxy buffert de eerste tokens totdat de verbinding stabiel blijkt voordat de headers naar de client worden gestuurd. Dit introduceert een lichte vertraging in TTFT, maar stelt de gateway in staat om bij een directe fout bij aanvang alsnog transparant over te schakelen naar een fallback-model.

Voor een gedetailleerde blik op hoe client-applicaties moeten omgaan met afgebroken streams en het netjes afhechten van half-gegenereerde JSON, biedt het dossier over streaming met terugval en gedeeltelijke antwoorden concrete implementatiepatronen.

Observability en metrieken: wat moet je monitoren?

Een routeringslaag zonder observability is een blind systeem. LiteLLM biedt native integraties met OpenTelemetry, Prometheus, Langfuse en Datadog. Om vast te stellen of de gekozen load balancing-strategie effectief functioneert, moeten specifieke kernstatistieken worden gemonitord.

# Prometheus metrieken configuratie in litellm config.yaml
general_settings:
  telemetry: false

litellm_settings:
  callbacks: ["prometheus", "otel"]
  success_callback: ["prometheus"]
  failure_callback: ["prometheus"]

De belangrijkste indicatoren op het dashboard zijn:

litellm_deployment_latency_per_output_token: Geeft inzicht in de werkelijke inferentiesnelheid per backend, gecorrigeerd voor promptlengte.
litellm_deployment_failed_requests_total: Moet per model en per statuscode worden uitgesplitst om patronen in 429- of 5xx-fouten vroegtijdig te signaleren.
litellm_deployment_cooled_down: Toont realtime welke endpoints tijdelijk buiten gebruik zijn gesteld door het cooldown-mechanisme.
litellm_deployment_successful_fallbacks: Meet hoe vaak een verzoek pas slaagde op een secundair of tertiair endpoint. Een aanhoudende toename duidt op structurele ondercapaciteit van de primaire tier.

Een overzicht van het bredere landschap van monitoring-tools en tracing-frameworks is te vinden in de analyse van AI-observability en tooling-signalen.

Analyse van faalmodi in een heterogene opstelling

Om te begrijpen hoe routering faalt onder belasting, helpt het om een conceptuele opstelling te analyseren waarin drie typen backends samenwerken: een commercieel cloud-endpoint met strakke rate limits (Tier 1), een secundaire cloudprovider met ruimere limieten (Tier 2) en een lokaal gehoste modelserver zoals vLLM.

Wanneer een eenvoudige simple-shuffle strategie wordt gebruikt bij piekbelasting, worden verzoeken blind verdeeld. Zodra het cloud-endpoint zijn TPM-limiet bereikt, treden kettingreacties op: retries belasten de proxy verder en verhogen de wachttijd voor alle volgende verzoeken. Bij een dynamische strategie zoals usage-based-routing-v2 met pre-call checks berekent de router vooraf de resterende capaciteit en buigt verzoeken tijdig af naar de overige tiers.

Een belangrijk aandachtspunt bij lokale fallbacks is de 'cold start' latentie: wanneer een lokale modelserver plotseling een golf aan verzoeken ontvangt die zijn afgebogen van de cloud, kan de verwerkingstijd per token tijdelijk toenemen doordat de server zijn geheugenbuffers en dynamische KV-cache moet heralloceren. Dit benadrukt dat ook een fallback-doelwit operationeel berekend moet zijn op abrupte verschuivingen in het verkeersvolume.

Checklist voor productie-implementaties

LiteLLM Proxy vormt een krachtige schakel in multi-provider AI-architecturen, mits men de routerings- en fallbackmechanismen afstemt op de operationele realiteit van de onderliggende providers.

De belangrijkste ontwerpregels voor een stabiele implementatie:

Koppel een centrale Redis-instantie voor gedistribueerde token-tracking en cooldown-registratie zodra er meerdere proxy-instanties draaien.
Stel expliciete rpm en tpm limieten in op elk individueel endpoint, bij voorkeur met een veiligheidsmarge onder het theoretische providerquotum.
Kies usage-based-routing-v2 voor heterogene cloud-accounts en least-busy voor lokaal gehoste modelservers met variabele rekentijden.
Definieer een strikte request_timeout op primaire endpoints om te voorkomen dat haperende verbindingen de wachtrij blokkeren.
Houd er rekening mee dat streaming responses bij provider-crashes na de initiële tokens niet transparant kunnen overschakelen zonder applicatie-interventie.