Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Stvaranje ugrađenih vektora (Embeddings)

Lekcija 11 od 18 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Kodiranje isječaka u vektore
  2. Kodiranje u serijama (Batch Encoding)
  3. Preživljavanje mrežnih pogrešaka
  4. Spremanje indeksa na disk
  5. Provjera prije nastavka
  6. Ključne točke

Kodiranje isječaka u vektore

Tvoji su dokumenti sada podijeljeni na čiste isječke. Sljedeći korak je njihova transformacija u ugrađene vektore (embeddings) pomoću mistral-embed API-ja, a zatim pohrana tih vektora u vektorsku bazu koja će djelovati kao tvoj tražilica. U ovom trenutku tvoj korpus prestaje biti običan tekst i postaje geometrija po kojoj se može pretraživati. Nekoliko inženjerskih mjera opreza—grupiranje u serije (batching), ponovni pokušaji i trajnost—čine razliku između krhkog prototipa i pouzdanog indeksa.

Za mali korpus, recimo manje od stotinu isječaka, dovoljan je jedan izravan poziv. Izvuci tekst iz svojih rječnika isječaka, proslijedi ih API-ju kakvi jesu i dohvati cijelu matricu. Oblik (87, 1024) prikazan na kraju izvršavanja tvoja je prva kontrola ispravnosti: toliko redaka koliko imaš isječaka i 1024 stupca jer je to dimenzija modela mistral-embed. Ako se broj redaka ne podudara, neki prazan isječak se provukao u seriju.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Assume chunks is the list of our prepared chunks
chunk_texts = [c["text"] for c in chunks]

# Encode in a single call
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) for example

Kodiranje u serijama (Batch Encoding)

Kod više od nekoliko desetaka isječaka, jedan poziv udara u ograničenja API-ja. Rješenje je podijeliti popis u serije i spojiti rezultate. Donja funkcija obrađuje dijelove od po 25 isječaka i prikazuje napredak. Ovo nije kozmetika: kod korpusa od nekoliko tisuća isječaka, kodiranje traje nekoliko minuta i htjet ćeš znati gdje se proces nalazi umjesto da buljiš u nijemi terminal. Redoslijed je očuvan, tako da svaki vektor ostaje usklađen sa svojim odgovarajućim isječkom u izvornom popisu.

def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
    """Encode a list of chunks in batches."""
    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"  Encoding batch {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
              f"({len(batch)} chunks)...")

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

    return np.array(all_embeddings)

# Encode all chunks
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectors of {embeddings.shape[1]} dimensions")

Preživljavanje mrežnih pogrešaka

U proizvodnji će API poziv eventualno pasti: prekid mreže, dosegnuta stopa ograničenja (rate limit) ili privremeni kvar. Bez zaštite, tvoje indeksiranje staje kod serije 180 od 400 i vraćaš se na početak. Robusna verzija omata svaku seriju u petlju za ponovni pokušaj s eksponencijalnim kašnjenjem—jedna sekunda, pa dvije, pa četiri. Ovo povećavanje razmaka je bitno: ponovni pokušaj odmah nakon odbijanja zbog kvote samo pogoršava stvari. Nakon tri uzastopna neuspjeha, funkcija podiže izričitu iznimku koja imenuje neispravnu seriju, umjesto da vrati skraćenu matricu gdje biš jaz otkrio tek tijekom pretraživanja.

import time

def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
    """Robust encoding with error handling."""
    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  # Success, exit retry loop

            except Exception as e:
                wait_time = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
                print(f"  Error in batch {i // batch_size + 1}, "
                      f"attempt {attempt + 1}/{max_retries}: {e}")
                if attempt < max_retries - 1:
                    print(f"  Waiting {wait_time}s before retry...")
                    time.sleep(wait_time)
                else:
                    raise RuntimeError(
                        f"Failed after {max_retries} attempts for batch {i // batch_size + 1}"
                    )

    return np.array(all_embeddings)

Spremanje indeksa na disk

