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

Tekstiluokittelu upotuksilla

Oppitunti 17 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tavoitteet
  2. Nolla-esimerkin luokittelu (Zero-shot)
  3. Muutaman esimerkin luokittelu (Few-shot)
  4. Kevyt valvottu luokittelija
  5. Lähestymistapojen vertailu
  6. Keskeiset asiat

Tavoitteet

  • Luokittele tekstiä kouluttamatta mallia
  • Toteuta nolla- ja muutaman esimerkin luokittelu upotuksia hyödyntäen
  • Vertaa suorituskykyä kevyeseen valvottuun luokittelijaan

Nolla-esimerkin luokittelu (Zero-shot)

Semanttinen haku löytää tuhansien ehdokkaiden joukosta kyselyä muistuttavia asiakirjoja. Luokittelu kääntää tämän asetelman muuttamatta taustalla olevaa mekanismia: “asiakirjasi” ovat nyt luokkiasi (viisi tai kymmenen kappaletta), ja “kysely” on teksti, jonka haluat luokitella. Ennusteeksi tulee se label, jonka upotus on lähimpänä. Ei koulutusta, ei annotoitua dataa, vain yksi API-kutsu.

Alla olevassa koodissa kaksi toteutusyksityiskohtaa ansaitsevat huomion. Ensinnäkin teksti ja luokkien nimet syötetään yhteen embeddings.create-kutsuun, mikä leikkaa viivettä labelien määrän verran. Toiseksi softmax-funktion soveltaminen samankaltaisuuspisteisiin muuntaa raaka-arvot (tyypillisesti välillä 0,3–0,5) todennäköisyyksiksi, joiden summa on 1. Voit näyttää nämä todennäköisyydet käyttäjälle tai verrata niitä luottamuskynnykseen.

from openai import OpenAI
import numpy as np

client = OpenAI()

