W tym cyklu zastosujesz umiejętności z kolejnych modułów do jednego projektu: asystenta, który pomaga korzystać z dokumentacji DocAssist. Zaczniesz od pytań i granic wiedzy modelu, przygotujesz dokumenty oraz wyszukiwanie, połączysz je z odpowiedziami i rozmową, a na końcu sprawdzisz jakość rozwiązania. Wyniki wcześniejszych etapów stają się wejściem do następnych.

Sam płynnie napisany tekst nie wystarcza, aby uznać odpowiedź za poprawną. Asystent powinien odnaleźć właściwe informacje, zachować warunki opisanych procedur, wskazać źródła i jasno powiedzieć, kiedy dokumentacja nie daje odpowiedzi. Nauczysz się sprawdzać każdy z tych elementów na podstawie zapisanych wyników.

Wspólny przypadek DA-01

Po zmianie konfiguracji fikcyjnego DocAssist we wtorek o 18:20 aplikacja zgłasza brak połączenia, a awaria uniemożliwia pracę całego zespołu. Użytkownik potrzebuje wskazówek sprawdzenia stanu, postępowania po nieudanym uruchomieniu, eskalacji poza dyżurem i przygotowania zgłoszenia. Zadaje pytania uzupełniające, prosi o źródła i metadane, a następnie żąda wykonania restartu.

Opis przypadku określa potrzebę użytkownika. Odpowiedzi o procedurach musisz oprzeć na dokumentach. Sam opis DA-01 nie jest źródłem procedur i nie trafia do indeksu wiedzy.

DocAssist korzysta z RAG: przed wygenerowaniem odpowiedzi wyszukuje fragmenty dokumentacji i przekazuje je modelowi jako kontekst. Cały przepływ projektu wygląda tak:

Dokumenty są porządkowane i dzielone na fragmenty z metadanymi. Embeddingi przedstawiają ich znaczenie w postaci wektorów, a indeks umożliwia wyszukiwanie. Wybrane fragmenty tworzą kontekst promptu. Następnie oceniasz odpowiedź i sprawdzasz, czy wskazane źródła rzeczywiście potwierdzają jej twierdzenia.

Logika pracy przez cały cykl

1. Plan testów

   Określ odbiorcę, zakres pomocy i granice działania. Ustal, czego będziesz wymagać od rozwiązania i jaki dowód pozwoli ocenić wynik. Szczegółowe kontrakty M6 zatwierdź przed końcowym pomiarem.

2. Zestaw pytań

   Zapisz pytania związane z DA-01. Uwzględnij pytania bezpośrednie, parafrazy, pytania zależne od historii oraz sytuacje, w których informacji brakuje. Oczekiwania ustalaj na podstawie właściwej wersji dokumentów.

3. Retrieval i kontekst

   Sprawdź, co wyszukiwarka odnalazła i jakie fragmenty rzeczywiście trafiły do modelu. Ranking top-k oraz końcowy kontekst mogą się różnić; zachowaj oba zapisy.

4. Odpowiedzi, źródła i zachowanie

   Oceń zgodność i kompletność odpowiedzi, potwierdzenie twierdzeń w źródłach, obsługę rozmowy, komunikaty o braku danych oraz kontrolę narzędzi.

5. Analiza błędów i konfiguracji

   Znajdź pierwszy etap, na którym wynik przestaje spełniać oczekiwania. Sprawdź jedną zmianę konfiguracji, porównaj ją z wersją bazową i oceń, czy nie pogorszyła innych przypadków.

6. Dokumentacja i demonstracja

   Zbierz pliki, konfigurację, surowe wyniki, oceny i instrukcję odtworzenia. Pokaż działanie rozwiązania oraz jego ograniczenia i uzasadnij, czy jest gotowe do demonstracji.

Ta logika prowadzi przez cały projekt. Poszczególne moduły dostarczają kolejnych elementów rozwiązania; pełna ocena i porównanie poprawy następują w M6.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

Po materiałach merytorycznych i teście samokontroli danego modułu wykonaj odpowiadające mu zadanie DocAssist. Pracuj indywidualnie, w kolejności M1 → M2 → M3 → M4 → M5 → M6. Cykl jest nieobowiązkowym rozszerzeniem ćwiczeń podstawowych.

Orientacyjny czas całego cyklu wynosi 6,5–9 godzin przy przygotowanym środowisku. Instalacja, odtworzenie brakujących etapów i poprawki mogą wymagać dodatkowego czasu.

