Przejdź do głównej treści
Polski— Wybierz język
Menu

API Embeddings: Modele i Wymiary

Lekcja 2 z 22 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Cele
  2. Podstawowe wywołanie
  3. Dwa dostępne modele
  4. Embeddingi wsadowe
  5. Redukcja wymiarowości
  6. Zarządzanie tokenami
  7. Kluczowe wnioski

Cele

  • Opanuj wywołanie client.embeddings.create()
  • Zrozum różnice między modelami embeddingów
  • Wykorzystaj redukcję wymiarowości

Podstawowe wywołanie

Całe API Embeddings od OpenAI sprowadza się do jednej metody: client.embeddings.create(). Przekazujesz jej ciąg tekstowy i nazwę 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]

Zwracany obiekt nie jest samym wektorem, lecz kontenerem zawierającym wiele wektorów, ponieważ API zostało zaprojektowane do obsługi wsadów (batchy). Wewnątrz znajdziesz pole data – listę obiektów, z których każdy zawiera pole embedding (wektor) oraz index (jego pozycja w wysłanym wsadzie); pole model wskazujące faktycznie użyty model oraz usage.prompt_tokens, czyli liczbę rozliczanych tokenów. To ostatnie pole powinieneś logować od pierwszego dnia: to jedyne wiarygodne źródło informacji o kosztach indeksowania.

Dwa dostępne modele

text-embedding-3-large to model wysokiej wydajności. Jego 3072 wymiary wychwytują najdrobniejsze niuanse semantyczne, co czyni go idealnym do przeszukiwania dużych korpusów, wymagających potoków RAG i ogólnie wszelkich przypadków, gdzie precyzja przeważa nad kosztem. Jeśli użytkownik formułuje pytania pośrednio lub Twoje dokumenty obejmują gęstą domenę techniczną, zauważysz różnicę w rankingu wyników.

text-embedding-3-small jest bardziej zwarty, ma 1536 wymiarów i oferuje doskonały stosunek ceny do wydajności. To właściwy wybór do klasyfikacji tekstu, systemów rekomendacji, szybkiego prototypowania i aplikacji o dużej skali, gdzie celem nie jest rozróżnianie dwóch niemal identycznych dokumentów, lecz oddzielenie wyraźnie różnych tematów. Prosta pętla pozwala zweryfikować, co zwraca każdy z nich:

# Porównanie dwóch modeli
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")

Embeddingi wsadowe

Nie indeksujesz prawdziwego korpusu tekst po tekście: każde wywołanie HTTP kosztuje podróż w obie strony sieci (round-trip), a przetwarzanie tysiąca dokumentów indywidualnie oznacza skumulowanie tysiąca opóźnień. API akceptuje do 2048 tekstów w jednym wywołaniu, a pole index pozwala odwzorować każdy wektor z powrotem na właściwy 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}")

W praktyce grupuj teksty w wsady od 100 do 2048, w zależności od wolumenu: mniejsze wsady ułatwiają odzyskiwanie po awariach, podczas gdy większe redukują liczbę wywołań. Monitoruj usage.prompt_tokens przy każdej iteracji, aby na bieżąco szacować koszty, zamiast odkrywać je na fakturze, i wdróż mechanizm ponawiania z wykładniczym opóźnieniem (exponential backoff): przekroczenie limitu szybkości to błąd przejściowy, a nie powód do przerywania trzygodzinnego zadania indeksowania.

Redukcja wymiarowości

Modele z rodziny text-embedding-3-* akceptują parametr dimensions, który zwraca wektory krótsze niż ich natywny rozmiar:

# Pełny wektor: 3072 wymiary
full = client.embeddings.create(
    input="Reduction test",
    model="text-embedding-3-large"
)

# Wektor zredukowany: 256 wymiarów
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

Mechanizm jest prosty: redukcja obcina wektor, a następnie ponownie go normalizuje. Ponieważ pierwsze wymiary niosą najwięcej informacji, degradacja jakości jest bardzo stopniowa. Poniższa tabela przedstawia standardowe punkty odniesienia dla kompromisu między jakością a przechowywaniem.

WymiaryWzględna jakośćPrzechowywaniePrzypadek użycia
3 072100%~24 KBWyszukiwanie wysokiej precyzji
1 536~98%~12 KBDobry ogólny kompromis
512~93%~4 KBDuży wolumen, obniżony koszt
256~88%~2 KBPrototypowanie, prosta klasyfikacja

Pamiętaj, że wybór wymiarowości wiąże Ci ręce: wszystkie wektory w danym indeksie muszą mieć ten sam rozmiar, a zmiana zdania wymaga przeliczenia wszystkiego od nowa.

Zarządzanie tokenami

Modele embeddingów mają limit 8191 tokenów na tekst, a API zwróci błąd, jeśli go przekroczysz. Lepiej zmierzyć długość przed wysłaniem niż łapać wyjątek w środku przetwarzania wsadu:

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

text = "A potentially long text..."
tokens = encoder.encode(text)

if len(tokens) > 8191:
    # Skróć
    truncated_text = encoder.decode(tokens[:8191])
    print(f"Text truncated from {len(tokens)} to 8191 tokens")

Skracanie to siatka bezpieczeństwa, a nie strategia: skrócony długi dokument traci swoją końcówkę, a to właśnie tam często znajduje się szukana odpowiedź. Właściwe obsługiwanie dużych dokumentów polega na dzieleniu ich na fragmenty (chunking), czym zajmiemy się później w kursie.

Kluczowe wnioski

  • client.embeddings.create() akceptuje pojedynczy tekst lub listę tekstów
  • Użyj text-embedding-3-large (3072 wym.) dla precyzji, a text-embedding-3-small (1536 wym.) dla oszczędności
  • Parametr dimensions pozwala zmniejszyć rozmiar wektora
  • Grupowanie tekstów we wsady jest wydajniejsze niż indywidualne wywołania
  • Limit to 8191 tokenów na tekst