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

Kontrola jakości zamyka proces przygotowania danych i dostarcza podstaw do decyzji o dalszej pracy. Łączy sprawdzenie struktury plików, przegląd znaczenia fragmentów oraz ocenę pokrycia pytań. Żaden z tych elementów samodzielnie nie wystarcza.

1. Zachowaj etapy i możliwość powrotu

Oddziel źródła od wyników. Tekst surowy, tekst oczyszczony, fragmenty i oceny powinny mieć własne pliki. W pakiecie komputerowym wyniki trafiają do Student/wyniki/<RUN_ID>/R1 aż do R6. Ten sam identyfikator przebiegu łączy kolejne etapy. Nowy RUN_ID oznacza nowy przebieg i wymaga przygotowania poprzednich wyników; nie służy do dowolnego przeskakiwania do końca.

JSON zapisuje cały obiekt lub listę w jednym dokumencie. JSONL zapisuje po jednym kompletnym obiekcie JSON w każdym wierszu. W pliku JSONL nie dodajemy zewnętrznych nawiasów listy ani przecinków między rekordami. Dzięki temu następny etap może czytać rekordy kolejno. Oba formaty nadal wymagają poprawnych pól i wartości.

Końcowe pliki pełnią różne role:

Plik	Co zawiera	Po co go zachować
knowledge_base_all.jsonl	Wszystkie ocenione fragmenty	Ślad decyzji, także odrzuceń
knowledge_base_ready.jsonl	Wyłącznie fragmenty accepted	Wejście do kolejnego etapu
qa_report.json	Wyniki kontroli i decyzje	Możliwość sprawdzenia szczegółów
qa_summary.md	Uzasadnienie i ograniczenia	Czytelne przekazanie wyniku człowiekowi

2. Trzy warstwy kontroli

Kontrola techniczna sprawdza m.in. poprawny zapis, wymagane pola, unikalne identyfikatory, niepusty tekst, dozwolone wartości, logiczne zakresy znaków i stron oraz zgodność źródeł z inwentarzem. Dwustronicowy PDF nie może być źródłem strony 7. Po filtrowaniu indeksy w gotowym zbiorze powinny tworzyć ciąg od 0 bez luk.

Kontrola treści porównuje fragment z oryginałem. Sprawdza, czy zachował warunki, wyjątki, liczby, jednostki i kolejność. Wykrywa również fragmenty z samym tytułem, stopką lub urwanym wynikiem testu. Takie teksty mogą być poprawnym JSON-em i jednocześnie nie być użyteczną wiedzą.

Kontrola zakresu zestawia pytania P1–P5 z dopuszczonymi fragmentami. Dla każdego pytania zapisuje pełne pokrycie, częściowe pokrycie albo brak potrzebnej informacji oraz wskazuje dowody. Nie jest to jeszcze test wyszukiwania: ręczne znalezienie odpowiedzi w bazie nie dowodzi, że przyszły retriever wybierze właściwy fragment.

3. Decyzje o fragmentach

accepted oznacza, że fragment został sprawdzony i dopuszczony. review oznacza nierozstrzygniętą wątpliwość wymagającą działania. rejected oznacza świadome wyłączenie z gotowego zbioru wraz z powodem. Oceny nie należy nadawać wyłącznie na podstawie długości tekstu lub aktywnego statusu dokumentu.

W małym korpusie przejrzyj wszystkie fragmenty. Dla większego można zaplanować próbkę, np. co najmniej większą z liczb: 10 lub 5% zbioru zaokrąglone w górę, nie więcej niż cały zbiór. Do tego trzeba objąć kontrolą wszystkie ostrzeżenia, reprezentację formatów, granice procedur, wyjątki i inne miejsca podwyższonego ryzyka. Taka reguła organizuje przegląd, lecz nie dowodzi statystycznie bezbłędności całej bazy.

4. Co oznacza GO do kolejnego modułu

W notebookach M2 techniczny warunek GO wymaga rozstrzygnięcia ocen, braku fragmentów oczekujących na przegląd i co najmniej jednego fragmentu dopuszczonego. Błędy blokujące nie mogą pozostawać w fragmentach przyjętych. To jednak nie potwierdza pełnego pokrycia potrzeb użytkownika, jakości przyszłego wyszukiwania ani poprawności odpowiedzi modelu.