Na początku przeczytaj opis DA-01 i polecenie M1, wybierz ścieżkę praktyczną albo analityczną, a następnie zapisz plan testów przed pierwszym porównaniem. Możesz dołączyć później, korzystając z materiału referencyjnego: oznacz miejsce przejścia i jego pochodzenie. Dalsze wnioski odnoszą się wtedy do tej referencji.

Pełne polecenia, wymagane pliki i kryteria samooceny znajdziesz w sześciu zadaniach udostępnionych w kursie. Mapa pokazuje ich wspólny sens i zależności.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

Pobierz z kursu plik DocAssist_dane_i_notebooki.zip i rozpakuj go do własnego katalogu. Otrzymasz folder Student. Zachowaj jego strukturę i pracuj na rozpakowanych plikach. Wszystkie ścieżki w tej instrukcji i w zadaniach odnoszą się do tego folderu.

Student/
  CZYTAJ_NAJPIERW.html       — pełna instrukcja cyklu
  dane/                    — dokumenty, pytania, scenariusze i 6 notebooków
    M1/                    — dokumenty wprowadzające
    M2_zrodla/             — źródła aktualne i jeden plik archiwalny
    M6/                    — kontrakty testów i rubryki
    notebook_support/      — kod, konfiguracje, dane referencyjne, checkpointy
    notebook_utils.py      — funkcje obsługujące notebooki cyklu
    requirements_notebooki.txt
  szablony/                — pomocniczy plan testów
  wyniki/                  — powstaje po rozpoczęciu własnych prób

Paczka zawiera zaplecze potrzebne notebookom dodatkowym. Podręczniki, prezentacje oraz podstawowe pakiety Student M1–M6 z kursu służą do nauki i powtórek. Ich notebooki możesz wykorzystać zamiast notebooków cyklu, jeśli samodzielnie dostosujesz je do pełnego polecenia; nie są dodatkowym obowiązkiem w głównej ścieżce pracy.

Dwie wersje dokumentacji

• M1: używaj wyłącznie dane/M1/instrukcja.txt i dane/M1/regulamin.md. To punkt wyjścia do porównania odpowiedzi z kontekstem i bez niego.
• Od M2: pracuj na pięciu plikach dane/M2_zrodla: instrukcja.txt, regulamin.md, regulamin_v1_3.md, pomoc.html oraz docassist.pdf. Regulamin 1.3 jest archiwalny; pozostaje w inwentarzu, ale nie należy do korpusu bieżących odpowiedzi.
• Zachowaj identyfikatory dokumentów z inwentarza, szczególnie DOC-INSTR. Własne identyfikatory fragmentów muszą być unikalne i zgodne z późniejszym kluczem trafności oraz kontraktami testów.

Opis DA-01 z dane/opis_przypadku.txt przedstawia potrzebę użytkownika. Nie normuje procedur i nie trafia do indeksu. Zmiana dokumentacji między M1 i M2 jest celowa; różnic wyników nie przypisuj wyłącznie promptowi.

Pytania, scenariusze i ocena

• dane/pytania_M3.json — 12 pytań do wyszukiwania; zadanie M3 wskazuje sześć wybranych.
• dane/pytania_M4_M5.json — pytania P01–P06 do odpowiedzi RAG.
• dane/scenariusze_M5.json — dialog czteroturowy oraz trzy próby w nowych sesjach.
• dane/zakres_M6.json — wybór 12 rekordów do końcowej oceny.
• dane/M6/test_cases_wzorzec.jsonl, rubryki.json i slowniki.json — pełne kontrakty i zasady oceny M6. Listy zakresów checkpointów opisują dostępność; same zapisane wywołania są w notebook_support.
• szablony/plan_testow_szablon.json — pomocniczy plan do uzupełnienia przed M1; nie zastępuje kontraktów walidatora M6.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

Użyj Python 3.12 lub 3.11. W terminalu otwartym w katalogu Student wykonaj:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r dane/requirements_notebooki.txt
.\.venv\Scripts\python.exe -m ipykernel install --prefix .venv --name docassist_cykl --display-name "DocAssist - cykl zadan"
.\.venv\Scripts\python.exe -m jupyterlab

W Linux/macOS użyj python3 oraz .venv/bin/python. Instalacja bibliotek wymaga dostępu do Internetu. Jeśli korzystasz z istniejącego środowiska, sprawdź zależności z requirements_notebooki.txt.

