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

Masz już przygotowane fragmenty dokumentów. Teraz chcesz odnaleźć te, które zawierają informacje potrzebne do odpowiedzi na pytanie. W Module 3 przejdziesz od tekstu przez embedding i podobieństwo wektorów do zapisanego indeksu oraz testów wyszukiwania.

Co zrobisz w tym module

• Wyjaśnisz, co reprezentuje embedding i czego nie można wywnioskować z pojedynczej liczby w wektorze.
• Odróżnisz błąd przygotowania tekstu od problemu z modelem lub indeksem.
• Obliczysz podobieństwo kosinusowe na małych wektorach i zinterpretujesz ranking.
• Sprawdzisz powiązanie wektora z tekstem i dokumentem źródłowym.
• Ocenisz trafienia Hit@1, Hit@3 i Hit@5 oraz osobno opiszesz pytania bez odpowiedzi.

Jak pracować offline

Czytaj rozdziały R1–R6 kolejno. Każdy zawiera objaśnienia, przykład i zadanie z pytaniem kontrolnym. Najpierw zapisz własne rozwiązanie, następnie zajrzyj do części „Odpowiedzi do ćwiczeń”. Ważniejsze od identycznych sformułowań jest uzasadnienie oparte na danych. Słownik na końcu pomaga wrócić do znaczenia terminów.

Wersję scaloną HTML lub PDF możesz wcześniej zapisać na komputerze. Książka w przeglądarce Moodle wymaga dostępu do platformy; samo określenie „offline” oznacza tutaj samowystarczalność treści i możliwość czytania pobranej wersji bez sieci.

Wspólny przykład: fikcyjny DocAssist

W książce analizujesz dokumentację fikcyjnej aplikacji DocAssist. Materiały z Modułu 2 opisują m.in. zmianę konfiguracji, dyżur operatora i parametr oczekiwania. Nazwy poleceń w cytowanych fragmentach są treścią do analizy, a nie instrukcją uruchamiania usługi na Twoim komputerze. Numer strony podręcznika nie jest numerem strony dokumentu źródłowego.

Rozdział 1 używa krótkich tekstów A–D. W rozdziale 4 poznasz sześć fragmentów D1–D6 z korpusu M3, wraz z rzeczywistymi identyfikatorami. Małe wektory i rankingi oznaczone jako dydaktyczne służą obliczeniom ręcznym. Nie są pomiarem modelu BGE-M3 ani wynikiem oceny całego systemu.

Książka i notebooki

Wykonanie notebooków jest rozszerzeniem lektury. Instalacja środowiska i pobranie modelu mogą wymagać Internetu; należy je zakończyć przed pracą bez sieci. Sposób przygotowania opisuje M12_M3_instrukcja_moodle.html w pakiecie Student. Książka nie zastępuje tej instrukcji ani kart oddawanych do oceny.

Wyszukiwanie słów jest użyteczne, kiedy znasz nazwę pliku, symbol parametru lub kod błędu. Użytkownik często opisuje jednak tę samą czynność innymi słowami. Embedding pomaga porównywać teksty także wtedy, gdy nie mają identycznego brzmienia.

1. Od słów do reprezentacji liczbowej

„Uruchom ponownie usługę” i „wykonaj restart procesu” mogą opisywać podobną czynność. Proste sprawdzenie obecności słowa „restart” nie odnajdzie każdej parafrazy. Model embeddingowy przekształca tekst w uporządkowaną listę liczb, czyli wektor. Porównywanie takich wektorów pozwala szukać kandydatów podobnych do pytania.

tekst → model embeddingowy → wektor
pytanie → ten sam model → wektor pytania
wektor pytania + wektory fragmentów → ranking

Wektor nie jest streszczeniem, listą słów ani zapisem ich numerów. Poszczególne współrzędne wynikają z wyuczonych reprezentacji. Zwykle nie można powiedzieć, że konkretna współrzędna oznacza „konfigurację”, a inna „bezpieczeństwo”. Znaczenie ma cały układ wartości oraz sposób jego porównywania.