def classifier_zero_shot(
    texte: str,
    categories: list[str],
    model: str = "text-embedding-3-large"
) -> dict:
    """Classifies text into categories without training."""
    # Embeddings for categories
    all_inputs = [texte] + categories
    response = client.embeddings.create(
        input=all_inputs,
        model=model
    )
    embs = [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    texte_emb = np.array(embs[0])
    cat_embs = np.array(embs[1:])

    # Similarity with each category
    scores = cat_embs @ texte_emb

    # Softmax to get probabilities
    exp_scores = np.exp(scores - np.max(scores))
    probas = exp_scores / exp_scores.sum()

    resultats = sorted(
        zip(categories, probas),
        key=lambda x: x[1], reverse=True
    )

    return {
        "prediction": resultats[0][0],
        "confiance": float(resultats[0][1]),
        "scores": {cat: float(p) for cat, p in resultats}
    }

# Usage
texte = "Le cours de l'action a chuté de 15% après l'annonce"
categories = ["Finance", "Sport", "Technologie", "Politique", "Santé"]

resultat = classifier_zero_shot(texte, categories)
print(f"Prédiction : {resultat['prediction']} "
      f"({resultat['confiance']:.1%})")
print("Scores :", resultat["scores"])

Tässä esimerkissä lause “osakekurssi laski 15 % ilmoituksen jälkeen” osuu yllättäen Finance-luokkaan. Lähestymistapa törmää rajoihin, kun luokat ovat sisäisiä labeleja, joiden nimet eivät paljasta mitään niiden sisällöstä. Label kuten “P1” tai “tason 2 eskalaatio” ei sisällä hyödynnettävää semanttista merkitystä, jolloin luokittelu on pohjimmiltaan satunnaista.

Muutaman esimerkin luokittelu (Few-shot)

Tähän ongelmaan few-shot-luokittelu tarjoaa ratkaisun. Luokkaa ei edusteta sen nimellä, vaan muutaman todellisen esimerkin keskipisteellä (centroid). “Bug”-luokka ei ole enää sana “bug”, vaan keskiarvo upotuksista lauseille “sovellus kaatuu käynnistyksessä”, “500-virhe kirjautumissivulla” ja “painike ei toimi mobiilissa”. Kolmesta viiteen esimerkkiä luokkaa kohti riittää yleensä, ja kustannus pysyy yhden API-kutsun tasolla, sillä kaikki tekstit lähetetään yhdessä.

def classifier_few_shot(
    texte: str,
    exemples: dict[str, list[str]],
    model: str = "text-embedding-3-large"
) -> dict:
    """Classifies by similarity to labeled examples.

    Args:
        exemples: {"category": ["example1", "example2", ...]}
    """
    # Prepare all texts
    tous_textes = [texte]
    mapping = []
    for cat, txts in exemples.items():
        for t in txts:
            tous_textes.append(t)
            mapping.append(cat)

    # Embeddings in a single call
    response = client.embeddings.create(
        input=tous_textes, model=model
    )
    embs = [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    texte_emb = np.array(embs[0])

    # Average embeddings per category
    cat_embeddings = {}
    for i, cat in enumerate(mapping):
        emb = np.array(embs[i + 1])
        if cat not in cat_embeddings:
            cat_embeddings[cat] = []
        cat_embeddings[cat].append(emb)

    cat_moyennes = {
        cat: np.mean(embs_list, axis=0)
        for cat, embs_list in cat_embeddings.items()
    }

    # Similarity
    scores = {
        cat: float(np.dot(texte_emb, emb_moy) /
                    (np.linalg.norm(texte_emb) * np.linalg.norm(emb_moy)))
        for cat, emb_moy in cat_moyennes.items()
    }

    prediction = max(scores, key=scores.get)
    return {"prediction": prediction, "scores": scores}

# Usage
exemples = {
    "bug": [
        "L'application crash au démarrage",
        "Erreur 500 sur la page de connexion",
        "Le bouton ne fonctionne pas sur mobile",
    ],
    "feature": [
        "Pourriez-vous ajouter un mode sombre ?",
        "Il serait utile d'exporter en PDF",
        "Suggestion : intégrer un calendrier",
    ],
    "question": [
        "Comment changer mon mot de passe ?",
        "Où trouver les paramètres de notification ?",
        "Quelle est la limite de stockage ?",
    ],
}

texte = "L'export CSV ne contient pas toutes les colonnes"
resultat = classifier_few_shot(texte, exemples)
print(f"Catégorie : {resultat['prediction']}")

Testilippu – “CSV-viennistä puuttuu sarakkeita” – ei sisällä sanaa “bug” eikä “virhe”, mutta se muistuttaa annettuja kolmea toimintahäiriöesimerkkiä, joten se päätyy siihen luokkaan. Huomaa, että upotusten keskiarvon ottaminen olettaa luokan olevan homogeeninen. Jos “kysymys”-esimerkkisi sekoittavat laskutuskyselyitä ja API-kysymyksiä, niiden keskipiste päätyy semanttiseen ei-kenenkään-maahan. Tällöin on parempi jakaa luokka kahtia.

Kevyt valvottu luokittelija

Kun sinulla on useita kymmeniä esimerkkejä luokkaa kohti, keskiarvon ottaminen on tiedon hukkaamista: se litistää pistepilven muodon. Samoihin upotuksiin koulutettu lineaarinen luokittelija oppii sen sijaan päätösrajan. Upotus hoitaa kielen ymmärtämisen, kun taas LogisticRegression vain piirtää geometrisen viivan tähän avaruuteen. Tämä johtaa muutaman sekunnin koulutusaikoihin tavallisella CPU:lla, kun taas kielimallin hienosäätäminen vaatisi GPU:n.

Viiden osituksen ristiinvalidointi (five-fold cross-validation) ei ole pelkkää show’ta. Se antaa sinulle tarkkuuden keskihajonnan, mikä kertoo arviosi luotettavuudesta. Pisteet 0,91 ± 0,02 ovat käyttökelpoisia; 0,91 ± 0,15 signaloi datan olevan liian pieniä tai epätasapainoinen.

from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import cross_val_score
import numpy as np

def entrainer_classifieur(
    textes: list[str],
    labels: list[str],
    model: str = "text-embedding-3-large"
) -> LogisticRegression:
    """Trains a classifier on embeddings."""
    # Generate embeddings
    response = client.embeddings.create(
        input=textes, model=model
    )
    X = np.array([d.embedding for d in sorted(response.data, key=lambda x: x.index)])

    # Train a classifier
    clf = LogisticRegression(max_iter=1000)
    
    # Cross-validation
    scores = cross_val_score(clf, X, labels, cv=5)
    print(f"Accuracy (5-fold CV) : {scores.mean():.3f} ± {scores.std():.3f}")

    # Train on the full dataset
    clf.fit(X, labels)
    return clf

def predire(clf, texte: str, model: str = "text-embedding-3-large") -> str:
    """Predicts the category of a text."""
    emb = client.embeddings.create(
        input=texte, model=model
    ).data[0].embedding
    return clf.predict([emb])[0]

Lähestymistapojen vertailu

LähestymistapaVaaditut esimerkitTarkkuusViive
Nolla-esimerkki (Zero-shot)0~70–80 %1 API-kutsu
Muutaman esimerkin (3–5/luokka)15–25~80–90 %1 API-kutsu
Valvottu (50+/luokka)250+~90–95 %1 API-kutsu + inferenssi

Nämä kolme riviä luettuna järjestyksessä kuvaavat etenemistä, jota voit seurata tuotteen elinkaaren aikana. Aloita nolla-esimerkillä ensimmäisenä päivänä ilman dataa. Kun olet korjannut manuaalisesti parikymmentä ennustetta, kierrätä ne few-shot-esimerkkeinä. Kun annotointimäärä ylittää viisikymmentä luokkaa kohti, kouluta valvottu luokittelija. Pidä mielessäsi, että “viive”-rivi muistuttaa sinua siitä, että jopa valvottu malli pysyy nopeana; paikallinen inferenssi lisää merkityksettömän vähän ylimääräistä viivettä upotus-API-kutsuun verrattuna.

Keskeiset asiat

  • Nolla-esimerkin luokittelu vertaa tekstiä labeleihin upotusten avulla
  • Muutaman esimerkin menetelmä käyttää esimerkkejä määrittelemään jokaisen luokan
  • Valvottu luokittelija (LogisticRegression) saavuttaa parhaan suorituskyvyn
  • Aloita nolla-esimerkillä ja lisää esimerkkejä, jos tarkkuus ei riitä