Ostateczne przekazanie powinno zawierać cel eksperymentu, zakres, liczbę przyjętych i odrzuconych fragmentów oraz znane braki. Jeśli brak dotyczy obowiązkowej funkcji, wróć do źródeł. Jeżeli jest świadomą granicą zakresu, opisz ją w raporcie. Nie zmieniaj oceny tylko po to, aby uzyskać napis GO.

W przykładowym rozwiązaniu komputerowym do tego pakietu cztery aktywne dokumenty dają pięć rekordów odczytu i piętnaście fragmentów. Dziesięć przyjęto, pięć wstępnych fragmentów bez samodzielnej wiedzy odrzucono. P1–P4 mają pokrycie, a dla P5 brak wartości gwarantowanego czasu. Regulamin mówi wprost, że takiego czasu nie podaje. Liczby opisują konkretny przebieg i parametry; nie są oczekiwanym wynikiem każdego poprawnego podziału.

Ważne. Wartość timeout_seconds = 30 s opisuje parametr diagnostyczny. Nie jest odpowiedzią na pytanie o gwarantowany czas rozwiązania zgłoszenia. Dopasowanie samego słowa „czas” nie daje jeszcze właściwej podstawy odpowiedzi.

5. Ćwiczenie 6 — przeprowadź audyt

Poniższy miniaturowy zbiór został przygotowany wyłącznie do ćwiczenia offline; nie jest kopią wyników notebooka. Zakładamy unikalne identyfikatory A–E i poprawny format pól poza jawnie wskazanymi problemami. Indeksy początkowe to kolejno 0–4.

ID	Treść lub opis fragmentu	Pochodzenie i problem
A	Cała sekcja „Dyżur operatora” z R4, wraz z wyjątkiem	regulamin.md 1.4, active, strony null; treść sprawdzona
B	Dyżur 09:00–15:00	regulamin_v1_3.md 1.3, archived; poza bieżącym zakresem
C	„Prawidłowy wynik: active.”	instrukcja.txt 1.4; brak opisu testu i warunku
D	Minimum 8 GB RAM i 2 GB wolnego miejsca	docassist.pdf 1.4; wszystkie pola strony błędnie mają wartość 7
E	Pusty tekst	pomoc.html 1.4; ekstrakcja fragmentu nie dostarczyła treści

Do naprawy C dysponujesz następującą pełną sekcją z instrukcja.txt 1.4:

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.

Dla D wiesz z R2, że wymagania znajdują się na stronie 1 dwustronicowego PDF. Dla E masz w R2 pełną treść pomocy, ale założeniem pierwszego przeglądu jest odrzucenie pustego fragmentu; poprawę ekstrakcji zapiszesz jako oddzielne działanie.

1. Nadaj A–E ocenę accepted, review lub rejected i podaj powód. Nie akceptuj fragmentu wymagającego naprawy.
2. Zdecyduj, czy w tej chwili można ogłosić GO. Wymień działania potrzebne przy C i D.
3. Załóż, że wrócono do wcześniejszych etapów, poprawiono C oraz D, przeliczono potrzebne zakresy i ponownie je sprawdzono. A, C i D są przyjęte, B i E odrzucone. Nadaj indeksom przyjętego zbioru kolejne wartości. W tym ćwiczeniu zachowaj etykiety A, C i D; w rzeczywistym przebiegu identyfikatory po ponownej fragmentacji nadaje proces.
4. Oceń pokrycie P1–P5. Który brak wymaga uzupełnienia dla wcześniej zdefiniowanego zakresu, a którego nie wolno uzupełnić domysłem?
5. Napisz trzyzdaniowe podsumowanie dla osoby rozpoczynającej M3: stan techniczny, brak merytoryczny i następne działanie.

Wynik: pięć ocen, plan naprawy, indeksy zbioru gotowego i raport ograniczeń.

Sprawdź rozumienie

Czy fragment odrzucony musi zniknąć także z raportu? Czym różni się brak danych w źródle od utraty treści przy przetwarzaniu? Co należy ponowić po wymianie regulaminu na nową wersję?

Po zmianie źródeł ponownie oceń zakres i wykonaj zależne etapy odczytu, czyszczenia, podziału, metadanych i kontroli. W kolejnych modułach będzie trzeba także odświeżyć powiązane embeddingi oraz indeks; stare wyniki nie stają się aktualne automatycznie.

Przygotowanie dokumentów i bazy wiedzy
ENHANCER+ · Politechnika Warszawska · materiał do samodzielnej nauki offline