2. Jeden tekst, jeden punkt porównania

W kursie używamy modelu bge-m3:latest przez Ollama. W pakiecie M3 każdy embedding ma 1024 współrzędne. Taki wymiar nie oznacza 1024 słów ani 1024 fragmentów bazy. Długość tekstu i liczba wymiarów reprezentacji to różne wielkości. W rozdziale 3 zobaczysz wektory dwuwymiarowe wyłącznie po to, aby łatwo wykonać rachunek.

Model embeddingowy tworzy reprezentację tekstu. Model generujący tworzy kolejne tokeny odpowiedzi. Oba mogą należeć do szerszej rodziny modeli językowych, lecz pełnią inne zadania w aplikacji. Wynik embeddingu nie jest odpowiedzią dla użytkownika.

3. Podobny temat a przydatna informacja

Wysoka bliskość reprezentacji nie sprawdza prawdziwości, aktualności ani uprawnień do dokumentu. Negacja, liczba, wersja i kolejność czynności mogą zmienić odpowiedź mimo dużego podobieństwa tematycznego. Dlatego zawsze wracasz do tekstu i metadanych. Wyszukiwanie po słowach może uzupełniać semantyczne, szczególnie dla dokładnych identyfikatorów; w M3 skupiamy się na wariancie wektorowym.

4. Materiał do własnej oceny

Pytanie: Jak sprawdzić, czy usługa działa po zmianie konfiguracji?

A–D są oznaczeniami krótkiego ćwiczenia z pakietu M3, nie identyfikatorami chunk_id. Tekst C nie ustala reguły przechowywania konfiguracji dla rzeczywistego systemu; oceniasz jego przydatność do zadanego pytania.

Ćwiczenie 1. Porównaj słowa i znaczenie

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

Podobieństwo kosinusowe porównuje kierunki wektorów. Dzięki prostemu przykładowi zobaczysz, dlaczego sama długość wektora nie rozstrzyga rankingu i dlaczego wynik 0,82 nie jest prawdopodobieństwem poprawnej odpowiedzi.

1. Długość i kierunek

Wektor [3, 4] ma długość 5, ponieważ pierwiastek z 3² + 4² wynosi 5. Wektor [6, 8] jest dwa razy dłuższy, lecz wskazuje ten sam kierunek. Jeśli chcesz porównywać kierunki, musisz uwzględnić obie długości. Iloczyn skalarny mnoży odpowiadające sobie współrzędne i sumuje wyniki.

a · b = a_1 × b_1 + a_2 × b_2 + ... + a_D × b_D
||a|| = √(a_1² + a_2² + ... + a_D²)
cosine_similarity(a, b) = (a · b) / (||a|| × ||b||)

Wzór wymaga wektorów tego samego wymiaru oraz niezerowych norm. Dla wektora zerowego mianownik wynosi zero, więc miara nie jest określona. Nie traktuj takiego przypadku jako „braku podobieństwa”; to niepoprawne wejście, które trzeba wyjaśnić.

2. Rachunek na małych wektorach

Nie są to embeddingi tekstów ani wartości z BGE-M3. Przyjmij pytanie reprezentowane przez q = [1, 0] i cztery wektory kontrolne.

Kierunki identyczne dają 1, prostopadłe 0, a przeciwne -1. Matematyczny zakres to od -1 do 1. W rzeczywistych reprezentacjach rozkład wartości zależy od modelu i danych. Nie odczytuj ujemnego wyniku jako logicznego zaprzeczenia zdania ani zera jako gwarancji braku związku między tekstami.

3. Co zmienia normalizacja L2

Normalizacja dzieli wszystkie współrzędne przez długość wektora. Z [3, 4] otrzymujesz [0.6, 0.8]; długość nowego wektora wynosi 1, a kierunek się nie zmienia. W kodzie kursu odpowiada za to normalize_vector().

