Salt la conținutul principal
Română— Alege o limbă
Meniu

API-ul de Embeddings: Modele și Dimensiuni

Lecția 2 din 22 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Obiective
  2. Apelul de bază
  3. Cele două modele disponibile
  4. Embeddings în lot (Batch Embeddings)
  5. Reducerea dimensionalității
  6. Gestionarea tokenilor
  7. Puncte cheie

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.

DimensionsRelative QualityStorageUse Case
3,072100%~24 KBHigh-precision search
1,536~98%~12 KBGood general compromise
512~93%~4 KBHigh volume, reduced cost
256~88%~2 KBPrototyping, 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 și text-embedding-3-small (1.536 dim) pentru eficiența costurilor
  • Parametrul dimensions vă 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