Instrukcja pracy z modułem 4

Od indeksu wektorowego do odpowiedzi opartej na źródłach

Zakres: Sześć rozdziałów
Ćwiczenia: Około 270 minut
Punkt startu: Indeks z M3

Zbudujesz i sprawdzisz lokalny przepływ RAG: pytanie, wyszukiwanie, kontekst, prompt, odpowiedź i źródła. Pakiet zawiera gotowy kod i notebooki. Twoim zadaniem jest uruchomienie prób, prześledzenie działania funkcji oraz własna ocena odpowiedzi na podstawie dokumentów.

1Cel i rezultat modułu

Wczytasz sprawdzony indeks z M3 bez ponownego tworzenia embeddingów dokumentów.
Połączysz retrieval z generacją i zachowasz pełne metadane źródeł.
Odróżnisz status techniczny od kompletności i poprawności odpowiedzi.
Porównasz A–D oraz wpływ top_k, progu i promptu; opiszesz ograniczenia wyników.

2Materiały i organizacja pracy

Pobierz M12_M4_Student.zip i rozpakuj go w całości. W środku znajduje się katalog Student. Nie przenoś samych notebooków; zachowaj obok nich kod, dane, checkpointy, karty_pracy i wyniki. Prezentacja odniesienia to M12-M4-v4. Wprowadzenie zostało już skrócone do dwóch slajdów; karty odwołują się do rozdziałów po nazwie.

Materiał	Jak z niego korzystać
`00_sprawdzenie_srodowiska.ipynb`	Sprawdź środowisko, tryb i integralność indeksu.
Sześć kart pracy DOCX i HTML	Otwórz kartę przed rozdziałem; wykonuj jej kroki razem z notebookiem.
Sześć notebooków `*_start.ipynb`	Kod wykonuje próby; Ty uzupełniasz własną ocenę i raport.
`kod/m3_tools.py` i `kod/m4_tools.py`	Funkcje indeksu M3 oraz kod przepływu M4.
`kod/m4_exercises.py`	Pełne pętle eksperymentów; punkt wyjścia do własnych modyfikacji.
dane/`semantic_index`/ i dane/zrodla/	Kompletny indeks oraz dokumenty dydaktyczne DocAssist.
checkpointy/	Rzeczywiste zapisane wywołania do odtwarzania.
`M12_M4_autosprawdzenie.md`	Pytania do samodzielnego sprawdzenia rozumienia.

3Przygotowanie stanowiska

Wykorzystaj środowisko Python i Jupyter z M1–M3. Poniższe polecenia wykonaj w terminalu otwartym w katalogu Student. Instalację wykonuje się raz; nie jest wliczona w czas ćwiczeń.

python -m pip install -r requirements.txt
python -m jupyterlab

Jeżeli potrzebujesz osobnego środowiska na Windows:

py -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m jupyterlab

Dla MODE="ollama" uruchom aplikację Ollama i sprawdź dostępność modeli. Pobieranie modeli może wymagać kilku GB miejsca oraz czasu; jeżeli masz je z M1–M3, sprawdź listę przed pobraniem.

ollama list
ollama pull bge-m3:latest
ollama pull qwen3:4b-instruct-2507-q4_K_M

Indeks wymaga tego samego modelu embeddingowego i tego samego digestu co w M3. Sama zgodność wymiaru 1024 nie wystarcza. Notebook sprawdza zgodność. Nie zmieniaj manifestu, aby ominąć ten warunek.

Otwórz notebooki/00_sprawdzenie_srodowiska.ipynb. Wybierz kernel przygotowanego środowiska. Wynik powinien pokazać 10 fragmentów i wymiar 1024 dla dostarczonego indeksu. Błąd wykryj przed R1; nie pomijaj komórki sprawdzającej.

4Wybór sposobu pracy

Tryb	Co jest wykonywane	Jak opisać wynik
ollama	Nowy embedding pytania i nowe lokalne odpowiedzi. Kod nie wysyła ich do usługi zewnętrznej.	Własne wywołanie; zapisz model, digest i parametry.
checkpoint	Odtworzenie zapisanych rzeczywistych odpowiedzi i embeddingów dla identycznych żądań.	Analiza zapisanej próby; original_elapsed_s to czas pilota, nie nowy pomiar.

Domyślny tryb notebooków to ollama. W razie potrzeby ustaw MODE="checkpoint" przed komórką Przygotowanie. Kod nie przełącza trybu automatycznie. Checkpoint obsługuje domyślne pytania, prompty i ustawienia pakietu; własne zmiany wymagają trybu ollama. W R1 nie ma wywołania modelu.

5Plan rozdziałów

Czasy są propozycją dla ćwiczeń i analizy wyników, łącznie 270 minut. Nie obejmują oglądania prezentacji, instalacji ani pobierania modeli. Tempo pracy i zakres obowiązkowy określa prowadzący.

Rozdział	Zadanie i notebook	Czas	Rezultat
R1 — Pełny przepływ systemu RAG	`M12_M4_R1_przeplyw_rag_start.ipynb`	25 min	`mapa_przeplywu.json`
R2 — Wywołanie lokalnego modelu LLM z Pythona	`M12_M4_R2_wywolanie_llm_start.ipynb`	40 min	`proby.jsonl`
R3 — Budowanie promptu z kontekstem	`M12_M4_R3_prompt_z_kontekstem_start.ipynb`	45 min	`prompt_i_kontekst.json` i `retrieval.json`
R4 — Odpowiedź oparta wyłącznie na źródłach	`M12_M4_R4_kontrola_kontekstu_start.ipynb`	40 min	`proby.jsonl`
R5 — Źródła i weryfikowalność odpowiedzi	`M12_M4_R5_zrodla_odpowiedzi_start.ipynb`	40 min	`kontrola_cytowan.json`
R6 — Integracja i porównanie wariantów RAG	`M12_M4_R6_kompletny_rag_start.ipynb`	80 min	`rag_experiments.jsonl` i `raport_z_eksperymentu.md`