v_norm = v / ||v||
Jeżeli ||a_norm|| = ||b_norm|| = 1,
to cosine_similarity(a_norm, b_norm) = a_norm · b_norm.

Pełny wzór kosinusowy już uwzględnia długości, dlatego osobna normalizacja nie jest konieczna przy każdym jego użyciu. Jest za to wygodna przed obliczaniem wielu podobieństw operacją macierzową. W rozdziale 5 znormalizujesz wiersze macierzy i wektor pytania. Nie normalizuj wektora zerowego i nie zastępuj błędu dopisaniem drobnej liczby bez wyjaśnienia.

4. Wynik liczbowy wymaga tekstu

cosine_similarity(vector_a, vector_b) zwraca jedną liczbę. Pozwala porównać pary w danej konfiguracji, ale nie wie, czy dokument jest aktualny ani czy zawiera dokładne polecenie. Score 0,82 nie oznacza 82% pewności, 82% prawdy ani 82% informacji potrzebnych do odpowiedzi.

Do interpretacji zapisz pytanie, chunk_id, tekst, metadane i wartość podobieństwa. Porównuj wynik z przewidywaniem zapisanym przed obliczeniami. Jeśli ranking jest zaskakujący, sprawdź warunki, negacje, nazwy obiektów oraz zgodność modelu. Zaokrąglaj wartości do wyświetlenia, zachowując pełną precyzję w pliku.

Ćwiczenie 3. Oblicz i zinterpretuj

Dla jednego pytania obliczasz podobieństwo do wszystkich fragmentów, sortujesz wyniki malejąco i wybierasz pierwsze k. Ten mechanizm zwraca kandydatów na kontekst. O ich przydatności rozstrzyga treść.

1. Miniaturowa baza do dalszych ćwiczeń

Poniżej znajduje się pełna treść sześciu wybranych fragmentów pakietu M3, wersja dokumentów 1.4. Na potrzeby książki nazywamy je D1–D6. To skróty do rachunków, nie nowe chunk_id i nie cały dziesięcioelementowy korpus. W ćwiczeniach książkowych oceniasz odpowiedzi względem tej miniaturowej bazy.

## Ponowne uruchomienie usługi
Po zmianie pliku /etc/docassist/config.yaml wykonaj kolejno:
1. Uruchom ponownie usługę: sudo systemctl restart docassist-api
2. Sprawdź stan: systemctl is-active docassist-api
Prawidłowy wynik: active.
Uwaga: wykonaj ponowne uruchomienie tylko po zmianie konfiguracji.

## Kopia konfiguracji
Przed edycją zachowaj kopię pliku konfiguracyjnego w katalogu kopii.
Nie zapisuj w zgłoszeniu haseł ani kluczy. W razie nieudanego uruchomienia
przywróć zatwierdzoną kopię i zgłoś problem administratorowi.

## Dyżur operatora
Operator przyjmuje zgłoszenia w dni robocze od 08:00 do 16:00.
Poza tymi godzinami zgłoszenie czeka do następnego dyżuru.
Wyjątek: awarię uniemożliwiającą pracę całego zespołu zgłoś dyżurnemu
administratorowi zgodnie z wewnętrzną procedurą eskalacji.

## Treść zgłoszenia
Podaj wersję systemu, czas zdarzenia, komunikat błędu i wykonane kroki.
Nie dołączaj danych osobowych ani sekretów. Opisz oczekiwany wynik.
Nie podajemy w tym regulaminie gwarantowanego czasu rozwiązania zgłoszenia.

## Parametr oczekiwania
Parametr: timeout_seconds. Wartość zalecana w tym przykładzie: 30 s.
Zwiększ wartość dopiero po ustaleniu, że operacja trwa dłużej.
Nie traktuj tego parametru jako gwarancji czasu odpowiedzi.

