Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

API pro vnoření: Modely a dimenze

Lekce 2 z 22 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Cíle
  2. Základní volání
  3. Dva dostupné modely
  4. Dávkové vnoření
  5. Redukce dimenzionality
  6. Správa tokenů
  7. Klíčové poznatky

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.

DimenzeRelativní kvalitaÚložištěPřípad použití
3 072100 %~24 KBVyhledávání s vysokou přesností
1 536~98 %~12 KBDobrý obecný kompromis
512~93 %~4 KBVysoký objem, nižší náklady
256~88 %~2 KBPrototypová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 dimensions umožňuje zmenšit velikost vektoru
  • Dávkování textů je efektivnější než jednotlivá volání
  • Limit 8 191 tokenů na text