6Powtarzalny sposób pracy

Przeczytaj kartę
Otwórz właściwą kartę i odpowiedni rozdział prezentacji. Zachowaj oryginalną paczkę jako punkt odniesienia.
Przygotuj próbę
Wybierz MODE i uruchom Przygotowanie. Odczytaj nowy katalog OUT.
Wykonaj i przejrzyj próby
Uruchom kod, a następnie przeczytaj pełne wyniki. Konsolowy skrót nie wystarcza do oceny.
Uzupełnij własne uzasadnienia
Wypełnij pola twierdzenie, dowod_w_kontekscie, braki_lub_bledy, wniosek dla każdego result_id. Edytuj plik ocena_do_uzupelnienia.json albo listę w notebooku.
Zapisz ocenę
Uruchom komórkę zapisu. Kontrola sprawdza kompletność pól, nie prawdziwość analizy. Nowa wersja oceny ma osobną nazwę.
Zapisz notebook i raport
W R6 uzupełnij raport_z_eksperymentu.md. Zachowaj log i wybraną ocenę, a notebook zapisz przez Ctrl+S.

Ponowne Przygotowanie tworzy nowy katalog. Po ponownej generacji oceń nowe odpowiedzi. Po samej zmianie komentarzy uruchom wyłącznie zapis oceny, bez ponawiania modelu.

7Co i jak sprawdzasz

Obserwacja	Wniosek dopuszczalny	Czego jeszcze nie dowodzi
status=answered	Model zwrócił tekst; może to być odmowa.	Że odpowiedź jest prawdziwa lub kompletna.
insufficient_context	Program zatrzymał się przed generacją: sprawdź reason.	Że wiedzy nie ma w całym korpusie.
Poprawne etykiety S1 i S2	Odsyłacze istnieją na liście sources.	Że twierdzenia wynikają z cytowanych fragmentów.
Wysoki `score`	Fragment jest bliski pytaniu w przestrzeni modelu.	Że zawiera odpowiedź lub jest aktualny.
Wariant D	Model może wiernie powtórzyć błędny materiał.	Że cytowanie zapewnia prawdziwość treści.

W kontrolowanych kontekstach score=1.0 jest wyłącznie znacznikiem ćwiczenia. Porównania progów w R6 korzystają z rzeczywistego rankingu. A/B zmienia kontekst i instrukcję; czystsze porównanie zmiany zawartości kontekstu daje B/C/D.

8Zapis wyników i własny indeks

Student/wyniki/R1–R6/<proba_id>/
  proby.jsonl                 # R1–R5
  rag_experiments.jsonl        # R6
  ocena_do_uzupelnienia.json   # formularz roboczy
  ocena_<czas>_<id>.json       # zapisana własna ocena
  raport_z_eksperymentu.md     # R6

Dodatkowe pliki R1, R3 i R5 wymieniono w kartach. Nie edytuj surowych logów ani plików checkpointu. W notebooku 07_kontrola_zapisu.ipynb wskaż folder wybranej próby i sprawdź spójność result_id oraz brak pustych ocen.

Ścieżka podstawowa korzysta z dołączonego indeksu M3. Dodatkowy notebook M12_M4_R6_wlasny_indeks.ipynb pozwala wskazać własny kompletny semantic_index. Działa w trybie ollama; trzeba przygotować własne pytania i oczekiwane fragmenty. Nie przenoś mechanicznie pytań DocAssist ani pozycji fragmentów z zestawu A–D do innego korpusu.

9Lista kontroli i problemy

Pola poniżej pomagają w pracy; strona nie zapisuje zaznaczeń ani nie wysyła ich do oceny.

Mam sześć uzupełnionych notebooków i wybrane próby R1–R6.
Potrafię wskazać prompt, kontekst i źródło dla ocenianego twierdzenia.
Rozróżniam własne wywołanie od odtworzenia checkpointu.
Nie utożsamiam statusu answered z poprawnością.
Zachowałem osobną ocenę i uzupełniony raport R6.

Nie można połączyć się z modelem

Uruchom Ollama i sprawdź adres w konfiguracja.json. Domyślnie jest to http://127.0.0.1:11434. Możesz jawnie wybrać checkpoint.

Niezgodny digest lub uszkodzony indeks

Przywróć kompletne pliki z paczki. Dla własnego indeksu użyj zgodnego modelu z M3 lub zbuduj nowy indeks w M3. Nie poprawiaj ręcznie sum kontrolnych.

Brak identycznego żądania w checkpoincie

Przywróć domyślne parametry i pytania albo wykonaj własną próbę w ollama. Checkpoint nie generuje brakujących odpowiedzi.

Odpowiedź urwana lub wolna

Sprawdź generation.done_reason. Ustawienia num_predict=384, num_ctx=4096 oraz limit czasu 180 s są w kod/m4_tools.py. Przy zmianie ustawień wykonaj cały porównywany zestaw w ollama i zachowaj poprzednią próbę.

Nie można zapisać oceny

Wypełnij cztery pola dla każdego result_id. Wskaż fragment lub uzasadnij brak podstaw. Komunikat kompletności nie jest oceną merytoryczną.

10Przekazanie pracy

Przekaż sześć notebooków oraz wybrane katalogi wyników z ocenami i raportem R6, zgodnie z ustaleniami prowadzącego. Materiały proponują dowody wykonania ćwiczeń; nie ustanawiają nowych zasad zaliczenia. Błąd modelu jest wartościowym wynikiem, jeśli potrafisz go wykryć i uzasadnić.