Moduł 2 | Instrukcja pracy | Lokalne chatboty i RAG

Instrukcja pracy uczestnika · Moduł 2

Instrukcja pracy z modułem 2

Przygotowanie dokumentów i bazy wiedzy

Czas: około 165 min ćwiczeń
Pracujesz z: kartami pracy, notebookami i dokumentacją DocAssist
Rezultat: sprawdzony zbiór fragmentów JSONL i raport jakości

Przygotujesz dokumenty do wykorzystania w systemie RAG: wybierzesz źródła, odczytasz i oczyścisz tekst, podzielisz go na fragmenty, dodasz metadane oraz sprawdzisz jakość. Zaakceptowany zbiór wykorzystasz w Module 3.

1Cel i rezultat modułu

Przejdziesz od plików źródłowych do fragmentów, które zachowują znaczenie i pozwalają wskazać pochodzenie informacji. W tym module pracujesz bez LLM, Ollama i modelu embeddingowego. Ręcznie oceniasz pokrycie pytań; wyszukiwanie semantyczne powstanie w Module 3.

Po zakończeniu masz

sześć uzupełnionych notebooków oraz wyniki R1–R6;
knowledge_base_all.jsonl ze wszystkimi ocenionymi fragmentami i knowledge_base_ready.jsonl zawierający tylko accepted;
qa_report.json, qa_summary.md oraz uzasadnienia decyzji i ograniczeń pokrycia pytań.

2Zanim zaczniesz

Rozpakuj cały pakiet M12_M2_student.zip i pracuj na własnej kopii folderu Student. Zachowaj razem dane, kod, notebooki, karty_pracy i wyniki. Ścieżki w instrukcji są liczone od Student. Przeczytaj START.md i dane/CZYTAJ.md.

Materiał	Do czego służy
`START.md` i `requirements.txt`	Przygotowanie środowiska i kolejność pracy.
`notebooki` i `karty_pracy`	Test środowiska oraz sześć ćwiczeń z miejscem na własną ocenę.
`dane/zrodla`	Cztery aktualne dokumenty w TXT, MD, PDF i HTML oraz archiwalny regulamin.
`dane/inwentarz_start.json` i `dane/pytania.json`	Metadane startowe i pięć pytań do kontroli pokrycia.
`kod/m2_tools.py`	Gotowe funkcje odczytu, czyszczenia, podziału i kontroli.

Dokumentacja DocAssist jest fikcyjnym materiałem dydaktycznym. Polecenia w niej zawarte są tekstem do analizy; nie wykonuj ich na komputerze. Ten korpus jest odrębnym zestawem dla M2 i nie zmienia wyników M1.

Czas ćwiczeń jest orientacyjny i nie obejmuje prezentacji ani instalacji. Korzystaj z prezentacji M12-M2-v4.pptx lub jej wersji udostępnionej w rozdziałach kursu. Daty nieobecne w źródłach pozostaw jako null.

3Przygotowanie stanowiska krok po kroku

Przygotuj Python 3.10 lub nowszy i JupyterLab. Instalacja zależności wymaga Internetu; po przygotowaniu środowiska ćwiczenia pracują lokalnie. Pakiet nie pobiera dokumentów z sieci i nie wykonuje OCR.

Utwórz środowisko
Otwórz terminal w folderze Student i wykonaj kolejno:
py -m venv .venv .\.venv\Scripts\python.exe -m pip install -r requirements.txt .\.venv\Scripts\python.exe -m ipykernel install --prefix .venv --name m2 --display-name "Python M2" .\.venv\Scripts\python.exe -m jupyterlab
Wybierz właściwy kernel
Otwórz notebooki/00_sprawdzenie_srodowiska.ipynb i wybierz Python M2. Uruchamiaj komórki od góry przez Shift + Enter. Test sprawdza biblioteki i pliki; nie wywołuje modelu.
Nazwij projekt
W komórce Przygotowanie każdego notebooka ustaw ten sam RUN_ID, domyślnie projekt_01. Dzięki temu R2–R6 odczytają wyniki poprzednich etapów.

Linux i macOS

Utwórz środowisko przez python3 -m venv .venv. W kolejnych poleceniach zastąp ścieżkę Windows przez .venv/bin/python.

4Sposób pracy i własna analiza

Podstawowa ścieżka to samodzielne przetwarzanie lokalnego korpusu. Uruchamiasz gotowe funkcje, dobierasz reguły i parametry oraz wpisujesz własne oceny w komórkach notebooka. Każde pole UZUPEŁNIJ zastąp konkretnym uzasadnieniem przed zapisem wyników.