## Test po zmianie konfiguracji
Po zmianie konfiguracji sprawdź uruchomienie usługi i zapisz wynik.
Nie usuwaj łącznika w nazwie docassist-api.

Fragmenty TXT i Markdown nie otrzymują wymyślonych numerów stron. Identyfikatory i metadane pozwalają odnaleźć dokument niezależnie od miejsca fragmentu w rankingu. Jeśli w dalszym zadaniu widzisz D1, odwołuje się ono dokładnie do tekstu powyżej.

2. Budowanie rankingu

1. Zakoduj pytanie tym samym modelem i w zgodny sposób jak fragmenty.
2. Dla każdego rekordu oblicz kosinus i zachowaj powiązanie z chunk_id, tekstem oraz metadanymi.
3. Uporządkuj wyniki od największego score i wybierz top_k pierwszych.
4. Przeczytaj wynik, sprawdź źródło i oceń, czy dostarcza potrzebnej informacji.

Funkcja search_similar_chunks(query_embedding, chunks, top_k=3) realizuje wersję z pętlą. Zwraca płaskie rekordy z polami chunk_id, text, metadata i score. top_k musi być dodatnią liczbą całkowitą. Gdy w zbiorze jest mniej fragmentów niż k, można zwrócić tylko dostępne rekordy. Remisy wymagają stałej, jawnej reguły; pakiet zachowuje kolejność wejściową.

3. Ile fragmentów wybrać

Załóżmy pytanie: „Jakim poleceniem sprawdzę stan usługi po zmianie konfiguracji?”. Poniższy ranking jest dydaktyczny, przygotowany do ćwiczenia. Liczby nie pochodzą z pomiaru BGE-M3.

Przy k = 1 otrzymasz tylko ogólny tekst. Przy k = 2 odzyskasz dokładną informację potrzebną w tym pytaniu. Dodanie D2 zwiększa objętość przyszłego kontekstu, lecz nie jest niezbędne do podania komendy. W innym pytaniu, np. o przygotowanie do edycji, D2 może być najważniejsze. Wybór k oceniaj na zestawie pytań, nie na pojedynczym trafieniu.

Ćwiczenie 4. Sprawdź przydatność top-k

Lista wektorów wystarcza do pierwszego eksperymentu. Indeks pozwala uporządkować dane, zapisać je i ponownie wyszukać te same fragmenty po uruchomieniu nowej sesji. Jego najważniejszą cechą jest zachowanie zgodnego powiązania liczb z tekstami.

1. Embedding, macierz i indeks

Dla 10 fragmentów i 1024 wymiarów macierz ma kształt (10, 1024). Po normalizacji każdego wiersza i pytania podobieństwa można policzyć przez embedding_matrix @ query_norm. Otrzymujesz po jednej liczbie dla każdego wiersza. Sortowanie tych wartości dopiero wyznacza kolejność wyniku.

Obliczenie w NumPy eliminuje część narzutu pętli Pythona, lecz nadal porównuje pytanie ze wszystkimi fragmentami. Jest to wyszukiwanie dokładne. Sam zapis do pliku NPY nie tworzy struktury przybliżonego wyszukiwania ANN i nie dowodzi przyspieszenia w każdym przypadku. M3 wybiera prosty indeks ze względu na czytelność i możliwość weryfikacji.

2. Zasada mapowania

Po odrzuceniu rekordu albo zmianie kolejności odtwórz ciąg indeksów od zera. Zachowaj oryginalne chunk_id i pełne metadane. Nie sortuj samej macierzy lub samego pliku rekordów. Ranking wyników jest osobną listą odwołań i nie wymaga przestawiania bazy.

3. Trzy pliki jednego indeksu

semantic_index/
    embeddings.npy
    chunks.jsonl
    index_metadata.json

