Moduł 5 | Instrukcja pracy | Lokalne chatboty i RAG

Instrukcja pracy uczestnika · Moduł 5

Instrukcja pracy z modułem 5

Od interfejsu rozmowy do lokalnego asystenta z RAG

Czas: około 250 min ćwiczeń
Pracujesz z: kartami R1–R6, notebookami i bazą DocAssist
Rezultat: kontrakt zakresu, działający prototyp i wyniki testów

Zbudujesz i sprawdzisz kolejne warstwy DocAssist: interfejs, historię, wybór narzędzia, kontrolę wykonania i integrację z RAG. Pakiet zawiera pełne funkcje pomocnicze. Twoim zadaniem jest prześledzenie kodu, wykonanie scenariuszy i uzasadnienie wyników.

1Cel i rezultat modułu

Rozróżnisz rolę modelu i aplikacji, przypiszesz źródła do właściwej tury i sprawdzisz, czy kod zatrzymuje niedozwoloną propozycję. Ocenisz oddzielnie wybór działania, wykonanie narzędzia oraz poparcie odpowiedzi dokumentami.

Kontrakt zakresu DocAssist i sześć uzupełnionych notebooków.
Wyniki R2–R6 z identyfikatorami konkretnych wykonań i własnymi ocenami.
Raport integracji oraz functional_tests.jsonl, assistant_trace.jsonl i tool_trace.jsonl do późniejszej pracy w M6.

2Zanim zaczniesz

Pracuj na kopii katalogu Student. Ścieżki w tej instrukcji są liczone od niego. Zachowaj razem kod, dane, checkpointy, notebooki, karty_pracy i wyniki. Nie trzeba kopiować plików z wcześniejszych modułów: pakiet zawiera zgodny indeks M4 i jego zależności.

Materiał	Zastosowanie
START.md, requirements.txt, konfiguracja.json	Przygotowanie środowiska i ustawienia lokalnego backendu.
karty_pracy/	Sześć kart w DOCX, PDF i HTML. Każda prowadzi do właściwego notebooka.
notebooki/	00 — środowisko, R1–R6 — ćwiczenia, 07 — kontrola zapisu R6.
kod/m5_tools.py i kod/m5_exercises.py	Gotowe implementacje oraz scenariusze do prześledzenia i testowania.
kod/m3_tools.py i kod/m4_tools.py	Niezmienione funkcje wyszukiwania i RAG ze wcześniejszych modułów.
dane/semantic_index/	embeddings.npy, chunks.jsonl i index_metadata.json; 10 fragmentów, 1024 wymiary.
dane/zrodla/, dane/tool_specs.json	Źródła DocAssist i opis trzech narzędzi.
checkpointy/	Zapis rzeczywistych wywołań dla domyślnych scenariuszy, z kontrolą integralności.

DocAssist i dokumenty kursu są fikcyjne. Polecenia restartu i diagnostyki są treścią dokumentów, a nie poleceniami do wykonania. Nie potrzebujesz serwera DocAssist. Pakiet nie ma narzędzia powłoki.

Szacowany czas 250 minut dotyczy pracy praktycznej. Oglądanie prezentacji, instalację oraz pobranie modeli zaplanuj osobno. Możesz rozłożyć ćwiczenia na kilka sesji.

3Przygotowanie stanowiska krok po kroku

Przygotuj środowisko Python
Użyj Python 3.10 lub nowszego. Otwórz terminal w katalogu Student i wykonaj polecenia.

py -m venv .venv .\.venv\Scripts\python.exe -m pip install -r requirements.txt .\.venv\Scripts\python.exe -m ipykernel install --prefix .venv --name m5 --display-name "Python M5" .\.venv\Scripts\python.exe -m jupyterlab

Na Linux/macOS użyj python3 zamiast py oraz .venv/bin/python zamiast ścieżki Windows. Instalacja zależności wymaga Internetu.
Przygotuj modele do własnych wywołań
Uruchom lokalną Ollama i pobierz oba modele, jeżeli nie były przygotowane w M4.

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

Adres w konfiguracja.json to http://127.0.0.1:11434. Model embeddingowy i jego digest muszą zgadzać się z indeksem. Nie zmieniaj samej nazwy modelu, pozostawiając stare wektory.
Sprawdź środowisko
W Jupyter otwórz notebooki/00_sprawdzenie_srodowiska.ipynb i wybierz kernel Python M5. Uruchom komórki od góry przez Shift+Enter.

MODE="ollama" sprawdza lokalny backend i wykonuje próbę selektora. Jawne MODE="checkpoint" wczytuje indeks i odtwarza zapisane wywołanie, bez modelu.