Wariant	Zasada
Praca własna	Wyniki R1 są wejściem R2, a kolejne rozdziały rozwijają ten sam projekt.
Przykład prowadzącego	Jeśli prowadzący udostępni punkt wznowienia, oznacz w notebooku, które dane są przykładem i od którego miejsca pracujesz samodzielnie.
Rozszerzenie	Własny korpus, skan lub OCR wymagają dodatkowej kontroli. Najpierw ukończ podstawowy zestaw czterech formatów.

Nie wpisuj ocen wyłącznie po to, aby przejść kontrolę formularza. Automatyczny zapis sprawdza strukturę i obecność komentarzy, ale nie rozstrzyga ich poprawności.

5Praca z rozdziałami krok po kroku

Pracuj kolejno od R1 do R6. Przy każdym rozdziale otwórz kartę M12_M2_Rx_karta_pracy.docx i odpowiadający jej notebook.

Rozdział i czas	Temat oraz prezentacja v4	Główne wyniki
R1 · 20 min	Dokumenty źródłowe i zakres bazy wiedzy Slajdy 8–24	`inwentarz_zrodel.json` `zakres_bazy.md` `pytania.json`
R2 · 25 min	Wczytywanie treści z różnych formatów Slajdy 27–45	`documents_extracted.json` `kontrola_odczytu.json`
R3 · 30 min	Czyszczenie i normalizacja tekstu Slajdy 48–68	`documents_cleaned.json` `ocena_czyszczenia.json`
R4 · 30 min	Podział dokumentów na fragmenty Slajdy 71–95	`chunks.json` `strategia.json` `porownanie_strategii.json`
R5 · 25 min	Metadane i identyfikacja źródeł Slajdy 98–116	`fragments_with_metadata.json` `kontrola_metadanych.json`
R6 · 35 min	Organizacja i kontrola jakości bazy wiedzy Slajdy 119–141	`knowledge_base_all.jsonl` `knowledge_base_ready.jsonl` `qa_report.json` `qa_summary.md`

Przygotuj wejście
Sprawdź RUN_ID, wymagane pliki i wynik poprzedniego rozdziału. Nie omijaj kontroli źródeł.
Wykonaj operacje
Uruchom komórki wskazane w karcie. W R3 dobierz dokładne reguły czyszczenia; w R4 porównaj trzy strategie na tych samych danych.
Uzupełnij ocenę
Porównaj rezultat z oryginałem. Wskaż identyfikatory rekordów, zachowane warunki, wartości i miejsca wymagające korekty.
Zapisz i odczytaj
Uruchom końcową komórkę zapisu, otwórz powstałe pliki i zapisz notebook przez Ctrl + S. Po zmianie wcześniejszego etapu powtórz wszystkie zależne etapy.

6Punkty kontrolne pracy

Po etapie	Masz sprawdzić	Gdy wynik nie pasuje
R1	Każde źródło ma status i uzasadnioną decyzję.	Wróć do zakresu asystenta i wersji dokumentu.
R2–R3	Odczyt jest kompletny; clean_text zachowuje warunki, polecenia i jednostki.	Porównaj oryginał, raw_text i clean_text; popraw reguły.
R4–R5	Fragment ma sensowny kontekst i pozwala odnaleźć oryginał.	Sprawdź granice, sekcję, wersję i rzeczywiste strony.
R6	Każdy rekord ma decyzję, a ready zawiera tylko accepted.	Wyjaśnij błędy i review; ponów kontrolę po poprawkach.

Kontrola końcowa w R6

Mały korpus sprawdź w całości. Przy większym zbiorze obejrzyj losowo co najmniej większą z liczb: 10 fragmentów lub 5% zbioru (zaokrąglij w górę). Dodatkowo sprawdź wszystkie ostrzeżenia, granice stron, początki i końce dokumentów oraz procedury. Jeśli fragmentów jest mniej niż 10, sprawdź wszystkie.

status dotyczy dokumentu, a metadata.qa_status decyzji o fragmencie: accepted, review lub rejected. Błąd blokuje akceptację. Ostrzeżenia, np. krótki tekst lub powtórzona treść, wymagają oceny; overlap nie jest automatycznie błędnym duplikatem.

