Az Embeddings API: Modellek és dimenziók
Ezen az oldalon
Célok
- Sajátítsd el a
client.embeddings.create()hívást - Értsd meg a különbségeket az egyes embedding modellek között
- Alkalmazz dimenziócsökkentést
Az alapvető hívás
Az OpenAI teljes Embeddings API-ja egyetlen metódusra épül: client.embeddings.create(). Egy szöveges karakterláncot és egy modellnevet adsz át neki:
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]
A visszakapott objektum nem maga a vektor, hanem egy burkoló, amely több vektort tartalmaz, mivel az API kötegek (batch) kezelésére lett tervezve. Benne megtalálod a data mezőt, ami objektumok listája; mindegyik rendelkezik egy embedding mezővel (maga a vektor) és egy index mezővel (a pozíciója a elküldött kötegben); továbbá a model mezőt, ami a ténylegesen használt modellt jelöli, valamint a usage.prompt_tokens értéket, ami a számlázott tokenek számát mutatja. Ezt az utóbbi mezőt az első naptól kezdve naplóznod kell: ez az egyetlen megbízható mérőszám arra, mennyibe kerül az indexelésed.
A két elérhető modell
A text-embedding-3-large a nagy teljesítményű modell. 3072 dimenziója a legfinomabb szemantikai árnyalatokat is rögzíti, így ideális nagy korpuszok kereséséhez, igényes RAG folyamatokhoz, és általában minden olyan esethez, ahol a pontosság fontosabb a költségeknél. Ha a felhasználó közvetett módon fogalmazza meg a kérdéseit, vagy a dokumentumaid sűrű technikai témákat fednek le, észreveszed a különbséget a találatok rangsorolásában.
A text-embedding-3-small kompaktabb, 1536 dimenzióval rendelkezik, és kiváló ár-érték arányt kínál. Ez a helyes választás szövegosztályozáshoz, ajánlórendszerekhez, gyors prototípuskészítéshez és nagy volumenű alkalmazásokhoz, ahol a cél nem két szinte azonos dokumentum megkülönböztetése, hanem egyértelműen eltérő témák szétválasztása. Egy egyszerű ciklus ellenőrzi, mit ad vissza mindkettő:
# Compare the two models
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")
Kötegelt embeddingek
Egy valós korpuszt nem szövegenként indexelsz: minden HTTP-hívás egy oda-vissza hálózati utat jelent, és ezer dokumentum egyenkénti feldolgozása ezer késleltetés összegződését eredményezi. Az API egyetlen hívásban legfeljebb 2048 szöveget fogad el, az index mező pedig lehetővé teszi, hogy minden vektort visszarendelj a megfelelő dokumentumhoz.
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}")
A gyakorlatban csoportosítsd a szövegeidet 100 és 2048 közötti kötegekbe a volumened függvényében: a kisebb kötegek megkönnyítik a helyreállítást hibák esetén, míg a nagyobbak csökkentik a hívások számát. Minden iterációnál figyeld a usage.prompt_tokens értéket, hogy menet közben becsüld meg a költségeket, ne pedig a számlán szembesülj velük, és valósíts meg exponenciális visszalépéses (exponential backoff) újrapróbálkozást: a sebességkorlát túllépése átmeneti hiba, nem ok arra, hogy megszakíts egy háromórás indexelési feladatot.
Dimenziócsökkentés
A text-embedding-3-* modellek elfogadnak egy dimensions paramétert, amely a natív méretüknél rövidebb vektorokat ad vissza:
# Full vector: 3072 dimensions
full = client.embeddings.create(
input="Reduction test",
model="text-embedding-3-large"
)
# Reduced vector: 256 dimensions
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
A mechanizmus egyszerű: a csökkentés levágja a vektort, majd újra-normalizálja azt. Mivel az első dimenziók hordozzák a legtöbb információt, a minőségromlás nagyon fokozatos marad. Az alábbi táblázat szabványos referenciaértékeket kínál a minőség és a tárhely közötti kompromisszumhoz.
| Dimensions | Relative Quality | Storage | Use Case |
|---|---|---|---|
| 3,072 | 100% | ~24 KB | High-precision search |
| 1,536 | ~98% | ~12 KB | Good general compromise |
| 512 | ~93% | ~4 KB | High volume, reduced cost |
| 256 | ~88% | ~2 KB | Prototyping, simple classification |
Ne feledd: a dimenzióválasztásod kötött pályát jelent: egy adott indexen belül minden vektornak azonos méretűnek kell lennie, és a meggondolásod megváltoztatása mindennek újraszámítását igényli.
Tokenkezelés
Az embedding modellek szövegenként maximum 8191 tokent engedélyeznek, és az API hibát dob, ha túlléped ezt. Jobb mérni elküldés előtt, mintsem kivételt elkapni egy köteg közepén:
import tiktoken
encoder = tiktoken.get_encoding("cl100k_base")
text = "A potentially long text..."
tokens = encoder.encode(text)
if len(tokens) > 8191:
# Truncate
truncated_text = encoder.decode(tokens[:8191])
print(f"Text truncated from {len(tokens)} to 8191 tokens")
A csonkítás biztonsági háló, nem stratégia: egy csonkított hosszú dokumentum elveszíti a végét, a vég pedig gyakran tartalmazza a keresett választ. A nagy dokumentumok megfelelő kezelése a darabolást (chunking) igényli, amivel a tanfolyam későbbi részében foglalkozunk.
Főbb megállapítások
- A
client.embeddings.create()elfogad egyetlen szöveget vagy szövegek listáját - Használd a
text-embedding-3-large(3072 dim) modellt a pontosság érdekében, atext-embedding-3-small(1536 dim) modellt pedig a költséghatékonyság miatt - A
dimensionsparaméter lehetővé teszi a vektorméret csökkentését - A szövegek kötegelt feldolgozása hatékonyabb, mint az egyesével történő hívás
- Szövegenkénti limit: 8191 token