Do nowych wywołań M1 i M3–M6 uruchom lokalny Ollama i przygotuj modele z materiałów kursowych:

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

M2 nie używa LLM. Checkpointy odtwarzają zapisane wywołania i wymagają zgodnego indeksu referencyjnego. Digest modelu embeddingowego musi odpowiadać indeksowi przy nowych wywołaniach. Wagi modeli i środowisko .venv nie są dołączone do paczki.

Podane w fikcyjnym PDF DocAssist parametry RAM i miejsca na dysku należą do opisu systemu w ćwiczeniu. Wymagania lokalnych modeli sprawdzaj w materiałach kursowych.

1. Po uruchomieniu JupyterLab otwórz folder dane, a następnie notebook M1.

2. Wybierz kernel DocAssist - cykl zadan albo własny kernel Python ze wskazanymi bibliotekami.

3. Przed uruchomieniem nowych wywołań sprawdź, czy działa Ollama i czy masz modele wskazane w konfiguracji. Jeśli używasz innego tagu modelu, zmień konfigurację roboczą w notebooku i zapisz tę zmianę w notatce.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

W JupyterLab otwórz plik w katalogu dane i wybierz kernel DocAssist - cykl zadan albo przygotowany kernel Python z tymi bibliotekami. Dla każdego notebooka używaj osobnego kernela. Wykonuj komórki od góry przez Shift+Enter, uzupełniając wskazane pola i formularze.

Pliki z dopiskiem draft, plany, oceny i notatki zawierają pola do samodzielnego uzupełnienia. Otwórz je w JupyterLab, wpisz własne oceny, zapisz plik, a potem wykonaj kolejną komórkę notebooka. Blokady przed pomiarem chronią kolejność: najpierw oczekiwania i plan, potem wynik i ocena.

Surowych odpowiedzi nie poprawiaj. Błąd wykonania i brak danych pozostają widoczne. Przy ponownym wykonaniu pomiaru rozpocznij nową próbę komórką przygotowania; nie nadpisuj wcześniejszych rezultatów. W M3 instrukcja wskazuje samodzielną komórkę kontroli indeksu po restarcie kernela.

Notebook wspiera wykonanie, uczestnik ocenia

Notebooki zapisują dane i przygotowują formularze. Samodzielnie ustalasz oczekiwania, wybierasz właściwe fragmenty, akceptujesz bazę, przypisujesz twierdzenia do źródeł, oceniasz błędy i formułujesz wnioski. Pozostawienie pól UZUPEŁNIJ nie oznacza ukończenia zadania.

Komórka przygotowania tworzy nowy folder próby. Po jej ponownym wykonaniu kolejne komórki odnoszą się do nowej próby: nie mieszaj plików z różnych uruchomień. Samo Run All bez uzupełnienia wymaganych decyzji nie stanowi poprawnego wykonania.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

Każdy notebook zapisuje wyniki w Student/wyniki/M1 … M6, w osobnym folderze próby. Wskaż w notatce folder i identyfikator ocenianego uruchomienia.

Gdy pozostawisz pustą ścieżkę wejścia, notebook wybierze ostatni dostępny eksport z wcześniejszego etapu w tej paczce i wypisze jego lokalizację. Przed kontynuacją sprawdź, czy to właściwa wersja. Możesz wpisać pełną ścieżkę do wybranej bazy lub indeksu.

Pliki pomocnicze w notebook_support są materiałem wejściowym. Notebook kopiuje je do runtime w folderze próby; modyfikuj własną kopię. Zapisz zmiany kodu lub konfiguracji, które wpływają na oceniany prototyp. Nie nadpisuj checkpointów ani poprzednich pomiarów.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

Przy każdym etapie zapisz użyty korpus lub indeks, konfigurację, tryb pracy i pochodzenie wyników: własne wykonanie Ollama, checkpoint (odtworzenie), DEMO albo test kontrolowany. Zachowuj surowe odpowiedzi i oceniaj je samodzielnie. Rozpoznany i uzasadniony błąd modelu może być wartościowym rezultatem zadania.