W manifestach pakietu schema_version jest tekstem "1.0", dimension liczbą 1024, metric ma wartość "cosine", normalized to logiczne true, a data_type to "float32". chunk_count opisuje liczbę wierszy. Tekst "true" nie zastępuje logicznego true; format pliku ma znaczenie dla walidacji.

Dodatkowo zachowano model_digest i sumy SHA-256 danych. Suma kontrolna pozwala wykryć zmianę zawartości od momentu zapisu, ale nie dowodzi poprawności tekstu ani prawidłowego mapowania. embedding_manifest.json opisuje etap R2; index_metadata.json opisuje gotowy indeks R5. Nie zastępują się wzajemnie.

4. Odczyt i test po restarcie

1. Wczytaj manifest i sprawdź wymagane pola oraz zgodność konfiguracji.
2. Odczytaj pliki wskazane w manifeście; sprawdź sumy, kształt macierzy, typ i liczbę rekordów.
3. Zweryfikuj unikatowość chunk_id, ciąg vector_index i powiązanie z wektorami R2.
4. W nowym procesie wczytaj zapisany indeks i odtwórz ranking dla zapisanego wektora kontrolnego.
5. Porównaj identyfikatory i score przed oraz po zapisie. Drobne różnice zmiennoprzecinkowe oceniaj z określoną tolerancją.

search_local_index(query_embedding, embedding_matrix, chunk_records, top_k=3) zwraca elementy score i chunk. To inny kształt niż płaski wynik search_similar_chunks() z R4. Funkcja normalize_search_results() ujednolica strukturę wyników; nie normalizuje długości wektorów. Sprawdź tę różnicę, zanim napiszesz kod odczytujący chunk_id.

Ćwiczenie 5. Wykryj uszkodzone mapowanie

Ocena wyszukiwania zaczyna się od ustalenia, jaka informacja znajduje się w bazie. Oczekiwane trafienie wynika ze źródeł, a nie z wyniku modelu. Dopiero po zapisaniu tego oczekiwania uruchamiasz pomiar.

1. Przygotuj klucz przed rankingiem

Przypadek testowy opisuje pytanie oraz oczekiwane fragmenty. W plikach pakietu M3 identyfikator nazywa się question_id, a lista dopuszczalnych trafień expected_chunk_ids. question_type opisuje formę, np. direct, paraphrase lub ambiguous. case_type opisuje obecność odpowiedzi i zakres zadania.

Pytanie wieloznaczne może mieć odpowiedź przy ustalonej interpretacji. Zapisz tę interpretację w uzasadnieniu albo doprecyzuj pytanie przed pomiarem. Lista kilku expected_chunk_ids w przyjętej mierze oznacza, że wystarczy dowolny z nich. Jeżeli odpowiedź wymaga łącznie dwóch fragmentów, zwykłe Hit@k nie mierzy kompletności tego zestawu; potrzebujesz dodatkowej oceny pokrycia.

2. Hit@1, Hit@3 i Hit@5

Dla pojedynczego przypadku z odpowiedzią Hit@k wynosi 1, jeśli co najmniej jeden oczekiwany identyfikator znajduje się w pierwszych k wynikach. W przeciwnym razie wynosi 0. Pozycje rankingu liczysz od 1. Oczekiwany fragment na pozycji 2 daje Hit@1 = 0, a Hit@3 i Hit@5 = 1.

Hit@k pytania = 1, gdy top-k zawiera dopuszczalny chunk_id;
                0, gdy go nie zawiera.

Średni Hit@k = suma trafień / liczba pytań answerable.

Pytania bez odpowiedzi nie są automatycznie nieudanymi trafieniami i nie wchodzą do tego mianownika. Zapis null oznacza „nie dotyczy”, nie zero. Gdy cały zestaw nie ma przypadków answerable, średnia jest nieokreślona, a nie równa 0 lub 100%. Dla tego samego rankingu i klucza Hit@1 ≤ Hit@3 ≤ Hit@5.

