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

Loo embeedinguid

Õppetund 11 / 18 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Kodeeri tükid vektoriteks
  2. Pakendatud kodeerimine
  3. Võrguvigade ellujäämine
  4. Salvesta indeks kettale
  5. Kontrolli enne jätkamist
  6. Peamised punktid

Kodeeri tükid vektoriteks

Su dokumendid on nüüd puhtateks tükkideks jagatud. Järgmine samm on teisendada need embeedinguideks kasutades mistral-embed API-t ning salvestada need vektorid vektorpoodi, mis toimib sinu otsingumootorina. See on hetk, mil su tekstikogu lakkab olemast lihtsalt tekst ja muutub päringutele vastavaks geomeetriaks. Mõned inseneritarkuse nõuded – pakendamine, korduskatsed ja püsivus – teevad vahet habras prototüübi ja usaldusväärse indeksi vahel.

Väikese tekstikogu puhul, ütleme vähem kui sada tükki, piisab ühest otsesest väljakutsest. Ekstraheeri tekst oma tükkide sõnastikest, edasta need muutumatuna API-le ja too tagasi täismaatriks. Täitmise lõpus kuvatav kuju (87, 1024) on sinu esimene mõistlikkuse kontroll: ridu on sama palju kui tükke ja veerge 1024, sest see on mistral-embed mõõde. Kui ridade arv ei klapi, on paketti libisenud tühi tükk.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Eeldame, et chunks on meie ettevalmistatud tükkide loend
chunk_texts = [c["text"] for c in chunks]

# Kodeeri ühes väljakutses
response = client.embeddings.create(
    model="mistral-embed",
    inputs=chunk_texts,
)

embeddings = np.array([d.embedding for d in response.data])
print(f"Embeddings: {embeddings.shape}")
# Embeddings: (87, 1024) näiteks

Pakendatud kodeerimine

Paarikümne tükist kaugemale minnes tabab üksik väljakutse API piiranguid. Lahenduseks on loendi jagamine pakettideks ja tulemuste liitmine. Allpool olev funktsioon töötleb 25-e kaupa lõike ja kuvab edenemist. See pole kosmeetika: mitme tuhande tükiga tekstikogu kodeerimine võtab mitu minutit ja sa tahad teada, kus protsess seisab, selle asemel et vahtida vaikivat terminali. Järjestus säilib, nii et iga vektor jääb joondatuks vastava tükiga sinu algsest loendist.

def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
    """Kodeeri tükkide loend pakettidena."""
    texts = [c["text"] for c in chunks]
    all_embeddings = []

    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        print(f"  Kodeerin paketti {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
              f"({len(batch)} tükki)...")

        response = client.embeddings.create(
            model=model,
            inputs=batch,
        )
        all_embeddings.extend([d.embedding for d in response.data])

    return np.array(all_embeddings)

# Kodeeri kõik tükid
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Kokku: {embeddings.shape[0]} vektorit mõõtmega {embeddings.shape[1]}")

Võrguvigade ellujäämine

Tootmises ebaõnnestub API väljakutse varem või hiljem: võrgukatkestus, kiirusepiirangu tabamine või ajutine tõrge. Ilma kaitseta peatub sinu indekseerimine paketil 180 neljasajast ja oled taas alguses. Tugev versioon pakendab iga paketi korduskatsete tsüklisse eksponentsiaalse taganemisega – üks sekund, siis kaks, siis neli. See kasvav vahemaa on oluline: kohe pärast kvoodi tagasilükkamist uuesti proovimine teeb asja ainult hullemaks. Pärast kolme järjestikust ebaõnnestumist tõstab funktsioon selge erindi, nimetades vigase paketi, selle asemel et tagastada lühendatud maatriks, kus lünka avastaksid alles otsingu käigus.

import time

def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
    """Tugev kodeerimine veakäitlusega."""
    texts = [c["text"] for c in chunks]
    all_embeddings = []

    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]

        for attempt in range(max_retries):
            try:
                response = client.embeddings.create(
                    model="mistral-embed",
                    inputs=batch,
                )
                all_embeddings.extend([d.embedding for d in response.data])
                break  # Õnnestus, välju korduskatsete tsüklist

            except Exception as e:
                wait_time = 2 ** attempt  # Eksponentsiaalne taganemine: 1s, 2s, 4s
                print(f"  Viga paketis {i // batch_size + 1}, "
                      f"katsed {attempt + 1}/{max_retries}: {e}")
                if attempt < max_retries - 1:
                    print(f"  Ootan {wait_time}s enne uut katset...")
                    time.sleep(wait_time)
                else:
                    raise RuntimeError(
                        f"Ebaõnnestus pärast {max_retries} katset paketile {i // batch_size + 1}"
                    )

    return np.array(all_embeddings)

Salvesta indeks kettale