4Wybierz i oznacz tryb pracy

Tryb	Co robisz	Ograniczenie
ollama	Nowe wywołania modeli w R2, R3, R4 i R6.	Odpowiedzi i decyzje mogą być błędne. Zachowaj surowy wynik.
checkpoint	Odtwarzasz autentyczny zapis dla niezmienionych pytań, promptów i konfiguracji.	To nie jest nowy pomiar modelu; własne pytanie może nie mieć zapisanego żądania.
Bez LLM	R1: kontrakt. R5: testy wykonawcy z dublerem RAG i lokalnym odczytem danych.	Wynik dublera potwierdza działanie testu, nie jakość modelu.

Po błędzie program nie przełącza się automatycznie na inny tryb. Dla swobodnej rozmowy i zmienionego promptu wybierz Ollama. Odtwarzanie checkpointu wymaga przygotowanego Pythona, ale nie wymaga uruchomionej Ollama.

5Praca z rozdziałami

Otwórz kartę i notebook tego samego rozdziału. Nazwy odpowiadają prezentacji M12-M5-v5. Pliki pomocnicze są gotowe; prześledź wskazane funkcje, sprawdź ich warunki i wykonaj własną analizę. Dodatkowe modyfikacje kodu rób na kopii.

Rozdział	Temat	Główny wynik
R1 · 25 min	Chatbot, asystent i agent	kontrakt_zakresu_<id>.md
R2 · 35 min	Od pojedynczego pytania do rozmowy	chat_results.jsonl
R3 · 45 min	Historia konwersacji i kolejne pytania	conversation_tests.jsonl
R4 · 40 min	Narzędzia wywoływane przez model	action_proposals.jsonl
R5 · 45 min	Kontrolowane wykonywanie narzędzi	tool_tests.jsonl i tool_trace.jsonl
R6 · 60 min	Integracja lokalnego asystenta z RAG	functional_tests.jsonl i assistant_trace.jsonl

Stały rytm pracy

Przygotuj próbę
Przeczytaj kartę, wybierz tryb i uruchom komórkę Przygotowanie. Zanotuj katalog OUT wyświetlony po komunikacie Wyniki.
Prześledź kod i wykonaj scenariusze
Odczytaj wskazane funkcje. Komórkę Próby wykonaj raz dla bieżącego katalogu. Powtórne wykonanie jest blokowane, aby nie mieszać różnych wyników.
Uzupełnij własną ocenę
W R1 wypełnij kontrakt. W R2–R6 dla każdego result_id wpisz obserwacja, dowod i wniosek. Dowodem może być konkretne pole wyniku albo fragment dokumentu z chunk_id.
Zapisz i sprawdź
Uruchom zapis oceny. W R6 uzupełnij dodatkowo granice, dowody i przekazanie_do_M6 w raporcie. Otwórz zapisane pliki i zachowaj notebook przez Ctrl+S.

Ważne: po ponownym Przygotowaniu powstaje nowa próba. Nowe odpowiedzi oceń ponownie. Jeśli zmieniasz tylko komentarz, wykonaj komórki oceny i zapisu bez nowego wywołania modelu.

6Jak czytać wynik i źródła

Element	Znaczenie
decision.status	Czy selektor zaproponował działanie lub zakończył wybór.
tool.status	Czy aplikacja dopuściła i wykonała narzędzie. tool_completed nie rozstrzyga jakości odpowiedzi.
rag.status	answered oznacza zwrócony tekst, również odmowę; insufficient_context oznacza brak dopuszczonego kontekstu.
reason	below_threshold: wszystkie znalezione wyniki odrzucono progiem. no_usable_results: pozostałe rekordy nie nadawały się do kontekstu. no_results: wyszukiwanie nic nie zwróciło.
sources i chunk_id	Lista kontekstu przekazanego modelowi oraz trwałe identyfikatory fragmentów. To nie jest dowód użycia każdego źródła.
conversation_id, turn_id, result_id	Rozmowa, numer tury i konkretny wynik. Oceny łączysz po result_id.

W indeksie używamy DOC-INSTR, DOC-REG, DOC-PDF i DOC-HELP. Pole version ma wartość 1.4, a status active. Przykład sprawdzenia stanu opiera się na systemctl is-active docassist-api i wyniku active. Gdy model dopowie inną procedurę, sprawdź jej podstawę w przekazanym kontekście.

Dla TLS z domyślnym progiem None możliwa jest odmowa z answered i niepustymi źródłami. Przy progu odrzucającym wszystkie znalezione wyniki otrzymasz insufficient_context / below_threshold. Sam status nie dowodzi braku tematu w całym korpusie.

7Komendy i stan rozmowy

