API za ugradnje (Embeddings): modeli i dimenzije
Na ovoj stranici
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.
| Dimenzije | Relativna kvaliteta | Pohrana | Slučaj upotrebe |
|---|---|---|---|
| 3.072 | 100 % | ~24 KB | Pretraživanje visoke preciznosti |
| 1.536 | ~98 % | ~12 KB | Dobar opći kompromis |
| 512 | ~93 % | ~4 KB | Veliki obujam, smanjeni troškovi |
| 256 | ~88 % | ~2 KB | Prototipiranje, 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
dimensionsomogućuje smanjenje veličine vektora - Grupiranje tekstova u serije učinkovitije je od pojedinačnih poziva
- Ograničenje od 8.191 tokena po tekstu