API pro vnoření: Modely a dimenze
Na této stránce
Cíle
- Zvládni volání
client.embeddings.create() - Pochopej rozdíly mezi modely pro vnoření
- Využij redukci dimenzionality
Základní volání
Celé API pro vnoření od OpenAI se vejde do jediné metody: client.embeddings.create(). Předáš jí textový řetězec a název modelu:
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]
Vrácený objekt není samotný vektor, ale obálka obsahující více vektorů, protože API je navrženo pro zpracování dávek. Uvnitř najdeš data, což je seznam objektů, kde každý má pole embedding (vektor) a pole index (jeho pozice v odeslané dávce); dále model, což je skutečný použitý model, a usage.prompt_tokens, tedy počet zpoplatněných tokenů. Toto poslední pole bys měl logovat od prvního dne: je to jediné spolehlivé měřítko toho, kolik tě indexace stojí.
Dva dostupné modely
text-embedding-3-large je vysoce výkonný model. Jeho 3 072 dimenzí zachycuje nejjemnější sémantické nuance, což z něj činí ideální volbu pro vyhledávání ve velkých korpusech, náročné RAG pipeline a obecně pro všechny případy, kde přesnost převyšuje cenu. Pokud uživatel formulují otázky nepřímo nebo vaše dokumenty pokrývají hustou technickou doménu, uvidíš rozdíl v tom, jak jsou výsledky řazeny.
text-embedding-3-small je kompaktnější s 1 536 dimenzemi a nabízí vynikající poměr ceny k výkonu. Je to správná volba pro klasifikaci textu, doporučení, rychlé prototypování a aplikace s vysokým objemem, kde cílem není rozlišit dva téměř identické dokumenty, ale oddělit jasně odlišná témata. Jednoduchá smyčka ověří, co každý z nich vrací:
# Porovnání dvou modelů
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")
Dávkové vnoření
Reálný korpus neindexuješ text po textu: každé HTTP volání stojí jeden síťový round-trip a zpracování tisíce dokumentů jednotlivě znamená akumulaci tisíce latencí. API přijme až 2 048 textů v jediném volání a pole index ti umožní mapovat každý vektor zpět ke správnému dokumentu.
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}")
V praxi seskupuj své texty do dávek o velikosti 100 až 2 048 v závislosti na svém objemu: menší dávky usnadňují obnovu po chybách, zatímco větší snižují počet volání. Sleduj usage.prompt_tokens při každé iteraci, abys odhadoval náklady průběžně, místo abys je zjistil až na faktuře, a implementuj exponenciální backoff pro opakování: překročení limitu rychlosti je přechodná chyba, nikoliv důvod k přerušení tříhodinové úlohy indexace.
Redukce dimenzionality
Modely řady text-embedding-3-* přijímají parametr dimensions, který vrací vektory kratší než jejich nativní velikost:
# Plný vektor: 3072 dimenzí
full = client.embeddings.create(
input="Reduction test",
model="text-embedding-3-large"
)
# Redukovaný vektor: 256 dimenzí
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
Mechanismus je jednoduchý: redukce vektor zkrátí a následně jej znovu normalizuje. Protože první dimenze nesou nejvíce informací, degradace kvality je velmi pozvolná. Níže uvedená tabulka poskytuje standardní referenční hodnoty pro kompromis mezi kvalitou a úložištěm.
| Dimenze | Relativní kvalita | Úložiště | Případ použití |
|---|---|---|---|
| 3 072 | 100 % | ~24 KB | Vyhledávání s vysokou přesností |
| 1 536 | ~98 % | ~12 KB | Dobrý obecný kompromis |
| 512 | ~93 % | ~4 KB | Vysoký objem, nižší náklady |
| 256 | ~88 % | ~2 KB | Prototypování, jednoduchá klasifikace |
Pamatuj, že volba dimenzí tě zavazuje: všechny vektory v daném indexu musí mít stejnou velikost a změna názoru vyžaduje přepočítání všeho od začátku.
Správa tokenů
Modely pro vnoření mají limit 8 191 tokenů na text a API vrátí chybu, pokud tento limit překročíš. Je lepší měřit před odesláním, než chytat výjimku uprostřed dávky:
import tiktoken
encoder = tiktoken.get_encoding("cl100k_base")
text = "A potentially long text..."
tokens = encoder.encode(text)
if len(tokens) > 8191:
# Zkrácení
truncated_text = encoder.decode(tokens[:8191])
print(f"Text truncated from {len(tokens)} to 8191 tokens")
Zkrácení je bezpečnostní síť, nikoliv strategie: zkrácený dlouhý dokument ztrácí svůj konec a konec často obsahuje odpověď, kterou hledáš. Správné zpracování velkých dokumentů zahrnuje rozdělování na části (chunking), kterým se budeme věnovat později v kurzu.
Klíčové poznatky
client.embeddings.create()přijímá jeden text nebo seznam textů- Pro přesnost použij
text-embedding-3-large(3 072 dim), pro efektivitu nákladůtext-embedding-3-small(1 536 dim) - Parametr
dimensionsumožňuje zmenšit velikost vektoru - Dávkování textů je efektivnější než jednotlivá volání
- Limit 8 191 tokenů na text