Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Genereeri oma andmete jaoks manused

Õppetund 3 / 22 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Eesmärgid
  2. Valmista oma andmed ette
  3. Genereeri manuseid partiidena
  4. Salvesta manused
  5. Täielik torustik: tekstifailidest manusteni
  6. Hinda kulusid
  7. Peamised punktid

Eesmärgid

  • Valmista oma tekstiandmed manuste loomiseks ette
  • Genereeri manuseid tõhusalt suurel skaalal
  • Salvesta vektorid hilisemaks kasutamiseks

Valmista oma andmed ette

Sinu manuste kvaliteet sõltub otseselt sinu andmete kvaliteedist. Tekst, mis on täis juhuslikke tühikuid, valesti konfigureeritud ekspordist pärit juhtmärke või ebakorrapäraseid reavahetusi, tekitab veidi nihkes vektori. See nihe kuhjub iga otsingu korral. Puhastamine ei ole kosmeetiline: see on esimene ja odavaim asjakohasuse optimeerimine.

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"

Konteksti rikastamine

Eraldi dokumentatsiooni väljavõte kaotab ilma pealkirjata osa oma tähendusest. Võta lõik, mis algab sõnadega „Laadi pakett alla ametlikult saidilt“: kontekstist väljas ei viita miski sellele, et jutt käib PostgreSQList, ja sellest tulenev vektor ei sobi kunagi PostgreSQLi puudutava päringuga. Lisades sisule eesliitesena selle pealkirja ja jaotise, süstid selle info tagasi teksti, mida mudel näeb.

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..."
)

Genereeri manuseid partiidena

Sajade või tuhandete dokumentide reaalse korpuse puhul tuleb töötlemine jagada tükkideks ja muuta see võrguhäirete suhtes vastupidavaks. Allpool olev funktsioon läbib tekste lõikude kaupa, sorteerib vastuse süstemaatiliselt index järgi, et tagada vektori nr 7 vastavus dokumendile nr 7, ja proovib vea korral pärast pausi uuesti.

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

Sorteerimine index järgi on ettevaatusabinõu, mida ei tohi kunagi vahele jätta. Vaikne üherealine nihe piisab, et seostada iga dokument selle naabri vektoriga. Sümptom, mida märkad, on „otsing tagastab prügi“, ilma ühegi tehnilise veata, mis sind õiges suunas juhataks.

Salvesta manused

Mõne tuhande dokumendi väikese korpuse jaoks sobib suurepäraselt lihtne JSON-fail, mis sisaldab tekste, metaandmeid ja vektoreid. Selle eeliseks on inimloetavus, kui pead imelikku tulemust siluma.

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)

Sellest skaalast kaugemal muutub JSON pudelikaelaks: iga number kirjutatakse välja täies ulatuses, paisutades faili ja tekitades iga laadimise korral kuluka parsimise. NumPy salvestab samad väärtused binaarselt 4 baiti peale ja laadib need koheselt uuesti.

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äielik torustik: tekstifailidest manusteni

Ühendame need elemendid funktsiooniks, mis loeb kausta, puhastab iga faili, genereerib vektorid ja jagab salvestamise kaheks: metaandmed JSON-is (loetav ja muudetav) ning maatriks NumPy-s (kompaktne ja kiire).

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/")

Pane tähele sorted() kasutamist glob-i peal: ilma selleta sõltub failide järjekord failisüsteemist ja sinu kaks väljundfaili võivad pärast lihtsat masinavahetust sünkroonist välja minna.

Hinda kulusid

Enne massilise töö käivitamist loe tokenid kohapeal tiktokeniga. Toiming võtab paar sekundit ja hoiab sind avastamast liiga hilja, et halvasti filtreeritud korpus sisaldas kümme korda oodatust suuremat mahtu.

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

Sõnastikus toodud hinnad on soovituslikud ja vananevad kiiresti: kontrolli enne kliendile hinnapakkumise esitamist alati kehtivaid hindu.

Peamised punktid

  • Puhasta ja rikasta oma tekste enne manuste genereerimist
  • Kasuta suurte korpuste puhul partii töötlemist
  • Salvesta metaandmed JSON-i ja vektorid NumPy-sse
  • Hinda oma kulusid enne massilise töö käivitamist