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

Ten moduł wyjaśnia, czym różni się rozmowa z modelem językowym od systemu odpowiadającego na podstawie własnych dokumentów. Przejdziesz od pytania wpisanego do czatu do prostego schematu RAG, w którym aplikacja wyszukuje potrzebny fragment, a model wykorzystuje go do przygotowania odpowiedzi. Najważniejsza umiejętność to sprawdzenie, czy konkretne twierdzenie rzeczywiście wynika ze wskazanego źródła.

Czytaj sześć rozdziałów w podanej kolejności. Każdy zawiera objaśnienia, przykład oraz ćwiczenie do wykonania w zeszycie lub w edytorze tekstu. Najpierw zapisz własną odpowiedź, a dopiero później zajrzyj do rozdziału „Odpowiedzi do ćwiczeń”.

Przykład przewodni to fikcyjny system DocAssist. Jego instrukcja i regulamin są materiałami dydaktycznymi. Pokazane polecenia analizujesz jako tekst; nie wykonujesz ich na swoim komputerze. Przykładowe odpowiedzi oznaczone jako demonstracyjne zostały przygotowane do nauki i nie są pomiarami jakości konkretnego modelu.

Po ukończeniu modułu

Plan modułu

Gdy wpisujesz pytanie do czatu, aplikacja przygotowuje wejście dla modelu i wyświetla wygenerowaną odpowiedź. Model językowy (LLM) tworzy tekst przez kolejne przewidywania tokenów.

Model wykorzystuje wzorce utrwalone podczas trenowania oraz treść aktualnie otrzymanego wejścia. Token jest jednostką reprezentacji tekstu: może odpowiadać części słowa, całemu słowu lub znakowi. Nie należy utożsamiać liczby tokenów z liczbą słów.

Przewidywanie kolejnych tokenów pozwala tworzyć użyteczne wyjaśnienia, podsumowania i propozycje. Sam ten mechanizm nie sprawdza jednak automatycznie zgodności wypowiedzi z Twoją lokalną instrukcją. Model może napisać przekonującą procedurę, mimo że nie otrzymał dokumentu, w którym ta procedura została określona.

Model i aplikacja

Model oraz interfejs czatu pełnią różne role. Model przetwarza dostarczone wejście. Aplikacja może dodatkowo odczytywać pliki, wybierać fragmenty historii, wyszukiwać informacje lub korzystać z narzędzi. Dlatego stwierdzenie „czat ma dostęp do dokumentów” wymaga ustalenia, jaka funkcja aplikacji ten dostęp zapewnia i co faktycznie przekazuje modelowi.

Co model rzeczywiście otrzymał

Załóżmy, że plik instrukcja.txt leży w katalogu na Twoim dysku. Wpisujesz do zwykłego czatu: „Co zrobić po zmianie konfiguracji DocAssist?”. Sama obecność pliku na komputerze nie włącza jego treści do rozmowy. Jeżeli nie wkleisz fragmentu ani aplikacja go nie odczyta i nie przekaże, model nie ma tego źródła w aktualnym wejściu.

Także zdanie „plik nazywa się instrukcja.txt” przekazuje tylko nazwę. Nie mówi, jaka jest treść pliku, wersja instrukcji ani warunki procedury. Dobrą praktyką jest osobne zapisanie pytania oraz materiału, który rzeczywiście trafił do modelu.

Okno kontekstowe i historia

Okno kontekstowe określa, ile tokenów może obejmować pojedyncze przetwarzanie; sposób podziału limitu między wejście i odpowiedź zależy od modelu oraz aplikacji. Instrukcje, historia rozmowy i fragmenty dokumentów konkurują o ograniczone miejsce. Długa rozmowa nie oznacza więc, że cała jej treść jest nadal dostępna modelowi.

Prompt, który można ocenić

