Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

De Embeddings API: Modellen en Dimensies

Les 2 van 22 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Doelstellingen
  2. De Basisaanroep
  3. De Twee Beschikbare Modellen
  4. Batch-embeddings
  5. Dimensiereductie
  6. Tokenbeheer
  7. Belangrijkste punten

Doelstellingen

  • De aanroep client.embeddings.create() onder de knie krijgen
  • De verschillen tussen embedding-modellen begrijpen
  • Dimensiereductie toepassen

De Basisaanroep

De volledige Embeddings API van OpenAI past in één enkele methode: client.embeddings.create(). U geeft hierin een tekststring en een modelnaam mee:

from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    input="Hello, how are you?",
    model="text-embedding-3-large"
)

embedding = response.data[0].embedding
print(f"Type: {type(embedding)}")        # list
print(f"Length: {len(embedding)}")      # 3072
print(f"Snippet: {embedding[:3]}")        # [0.023, -0.041, 0.012]

Het geretourneerde object is niet de vector zelf, maar een wrapper die meerdere vectoren bevat, omdat de API is ontworpen om batches te verwerken. Hierin vindt u data, een lijst met objecten waarbij elk een veld embedding (de vector) en een veld index (de positie in de verzonden batch) heeft; model, het daadwerkelijk gebruikte model; en usage.prompt_tokens, het aantal gefactureerde tokens. U moet dit laatste veld vanaf dag één loggen: het is de enige betrouwbare maatstaf voor uw indexeringskosten.

De Twee Beschikbare Modellen

text-embedding-3-large is het hoogwaardige model. De 3.072 dimensies vangen de fijnste semantische nuances, waardoor het ideaal is voor het doorzoeken van grote corpora, veeleisende RAG-pipelines en algemeen elk geval waarbij precisie zwaarder weegt dan kosten. Als een gebruiker vragen indirect formuleert of uw documenten een dicht technisch domein bestrijken, zult u het verschil merken in de rangschikking van de resultaten.

text-embedding-3-small is compacter met 1.536 dimensies en biedt een uitstekende prijs-kwaliteitverhouding. Het is de juiste keuze voor tekstclassificatie, aanbevelingen, snelle prototyping en toepassingen met een hoog volume waarbij het doel niet is om twee nagenoeg identieke documenten te onderscheiden, maar om duidelijk verschillende thema’s te scheiden. Een eenvoudige lus verifieert wat elk retourneert:

# Vergelijk de twee modellen
for model_name in ["text-embedding-3-small", "text-embedding-3-large"]:
    resp = client.embeddings.create(
        input="Artificial intelligence",
        model=model_name
    )
    vec = resp.data[0].embedding
    print(f"{model_name}: {len(vec)} dimensions")

Batch-embeddings

U indexeert een echt corpus niet tekst voor tekst: elke HTTP-aanroep kost een netwerkround-trip en het individueel verwerken van duizend documenten betekent het accumuleren van duizend latenties. De API accepteert tot 2.048 teksten in één enkele aanroep en het veld index stelt u in staat elke vector terug te koppelen aan het juiste document.

texts = [
    "Machine learning is advancing rapidly",
    "Deep learning is revolutionizing computer vision",
    "Vector databases store embeddings",
    "Python is the preferred language for data scientists"
]

response = client.embeddings.create(
    input=textes,
    model="text-embedding-3-large"
)

for item in response.data:
    print(f"Text {item.index}: vector of {len(item.embedding)} dimensions")

print(f"Tokens consumed: {response.usage.prompt_tokens}")

Groepeer uw teksten in de praktijk in batches van 100 tot 2.048, afhankelijk van uw volume: kleinere batches maken herstel na fouten eenvoudiger, terwijl grotere het aantal aanroepen verminderen. Monitor usage.prompt_tokens bij elke iteratie om kosten lopend in te schatten in plaats van ze pas op de factuur te ontdekken, en implementeer retries met exponentiële backoff: het overschrijden van een tarieflimiet is een tijdelijke fout, geen reden om een indexeringsklus van drie uur te onderbreken.

Dimensiereductie

De text-embedding-3-*-modellen accepteren een parameter dimensions die vectoren retourneert die korter zijn dan hun native grootte:

# Volledige vector: 3072 dimensies
full = client.embeddings.create(
    input="Reduction test",
    model="text-embedding-3-large"
)

# Gereduceerde vector: 256 dimensies
reduced = client.embeddings.create(
    input="Reduction test",
    model="text-embedding-3-large",
    dimensions=256
)

print(f"Full: {len(full.data[0].embedding)} dim")    # 3072
print(f"Reduced: {len(reduced.data[0].embedding)} dim")  # 256

Het mechanisme is eenvoudig: reductie kappt de vector af en normaliseert deze vervolgens opnieuw. Omdat de eerste dimensies de meeste informatie dragen, blijft de degradatie zeer geleidelijk. De onderstaande tabel biedt standaardbenchmarks voor het afwegen van kwaliteit tegen opslag.

DimensiesRelatieve KwaliteitOpslagUse Case
3.072100%~24 KBZoeken met hoge precisie
1.536~98%~12 KBGoed algemeen compromis
512~93%~4 KBHoog volume, lagere kosten
256~88%~2 KBPrototyping, eenvoudige classificatie

Onthoud dat uw dimensiekeuze bindend is: alle vectoren in een gegeven index moeten dezelfde grootte hebben en van gedachten veranderen vereist dat u alles opnieuw berekent.

Tokenbeheer

Embedding-modellen hebben een maximum van 8.191 tokens per tekst en de API retourneert een fout als u dit overschrijdt. Het is beter om te meten voordat u verzendt dan om midden in een batch een uitzondering af te vangen:

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

text = "A potentially long text..."
tokens = encoder.encode(text)

if len(tokens) > 8191:
    # Afkappen
    truncated_text = encoder.decode(tokens[:8191])
    print(f"Text truncated from {len(tokens)} to 8191 tokens")

Afkappen is een veiligheidsnet, geen strategie: een afgekapt lang document verliest zijn einde en vaak bevat juist het einde het antwoord dat u zoekt. Een juiste afhandeling van grote documenten involves chunking, wat we later in de cursus behandelen.

Belangrijkste punten

  • client.embeddings.create() accepteert een enkele tekst of een lijst met teksten
  • Gebruik text-embedding-3-large (3.072 dim) voor precisie, text-embedding-3-small (1.536 dim) voor kostenefficiëntie
  • De parameter dimensions stelt u in staat de vectorgrootte te verkleinen
  • Het batchen van teksten is efficiënter dan individuele aanroepen
  • Limiet van 8.191 tokens per tekst