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

Luo upotuksia datallesi

Oppitunti 3 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tavoitteet
  2. Valmistele data
  3. Luo upotuksia erissä
  4. Tallenna upotukset
  5. Täydellinen putki: tekstiTiedostoista upotuksiin
  6. Arvioi kustannukset
  7. Keskeiset asiat

Tavoitteet

  • Valmistele tekstidatasi upotusta varten
  • Luo upotuksia tehokkaasti suurissa mittakaavoissa
  • Tallenna vektorit myöhempää käyttöä varten

Valmistele data

Upotusten laatu riippuu suoraan datan laadusta. Teksti, joka on täynnä harhailevia välilyöntejä, väärin määritellystä viennistä peräisin olevia ohjausmerkkejä tai epäsäännöllisiä rivinvaihtoja, tuottaa hieman vinoutuneen vektorin. Tämä virhe kasautuu jokaisessa haussa. Siivoaminen ei ole kosmeettista: se on ensimmäinen ja edullisin osuvuuden optimointi.

import re

def nettoyer_texte(texte: str) -> str:
    """Prepares text for embedding."""
    # Remove multiple spaces
    texte = re.sub(r"\s+", " ", texte)
    # Remove control characters
    texte = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", texte)
    # Trim
    texte = texte.strip()
    return texte

# Example
brut = "  Texte   avec   des   espaces\n\n\nen trop  "
propre = nettoyer_texte(brut)
print(propre)  # "Texte avec des espaces en trop"

Rikasta kontekstia

Yksinäinen dokumentaatio-ote menettää osan merkityksestään ilman otsikkoa. Ota kappale, joka alkaa sanoilla “Lataa paketti viralliselta sivustolta”: ilman kontekstia mikään ei viittaa siihen, että kyseessä olisi PostgreSQL, ja tuloksena oleva vektori ei koskaan täsmää PostgreSQL-kyselyyn. Lisäämällä sisällön eteen sen otsikon ja osion injisoit tämän tiedon takaisin tekstiin, jonka malli näkee.

def enrichir_document(titre: str, section: str, contenu: str) -> str:
    """Creates enriched text for better embedding."""
    return f"Titre : {titre}\nSection : {section}\n\n{contenu}"

texte_enrichi = enrichir_document(
    titre="Installation de PostgreSQL",
    section="Getting Started Guide",
    contenu="Download the package from the official site..."
)

Luo upotuksia erissä

Kun käsitellään satojen tai tuhansien dokumenttien todellista kokoelmaa, käsittely on pilkottava osiin ja tehtävä kestäväksi verkkokatkojen varalta. Alla oleva funktio iteroi tekstejä paloissa, järjestää vastauksen systemaattisesti index-kentän mukaan varmistaakseen, että vektori #7 vastaa dokumenttia #7, ja yrittää uudelleen kerran tauon jälkeen, jos virhe ilmenee.

from openai import OpenAI
import time
import json

client = OpenAI()

def generer_embeddings(
    textes: list[str],
    model: str = "text-embedding-3-large",
    batch_size: int = 100
) -> list[list[float]]:
    """Generates embeddings in batches with error handling."""
    tous_les_embeddings = []

    for i in range(0, len(textes), batch_size):
        batch = textes[i:i + batch_size]
        print(f"Processing batch {i // batch_size + 1}/"
              f"{(len(textes) - 1) // batch_size + 1}")

        try:
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            # Sort by index to guarantee order
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )
        except Exception as e:
            print(f"Error on batch {i}: {e}")
            # Retry after a pause
            time.sleep(5)
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )

    return tous_les_embeddings

Järjestäminen index-kentän mukaan on varotoimi, jota ei saa koskaan jättää väliin. Yksi hiljainen rivin siirtymä riittää yhdistämään jokaisen dokumentin naapurinsa vektoriin. Oire, jonka havaitset, on “haku palauttaa roskaa”, ilman teknistä virhettä, joka ohjaisi sinut oikeaan suuntaan.

Tallenna upotukset

Muutaman tuhannen dokumentin pienelle kokoelmalle yksinkertainen JSON-tiedosto, joka sisältää tekstit, metadata ja vektorit, toimii täydellisesti. Sen etuna on ihmislukutaitoisuus, kun tarvitset outojen tulosten vianetsintää.

import json

documents = [
    {"id": 1, "texte": "Premier document...", "metadata": {"source": "faq"}},
    {"id": 2, "texte": "Deuxième document...", "metadata": {"source": "docs"}},
]