Ogólna prośba „Opisz DocAssist” pozostawia szerokie pole odpowiedzi. Lepszy prompt określa zadanie, podstawę odpowiedzi, oczekiwany format i zachowanie przy braku danych — tak, by później można było sprawdzić wykonanie polecenia.

Zadanie: wyjaśnij, co użytkownik powinien sprawdzić po zmianie konfiguracji DocAssist.
Podstawa: wyłącznie przekazany fragment instrukcji.
Format: kroki, warunki wykonania i wskazanie źródła.
Jeśli fragment nie wystarcza, wskaż brakującą informację.

Odpowiedź modelu może być płynna, szczegółowa i uporządkowana, a jednocześnie nie mieć oparcia w źródle. Styl wypowiedzi nie jest miarą jej prawdziwości.

W pracy z dokumentacją potrzebujesz innego pytania: „Z którego fragmentu wynika to twierdzenie i czy fragment dotyczy właściwej wersji systemu?”.

Wiedza utrwalona w parametrach modelu może nie obejmować Twojego dokumentu albo jego najnowszej wersji. Dotyczy to szczególnie procedur lokalnych, regulaminów organizacji i instrukcji przygotowanych wyłącznie na potrzeby kursu. Nawet jeśli model zna podobny produkt, nie daje to podstaw do przenoszenia jego zasad na DocAssist.

Cztery problemy, które warto odróżniać

Halucynacją nazywa się w tym kontekście wygenerowaną treść przedstawioną jak fakt, choć jest zmyślona lub pozbawiona właściwej podstawy. Może nią być wymyślona funkcja, nazwa dokumentu, cytat, data lub procedura. Nie każda słaba odpowiedź jest jednak halucynacją. Zdanie „sprawdź stan usługi” może być zgodne z instrukcją, lecz za mało konkretne, by wykonać zadanie.

Źródło do analizy: regulamin DocAssist

Lokalny model a wiarygodność odpowiedzi

Słowo „lokalny” opisuje miejsce wykonywania obliczeń. Nie oznacza automatycznie, że model otrzymał wszystkie pliki z komputera, zna aktualne procedury albo nigdy się nie myli. Można uruchomić lokalny model i nadal zadawać mu pytania bez potrzebnego kontekstu.

Offline oznacza w tym materiale pracę bez połączenia z Internetem. Samodzielne czytanie i ćwiczenia spełniają ten warunek od razu. Uruchomienie modelu offline wymaga wcześniejszego przygotowania aplikacji i plików modelu — to osobna czynność techniczna, nie jest warunkiem zrozumienia treści tego modułu.

Kontekst to informacje przekazane modelowi na potrzeby konkretnego zadania: fragment instrukcji, treść regulaminu lub wynik wyszukania w bazie wiedzy.

Dodanie kontekstu zmienia podstawę odpowiedzi: model otrzymuje tekst, którego nie musiał znać wcześniej. Samo wklejenie dokumentu nie jest trenowaniem modelu i nie oznacza trwałego zapisania jego treści w parametrach.

W tym rozdziale samodzielnie wybierasz fragment i umieszczasz go obok pytania. Jest to ręczne przygotowanie kontekstu. Automatyczne wyszukiwanie odpowiedniego fragmentu pojawi się w opisie RAG w rozdziale 5.

Instrukcja, która będzie podstawą odpowiedzi

sudo systemctl restart docassist-api
systemctl is-active docassist-api

journalctl -u docassist-api -n 50 --no-pager

Pytanie, kontekst i zasady odpowiedzi

Pytanie przewodnie brzmi: „Co należy zrobić po zmianie pliku konfiguracyjnego DocAssist, aby sprawdzić poprawność działania usługi?”. Potrzebujesz sekcji 5.2, ponieważ zawiera czynność, polecenie sprawdzające, oczekiwany wynik oraz warunek dalszego działania. Sama sekcja o kopii przed aktualizacją dotyczy innego zadania.

