De Embeddings API: Modellen en Dimensies
Op deze pagina
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.
| Dimensies | Relatieve Kwaliteit | Opslag | Use Case |
|---|---|---|---|
| 3.072 | 100% | ~24 KB | Zoeken met hoge precisie |
| 1.536 | ~98% | ~12 KB | Goed algemeen compromis |
| 512 | ~93% | ~4 KB | Hoog volume, lagere kosten |
| 256 | ~88% | ~2 KB | Prototyping, 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
dimensionsstelt u in staat de vectorgrootte te verkleinen - Het batchen van teksten is efficiënter dan individuele aanroepen
- Limiet van 8.191 tokens per tekst