Podręcznik uczestnika z objaśnieniami, przykładami i ćwiczeniami do samodzielnej nauki do Modułu 3

Embedding jest użyteczny dopiero wtedy, gdy wiadomo, jaki tekst reprezentuje i jak go utworzono. W tym rozdziale śledzisz przetwarzanie fragmentów, sprawdzasz błędy i projektujesz zapis pozwalający odtworzyć kolejne etapy.

1. Co przychodzi z Modułu 2

Wejściem jest knowledge_base_ready.jsonl: plik JSON Lines, w którym każdy niepusty wiersz zawiera oddzielny rekord JSON. Rdzeń rekordu stanowią chunk_id, text i metadata. Pakiet referencyjny M3 zawiera 10 zaakceptowanych fragmentów z czterech plików: instrukcja.txt, regulamin.md, docassist.pdf i pomoc.html.

Nie tworzysz embeddingu z nazwy pliku zamiast treści. Nie usuwasz metadanych po obliczeniu wektora. Do kopii rekordu dopisujesz pole embedding, zachowując identyfikator, tekst oraz informacje o dokumencie. Obecne w danych vector_index wymaga ponownego sprawdzenia przy budowie macierzy, zwłaszcza gdy odfiltrowano rekordy.

2. Wspólna konfiguracja

W pliku konfiguracja.json zapisano model bge-m3:latest, wymiar 1024 i lokalny adres Ollama. Stała EMBEDDING_MODEL pozwala używać tej samej nazwy w kolejnych wywołaniach. Funkcja create_embedding(text, model_name=EMBEDDING_MODEL) zwraca pojedynczy wektor; pytanie i fragmenty muszą być kodowane w zgodnej konfiguracji.

Sam wspólny wymiar nie dowodzi zgodności. Dwa różne modele mogą zwracać po 1024 liczby, lecz reprezentować tekst w innych przestrzeniach. Tag latest też nie jest trwałym identyfikatorem zawartości. Dlatego pakiet zapisuje model_digest, czyli identyfikator konkretnego modelu zgłoszony przez Ollama. Po zmianie modelu lub sposobu przygotowania tekstu przelicz spójny zbiór i utwórz nowy indeks.

3. Kontrole przed i po wywołaniu

1. Sprawdź, czy rekord ma unikatowy identyfikator, niepusty tekst i potrzebne metadane.
2. Utwórz wektor i sprawdź, czy jest jednowymiarowy, liczbowy i ma 1024 elementy.
3. Odrzuć NaN, nieskończoność i wektor zerowy; nie nadają się do dalszych porównań kosinusowych.
4. Zachowaj przyczynę problemu i rozlicz każdy rekord wejściowy. Nie maskuj awarii modelu sztucznym wektorem.

Brak działającej usługi jest problemem środowiska, a pusty tekst problemem danych. Wymagają innych działań. W pakiecie ustawienie truncate=False wyraża żądanie, aby zbyt długi tekst nie był automatycznie skracany. Kontrola długości, obsługa błędu i ewentualny ponowny podział tekstu powinny być jawne. Parametry stanowiska opisane w fikcyjnej dokumentacji DocAssist nie są wymaganiami sprzętowymi BGE-M3.

4. Trzy pliki wyniku R2

Manifest jest opisem przebiegu, a nie kolejnym zbiorem fragmentów. Sprawdź zależność: liczba rekordów wejściowych = liczba poprawnych + pominiętych + błędnych. Rozstrzygnięcia muszą być rozłączne. Sam plik wynikowy bez opisu nie pokazuje, czy utracono część danych. Podczas filtrowania zachowaj chunk_id; numer kolejnego wiersza nie zastępuje tożsamości fragmentu.

5. Lokalny model i checkpoint

W notebookach MODE="ollama" uruchamia rzeczywiste obliczenia. MODE="checkpoint" korzysta z wcześniej zapisanych prawdziwych wektorów. W R2 taki tryb odtwarza dostarczony wynik dla zgodnego pliku wejściowego; nie jest nowym pomiarem. Dla pytań dostępny jest cache dokładnych tekstów. Nowego pytania nie można zakodować bez modelu tylko dlatego, że jest parafrazą pytania już zapisanego.

SOURCE pełni inną rolę niż MODE: w R3–R5 wybiera pochodzenie wejściowego R2, a w R6 pochodzenie indeksu R5. Może wskazywać własny wynik albo checkpoint. Wybranie checkpointu jest świadomą decyzją; błąd usługi nie powoduje cichej zmiany trybu.

Ćwiczenie 2. Rozlicz przetwarzanie