Poniższy schemat rozdziela polecenie dla modelu od analizowanego dokumentu. W miejscu oznaczonym nawiasami wstaw pełną treść sekcji 5.2, łącznie z poleceniami i warunkiem.

Odpowiedz wyłącznie na podstawie KONTEKSTU.
Przedstaw kroki i warunki ich wykonania.
Wskaż nazwę pliku, wersję i sekcję.
Jeśli brakuje danych, napisz, czego nie można ustalić.

KONTEKST
Źródło: instrukcja.txt, wersja 1.4, sekcja 5.2
[pełna treść sekcji 5.2]
KONIEC KONTEKSTU

PYTANIE
Co należy zrobić po zmianie pliku konfiguracyjnego DocAssist,
aby sprawdzić poprawność działania usługi?

Oznaczenie granic ułatwia czytanie i analizę wejścia. Nie daje jednak gwarancji, że model zawsze poprawnie oddzieli dane od instrukcji. Dokument źródłowy traktujesz jako materiał do odpowiedzi, a nie jako upoważnienie do wykonywania poleceń lub zmiany zasad pracy asystenta.

Odpowiedź oparta na kompletnym fragmencie

Zwróć uwagę na warunek. Dokument nie nakazuje wyświetlania dziennika tylko wtedy, gdy pojawi się słowo failed. Mówi o każdym wyniku innym niż active. Zawężenie tego warunku zmieniłoby znaczenie procedury. Podobnie pominięcie oczekiwanego wyniku utrudniłoby ocenę, czy sprawdzenie zakończyło się poprawnie.

Gdy kontekst jest niepełny

Załóżmy, że przekazano tylko pierwsze zdanie sekcji 5.2 oraz polecenie restartu. Model może na tej podstawie opisać ponowne uruchomienie. Nie ma jednak w tym fragmencie polecenia sprawdzającego, oczekiwanego wyniku ani sposobu wyświetlenia dziennika. Odpowiedź powinna wyraźnie wskazać te ograniczenia.

Jest użyteczna, ponieważ oddziela to, co wiadomo, od brakujących danych. Dopisanie znajomego polecenia z pamięci naruszyłoby przyjętą zasadę odpowiedzi wyłącznie na podstawie kontekstu.

Dokument jest nośnikiem informacji, a baza wiedzy jest uporządkowanym zbiorem źródeł przygotowanych do wykorzystania przez system.

Fragment dokumentu, często nazywany chunk, jest mniejszą jednostką tekstu wybieraną do odpowiedzi. Aby można było ustalić jego pochodzenie, treści towarzyszą metadane: na przykład nazwa pliku, wersja i numer sekcji.

Nie przekazujemy zawsze całej bazy wiedzy do modelu. Duży zbiór może przekraczać dostępny kontekst, zawierać niepowiązane informacje lub wiele wersji tej samej procedury. Wybór potrzebnych fragmentów ogranicza ilość wejścia i pomaga skupić odpowiedź na pytaniu. Nie oznacza to jednak, że najkrótszy fragment będzie najlepszy: trzeba zachować informacje konieczne do interpretacji.

Granica fragmentu ma znaczenie

W DocAssist sekcja 5.2 tworzy spójną procedurę. Jeżeli oddzielisz polecenie wyświetlenia dziennika od zdania „Jeżeli wynik jest inny niż active”, możesz utracić warunek wykonania. System otrzyma wtedy poprawne słowa, ale niepełną relację między nimi. Dobry fragment zachowuje czynność, jej warunki i niezbędne objaśnienia.

Metadane umożliwiają powrót do źródła

Powyższy identyfikator fragmentu jest przykładem projektowym, a nie obowiązkową nazwą pola w każdym systemie RAG. Ważna jest możliwość odtworzenia pochodzenia tekstu. Numery stron podaje się wtedy, gdy źródło ma rzeczywistą, stabilną paginację. Numer strony tego podręcznika nie jest numerem strony pliku instrukcja.txt.

