Embeddings-API's in productie: limieten, kosten en doorvoer

In veel Retrieval-Augmented Generation (RAG) en zoektoepassingen ligt de focus vrijwel direct op het generatieve taalmodel dat het uiteindelijke antwoord formuleert. Toch vormt de achterliggende vectorrepresentatie van de data het fundament van het hele retrieval-systeem. Wie een proof-of-concept opschaalt naar een volwaardige productieomgeving ontdekt snel dat het genereren van vectoren via externe API's zijn eigen operationele uitdagingen kent. Dit artikel behandelt de specifieke doorvoerbeperkingen, rate limits, kostenbeheersing en foutafhandeling die komen kijken bij het grootschalig inzetten van embeddings-endpoints.

Waar een standaard chat-aanroep draait om sequentiële tokens en streaming interfaces, vereisen embeddings juist massale parallellisatie, strikte batchverwerking en een zorgvuldige afweging van dimensiegroottes. Wie wil begrijpen hoe de query-kant exact aansluit op vector-zoekopdrachten kan het fundament nalezen in semantisch zoeken bouwen met een embeddings-API. Hieronder richten we ons op de architectonische en infrastructurele vereisten om miljoenen tekstelementen stabiel en efficiënt om te zetten in vectoren.

De twee operationele profielen: bulk indexering versus realtime query's

In een productiesysteem vertonen embeddings-aanroepen twee volstrekt verschillende verkeerspatronen die niet over één kam geschoren kunnen worden: bulk indexering van documenten en realtime transformatie van zoekvragen van eindgebruikers.

Bulk indexering ontstaat wanneer een initieel gegevensbestand van duizenden of miljoenen documenten moet worden omgezet in vectoren, of wanneer periodieke sync-jobs draaien. Het verkeerspatroon is hier asynchroon, vereist maximale doorvoer (throughput), en is relatief tolerant voor wachttijden van enkele minuten of uren. Het hoofddoel is om zo dicht mogelijk tegen de maximale tokenlimieten van de provider aan te schuren zonder geblokkeerd te worden door HTTP 429-foutmeldingen.

Realtime query-verwerking ontstaat wanneer een gebruiker een zoekopdracht intypt. Hier telt uitsluitend de round-trip latency. De API-aanroep bevat meestal slechts één enkele zin van 10 tot 50 tokens, maar de vector moet binnen 50 tot 150 milliseconden beschikbaar zijn om de totale latentie van de applicatie acceptabel te houden. Als de beheerder dezelfde gateway-configuratie of wachtrij hanteert voor zowel bulkverwerking als realtime zoekvragen, leidt een achtergrondjob onherroepelijk tot onacceptabele wachttijden voor actieve gebruikers.

Doorvoer maximaliseren met micro-batching en chunk-optimalisatie

De meeste providers van embeddings-endpoints staan toe dat een array van invoerteksten in één enkel HTTP-verzoek wordt verstuurd. Het afzonderlijk versturen van losse tekstfragmenten (chunks) per HTTP-call introduceert enorme overhead door TLS-handshakes, TCP-roundtrips en header-parsing. Omgekeerd leidt het bundelen van te veel tekst in één request tot timeouts of het overschrijden van de maximale payloadgrootte.

De optimale batchgrootte is een dynamische balans tussen drie parameters:

• Aantal items per batch: Providers hanteren vaak een harde limiet, variërend van 96 tot 2048 tekstregels per request.
• Totaal aantal tokens per batch: Vaak geldt een gecombineerd plafond per request (bijvoorbeeld maximaal 8.192 of 32.768 tokens per call).
• Netwerk-payload en serialization: Grote JSON-arrays vereisen aanzienlijke CPU-capaciteit voor string-escaping en JSON-parsing aan zowel client- als serverzijde.

In productie implementeren we daarom een worker-pool met micro-batching. Een ingestiedienst verzamelt tekstfragmenten in een buffer en stuurt een batch af zodra óf het tokenplafond wordt bereikt (bijvoorbeeld 90% van het maximum om veiligheidsmarges aan te houden), óf een korte tijdslimiet (bijvoorbeeld 50 ms) verloopt.

Rate limits en concurrency: TPM versus RPM

