# Token Bucket Algoritme in een LLM-Gateway: Praktische Gids

Deel:[𝕏](https://twitter.com/intent/tweet?url=https%3A//api.llmnet.nl/token-bucket-algoritme-llm-gateway&text=Token%20Bucket%20Algoritme%20in%20een%20LLM-Gateway%3A%20Praktische%20Gids)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A//api.llmnet.nl/token-bucket-algoritme-llm-gateway)[Reddit](https://www.reddit.com/submit?url=https%3A//api.llmnet.nl/token-bucket-algoritme-llm-gateway&title=Token%20Bucket%20Algoritme%20in%20een%20LLM-Gateway%3A%20Praktische%20Gids)[Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A//api.llmnet.nl/token-bucket-algoritme-llm-gateway)[Kopieer link](#)

# Token bucket toepassen in een LLM-gateway

Door Ivo Donker — samengesteld met AI-ondersteuning (Claude & Gemini) · Laatst bijgewerkt: 6 augustus 2026

Het beheren van de stroom verzoeken naar Large Language Models (LLM's) stelt ontwikkelaars voor unieke uitdagingen. Waar traditionele API-gateways volstaan met het tellen van het aantal verzoeken per minuut, vereist de verwerking van taalmodellen een fundamenteel andere benadering. Het verwerken van een korte zoekopdracht kost immers een fractie van de rekenkracht die nodig is voor het samenvatten van een compleet document. Om overbelasting en onverwachte kosten te voorkomen, is het toepassen van het token bucket-algoritme binnen de LLM-gateway de aangewezen methode.

In dit artikel behandelen we de werking van de token bucket, waarom standaard verzoeklimieten tekortschieten, hoe je omgaat met onzekere invoer- en uitvoerlengtes, en op welke manier je dit algoritme schaalbaar implementeert binnen een gedistribueerde architectuur.

## Waarom standaard verzoeklimieten tekortschieten

Traditionele API-gateways maken veelal gebruik van verzoekgebaseerde snelheidsbeperkingen, zoals maximaal honderd verzoeken per minuut (Requests Per Minute of RPM). Bij een standaard REST-API levert dit een voorspelbare belasting op, omdat elke API-endpoint een vergelijkbare hoeveelheid rekenkracht of databankcapaciteit vraagt.

Bij taalmodellen is die aanname ongeldig. De werkelijke belasting van een LLM-infrastructuur en de daaraan gekoppelde kosten worden niet bepaald door het aantal HTTP-aanroepen, maar door het aantal verwerkte tokens (zowel invoer- als uitvoertokens). Twee opeenvolgende verzoeken aan dezelfde gateway kunnen enorm uiteenlopen:

- Aanroep A: Een simpele gebruikersvraag van 15 tokens die resulteert in een kort antwoord van 20 tokens (totaal 35 tokens).

- Aanroep B: Een verzoek dat een uitgebreide systeem-prompt, meerdere documenten als context en een gegenereerde analyse van 3000 tokens omvat (totaal 35.000 tokens).

Wanneer een gateway uitsluitend begrenst op verzoeken, telt Aanroep A net zo zwaar mee als Aanroep B. Hierdoor kan een enkele gebruiker met omvangrijke prompts de volledige capaciteit van een upstream API-provider uitputten of torenhoge rekeningen veroorzaken, terwijl hij formeel binnen zijn verzoeks-quota blijft. Het is daarom noodzakelijk om te begrenzen op het daadwerkelijke verbruik van de onderliggende bron: het aantal tokens per tijdseenheid (Tokens Per Minute of TPM).

## Het token bucket-concept in gewone taal

Het token bucket-algoritme is een beproefd mechanisme uit de netwerkwereld om gegevensstromen te reguleren. Je kunt de werking visualiseren als een fysieke emmer waarin met een vast, constant tempo digitale tokens worden gegoten.

Het algoritme werkt op basis van drie vaste principes:

- De emmercapaciteit (Burst Size): De emmer heeft een maximale inhoud. Boven dit niveau stroomt de emmer over; overtollige tokens die worden toegevoegd gaan verloren. Dit bepaalt de maximale piekbelasting die in één keer mag worden verbruikt.

- Het bijvultempo (Refill Rate): Er worden continu tokens aan de emmer toegevoegd met een vooraf ingestelde snelheid, bijvoorbeeld een vast aantal tokens per seconde. Dit tempo bepaalt de gemiddelde doorvoer op de lange termijn.

- Consumptie vooraf: Voordat een verzoek wordt doorgestuurd naar het LLM, moet de client het vereiste aantal tokens uit de emmer halen. Zijn er voldoende tokens aanwezig, dan wordt het aantal afgetrokken en gaat het verzoek door. Zijn er te weinig tokens, dan wordt het verzoek geweigerd of in een wachtrij geplaatst.

Het grote voordeel van de token bucket is de flexibiliteit: het staat korte, hevige pieken in het verkeer toe zolang er nog voorraad in de emmer zit, maar dwingt over een langere periode onverbiddelijk het gemiddelde bijvultempo af.

## De emmergrootte als cruciale ontwerpkeuze

De balans tussen de maximale emmercapaciteit en het bijvultempo is de belangrijkste parameter bij het inrichten van een LLM-gateway. De keuzes die je hierin maakt hebben een rechtstreekse invloed op de gebruikerservaring en de stabiliteit van de backend.

Ontwerpalternatieven bij emmergrootte:
Een te kleine emmer blokkeert legitiem piekverkeer, zoals een gebruiker die een groot document uploadt. Een te grote emmer stelt een enkele client in staat om binnen een fractie van een seconde de complete dag- of minuutcapaciteit van de gateway op te souperen, waardoor andere gebruikers op foutmeldingen stuiten.

Bij het bepalen van de emmercapaciteit analyseer je het verwachte patroon van de applicatie. Voor een interactieve chattoepassing is een relatief lage emmercapaciteit met een snelle bijvultijd geschikter, omdat verzoeken klein en frequent zijn. Voor verwerkingstaken in de achtergrond (batch-verwerking) is juist een grotere emmercapaciteit vereist om grote documenten in één keer te kunnen accepteren, waarbij de verwerking daarna over een langere tijd kan worden uitgesmeerd.

## Het kernprobleem bij LLM's: Onzekerheid vooraf

In een traditionele netwerkcontext weet de gateway exact hoeveel bytes een pakket groot is voordat het wordt doorgelaten. Bij LLM-aanroepen geldt dit niet. De lengte van de invoer-prompt is nauwkeurig te berekenen met een tokenizer, maar het aantal uitvoertokens dat het model zal genereren is vooraf niet met zekerheid bekend.

Om dit op te lossen hanteren geavanceerde gateways een reserverings- en verrekeningscyclus. Deze cyclus bestaat uit drie stappen:

Fase | 
Actie in de Gateway | 
Omschrijving | 

1. Reservering | 
Trek geschat aantal tokens af | 
De gateway telt de exacte invoertokens en telt daar de ingestelde max_tokens-parameter (of een heuristieke schatting) bij op. Dit totaal wordt direct gereserveerd uit de emmer. | 

2. Uitvoering | 
Stuur verzoek naar provider | 
Het verzoek wordt doorgestuurd naar de upstream modelaanbieder en verwerkt. | 

3. Verrekening | 
Corrigeer het werkelijke verbruik | 
Na afloop leest de gateway het exacte tokenverbruik uit de API-respons. Het verschil tussen de reservering en het werkelijke verbruik wordt teruggegeven aan de emmer (bij een overschatting) of extra afgetrokken (bij een onderschatting). | 

In situaties waarin de API-provider geen limiet oplegt via max_tokens, is de gateway genoodzaakt om op basis van historische gegevens van vergelijkbare prompts een schatting te maken van de uitvoerlengte. Het doordacht inrichten van deze schattingen voorkomt dat de emmer onnodig lang geblokkeerd blijft door overmatige reserveringen.

Voor een breed overzicht van hoe verschillende aanbieders tokens en verbruik consolideren, kun je ons artikel over [token usage normalisatie bij providers](https://api.llmnet.nl/token-usage-normalisatie-providers) raadplegen.

## Omgaan met een negatieve emmerstand

Wanneer de initiële schatting van het aantal uitvoertokens te laag was, kan de verrekening achteraf tot een opmerkelijke situatie leiden: het werkelijke verbruik blijkt groter dan de gereserveerde hoeveelheid, waardoor de emmerstand onder nul zakt.

Het is uitdrukkelijk geen goede praktijk om een reeds gestarte of afgeronde streaming-respons af te breken op het moment dat de emmer negatief wordt. Dit leidt tot een slechte gebruikerservaring en verspilde rekenkracht, aangezien de upstream provider de reeds gegenereerde tokens immers toch in rekening brengt.

De correcte afhandeling van een negatieve emmerstand is als volgt:

- Accepteer de negatieve waarde: Laat de emmerstand zakken tot onder nul (bijvoorbeeld -200 tokens).

- Blokkeer vervolgverzoeken: Zolang het saldo van de emmer negatief is, worden nieuwe verzoeken van de betreffende client geweigerd of gecachet.

- Herstel via bijvulling: Pas wanneer het automatische bijvultempo het saldo weer boven het vereiste drempelniveau voor een nieuw verzoek heeft gebracht, wordt de client weer toegelaten.

Op deze manier incasseert het systeem de overschrijding achteraf, zonder dat lopende processen abrupt worden onderbroken.

## Hiërarchische emmers: Meerdere niveaus naast elkaar

In een professionele productie-omgeving volstaat een enkele emmer per gebruiker niet. Om overbelasting op verschillende lagen in de keten te voorkomen, past een LLM-gateway hiërarchische limieten toe. Een verzoek moet door meerdere emmers achter elkaar worden goedgekeurd voordat het naar de upstream provider wordt gestuurd.

Een veelvoorkomende gelaagdheid omvat de volgende niveaus:

- Gebruikersniveau (Per User/API Key): Voorkomt dat één individuele gebruiker het budget van een organisatie of applicatie opmaakt.

- Team- of Afdelingsniveau (Per Tenant/Group): Garandeert dat een specifiek team niet de capaciteit van de gehele organisatie claimt.

- Aanbiedersniveau (Per Provider/Model): Beveiligt het centrale account bij de modelaanbieder (zoals OpenAI of Anthropic). Dit niveau voorkomt dat de totale organisatie de door de aanbieder opgelegde TPM-limieten overschrijdt.

Bij elke binnenkomende aanroep controleert de gateway of er in alle toepasselijke emmers voldoende capaciteit beschikbaar is voor de initiële reservering. Als ook maar één emmer onvoldoende saldo heeft, wordt het verzoek tegengehouden. Mocht je overwegen om een dergelijke architectuur in te richten op eigen infrastructuur, lees dan meer in de handleiding over een [LLM-gateway zelf hosten](https://api.llmnet.nl/llm-gateway-zelf-hosten).

## Streaming responsen en voorttijdige afbreking

Bij het gebruik van streaming (Server-Sent Events) worden tokens stuk voor stuk van de modelaanbieder naar de client gestuurd. Dit stelt de gateway in staat om het verbruik tijdens het genereren live bij te houden.

Indien er vooraf geen harde reservering is gemaakt of wanneer een client met een zeer krap budget werkt, kan de gateway het aantal binnenkomende stream-chunks tellen. Zodra het toegestane limiet binnen de sessie wordt bereikt, grijpt de gateway in:

- Gecontroleerde sluiting: De gateway stopt met het doorsturen van nieuwe tokens van de provider naar de client.

- Aflsuitsignaal invullen: De gateway stuurt een net sluitingsbericht (zoals een specifieke finish_reason: "length" of een aangepast foutbericht) naar de client, zodat de client-applicatie weet dat het antwoord is afgekapt vanwege een bereikte limiet.

- Upstream annulering: De HTTP-verbinding met de upstream provider wordt direct verbroken om het nutteloos gegenereerd van verdere tokens stop te zetten en zo onnodige kosten te vermijden.

Voor diepere inzichten in de netwerktechnische aspecten van dit proces, verwijzen we naar onze gids over [streaming responses](https://api.llmnet.nl/streaming-responses).

## Gedistribueerde opslag en atomaire bijwerkingen

Moderne API-gateways draaien zelden op één enkele server; ze zijn geschaald over meerdere instanties of containers. Dit betekent dat de status van de token emmers niet in het lokale geheugen van een enkele instantie kan worden bijgehouden, maar in een centraal en snel opslagsysteem moet worden geplaatst, zoals Redis of KeyDB.

Bij een gedistribueerde architectuur ontstaat het risico op race conditions: twee gateway-instanties lezen tegelijkertijd een emmerstand van 500 tokens, keuren allebei een verzoek van 400 tokens goed, en schrijven vervolgens een verkeerde eindstand weg. Hierdoor wordt de limiet overschreden.

Om dit te voorkomen moeten alle operaties op de emmer atomair worden uitgevoerd. Dit wordt in de praktijk op twee manieren gerealiseerd:

- Lua-scripts binnen de databank: Zowel het berekenen van de bijgevulde tokens op basis van de verstreken tijd, het controleren van het saldo, als het aftrekken van de gereserveerde tokens wordt uitgevoerd binnen één enkel Lua-script direct op de In-Memory databank. Dit garandeert dat geen enkele andere instantie de emmerstand kan wijzigen tijdens de berekening.

- Lazy Evaluation (Luie berekening): In plaats van een achtergrondproces te laten draaien dat elke seconde miljoenen emmers bijvult, wordt de emmerstand pas berekend op het moment dat er een verzoek binnenkomt. Het script pakt de vorige status, berekent hoeveel tijd er is verstreken sinds het laatste verzoek, vermenigvuldigt die tijd met de bijvulsnelheid, telt dat op bij het oude saldo (met een maximum van de emmercapaciteit) en voert vervolgens de consumptie uit.

## Wat stuur je terug naar de client?

Wanneer een verzoek wordt geweigerd omdat een emmer leeg is, moet de gateway de client van voldoende informatie voorzien om de situatie op een nette manier op te vangen. Dit voorkomt dat vastgelopen clients onnodig de gateway blijven bestoken met nieuwe aanroepen.

Een goed ingerichte gateway retourneert de standaard HTTP-statuscode 429 Too Many Requests, aangevuld met specifieke HTTP-headers:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
X-RateLimit-Limit-Tokens: 100000
X-RateLimit-Remaining-Tokens: 0
X-RateLimit-Reset-Tokens: 12s

{
 "error": {
 "code": "rate_limit_exceeded",
 "message": "Token capaciteit overschreden. Probeer het opnieuw over 12 seconden.",
 "type": "tokens"
 }
}

De velden in deze respons hebben een duidelijke functie:

- Retry-After: Het aantal seconden dat de client minimaal moet wachten voordat de emmer weer voldoende is bijgevuld voor een gemiddelde aanroep.

- X-RateLimit-Remaining-Tokens: De huidige beschikbare capaciteit (in dit geval nul).

- X-RateLimit-Reset-Tokens: De exacte tijd waarna de emmer weer volledig is gevuld.

Wanneer de client deze headers correct interpreteert, kan hij een geautomatiseerde pauze inlassen. Zie voor strategische patronen rondom herhaalpogingen ons artikel over [retries en backoff](https://api.llmnet.nl/retries-en-backoff).

## Verhouding tot provider-budgetten: Conservatief begrenzen

Een cruciale fout bij het inrichten van een eigen LLM-gateway is het exact overnemen van de limieten die de upstream provider (zoals OpenAI of Anthropic) op jouw account heeft ingesteld. Als een provider jou een limiet geeft van 150.000 TPM, is het onverstandig om de interne token buckets van de gateway eveneens af te stellen op 150.000 TPM.

Er zijn verschillende redenen om de interne limieten van je gateway conservatiever in te stellen dan de harde limieten van de provider:

- Netwerk-latency en synchronisatievertraging: Er zit altijd een kleine vertraging tussen het moment van meten in de gateway en het verwerken bij de provider. Bij extreme pieken kan dit leiden tot een lichte overschrijding aan de kant van de provider.

- Verschillen in tokenizers: Als de gateway een snelle, benaderende tokenizer gebruikt om de invoer te berekenen, kan er een gering afwijkingspercentage ontstaan ten opzichte van de officiële tokenizer van de provider.

- Buffer voor beheertaken: Door een marge aan te houden (bijvoorbeeld door de gateway in te stellen op 85-90% van de provider-limiet), behoud je capaciteit voor kritieke systeem-prompts, interne monitoring of beheerderstaken die nooit geblokkeerd mogen worden.

Bovendien spelen de kosten per taak een belangrijke rol bij het bepalen van de financiële plafonds die je in de gateway opneemt per gebruiker of team. Meer informatie over de verdeling van kosten vindt u in het overzicht over [kosten per taak](https://benchmark.llmnet.nl/kosten-per-taak).

## Conclusie

Het token bucket-algoritme is een onmisbaar onderdeel van een moderne LLM-gateway. Door te sturen op tokens in plaats van verzoeken, speel je in op de variabele belasting die inherent is aan taalmodellen. Het combineren van een initiële reservering met een verrekening achteraf, het opvangen van negatieve emmerstanden en het atomair uitvoeren van statussynchronisaties in Redis zorgt voor een robuuste infrastructuur. Door heldere limieten en accurate HTTP-headers terug te koppelen aan de client, blijft de gehele applicatieketen stabiel, voorspelbaar en financieel beheersbaar.

## Lees ook

- [Token usage normalisatie bij providers](https://api.llmnet.nl/token-usage-normalisatie-providers)

- [LLM-gateway zelf hosten](https://api.llmnet.nl/llm-gateway-zelf-hosten)

- [Streaming responses afhandelen](https://api.llmnet.nl/streaming-responses)

- [Retries en backoff strategieën](https://api.llmnet.nl/retries-en-backoff)

- [Kosten per taak analyseren](https://benchmark.llmnet.nl/kosten-per-taak)

llmnet.nl - LLM-aggregatie en API-integratie