Dwa warunki użytecznego wskazania źródła

Oba warunki trzeba spełnić równocześnie. Prawidłowa nazwa pliku nie naprawia błędnego numeru sekcji ani nie potwierdza dowolnej wypowiedzi modelu.

Weryfikacja nie kończy się na cytacie

Jeżeli w bazie znajdują się dwie wersje instrukcji, potrzebujesz ustalić, która dotyczy rozpatrywanego systemu. Cytat z nieaktualnego dokumentu może być wierny, a mimo to nie odpowiadać bieżącej sytuacji. Zapis wersji dokumentu nie rozstrzyga sam jej aktualności, lecz pozwala zadać właściwe pytanie i odtworzyć decyzję.

RAG to skrót od Retrieval Augmented Generation, czyli generowania wspomaganego wyszukiwaniem.

W odpowiedzi na pytanie system najpierw wyszukuje przydatne informacje, a następnie przekazuje je modelowi wraz z pytaniem i instrukcją odpowiedzi. Model nadal generuje tekst, ale otrzymuje dodatkową podstawę pochodzącą z wybranych dokumentów.

Przygotowanie źródeł i odpowiedź na pytanie

Dwa zasadnicze etapy odpowiedzi RAG to wyszukiwanie i generowanie. Weryfikacja wyniku jest potrzebną częścią pracy z systemem, lecz nie należy mylić jej z gwarancją zapewnianą automatycznie przez samą nazwę RAG.

Co wyszukuje system

Wyszukiwanie może opierać się na słowach, reprezentacjach wektorowych albo połączeniu metod. Embedding to liczbowa reprezentacja tekstu, którą można wykorzystać do porównywania fragmentów pod kątem podobieństwa. Baza lub indeks wektorowy pomaga odnajdywać takie reprezentacje. Sama obecność bazy wektorowej nie wystarcza jednak, aby otrzymać kompletny system odpowiadania.

Przepływ informacji w przykładzie DocAssist

Schemat poniżej opisuje logikę działania; nie jest kodem do uruchomienia.

W ręcznym ćwiczeniu z rozdziału 3 rolę wybierającego fragment pełnisz Ty. W RAG robi to mechanizm wyszukiwania. Generowanie może wykorzystywać ten sam model w obu przypadkach. Różnica dotyczy przede wszystkim sposobu przygotowania kontekstu i zachowania informacji o źródle.

Porównanie powinno pokazać, co zmienia dostęp do dokumentu i jak rozpoznajesz jakość odpowiedzi. Samo wrażenie, że drugi tekst „brzmi lepiej”, jest niewystarczające.

Potrzebujesz tego samego pytania, zapisanego wejścia oraz kryteriów ustalonych przed oceną.

Poniższy eksperyment możesz przeprowadzić bez modelu. Otrzymujesz trzy odpowiedzi demonstracyjne przygotowane do analizy. Nie są rzeczywistymi wynikami pomiaru ani dowodem przewagi określonego narzędzia. Twoim zadaniem jest ocenić je względem źródła i warunków wariantu.

Warianty porównania

We wszystkich wariantach pytanie brzmi: „Co należy zrobić po zmianie pliku konfiguracyjnego DocAssist, aby sprawdzić poprawność działania usługi?”. Pełna instrukcja z rozdziału 3 jest wzorcem dla osoby oceniającej. Nie zakładaj, że model otrzymał ją w każdym wariancie.

Wariant A różni się od B zarówno kontekstem, jak i dodatkową instrukcją. To demonstracja całego sposobu pracy, a nie pomiar wyizolowanego wpływu jednego czynnika. Jeżeli chcesz zbadać wyłącznie wpływ fragmentu, utrzymaj identyczną instrukcję, pytanie i ustawienia, a zmień tylko kontekst. Porównanie B z C przy tej samej instrukcji ułatwia ocenę znaczenia trafności kontekstu.

