API-ul de Embeddings: Modele și Dimensiuni
Pe această pagină
Obiective
- Stăpânirea apelului
client.embeddings.create() - Înțelegerea diferențelor dintre modelele de embedding
- Utilizarea reducerii dimensionalității
Apelul de bază
Întregul API de Embeddings de la OpenAI se rezumă la o singură metodă: client.embeddings.create(). Îi transmiteți un șir de text și numele unui model:
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]
Obiectul returnat nu este vectorul în sine, ci un wrapper care conține mai mulți vectori, deoarece API-ul este conceput să gestioneze loturi (batches). În interior, veți găsi data, o listă de obiecte unde fiecare are un câmp embedding (vectorul) și un câmp index (poziția sa în lotul trimis); model, modelul efectiv utilizat; și usage.prompt_tokens, numărul de tokeni facturați. Ar trebui să înregistrați (log) acest ultim câmp încă de la început: este singura măsură fiabilă a costurilor de indexare.
Cele două modele disponibile
text-embedding-3-large este modelul de înaltă performanță. Cele 3.072 de dimensiuni ale sale captează cele mai fine nuanțe semantice, făcându-l ideal pentru căutarea în corpusuri mari, pipeline-uri RAG exigente și, în general, orice caz în care precizia primează în fața costului. Dacă un utilizator formulează întrebări indirect sau documentele dumneavoastră acoperă un domeniu tehnic dens, veți observa diferența în modul în care sunt clasate rezultatele.
text-embedding-3-small este mai compact, cu 1.536 de dimensiuni, și oferă un raport preț-performanță excelent. Este alegerea potrivită pentru clasificarea textelor, recomandări, prototipare rapidă și aplicații cu volum mare, unde obiectivul nu este distingerea a două documente aproape identice, ci separarea temelor clar distincte. O simplă buclă verifică ce returnează fiecare:
# 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")
Embeddings în lot (Batch Embeddings)
Nu indexați un corpus real text cu text: fiecare apel HTTP costă o dus-întors prin rețea, iar procesarea a o mie de documente individual înseamnă acumularea a o mie de latențe. API-ul acceptă până la 2.048 de texte într-un singur apel, iar câmpul index vă permite să mapați fiecare vector la documentul corect.
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}")
În practică, grupați textele în loturi de 100 până la 2.048, în funcție de volumul dumneavoastră: loturile mai mici facilitează recuperarea după erori, în timp ce cele mai mari reduc numărul de apeluri. Monitorizați usage.prompt_tokens la fiecare iterație pentru a estima costurile pe măsură ce avansați, în loc să le descoperiți pe factură, și implementați reîncercări cu backoff exponențial: depășirea limitei de rată (rate limit) este o eroare tranzitorie, nu un motiv pentru a întrerupe o job de indexare de trei ore.
Reducerea dimensionalității
Modelele text-embedding-3-* acceptă un parametru dimensions care returnează vectori mai scurți decât dimensiunea lor nativă:
# 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
Mecanismul este simplu: reducerea trunchiază vectorul și apoi îl re-normalizează. Deoarece primele dimensiuni poartă cea mai mare parte a informației, degradarea rămâne foarte graduală. Tabelul de mai jos oferă repere standard pentru compromisul dintre calitate și stocare.
| 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 |
Rețineți că alegerea dimensionalității vă angajează pe termen lung: toți vectorii dintr-un index dat trebuie să aibă aceeași dimensiune, iar schimbarea deciziei necesită recalcularea tuturor datelor.
Gestionarea tokenilor
Modelele de embedding au o limită de 8.191 de tokeni per text, iar API-ul returnează o eroare dacă depășiți această valoare. Este mai bine să măsurați înainte de a trimite decât să prindeți o excepție în mijlocul unui lot:
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")
Trunchierea este o plasă de siguranță, nu o strategie: un document lung trunchiat își pierde finalul, iar finalul conține adesea răspunsul pe care îl căutați. Gestionarea corectă a documentelor mari implică segmentarea (chunking), pe care o vom aborda mai târziu în curs.
Puncte cheie
client.embeddings.create()acceptă un singur text sau o listă de texte- Utilizați
text-embedding-3-large(3.072 dim) pentru precizie șitext-embedding-3-small(1.536 dim) pentru eficiența costurilor - Parametrul
dimensionsvă permite să reduceți dimensiunea vectorului - Gruparea textelor în loturi este mai eficientă decât apelurile individuale
- Limita de 8.191 de tokeni per text