Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Upotusrajapinta: Mallit ja ulottuvuudet

Oppitunti 2 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tavoitteet
  2. Peruskutsu
  3. Kaksi saatavilla olevaa mallia
  4. Erien käsittely (Batching)
  5. Ulottuvuuksien vähentäminen
  6. Tokenien hallinta
  7. Keskeiset asiat

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.

UlottuvuudetSuhteellinen laatuTallennustilaKäyttötarkoitus
3 072100 %~24 ktKorkean tarkkuuden haku
1 536~98 %~12 ktHyvä yleinen kompromissi
512~93 %~4 ktSuuri volyymi, alhaiset kustannukset
256~88 %~2 ktPrototyyppaus, 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 ja text-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