Trzy odpowiedzi do oceny

Odpowiedź A uczciwie ujawnia brak dokumentu, lecz jest ogólna — nie przenoś jej automatycznie do instrukcji obsługi. Odpowiedź C nie wykonuje głównego zadania, ale poprawnie wyznacza granicę dostępnej informacji. Dla wariantu z nietrafnym kontekstem zgłoszenie braku danych jest zachowaniem pożądanym.

Kryteria oceny

Oceniaj osobno użyteczność procedury i rzetelność względem dostępnego źródła. W przeciwnym razie poprawne powstrzymanie się od dopowiedzenia danych może zostać niesłusznie uznane za tak samo zły wynik jak zmyślona procedura.

Jeżeli powtórzysz eksperyment z lokalnym modelem

Zapisz nazwę i wersję modelu, ustawienia generowania, pełny prompt, przekazany fragment oraz niezmienioną odpowiedź. Zanotuj też datę próby i ocenę z uzasadnieniem. Ustawienia i ta sama nazwa modelu pomagają porównywać wyniki, ale nie gwarantują identycznego tekstu na wszystkich komputerach i w każdej implementacji.

Powtórz próby, jeśli chcesz sprawdzić zmienność. Nie wybieraj tylko najlepiej brzmiącej odpowiedzi. Jeden wynik wskazuje, co wydarzyło się w konkretnej próbie; dopiero większy zestaw pytań i kontrolowanych warunków pozwala formułować szersze wnioski o systemie.

Model językowy generuje odpowiedź z otrzymanego wejścia. Nie zna automatycznie plików znajdujących się obok aplikacji. W RAG mechanizm wyszukiwania wybiera kontekst, a model przygotowuje odpowiedź. Oba etapy mogą być źródłem błędów.

Lista końcowa

Powiązanie z pakietem ćwiczeniowym

Ten dokument wystarcza do nauki offline. Rozszerzeniem są materiały w katalogu Student pakietu „Moduł 1”: instrukcja M12_M1_instrukcja_pracy.docx, sześć kart w karty_pracy i pliki R1–R6 w notebooki. Plik 00_sprawdzenie_srodowiska.ipynb pomaga sprawdzić środowisko. Wersja papierowa i notebookowa nie stanowią dwóch odrębnych obowiązkowych zadań.

Co zachować po pracy

Zachowaj odpowiedzi do sześciu ćwiczeń i tabelę A–B–C. Zapisuj twierdzenie, fragment źródła, ocenę i uzasadnienie. Ten sposób pracy wykorzystasz dalej przy przygotowywaniu dokumentów i budowie wyszukiwania.

Porównuj przede wszystkim sens i uzasadnienie. Twoje sformułowania nie muszą być identyczne.

Ćwiczenie 1 — Dostępne informacje

Model otrzymał nazwę instrukcja.txt, nazwę DocAssist i pytanie o ponowne uruchomienie. Nie otrzymał treści instrukcji, jej wersji ani konkretnej nazwy usługi. Odpowiedź o restarcie i sprawdzeniu stanu może wynikać z ogólnego wzorca postępowania, więc nie potwierdza odczytania pliku.

Przykładowe wymagania: użyj wyłącznie przekazanego fragmentu; podaj kroki wraz z warunkami; wskaż plik, wersję i sekcję; zgłoś brakujące informacje. Do wykonania takiego zadania trzeba jeszcze dodać właściwy fragment — samo dopisanie wymagań go nie zastępuje.

Ćwiczenie 2 — Ocena twierdzeń

O1 zawiera dwa niepotwierdzone twierdzenia: godziny 8:00–16:00 oraz czas reakcji 15 minut. Sekcja R4 nie określa żadnej z tych wartości. Nie wolno na tej podstawie twierdzić, że operator nie ma dyżurów lub że nigdy nie odpowiada w 15 minut.

