Tworzenie osadzeń
Na tej stronie
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