Svako pokretanje kodiranja košta vrijeme i naplaćuje se kroz API pozive. Ponovno izračunavanje vektora svaki put kada se tvoja aplikacija pokrene je čisto rasipanje, posebno jer se sam korpus nije promijenio. Spremanje se odvija u dvije komplementarne datoteke: vektori idu u NumPy, kompaktni binarni format koji se učitava trenutno, dok metapodaci—tekst, izvor, pozicija—idu u čitljivi JSON koji možeš otvoriti i pregledati sumnjivi isječak. Dvije datoteke su međusobno ovisne, povezane redoslijedom redaka: nikada ne regeneriraj jednu bez druge, inače će tvoji rezultati pretraživanja ukazivati na pogrešne tekstove.

import json

def save_index(chunks, embeddings, filepath="rag_index"):
    """Save chunks and embeddings."""
    # Save embeddings (NumPy)
    np.save(f"{filepath}_embeddings.npy", embeddings)

    # Save metadata (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"Index saved: {len(chunks)} chunks, {embeddings.shape}")


def load_index(filepath="rag_index"):
    """Load chunks and embeddings from disk."""
    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"Index loaded: {len(metadata)} chunks, {embeddings.shape}")
    return metadata, embeddings

# Save
save_index(chunks, embeddings)

# Load (on next startup)
chunks_loaded, embeddings_loaded = load_index()

Provjera prije nastavka

Tiho oštećen indeks pokazuje se kasno, obično kada korisnik prijavi apsurdan odgovor. Nekoliko izvanmrežnih provjera traje trideset sekundi i štedi te od tog otkrića. Funkcija za verifikaciju prvo prikazuje osnovne metrike—broj isječaka, dimenziju, prosječnu normu—zatim mjeri sličnost između susjednih isječaka: budući da dolaze iz istog dokumenta, trebali bi pokazivati znatno više vrijednosti od dva nasumična odlomka. Posljednji test je najjednostavniji i najotkrivajući: isječak uspoređen sa samim sobom mora dati točno 1.0. Bilo koja druga vrijednost signalizira problem usklađenja ili numeričke konverzije.

from sklearn.metrics.pairwise import cosine_similarity

def verify_embeddings(chunks, embeddings, n_tests=5):
    """Verify embedding quality with simple tests."""
    print("=== Verifying embeddings ===")
    print(f"Number of chunks: {len(chunks)}")
    print(f"Dimensions: {embeddings.shape[1]}")
    print(f"Average norm: {np.linalg.norm(embeddings, axis=1).mean():.4f}")

    # Test: chunks from the same document should be closer
    for i in range(min(n_tests, len(chunks) - 1)):
        sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
        print(f"  Similarity chunk {i} <-> {i+1}: {sim:.4f}")

    # Test: a chunk compared to itself = 1.0
    self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
    print(f"  Self-similarity (must be 1.0): {self_sim:.6f}")

verify_embeddings(chunks, embeddings)

Složeno zajedno, radni tok svodi se na četiri korisne linije. Pripremaš isječke s pipelineom iz prethodne lekcije, kodiraš u robusnom načinu, verificiraš i spremaš. Ovo je skripta koju ćeš ponovno pokretati svaki put kada se korpus ažurira.

# 1. Prepare chunks (previous lesson)
chunks = prepare_documents(raw_docs)

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

# 3. Verify
verify_embeddings(chunks, embeddings)

# 4. Save
save_index(chunks, embeddings)

print("Index ready for search!")

Ključne točke

  • Koristi grupiranje u serije za kodiranje velikih korpusa (serije od 25–50 isječaka)
  • Dodaj logiku ponovnog pokušaja s eksponencijalnim kašnjenjem radi robusnosti
  • Spremi ugrađene vektore na disk (NumPy) kako bi izbjegao ponovno izračunavanje
  • Drži metapodatke (tekst, izvor, pozicija) u zasebnoj JSON datoteci
  • Verificiraj kvalitetu ugrađenih vektora prije nego ih upotrijebiš u proizvodnji