Przejdź do głównej treści
Polski— Wybierz język
Menu

Tworzenie osadzeń

Lekcja 11 z 18 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Kodowanie fragmentów na wektory
  2. Kodowanie wsadowe (Batching)
  3. Przetrwanie błędów sieciowych
  4. Zapis indeksu na dysku
  5. Weryfikacja przed kontynuacją
  6. Kluczowe wnioski

Kodowanie fragmentów na wektory

Twoje dokumenty są już podzielone na czyste fragmenty. Kolejnym krokiem jest przekształcenie ich w osadzenia (embeddings) przy użyciu API mistral-embed, a następnie zapisanie tych wektorów w bazie wektorowej, która posłuży jako Twój silnik wyszukiwania. To moment, w którym Twój korpus przestaje być zwykłym tekstem, a staje się geometrią możliwą do odpytywania. Kilka środków ostrożności inżynieryjnych – batchowanie, ponawianie prób i trwałość danych – decyduje o tym, czy stworzysz kruchy prototyp, czy niezawodny indeks.

Dla małego korpusu, powiedzmy poniżej stu fragmentów, wystarczy pojedyncze bezpośrednie wywołanie. Wyodrębnij tekst ze swoich słowników fragmentów, przekaż je do API w niezmienionej formie i pobierz pełną macierz. Kształt (87, 1024) wyświetlony na końcu wykonania to Twoja pierwsza kontrola sanityzująca: tyle wierszy, ile fragmentów, i 1024 kolumny, ponieważ taki jest wymiar modelu mistral-embed. Jeśli liczba wierszy się nie zgadza, oznacza to, że do partii wszedł pusty fragment.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Zakładamy, że chunks to lista przygotowanych fragmentów
chunk_texts = [c["text"] for c in chunks]

# Kodowanie w jednym wywołaniu
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) na przykład

Kodowanie wsadowe (Batching)

Przy więcej niż kilkudziesięciu fragmentach pojedyncze wywołanie uderza w limity API. Rozwiązaniem jest podział listy na partie i połączenie wyników. Poniższa funkcja przetwarza slice’y po 25 elementów i wyświetla postęp. Nie jest to tylko efekt wizualny: przy korpusie liczącym kilka tysięcy fragmentów kodowanie zajmuje kilka minut i chcesz wiedzieć, na jakim etapie jest proces, zamiast gapić się w milczący terminal. Kolejność jest zachowana, więc każdy wektor pozostaje dopasowany do odpowiadającego mu fragmentu w oryginalnej liście.

def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
    """Koduje listę fragmentów w partiach."""
    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"  Kodowanie partii {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
              f"({len(batch)} fragmentów)...")

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

    return np.array(all_embeddings)

# Kodowanie wszystkich fragmentów
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Razem: {embeddings.shape[0]} wektorów o {embeddings.shape[1]} wymiarach")

Przetrwanie błędów sieciowych

W środowisku produkcyjnym wywołanie API w końcu się nie powiedzie: przerwa w sieci, osiągnięcie limitu zapytań lub tymczasowa awaria. Bez zabezpieczenia indeksowanie zatrzyma się na partii 180 z 400 i wrócisz do punktu wyjścia. Odporna wersja opakowuje każdą partię w pętlę ponawiania z wykładniczym opóźnieniem (exponential backoff) – jedna sekunda, potem dwie, potem cztery. To zwiększające się odstępy mają znaczenie: natychmiastowe ponowienie próby po odrzuceniu z powodu limitu tylko pogarsza sprawę. Po trzech kolejnych niepowodzeniach funkcja zgłasza wyraźny wyjątek wskazujący wadliwą partię, zamiast zwracać obciętą macierz, w której lukę odkryłbyś dopiero podczas wyszukiwania.

import time

def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
    """Odporno kodowanie z obsługą błędów."""
    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  # Sukces, wyjście z pętli ponawiania

            except Exception as e:
                wait_time = 2 ** attempt  # Wykładnicze opóźnienie: 1s, 2s, 4s
                print(f"  Błąd w partii {i // batch_size + 1}, "
                      f"próba {attempt + 1}/{max_retries}: {e}")
                if attempt < max_retries - 1:
                    print(f"  Oczekiwanie {wait_time}s przed ponowną próbą...")
                    time.sleep(wait_time)
                else:
                    raise RuntimeError(
                        f"Niepowodzenie po {max_retries} próbach dla partii {i // batch_size + 1}"
                    )

    return np.array(all_embeddings)