Embeddings-API's hanteren striktere limieten dan vaak wordt verwacht. Providers scheiden de limieten over het algemeen in twee categorieën: Requests Per Minute (RPM) en Tokens Per Minute (TPM). Bij embeddings loop je bij bulkverwerking vrijwel altijd tegen de TPM-limiet aan lang voordat de RPM-grens in zicht komt.

Wanneer een applicatie parallelle workers start die direct data naar de API pompen, reageert de server bij een overschrijding met een 429 Too Many Requests statuscode. Zonder gestructureerde afhandeling kan dit leiden tot een zogeheten retry-storm, waarbij alle workers gelijktijdig opnieuw proberen te verzenden en het endpoint permanent verstopt raakt. Hoe je algemene limieten en prijsmodellen overkoepelend beheerst binnen een architectuur lees je in het overzicht over rate limits, tokens en kosten.

Voor embeddings-pipelines is het noodzakelijk om een client-side concurrency limiter of token bucket te draaien. Het onderstaande Python-voorbeeld toont een robuuste worker met dynamische micro-batching, lokale tokentelling en exponentiële backoff met jitter:

import time
import random
import urllib.request
import json

def batch_embed_texts(chunks, token_limit=8000, max_retries=5):
    """
    Verstuurt batches naar een embeddings-API met foutafhandeling.
    chunks is een lijst van dicts: [{'id': str, 'text': str, 'tokens': int}]
    """
    url = "https://api.provider.example/v1/embeddings"
    api_key = "SECURE_API_KEY"
    
    batches = []
    current_batch = []
    current_tokens = 0
    
    # 1. Dynamische micro-batching op basis van tokens
    for item in chunks:
        if current_tokens + item['tokens'] > token_limit and current_batch:
            batches.append(current_batch)
            current_batch = []
            current_tokens = 0
        current_batch.append(item)
        current_tokens += item['tokens']
    if current_batch:
        batches.append(current_batch)
        
    results = []
    
    # 2. Uitvoeren per batch met retry- en backoff-patroon
    for batch in batches:
        payload = json.dumps({
            "model": "text-embedding-3-small",
            "input": [b['text'] for b in batch]
        }).encode('utf-8')
        
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}"
        }
        
        attempt = 0
        success = False
        
        while attempt < max_retries and not success:
            req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
            try:
                with urllib.request.urlopen(req, timeout=30) as resp:
                    if resp.status == 200:
                        body = json.loads(resp.read().decode('utf-8'))
                        for idx, data_item in enumerate(body.get('data', [])):
                            results.append({
                                "id": batch[idx]['id'],
                                "embedding": data_item['embedding']
                            })
                        success = True
            except urllib.error.HTTPError as e:
                attempt += 1
                if e.code == 429:
                    # Exponentiële backoff met decorrelated jitter
                    sleep_time = (2 ** attempt) + (random.uniform(0.1, 1.0))
                    time.sleep(sleep_time)
                elif e.code >= 500:
                    time.sleep(1.0 * attempt)
                else:
                    # Client-fouten (400, 401, 403) direct escaleren
                    raise RuntimeError(f"API client-fout {e.code}: {e.read().decode('utf-8')}")
            except Exception as ex:
                attempt += 1
                time.sleep(1.5 * attempt)
                
        if not success:
            raise TimeoutError(f"Batch mislukt na {max_retries} pogingen.")
            
    return results

Kostenanalyse en dimensie-reductie (Matryoshka Embeddings)

De kosten van embeddings-API's worden bijna universeel afgerekend per miljoen tokens. Hoewel de eenheidsprijs per token aanzienlijk lager ligt dan bij generatieve LLM's, kunnen de totale operationele kosten snel escaleren bij grote datasets, regelmatige herindexering of frequente documentmutaties.

Bovendien zijn de API-kosten slechts één onderdeel van de totale kostenstructuur. De gekozen embedding-dimensie beïnvloedt rechtstreeks de geheugenkosten (RAM/VRAM) van de vector-database en de netwerklatentie tijdens vectoroverdracht. Moderne embeddings-modellen (zoals Matryoshka Representation Learning modellen) bieden de mogelijkheid om de output-dimensie in te korten (bijvoorbeeld van 1536 of 3072 vectoren naar 512 of 256) zonder substantieel verlies aan zoekrelevantie.

