API Embeddings: Modele i Wymiary
Na tej stronie
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.
| Wymiary | Względna jakość | Przechowywanie | Przypadek użycia |
|---|---|---|---|
| 3 072 | 100% | ~24 KB | Wyszukiwanie wysokiej precyzji |
| 1 536 | ~98% | ~12 KB | Dobry ogólny kompromis |
| 512 | ~93% | ~4 KB | Duży wolumen, obniżony koszt |
| 256 | ~88% | ~2 KB | Prototypowanie, 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, atext-embedding-3-small(1536 wym.) dla oszczędności - Parametr
dimensionspozwala zmniejszyć rozmiar wektora - Grupowanie tekstów we wsady jest wydajniejsze niż indywidualne wywołania
- Limit to 8191 tokenów na tekst