Zapis indeksu na dysku

Każde uruchomienie kodowania kosztuje czas i płatne wywołania API. Przeliczanie wektorów przy każdym starcie aplikacji to czysta strata, zwłaszcza że sam korpus się nie zmienił. Zapis odbywa się w dwóch uzupełniających się plikach: wektory trafiają do NumPy – kompaktowego formatu binarnego, który ładuje się natychmiastowo – natomiast metadane (tekst, źródło, pozycja) lądują w czytelnym JSON-ie, który możesz otworzyć, by sprawdzić podejrzany fragment. Oba pliki są od siebie zależne, powiązane kolejnością wierszy: nigdy nie regeneruj jednego bez drugiego, inaczej wyniki wyszukiwania wskażą niewłaściwe teksty.

import json

def save_index(chunks, embeddings, filepath="rag_index"):
    """Zapisuje fragmenty i osadzenia."""
    # Zapis osadzeń (NumPy)
    np.save(f"{filepath}_embeddings.npy", embeddings)

    # Zapis metadanych (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 zapisany: {len(chunks)} fragmentów, {embeddings.shape}")


def load_index(filepath="rag_index"):
    """Ładuje fragmenty i osadzenia z dysku."""
    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 załadowany: {len(metadata)} fragmentów, {embeddings.shape}")
    return metadata, embeddings

# Zapis
save_index(chunks, embeddings)

# Ładowanie (przy następnym starcie)
chunks_loaded, embeddings_loaded = load_index()

Weryfikacja przed kontynuacją

Cicho uszkodzony indeks ujawnia się późno, zazwyczaj gdy użytkownik zgłosi absurdalną odpowiedź. Kilka kontroli offline zajmuje trzydzieści sekund i uchroni Cię przed takim odkryciem. Funkcja weryfikująca najpierw wyświetla podstawowe metryki – liczbę fragmentów, wymiar, średnią normę – a następnie mierzy podobieństwo między sąsiadującymi fragmentami: skoro pochodzą z tego samego dokumentu, powinny wykazywać znacznie wyższe wartości niż dwa losowe ustępy. Ostatni test jest najprostszy i najbardziej wymowny: fragment porównany sam ze sobą musi dać dokładnie 1.0. Każda inna wartość sygnalizuje problem z wyrównaniem lub konwersją numeryczną.

from sklearn.metrics.pairwise import cosine_similarity

def verify_embeddings(chunks, embeddings, n_tests=5):
    """Weryfikuje jakość osadzeń za pomocą prostych testów."""
    print("=== Weryfikacja osadzeń ===")
    print(f"Liczba fragmentów: {len(chunks)}")
    print(f"Wymiary: {embeddings.shape[1]}")
    print(f"Średnia norma: {np.linalg.norm(embeddings, axis=1).mean():.4f}")

    # Test: fragmenty z tego samego dokumentu powinny być bliżej siebie
    for i in range(min(n_tests, len(chunks) - 1)):
        sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
        print(f"  Podobieństwo fragment {i} <-> {i+1}: {sim:.4f}")

    # Test: fragment porównany sam ze sobą = 1.0
    self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
    print(f"  Auto-podobieństwo (musi być 1.0): {self_sim:.6f}")

verify_embeddings(chunks, embeddings)

Połączone razem, przeprowadzenie całego procesu sprowadza się do czterech użytecznych linii. Przygotowujesz fragmenty za pomocą potoku z poprzedniej lekcji, kodujesz w trybie odpornym na błędy, weryfikujesz i zapisujesz. To skrypt, który będziesz uruchamiać za każdym razem, gdy korpus ulegnie aktualizacji.

# 1. Przygotowanie fragmentów (poprzednia lekcja)
chunks = prepare_documents(raw_docs)

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

# 3. Weryfikacja
verify_embeddings(chunks, embeddings)

# 4. Zapis
save_index(chunks, embeddings)

print("Indeks gotowy do wyszukiwania!")

Kluczowe wnioski

  • Używaj batchowania do kodowania dużych korpusów (partie po 25–50 fragmentów)
  • Dodaj logikę ponawiania z wykładniczym opóźnieniem dla zwiększenia odporności
  • Zapisuj osadzenia na dysku (NumPy), aby uniknąć przeliczania
  • Przechowuj metadane (tekst, źródło, pozycja) w osobnym pliku JSON
  • Weryfikuj jakość osadzeń przed użyciem ich w środowisku produkcyjnym