O2 jest sprzeczne z R1, która wprost stwierdza, że korzystanie z czatu nie nadaje uprawnień operatora. O3 jest potwierdzone przez R2. Poprawna odpowiedź o godzinach może brzmieć: „Regulamin DocAssist w wersji 1.0, sekcja R4, nie określa godzin dyżurów operatora”.

Ćwiczenie 3 — Zakres kontekstu

Pełna sekcja 5.2 pozwala opisać restart, sprawdzenie stanu, oczekiwany wynik active i wyświetlenie 50 wpisów dziennika przy wyniku innym niż active. Fragment skrócony pozwala jedynie wskazać restart — brakuje w nim sposobu sprawdzenia stanu, kryterium poprawności i dalszego postępowania.

Przykładowa odpowiedź częściowa: „Uruchom ponownie usługę poleceniem sudo systemctl restart docassist-api. Przekazany fragment nie opisuje, jak sprawdzić stan usługi ani jaki wynik jest prawidłowy”. Przy sekcji 6.1 należy wskazać, że opisano kopię przed aktualizacją, a nie sprawdzenie po zmianie konfiguracji. Więcej tekstu pomaga tylko wtedy, gdy zachowuje informacje potrzebne do pytania.

Ćwiczenie 4 — Treść i źródło

T1 jest potwierdzone, a sekcja 5.2 wskazana poprawnie. T2 zawiera prawidłową czynność, lecz błędny odnośnik: należy wskazać sekcję 5.2 zamiast 6.1. T3 jest potwierdzone przez właściwą sekcję; istotne jest zachowanie warunku „inny niż active”. T4 nie ma podstawy w źródle: instrukcja nie wymaga trzech restartów.

„Strona 18” nie identyfikuje miejsca w źródłowym TXT, ponieważ plik ten nie ma stałej paginacji. Użyj zapisu „instrukcja.txt, wersja 1.4, sekcja 5.2”. Jeżeli tekst został później umieszczony w innym dokumencie, jego nowe numery stron nie stają się automatycznie metadanymi oryginału.

Ćwiczenie 5 — Lokalizacja błędu

A dotyczy przygotowania fragmentów: sprawdź, czy komenda i warunek pozostały razem. B dotyczy wyszukiwania: obejrzyj fragmenty faktycznie zwrócone dla pytania. C dotyczy generowania: porównaj twierdzenie o trzech restartach z otrzymaną sekcją 5.2 i oznacz dopowiedzenie.

Większy model nie naprawia automatycznie B, ponieważ nadal otrzymuje fragment o innym zadaniu. Potrzebna jest kontrola mechanizmu wyboru kontekstu. Gdy nie ma właściwego źródła, pożądanym zachowaniem generatora jest zgłoszenie braku informacji.

Ćwiczenie 6 — Przykładowa ocena

A daje ogólny kierunek, ale bez konkretnych poleceń, oczekiwanego wyniku i dokładnego warunku; wyraźnie wskazuje brak lokalnej instrukcji. B zachowuje wszystkie wymagane elementy procedury i właściwe źródło. C poprawnie opisuje ograniczenie przekazanej sekcji, dlatego brak pełnej procedury nie jest tu zmyśleniem ani błędem rozpoznania braków.

Aby wariant C mógł dać pełną odpowiedź, należy przekazać odpowiedni fragment, czyli sekcję 5.2. Przykładowy wniosek: właściwy kontekst umożliwia przygotowanie szczegółowej odpowiedzi, którą można sprawdzić w źródle; nietrafny kontekst wymaga zgłoszenia braku danych. Ograniczenie: odpowiedzi są przygotowanymi przykładami, a A i B różnią się również instrukcją, więc nie jest to pomiar wyłącznego wpływu kontekstu ani jakości modelu.

Krótkie definicje pojęć w znaczeniu przyjętym w tym module.