Komenda	Działanie
/exit lub /koniec	Zamyka interfejs. Nie uruchamia RAG.
/debug	R3/R6: przełącza szczegółowy widok; nie tworzy tury.
/sources	R3/R6: odczytuje zapisane źródła bez nowej tury i modelu. Naturalna prośba o źródła tworzy turę.
/clear	R3/R6: rozpoczyna nową rozmowę, czyści historię i ostatnie źródła, zachowuje tryb diagnostyczny oraz pliki wyników.

R2 nie interpretuje historii. R3 korzysta ze stałego przepływu i ograniczonego resolvera. R6 dodaje wybór narzędzia przez model. Brak rozpoznanego, jednoznacznego odniesienia wymaga doprecyzowania. Historia pomaga zrozumieć pytanie, lecz odpowiedź ma wynikać z dokumentów.

8Nazewnictwo i zapis wyników

wyniki/Rx/<data_id>/

Nazwę katalogu nadaje program. Zachowaj główny wynik z tabeli rozdziałów, pliki ocena_<id>.json oraz notebook. R1 tworzy kontrakt_zakresu_<id>.md. R6 dodaje raport_integracji_<id>.md.

Plik	Rola
tool_trace.jsonl	Skrócony zapis każdej próby narzędzia, także odrzuconej.
assistant_trace.jsonl	Skrócony przebieg każdej tury z identyfikatorami i śladem etapów.
functional_tests.jsonl	Pełne wyniki jedenastu scenariuszy R6.
surowe_wyniki.jsonl	Pełne wyniki tur; jawnie włączone w ćwiczeniach z fikcyjnym korpusem.
ocena_do_uzupelnienia.json	Szablon oceny. Gotową ocenę zapisujesz osobno jako ocena_<id>.json.

W zwykłym śladzie pytanie jest reprezentowane skrótem SHA-256. Pełne pytania, prompty i odpowiedzi zachowujemy jawnie w materiałach ćwiczeniowych do analizy. Nie dodawaj własnych poufnych danych do pakietu udostępnianego innym.

Po R6 otwórz notebooki/07_kontrola_zapisu.ipynb, wpisz ścieżkę katalogu w PROBA i uruchom kontrolę. Sprawdza identyfikatory, kompletność ocen i raportu, ale nie ocenia prawdziwości odpowiedzi.

9Lista kontroli przed zakończeniem

Zachowałem kontrakt R1, notebooki i wybrane wyniki R2–R6.
Oznaczyłem nowe wywołania, checkpoint i testy bez LLM.
Każda ocena wskazuje właściwy result_id i zawiera dowód.
Sprawdziłem źródła, brak wiedzy, doprecyzowanie i działanie zabronione.
Przetestowałem limit narzędzia i czyszczenie rozmowy.
Zapisałem raport R6 i sprawdziłem kompletność przez notebook 07.

10Gdy pojawi się problem

Nie działa import m5_tools

Uruchom Jupyter z Student i wybierz kernel Python M5. Zachowaj folder kod obok notebooki.

Ollama jest niedostępna

Sprawdź uruchomiony serwer, adres w konfiguracja.json i oba modele. Nie zmieniaj trybu automatycznie.

Digest embeddingu nie pasuje

Nie mieszaj indeksu z innym modelem. Użyj dostarczonego checkpointu lub uzgodnij z prowadzącym odbudowę indeksu.

Brak żądania w checkpoincie

Przywróć domyślne dane i prompt. Własne pytanie lub zmiana promptu wymaga trybu Ollama.

Model wybrał niewłaściwe narzędzie

Zachowaj raw_response i porównaj intencję z decyzją. Poprawność JSON nie oznacza trafności wyboru.

Ocena lub raport nie zostały zapisane

Zastąp wszystkie UZUPEŁNIJ własnym tekstem. Zapisz ponownie bez wykonywania prób.

Ślad nie zawiera pełnego pytania

To domyślna minimalizacja zapisu. Pełny wynik ćwiczenia znajduje się w pliku wynikowym i jawnie włączonym zapisie diagnostycznym.

11Zasady odbioru

Sposób oddania i znaczenie ćwiczeń dla zaliczenia określa prowadzący. Proponowany zestaw do przekazania to sześć notebooków, kontrakt R1, wybrane katalogi prób i raport R6. Materiały nie ustanawiają nowej punktacji kursu.

Dobra analiza błędnej odpowiedzi jest wartościowym wynikiem ćwiczenia. Nie poprawiaj surowego wyniku modelu; korektę i uzasadnienie zapisz w ocenie.

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

Ostatnia modyfikacja: sobota, 26 września 2026, 13:39