Iga kodeerimiskord maksab aega ja tasulisi API väljakutseid. Vektorite iga kord arvutamine rakenduse käivitamisel on puhas raiskamine, eriti kuna tekstikogu ise pole muutunud. Salvestamine toimub kahes täiendavas failis: vektorid lähevad NumPy vormingusse, kompaktne binaarformaad, mis laadub silmapilkselt, samas kui metaandmed – tekst, allikas, positsioon – lähevad loetavasse JSON-i, mille saad avada kahtlase tüki kontrollimiseks. Need kaks faili on omavahel sõltuvad, seotud realehe järjekorraga: ära kunagi regenereeri üht ilma teiseta, muidu viitavad sinu otsingutulemused valedele tekstidele.

import json

def save_index(chunks, embeddings, filepath="rag_index"):
    """Salvesta tükid ja embeedinguid."""
    # Salvesta embeedinguid (NumPy)
    np.save(f"{filepath}_embeddings.npy", embeddings)

    # Salvesta metaandmed (JSON)
    metadata = []
    for c in chunks:
        metadata.append({
            "text": c["text"],
            "source": c.get("source", ""),
            "chunk_index": c.get("chunk_index", 0),
        })
    with open(f"{filepath}_metadata.json", "w", encoding="utf-8") as f:
        json.dump(metadata, f, ensure_ascii=False, indent=2)

    print(f"Indeks salvestatud: {len(chunks)} tükki, {embeddings.shape}")


def load_index(filepath="rag_index"):
    """Laadi tükid ja embeedinguid kettalt."""
    embeddings = np.load(f"{filepath}_embeddings.npy")

    with open(f"{filepath}_metadata.json", "r", encoding="utf-8") as f:
        metadata = json.load(f)

    print(f"Indeks laaditud: {len(metadata)} tükki, {embeddings.shape}")
    return metadata, embeddings

# Salvesta
save_index(chunks, embeddings)

# Laadi (järgmisel käivitamisel)
chunks_loaded, embeddings_loaded = load_index()

Kontrolli enne jätkamist

Vaikselt vigane indeks tuleb välja hilja, tavaliselt siis, kui kasutaja teatab absurdsesse vastusesse. Mõned offline-kontrollid võtavad kolmkümmend sekundit ja hoiavad sind selle avastamise eest. Kontrollifunktsioon kuvab esmalt põhimõõdikud – tükkide arv, mõõde, keskmine norm – ja mõõdab seejärel sarnasust naabertükkide vahel: kuna need pärinevad samast dokumendist, peaksid need näitama oluliselt kõrgemaid väärtusi kui kaks juhuslikku lõiku. Viimane test on lihtsaim ja paljastavaim: tüki võrdlemine iseendaga peab andma täpselt 1.0. Igasugune muu väärtus annab märku joondusprobleemist või arvutuslikust teisendusveast.

from sklearn.metrics.pairwise import cosine_similarity

def verify_embeddings(chunks, embeddings, n_tests=5):
    """Kontrolli embeedinguide kvaliteeti lihtsate testidega."""
    print("=== Embeedinguide kontrollimine ===")
    print(f"Tükkide arv: {len(chunks)}")
    print(f"Mõõtmed: {embeddings.shape[1]}")
    print(f"Keskmine norm: {np.linalg.norm(embeddings, axis=1).mean():.4f}")

    # Test: sama dokumendi tükid peaksid olema lähemal
    for i in range(min(n_tests, len(chunks) - 1)):
        sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
        print(f"  Sarnasus tükk {i} <-> {i+1}: {sim:.4f}")

    # Test: tüki võrdlemine iseendaga = 1.0
    self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
    print(f"  Enesesarnasus (peab olema 1.0): {self_sim:.6f}")

verify_embeddings(chunks, embeddings)

Kokku panduna taandub töövoog neljale kasulikule reale. Valmistad tükid ette eelmise tunni torustikuga, kodeerid tugevas režiimis, kontrollid ja salvestad. See on skript, mida käivitad uuesti iga kord, kui tekstikogu uueneb.

# 1. Valmista tükid ette (eelmine tund)
chunks = prepare_documents(raw_docs)

# 2. Kodeeri
embeddings = encode_chunks_robust(chunks, batch_size=25)

# 3. Kontrolli
verify_embeddings(chunks, embeddings)

# 4. Salvesta
save_index(chunks, embeddings)

print("Indeks on otsinguks valmis!")

Peamised punktid

  • Kasuta suurte tekstikogude kodeerimiseks pakendamist (paketid 25–50 tükki)
  • Lisa tugevuse huvides kordusloogika eksponentsiaalse taganemisega
  • Salvesta embeedinguid kettale (NumPy), et vältida ümberarvutamist
  • Hoia metaandmeid (tekst, allikas, positsioon) eraldiseisvas JSON-failis
  • Kontrolli embeedinguide kvaliteeti enne tootmises kasutamist