3. Zestaw do ćwiczenia

Wróć do miniaturowej bazy D1–D6 z rozdziału 4. Każde poniższe pytanie oceniaj wyłącznie względem tej bazy. Najpierw ustal typ przypadku i oczekiwany fragment, następnie skorzystaj z tabeli pozycji.

4. Diagnoza przed zmianą modelu

• Czy informacja w ogóle występuje w źródle? Jeżeli nie, większe k jej nie stworzy.
• Czy po odczycie i podziale tekst zachował warunek, komendę i wynik? W razie braku wróć do przygotowania danych.
• Czy indeks odpowiada aktualnym fragmentom i zgodnemu modelowi? Sprawdź manifest oraz mapowanie.
• Czy właściwy fragment istnieje, lecz znajduje się za nisko? Przeanalizuj pytanie, sąsiednie wyniki i ustawienie k.

Większe k może poprawić Hit@k i jednocześnie dodać niepotrzebny tekst. Wysoka wartość tej miary nie gwarantuje poprawnej przyszłej odpowiedzi. Stały próg score również wymaga oceny na danych, szczególnie na pytaniach bez odpowiedzi. Nie ma uniwersalnej wartości, od której fragment staje się prawdziwy.

Ćwiczenie 6. Oblicz wyniki i zaplanuj poprawę

Rezultatem Modułu 3 jest wyszukiwanie, którego działanie można sprawdzić i odtworzyć. Poprawna macierz to początek kontroli. Potrzebujesz jeszcze zgodnych źródeł, rankingu, niezależnego klucza i raportu pokazującego ograniczenia.

Mapa procesu

1. R1: przewidujesz przydatność tekstów i rozpoznajesz parafrazy.
2. R2: tworzysz embeddingi, zachowujesz pochodzenie i rozliczasz błędy.
3. R3: porównujesz wektory, sprawdzasz geometrię i interpretujesz score.
4. R4: tworzysz ranking top-k oraz wracasz do treści źródeł.
5. R5: zapisujesz macierz, rekordy i manifest jako jeden spójny indeks.
6. R6: testujesz wyszukiwanie i planujesz poprawę na podstawie konkretnych przypadków.

Nazwy, które łączą rozdziały

Co zachować po pracy w książce

Zachowaj uzasadnienie rankingu A–D, dziennik rozstrzygnięć E1–E5, obliczenia kosinusa, ocenę top-k, diagnozę mapowania i tabelę B01–B08. Te notatki pokazują, czy potrafisz sprawdzić mechanizm bez polegania na gotowym wyniku programu.

Co zachować po pracy w notebookach

Zachowaj uzupełnione notebooki i wskazane foldery prób. Nowa próba ma oddzielny <proba_id>, więc porównania nie wymagają nadpisywania poprzednich wyników. wybrane_proby.json wskazuje ostatnio opublikowane wyniki używane jako wejście następnych etapów. Jeśli chcesz wrócić do konkretnej wcześniejszej próby, wybierz ją świadomie zgodnie z instrukcją pakietu.

• Do M4 przekaż cały semantic_index wybranej próby R5 oraz raport i wyniki R6.
• Wskaż model, jego digest, wersję danych, źródło checkpointu lub własnego pomiaru oraz datę.
• Nie zastępuj index_metadata.json manifestem embeddingów. Nie przekazuj samego pliku embeddings.npy.
• Nie przedstawiaj trybu checkpoint jako nowego wywołania modelu ani rankingu dydaktycznego jako pomiaru.

Lista kontrolna przed kolejnym modułem

• Każdy wektor ma jednoznaczne powiązanie z tekstem i metadanymi.
• Indeks wczytuje się w nowej sesji i odtwarza ranking kontrolny.
• Oczekiwania do testu pochodzą ze źródeł i zostały zapisane przed pomiarem.
• Pytania bez odpowiedzi mają osobną ocenę, a mianownik Hit@k jest jawny.
• Raport wskazuje konkretne błędy, ograniczenia i kolejną zmianę do sprawdzenia.