# Generate embeddings
textes = [d["texte"] for d in documents]
embeddings = generer_embeddings(textes)

# Add vectors to documents
for doc, emb in zip(documents, embeddings):
    doc["embedding"] = emb

# Save
with open("corpus_embeddings.json", "w") as f:
    json.dump(documents, f)

Tämän mittakaavan ylittyessä JSON:sta tulee pullonkaula: jokainen numero kirjoitetaan auki, mikä kasvattaa tiedostoa ja aiheuttaa kalliita jäsennyksiä jokaisessa latauksessa. NumPy tallentaa samat arvot binäärimuodossa 4 tavulla ja lataa ne välittömästi.

import numpy as np

# Convert to NumPy matrix
matrice = np.array(embeddings, dtype=np.float32)
print(f"Shape : {matrice.shape}")  # (n_docs, 3072)

# Save in binary format
np.save("embeddings.npy", matrice)

# Load
matrice_chargee = np.load("embeddings.npy")

Täydellinen putki: tekstiTiedostoista upotuksiin

Yhdistetään nämä elementit funktioon, joka lukee kansion, siivoaa jokaisen tiedoston, luo vektorit ja jakaa tallennuksen kahtia: metadata JSON-muodossa (luettava ja muokattava) ja matriisi NumPy-muodossa (tiivis ja nopea).

from openai import OpenAI
from pathlib import Path
import json
import numpy as np

client = OpenAI()

def pipeline_embeddings(dossier: str, model: str = "text-embedding-3-large"):
    """Complete pipeline: files → embeddings → storage."""
    dossier_path = Path(dossier)

    # 1. Read files
    documents = []
    for fichier in sorted(dossier_path.glob("*.txt")):
        contenu = fichier.read_text(encoding="utf-8")
        contenu = nettoyer_texte(contenu)
        if contenu:
            documents.append({
                "id": fichier.stem,
                "fichier": fichier.name,
                "texte": contenu
            })

    print(f"{len(documents)} documents found")

    # 2. Generate embeddings
    textes = [d["texte"] for d in documents]
    embeddings = generer_embeddings(textes, model=model)

    # 3. Save
    # Metadata in JSON
    meta = [{"id": d["id"], "fichier": d["fichier"]} for d in documents]
    with open("metadata.json", "w") as f:
        json.dump(meta, f, ensure_ascii=False, indent=2)

    # Vectors in NumPy
    np.save("embeddings.npy", np.array(embeddings, dtype=np.float32))

    print(f"Embeddings saved: {len(embeddings)} vectors "
          f"of {len(embeddings[0])} dimensions")

    return documents, embeddings

# Usage
documents, embeddings = pipeline_embeddings("./mes_documents/")

Huomaa sorted()-kutsu glob-funktiossa: ilman sitä tiedostojen järjestys riippuu tiedostojärjestelmästä, ja kaksi tulostiedostoasi voivat mennä sekaisin pelkän koneenvaihdon jälkeen.

Arvioi kustannukset

Ennen massiivisen työn käynnistämistä laske tokenit paikallisesti tiktokenilla. Operaatio vie muutaman sekunnin ja säästää sinut myöhäiseltä havainnolta, että huonosti suodatettu kokoelma sisälsi kymmenkertaisen määrän odotettuun verrattuna.

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

def estimer_cout(textes: list[str], model: str = "text-embedding-3-large"):
    """Estimates embedding cost for a list of texts."""
    total_tokens = sum(len(encoder.encode(t)) for t in textes)

    # Approximate prices per million tokens (check current rates)
    prix = {
        "text-embedding-3-large": 0.13,
        "text-embedding-3-small": 0.02,
    }

    cout = total_tokens / 1_000_000 * prix.get(model, 0.13)
    print(f"Estimated tokens: {total_tokens:,}")
    print(f"Estimated cost: ${cout:.4f}")
    return total_tokens, cout

Sanakirjan hinnat ovat suuntaa antavia ja vanhentuvat nopeasti: tarkista aina nykyiset hinnat ennen tarjouksen esittämistä asiakkaalle.

Keskeiset asiat

  • Siivoa ja rikasta tekstisi ennen upotusten luomista
  • Käytä eräkäsittelyä suurille kokoelmille
  • Tallenna metadata JSON-muodossa ja vektorit NumPy-muodossa
  • Arvioi kustannuksesi ennen massiivisen työn käynnistämistä