Het verlagen van de dimensie via de API-parameter verlaagt niet direct de API-factuur, maar halveert of verdrievoudigt de doorvoersnelheid van de vector-database en verlaagt de hostingkosten van de index drastisch. Het effect van modelkeuze op de totale retrieval-keten en wanneer een extra reranker noodzakelijk wordt, is uitgebreid beschreven in de gids over embedding, reranker of hybride retrieval-modellen.

Wat kost een mitigatie? Latentie, complexiteit en geheugen

Elke technische oplossing die wordt ingezet om faalmodi rond embeddings op te vangen, brengt een eigen prijs met zich mee. Het is belangrijk om deze trade-offs expliciet af te wegen:

• Client-side caching van embeddings: Door een hash van de invoertekst te koppelen aan de gegenereerde vector, voorkom je dubbele API-kosten voor identieke zinnen of veelvoorkomende zoektermen. De prijs: Verhoogde architectuurcomplexiteit (bijvoorbeeld een Redis-instantie) en geheugengebruik. Een cache-lookup voegt bovendien 1 tot 3 milliseconden toe aan elke query.
• Lokale fallback-modellen: Wanneer de externe API kampt met een storing, kan het systeem terugvallen op een lokaal gehost embedding-model (zoals een compact ONNX- of HuggingFace-model). De prijs: Lokale rekenkracht (CPU/GPU-belasting op applicatieservers) en semantische incompatibiliteit. Een vector gegenereerd door model A kan nooit rechtstreeks vergeleken worden met een vector van model B in dezelfde indexruimte.
• Dynamische batching en wachtrijen: Het bufferen van verzoeken verhoogt de efficiëntie richting de externe provider aanzienlijk. De prijs: Verhoogde p99-latentie voor individuele items in de wachtrij en extra faalpunten indien de worker-processen crashen voordat de buffer is geleegd.

Faalgedrag en data-integriteit in productie

In een continue productiepijplijn treden onvermijdelijk partiële fouten op. Denk aan een batch van 100 documenten waarin één document onzichtbare binaire data bevat die een 400 Bad Request triggert, of een netwerkverbinding die halverwege een stream wegvalt. Als de pipeline niet transactieveilig is ontworpen, leidt dit tot 'stille corruptie': documenten die wel als verwerkt staan gemarkeerd in de relationele database, maar waarvan de vectoren ontbreken in de vector-index.

Om data-integriteit te waarborgen, moet de ingestie-applicatie werken met een twee-fasen synchronisatie:

1. Genereer eerst de vector via de API en sla het resultaat tijdelijk op in een staging-tabel of cache.
2. Schrijf de vector pas definitief weg naar de vector-database met een unieke document-versie-hash.
3. Werk daarna pas de status in het bronsysteem bij naar 'geïndexeerd'.

Als een document wijzigt, moet de oude vector direct ongeldig worden gemaakt om verouderde zoekresultaten te voorkomen. De volledige levenscyclus van vector-opslag, updates en opschoonprocessen wordt behandeld in de handleiding over een vector-index onderhouden: embeddings opslaan, bijwerken en verwijderen.

Observability en monitoring van embeddings-endpoints

Omdat embeddings-API's vaak als zwarte doos worden aangeroepen, blijven prestatieverslechteringen regelmatig onopgemerkt totdat eindgebruikers klagen over trage zoekschermen. Een volwassen productie-architectuur monitort minimaal de volgende vier telemetrie-dimensies:

• P95 en P99 Latency per batchgrootte: Geeft inzicht in server-side wachtrijen bij de provider en signaleert wanneer de netwerkverbinding hapert.
• Token-consumptie per taaktype: Onderscheidt het tokenverbruik van achtergrond-ingestie van het verbruik door realtime zoekopdrachten.
• HTTP-statuscode distributie: Een toename in 429-fouten duidt op een tekortschietende client-side token bucket of onverwachte pieken in de gegevensaanvoer.
• Vector-kwaliteitsmetingen (dimensie- en norm-validatie): Controleer vóór opslag altijd of de geretourneerde array de verwachte lengte heeft (bijvoorbeeld exact 1536 getallen) en of de vector geen NaN- of null-waarden bevat.

Door embeddings-endpoints niet te behandelen als eenvoudige hulpmiddelen maar als bedrijfskritieke netwerkcomponenten met eigen limieten, kosten en faalmechanismen, blijft de retrieval-laag van je AI-applicatie stabiel, voorspelbaar en schaalbaar onder zware productiebelasting.