Upotusrajapinta: Mallit ja ulottuvuudet
Tällä sivulla
Tavoitteet
- Hallitse
client.embeddings.create()-kutsu - Ymmärrä eroavaisuudet upotusmallien välillä
- Käytä ulottuvuuksien vähentämistä
Peruskutsu
Koko OpenAI:n upotusrajapinta mahtuu yhteen metodiin: client.embeddings.create(). Syötät sille merkkijonon ja mallin nimen:
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]
Palautettu objekti ei ole itse vektori, vaan kääre, joka sisältää useita vektoreita, koska rajapinta on suunniteltu käsittelemään eriä. Sen sisällä löydät kentän data, joka on luettelo objekteja; jokaisella on embedding-kenttä (vektori) ja index-kenttä (sen sijainti lähetetyssä erässä). Lisäksi mukana ovat model (käytetty todellinen malli) ja usage.prompt_tokens (laskutettujen tokenien määrä). Kirjaa tämä viimeksi mainittu kenttä heti alusta alkaen: se on ainoa luotettava mittari indeksointikustannuksillesi.
Kaksi saatavilla olevaa mallia
text-embedding-3-large on suorituskykyinen malli. Sen 3 072 ulottuvuutta tallentavat hienoimmat semanttiset vivahteet, mikä tekee siitä ihanteellisen suurten tekstikokoelmien hakuun, vaativiin RAG-putkiin ja yleisesti kaikkiin tapauksiin, joissa tarkkuus painaa enemmän kuin kustannukset. Jos käyttäjä muotoilee kysymyksensä epäsuorasti tai dokumenttisi kattavat tiheän teknisen aihealueen, näet eron siinä, miten tulokset järjestyvät.
text-embedding-3-small on kompaktimpi 1 536 ulottuvuudellaan ja tarjoaa erinomaisen hinta-laatusuhteen. Se on oikea valinta tekstiluokitteluun, suosituksiin, nopeaan prototyyppaukseen ja suuren volyymin sovelluksiin, joissa tavoitteena ei ole erottaa kahta lähes identtistä dokumenttia, vaan selkeästi erilaisia teemoja toisistaan. Yksinkertainen silmukka varmistaa, mitä kukin palauttaa:
# 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")
Erien käsittely (Batching)
Et indeksoi todellista tekstikokoelmaa yksi teksti kerrallaan: jokainen HTTP-kutsu maksaa verkkokierroksen, ja tuhannen dokumentin käsittely yksitellen tarkoittaa tuhannen viiveen kertymistä. Rajapinta hyväksyy jopa 2 048 tekstiä yhdessä kutsussa, ja index-kentän avulla voit mapittaa jokaisen vektorin takaisin oikeaan dokumenttiin.
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}")
Käytännössä ryhmittele tekstisi 100–2 048 tekstin eriin volyymisi mukaan: pienemmät erät helpottavat toipumista virhetilanteissa, kun taas suuremmat vähentävät kutsujen määrää. Seuraa usage.prompt_tokens-arvoa jokaisella iteraatiolla arvioidaksesi kustannuksia matkan varrella sen sijaan, että huomaisit ne jälkikäteen laskulta, ja toteuta eksponentiaalinen odotus uudelleenyrityksille: nopeusrajoituksen ylitys on ohimenevä virhe, ei syy keskeyttää kolmen tunnin indeksointityötä.
Ulottuvuuksien vähentäminen
text-embedding-3-*-mallit hyväksyvät dimensions-parametrin, joka palauttaa alkuperäistä lyhyempiä vektoreita:
# 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
Mekanismi on yksinkertainen: vähentäminen katkaisee vektorin ja normalisoi sen uudelleen. Koska ensimmäiset ulottuvuudet kantavat eniten informaatiota, laadun heikkeneminen on hyvin asteittaista. Alla oleva taulukko tarjoaa standardeja vertailuarvoja laadun ja tallennustilan väliselle kompromissille.
| Ulottuvuudet | Suhteellinen laatu | Tallennustila | Käyttötarkoitus |
|---|---|---|---|
| 3 072 | 100 % | ~24 kt | Korkean tarkkuuden haku |
| 1 536 | ~98 % | ~12 kt | Hyvä yleinen kompromissi |
| 512 | ~93 % | ~4 kt | Suuri volyymi, alhaiset kustannukset |
| 256 | ~88 % | ~2 kt | Prototyyppaus, yksinkertainen luokittelu |
Muista, että ulottuvuusvalintasi sitoo sinut: kaikilla vektoreilla tietyssä indeksissä on oltava sama koko, ja mielen muuttaminen vaatii kaiken uudelleenlaskennan.
Tokenien hallinta
Upotusmalleilla on 8 191 tokenin raja tekstiä kohden, ja rajapinta palauttaa virheen, jos ylität tämän. On parempi mitata ennen lähetystä kuin napata poikkeus keskellä erää:
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")
Katkaisu on varaverkko, ei strategia: katkaistu pitkä dokumentti menettää lopun, ja lopussa on usein etsimäsi vastaus. Suurten dokumenttien asianmukainen käsittely edellyttää pilkkomista, jota käsittelemme myöhemmin kurssilla.
Keskeiset asiat
client.embeddings.create()hyväksyy yhden tekstin tai listan tekstejä- Käytä
text-embedding-3-large-mallia (3 072 ulottuvuutta) tarkkuuteen jatext-embedding-3-small-mallia (1 536 ulottuvuutta) kustannustehokkuuteen dimensions-parametri mahdollistaa vektorikoon pienentämisen- Tekstien eristäminen on tehokkaampaa kuin yksittäiset kutsut
- Raja on 8 191 tokenia tekstiä kohden