Nowe pytania, własny indeks i zmienione prompty wymagają rzeczywistych wywołań lokalnych modeli. Checkpoint obsługuje tylko zgodne zapisane żądania. Jeśli potrzebnego wyniku nie ma, oznacz próbę jako niewykonaną. W M6 rozdziel dostępne wyniki retrieval, wyniki asystenta i historyczne wyniki M5; poprawa wyszukiwania nie jest jeszcze dowodem poprawy pełnej odpowiedzi.

Oceniaj osobno wyszukiwanie, kontekst, odpowiedź, źródła, rozmowę, narzędzia i wynik użytkowy. Wysoki wynik podobieństwa, etykieta źródła czy status odpowiedzi nie wystarczają do uznania treści za poprawną. Każdy ważny wniosek powinien mieć dowód; brak dowodu opisz jako nierozstrzygnięty. Metryki podawaj z licznikiem i mianownikiem.

Zakres dostępnych dowodów

M6: pełne kontrakty, wybrany pomiar

Pełny zestaw ma 24 rekordy i 13 kategorii. Notebook tworzy roboczą kopię evaluation/test_cases.jsonl w folderze próby. Dopasuj odwołania do fragmentów w całym zestawie, zachowując sens kontraktów, zatwierdź je przed pomiarem i wykonaj pełną walidację.

Wybrany pomiar obejmuje 12 rekordów / 14 tur i w pełnej postaci wymaga nowych wywołań. Dostępny zakres offline różni się dla retrieval i asystenta. Wspólny podzbiór z zakresem cyklu to: retrieval — M6-T001, T002, T004, T006, S001; asystent — M6-T007, T008, T010. Przy skrótach obowiązuje prefiks M6-. Pozostałe próby oznacz jako niewykonane.

Przed sprawdzeniem poprawy zachowaj wersję bazową. Notebook porównuje jedną zmianę top_k z 3 na 5. Porównuj sparowane przypadki, a nowe wyniki oceniaj według tych samych oczekiwań. Porównanie offline dotyczy retrieval; nie dowodzi poprawy pełnej odpowiedzi asystenta. Własną zmianę kodu lub innych parametrów opisz i przetestuj osobno.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026

Po każdym etapie przygotuj pliki wskazane w jego poleceniu: notatkę, wyniki oraz odpowiednie artefakty projektu. Prześlij ZIP albo notatkę z załącznikami zgodnie z instrukcją zadania w Moodle. Zrzuty ekranu mogą uzupełniać dane, ale nie zastępują surowych wyników.

• Rozwiązanie: kod lub notebooki, konfiguracja, kompletny indeks oraz źródła lub manifest ich pochodzenia.
• Dowody jakości: kontrakty testów, surowe wyniki, własne oceny i porównanie jednej zmiany z wersją bazową wraz ze sprawdzeniem regresji.
• Raport końcowy: 2–3 strony opisujące działanie, wyniki, ograniczenia i uzasadnioną decyzję o gotowości do demonstracji.
• Odtworzenie i pokaz: instrukcja uruchomienia oraz zapis ekranów i wyników lub opcjonalne nagranie 3–5 minut. Pokaż odpowiedź ze źródłem, rozmowę zależną od historii, komunikat o braku wiedzy i odrzucenie restartu.

Nie dołączaj środowiska .venv ani wag modeli. W ścieżce analitycznej raportuj wyłącznie przeanalizowane i dostępne próby; jasno wskaż zakres niewykonany. Odbiorca pracy powinien móc odnaleźć dowód każdego głównego wniosku i rozpoznać ograniczenia rozwiązania.

Porządek plików oddawanych w Moodle

1. Zapisz uzupełniony notebook. Wybierz folder próby zgodny z notatką i wynikami, które oceniasz.

2. Dołącz materiały wymagane w poleceniu modułu: notatkę, surowe prompty i odpowiedzi lub ślady, własne oceny oraz właściwą bazę albo kompletny indeks. Wyniki spoza notebooka też muszą mieć opis pochodzenia.

3. W M6 dołącz kod i konfigurację roboczego runtime, kontrakty testów oraz instrukcję odtworzenia. Jeżeli konfiguracja wskazuje pełną ścieżkę z Twojego komputera, przed przekazaniem przygotuj kopię do uruchomienia na innym komputerze i sprawdź ją według instrukcji.

4. Prześlij pracę przez moduł Zadanie w odpowiednim module kursu. Paczka pobrana z kursu jest materiałem wejściowym — oddajesz własne rezultaty, a nie jej niezmienioną kopię.

DocAssist · Instrukcja uczestnika · Wersja z 6 października 2026