Podstawa treści i lektury uzupełniające

Podręcznik odpowiada zakresowi M12-M3-v4.pptx oraz nazwom w gotowym pakiecie ćwiczeniowym M3 z 19.09.2026. Baza D1–D6 jest wyborem z knowledge_base_ready.jsonl. Wszystkie przykłady liczbowe przygotowane do obliczeń ręcznych są oznaczone jako dydaktyczne. Pochodzenie rzeczywistych checkpointów opisują manifesty pakietu.

Poniższe źródła są opcjonalne; do wykonania ćwiczeń nie musisz ich otwierać.

• Ollama: karta modelu BGE-M3
• Ollama: tworzenie embeddingów

Porównaj tok rozumowania i dane, nie tylko końcową liczbę. Jeżeli Twój wniosek jest inny, wróć do fragmentu, który ma go uzasadniać. Odpowiedzi dotyczą sześciu zadań w tej książce, a nie pełnego klucza do notebooków.

Ćwiczenie 1. Słowa i znaczenie

Najbardziej przydatny jest A: wiąże zmianę ustawień z restartem właściwego procesu i potwierdzeniem statusu active. „Nowe ustawienia” odpowiadają zmianie konfiguracji, „potwierdź status active” odpowiada sprawdzeniu, czy usługa działa. „Restart” jest parafrazą ponownego uruchomienia.

B ma wspólne słowa „usługa”, „działa” i „zmiana”, lecz dotyczy harmonogramu kopii. C wspomina konfigurację, ale mówi o przechowywaniu pliku. D dotyczy etapu instalacji. A powinno być pierwsze; kolejność słabszych B, C i D nie jest jednoznacznym pomiarem semantycznym. Możesz np. uznać B i C za podobnie nieprzydatne. Nie twórz pozornej precyzji przez przypisywanie im wymyślonych score.

Najwyższy wynik podobieństwa oznacza pierwsze miejsce w danym rankingu. Nie dowodzi prawdziwości dokumentu ani poprawności przyszłej odpowiedzi. W przykładzie A jest uzasadnionym wyborem na podstawie treści, a nie dlatego, że model nadał mu liczbę.

Ćwiczenie 2. Przetwarzanie i błędy

Liczności: 5 = 2 poprawne + 1 pominięty + 2 błędne. Zachowaj tekst i chunk_id, metadane, model i digest, wymiar, datę, pochodzenie wejścia i jego sumę kontrolną oraz opis problemów. E2 wymaga korekty danych; awaria Ollama wymaga sprawdzenia środowiska i wznowienia nowej próby. Nie usuwaj jej śladu ani nie twórz losowego wektora.

Ten dziennik jest zadaniem o klasyfikacji. W działającym pakiecie błędy systemowe mogą przerwać przebieg zamiast pozwolić kontynuować zapis. Jest to właściwe zachowanie: nie należy ogłaszać kompletnego wyniku, jeśli usługa przestała działać.

Ćwiczenie 3. Rachunek kosinusa

Znormalizowane q to [0.6, 0.8]. Pomnożenie A przez dodatnie 10 zmienia długość, lecz nie kierunek, więc kosinus pozostaje 1. Z wektorem [0, 0] miara nie jest określona. [3, 4, 0] ma inny wymiar, więc porównanie również wymaga odrzucenia wejścia, a nie zgadywania.

Poprawne zdanie: „Dla tej pary i tej konfiguracji podobieństwo kosinusowe wynosi 0,82; o przydatności fragmentu rozstrzygamy po przeczytaniu treści”. Nie ma tutaj interpretacji procentowej dotyczącej prawdziwości.

Ćwiczenie 4. Ranking i treść