GO w notebooku oznacza brak nierozstrzygniętych decyzji i co najmniej jeden poprawny technicznie, zaakceptowany fragment. Przed przekazaniem do M3 sprawdź również własne podsumowanie jakości i ograniczenia pokrycia. NO-GO oznacza konieczność dalszych decyzji lub pusty zbiór zaakceptowany. Błędne rekordy można odrzucić z uzasadnieniem; nie trafiają wtedy do ready.

7Nazewnictwo i zapis wyników

wyniki/<RUN_ID>/R1/   # inwentarz i pytania
wyniki/<RUN_ID>/R2/   # odczyt
wyniki/<RUN_ID>/R3/   # czyszczenie
wyniki/<RUN_ID>/R4/   # fragmenty i strategia
wyniki/<RUN_ID>/R5/   # metadane
wyniki/<RUN_ID>/R6/   # audyt i zbiór do M3

RUN_ID nadajesz samodzielnie; nie twórzy go program. Jeden projekt używa tej samej nazwy we wszystkich notebookach. Kod tworzy katalogi przy zapisie.

Ważne: istniejące pliki są chronione przed przypadkowym zastąpieniem. Nową próbę wykonaj pod nowym RUN_ID. Ustawienie NADPISZ=True zastępuje wyniki danej próby; przed tym zachowaj potrzebną kopię.

Końcowy schemat rekordu to vector_index, chunk_id, text, metadata. Pole section odpowiada nazwie section_title z pośrednich przykładów. page_number wskazuje początek; page_start i page_end zakres. Dla plików bez stron zapisuj null. Po odfiltrowaniu zbioru nadaj ciągły vector_index od 0, zachowując chunk_id.

Do M3 przekaż R6/knowledge_base_ready.jsonl wraz z raportem, podsumowaniem i możliwością odszukania źródeł. Zbiór all pozostaje materiałem audytowym.

8Lista kontroli przed zakończeniem

Zachowałem oryginały, tekst surowy oraz rejestr czyszczenia.
Uzasadniłem wybór źródeł i strategii fragmentacji.
Sprawdziłem identyfikatory, lokalizatory i brakujące wartości.
Każdy fragment ma własną decyzję jakościową i uzasadnienie.
Oceniłem pięć pytań bez dopisywania brakującej wiedzy.
Ready zawiera tylko accepted i ciągły vector_index od 0.
Zapisałem notebooki, raport i podsumowanie ograniczeń.

Zaznaczenia są pomocą podczas czytania i nie zapisują się po odświeżeniu strony. Wynik pracy przechowujesz w notebookach i plikach.

9Gdy pojawi się problem

Brak m2_tools lub biblioteki

Rozpakuj cały Student, wybierz Python M2 i sprawdź instalację requirements.txt. Nie przenoś samych notebooków.

Nie znaleziono wyniku poprzedniego rozdziału

Sprawdź RUN_ID i uruchom zapis poprzedniego etapu. Nowa nazwa projektu nie kopiuje automatycznie starych wyników.

W pliku pozostało UZUPEŁNIJ

Uzupełnij właściwą komórkę ocen, ponów ją i zapis. Nie uruchamiaj ponownie szablonu formularza po zmianie ocen bez zachowania własnych przypisań.

PDF daje pusty lub błędny odczyt

Obejrzyj stronę w czytniku. Rozpoznaj skan, błędy kolejności lub kodowania. Pusty wynik nie dowodzi automatycznie potrzeby OCR; pypdf nie rozpoznaje tekstu z obrazów.

Zapis jest blokowany

Sprawdź, czy wybrany katalog zawiera poprzedni wynik. Wybierz nowy RUN_ID albo świadomie zastąp pliki przez NADPISZ=True.

Zmiana fragmentów unieważniła ocenę

Ponów R5 i R6. Zmiana tekstu lub podziału wymaga ponownej kontroli lokalizatorów i pokrycia pytań.

10Zasady odbioru

Sposób oddania pracy i zasady zaliczenia określa prowadzący. Zachowaj sześć notebooków oraz kompletny katalog wybranego projektu. Ocenie podlegają odtwarzalność procesu, zgodność z dokumentami i jakość uzasadnień. Samo przejście walidatora nie potwierdza poprawności merytorycznej.

Poprawne wykrycie braku odpowiedzi lub niewłaściwego fragmentu jest wartościowym rezultatem. Test pokrycia w M2 nie jest testem trafności wyszukiwania semantycznego.

Dokumentacja narzędzi

Instrukcja pracy uczestnika | Moduł 2 | Lokalne chatboty i RAG

Ostatnia modyfikacja: piątek, 18 września 2026, 22:12