Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

API za ugradnje (Embeddings): modeli i dimenzije

Lekcija 2 od 22 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Ciljevi
  2. Osnovni poziv
  3. Dva dostupna modela
  4. Serijske ugradnje (Batch Embeddings)
  5. Smanjenje dimenzionalnosti
  6. Upravljanje tokenima
  7. Ključne točke

Ciljevi

  • Savladaj poziv client.embeddings.create()
  • Razumij razlike između modela za ugradnje
  • Koristi smanjenje dimenzionalnosti

Osnovni poziv

Cijeli OpenAI API za ugradnje stane u jednu metodu: client.embeddings.create(). Proslijediš joj tekstualni niz i naziv modela:

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]

Vraćeni objekt nije sam vektor, već omotač koji sadrži više vektora jer je API dizajniran za rukovanje serijama (batchevima). Unutra ćeš naći data, popis objekata gdje svaki ima polje embedding (vektor) i polje index (njegov položaj u poslanoj seriji); zatim model, stvarni korišteni model; i usage.prompt_tokens, broj naplaćenih tokena. Ovo zadnje polje moraš bilježiti od prvog dana: to je jedina pouzdana mjera troškova tvog indeksiranja.

Dva dostupna modela

text-embedding-3-large je model visokih performansi. Njegovih 3.072 dimenzije hvata najfinije semantičke nijanse, što ga čini idealnim za pretraživanje velikih korpusa, zahtjevne RAG cjevovode i općenito sve slučajeve gdje preciznost nadmašuje cijenu. Ako korisnik postavlja pitanja neizravno ili tvoji dokumenti pokrivaju gusto tehničko područje, vidjet ćeš razliku u rangiranju rezultata.

text-embedding-3-small kompaktniji je s 1.536 dimenzija i nudi izvrstan omjer cijene i performansi. Pravi je izbor za klasifikaciju teksta, preporuke, brzo prototipiranje i aplikacije velikog obujma gdje cilj nije razlikovati dva gotovo identična dokumenta, već razdvojiti jasno različite teme. Jednostavna petlja potvrđuje što svaki od njih vraća:

# 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")

Serijske ugradnje (Batch Embeddings)

Ne indeksiraš stvarni korpus tekst po tekst: svaki HTTP poziv košta jedan mrežni povratni put (round-trip), a obrada tisuću dokumenata pojedinačno znači akumuliranje tisuću kašnjenja. API prihvaća do 2.048 tekstova u jednom pozivu, a polje index omogućuje mapiranje svakog vektora natrag na ispravan dokument.

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}")

U praksi grupiraj svoje tekstove u serije od 100 do 2.048, ovisno o tvojem obujmu: manje serije olakšavaju oporavak nakon kvarova, dok veće smanjuju broj poziva. Prati usage.prompt_tokens u svakoj iteraciji kako bi procijenio troškove usput, umjesto da ih otkriješ na računu, i implementiraj ponovne pokušaje s eksponencijalnim kašnjenjem (exponential backoff): premašivanje ograničenja stope (rate limit) prolazna je pogreška, a ne razlog za prekid trosatnog posla indeksiranja.

Smanjenje dimenzionalnosti

Modeli text-embedding-3-* prihvaćaju parametar dimensions koji vraća vektore kraće od njihove izvorne veličine:

# 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

Mehanizam je jednostavan: smanjenje skraćuje vektor, a zatim ga ponovno normalizira. Budući da prve dimenzije nose najviše informacija, degradacija ostaje vrlo postupna. Tablica u nastavku pruža standardne referentne vrijednosti za kompromis između kvalitete i pohrane.

DimenzijeRelativna kvalitetaPohranaSlučaj upotrebe
3.072100 %~24 KBPretraživanje visoke preciznosti
1.536~98 %~12 KBDobar opći kompromis
512~93 %~4 KBVeliki obujam, smanjeni troškovi
256~88 %~2 KBPrototipiranje, jednostavna klasifikacija

Zapamti da te odabir dimenzije obvezuje: svi vektori u danom indeksu moraju imati istu veličinu, a promjena mišljenja zahtijeva ponovni izračun svega.

Upravljanje tokenima

Modeli za ugradnje imaju ograničenje od 8.191 tokena po tekstu, a API vraća pogrešku ako to prijeđeš. Bolje je izmjeriti prije slanja nego hvatati iznimku usred serije:

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")

Skraćivanje je sigurnosna mreža, a ne strategija: skraćeni dugi dokument gubi svoj kraj, a kraj često sadrži odgovor koji tražiš. Ispravno rukovanje velikim dokumentima uključuje cijepanje (chunking), što ćemo pokriti kasnije u tečaju.

Ključne točke

  • client.embeddings.create() prihvaća jedan tekst ili popis tekstova
  • Koristi text-embedding-3-large (3.072 dim) za preciznost, text-embedding-3-small (1.536 dim) za isplativost
  • Parametar dimensions omogućuje smanjenje veličine vektora
  • Grupiranje tekstova u serije učinkovitije je od pojedinačnih poziva
  • Ograničenje od 8.191 tokena po tekstu