Dla k = 1 dostajesz D6, dla k = 2 D6 i D1, a dla k = 3 również D2. Dokładna komenda systemctl is-active docassist-api znajduje się w D1, więc dopiero warianty k = 2 i k = 3 obejmują potrzebny fragment. D6 mówi o sprawdzeniu uruchomienia, ale nie podaje polecenia. D2 dotyczy kopii i nie uzupełnia komendy sprawdzającej.

Dla godzin przyjmowania zgłoszeń wybierasz D3: dni robocze 08:00–16:00, wraz z opisem działania poza godzinami i wyjątkiem. Telefonu administratora w D1–D6 nie ma. Wynik dotyczący administratora nie daje prawa do wymyślenia numeru.

Obok score pokaż chunk_id, tekst i metadane, co najmniej nazwę pliku, identyfikator dokumentu, wersję oraz stronę albo sekcję, jeżeli występuje. Miejsce w rankingu nie zastępuje identyfikatora fragmentu.

Ćwiczenie 5. Spójność indeksu

Najwyższy score wskazuje wiersz 0, ale po błędnym sortowaniu rekord 0 opisuje D2. System zwróci więc niewłaściwy tekst z poprawnie obliczoną liczbą 1. Liczności, typ macierzy i normy mogą być prawidłowe mimo zerwania powiązania.

Naprawa polega na odbudowaniu par z oryginalnego R2: wektor D1 z rekordem D1 i wektor D2 z rekordem D2. Dopiero potem nadaj vector_index zgodny z kolejnością wierszy. Samo przepisanie indeksów na 0 i 1 bez sprawdzenia par nie naprawia błędu. Jeżeli oryginalnego powiązania nie da się wiarygodnie odtworzyć, przelicz indeks ze znanych danych.

Przy 9 wierszach macierzy i 10 rekordach zatrzymaj odczyt: nie wybieraj arbitralnie, który rekord pominąć. Test restartu uruchom w nowym procesie lub kernelu. Wczytaj trzy pliki, zweryfikuj je i użyj zapisanego wektora pytania kontrolnego. Porównaj identyfikatory oraz wartości score z wynikiem przed zapisem. Takie sprawdzenie bada odtwarzalność zapisu; samo nie dowodzi merytorycznej trafności indeksu.

Ćwiczenie 6. Klucz i metryki

Średnie dla sześciu przypadków answerable: Hit@1 = 2/6 ≈ 33,3%; Hit@3 = 4/6 ≈ 66,7%; Hit@5 = 5/6 ≈ 83,3%. B07 jest pytaniem z zakresu obsługi DocAssist, lecz brakuje danych kontaktowych. B08 dotyczy zupełnie innej dziedziny. Obu nie dodajesz do mianownika i nie zamieniasz null na 0.

B05 bez doprecyzowania mogłoby odnosić się do kopii pliku, wyniku testu albo zgłoszenia. Przyjęta interpretacja ustala D4 jako oczekiwany fragment; nie zmieniaj jej po zobaczeniu rankingu. B03 zyskuje przy przejściu z k = 3 do 5. B04 nadal nie mieści się w top-5, mimo obecności właściwej informacji w bazie.

Przykładowy plan: zbadać, dlaczego D3 jest dopiero szósty dla B04. Najpierw sprawdzić treść i mapowanie, potem porównać jedną zmianę reprezentacji lub przygotowania fragmentu na niezmienionym zestawie. Zachować pierwszy raport. Samo podniesienie k do 6 w tej miniaturze obejmuje całą bazę i podnosi trafienia, ale znosi selekcję; nie jest automatycznie dobrym rozwiązaniem dla przyszłego kontekstu.

Pojęcia w znaczeniu przyjętym w Module 3. Przy analizie wyniku zawsze ustal, czy mówisz o treści, reprezentacji liczbowej, pliku czy ocenie jakości.

Tekst i reprezentacja

Porównanie i wyszukiwanie

Zapis i odtwarzalność

Ocena jakości