3. R2. Kontrakty przypadków i scenariuszy

ENHANCER+ · Moduł 6 · Ewaluacja RAG · Rozdział

Kontrakt testu opisuje, co ma się wydarzyć dla konkretnego wejścia. Zamiast jednej wzorcowej odpowiedzi zapisujesz wymagane fakty, dopuszczalne źródła, oczekiwane zachowanie i treści zabronione. Dzięki temu poprawna parafraza nie przegrywa tylko dlatego, że różni się słowami od klucza.

Zestaw startowy i zakres

Pakiet zawiera 24 przypadki w 13 kategoriach. Jeden z nich jest scenariuszem z trzema turami, więc pełne wykonanie asystenta obejmuje 26 tur. Minimum 20 przypadków i 8 kategorii jest propozycją dydaktyczną przyjętą w materiałach. Różnorodność obejmuje m.in. pytania proste, parafrazy, procedury, wiele źródeł, brak danych, działania zabronione, metadane, doprecyzowanie i odwołania do poprzednich źródeł.

Oczekiwania w pakiecie są propozycją do świadomego zatwierdzenia. Otwórz źródła i sprawdź fakty. Jeżeli zmieniasz kontrakt, zmień wersję zestawu i wykonaj powiązane próby ponownie. Nie poprawiaj oczekiwania tylko dlatego, że model odpowiedział inaczej.

Pełny rekord zamiast skrótu ze slajdu

Poniżej znajduje się cały przypadek T001 odczytany z pakietu. W JSON wartości logiczne zapisuje się małymi literami, a brak wartości jako null. W Pythonie odpowiadają im True, False i None.

Pełny kontrakt z pakietu Studenta

{
  "test_id": "M6-T001",
  "test_set_version": "m6-1.0",
  "category": "direct_question",
  "question": "Jak sprawdzić stan usługi docassist-api?",
  "initial_history": [],
  "expected_status": "answered",
  "expected_reason": "answer_generated",
  "expected_tool": {
    "name": "answer_from_documents",
    "arguments": {
      "question": "Jak sprawdzić stan usługi docassist-api?"
    }
  },
  "expected_sources": [
    {
      "document_id": "DOC-INSTR",
      "section": "Ponowne uruchomienie usługi",
      "required_chunk_ids": [
        "DOC-INSTR-dd6055d675-0002"
      ],
      "alternative_chunk_ids": []
    }
  ],
  "required_facts": [
    "systemctl is-active docassist-api",
    "active"
  ],
  "optional_facts": [],
  "forbidden_claims": [],
  "critical_conditions": [],
  "applicable_criteria": {
    "context": [
      "trafnosc",
      "pokrycie",
      "wystarczalnosc",
      "niski_szum",
      "spojnosc",
      "identyfikowalnosc"
    ],
    "answer": [
      "poprawnosc",
      "kompletnosc",
      "oparcie",
      "precyzja",
      "adekwatnosc",
      "ostroznosc"
    ]
  },
  "retrieval_question": "Jak sprawdzić stan usługi docassist-api?",
  "contract_note": "Przeczytaj źródła i zatwierdź oczekiwania przed wykonaniem. Oceny wyników wypełniasz samodzielnie."
}

question jest wiadomością użytkownika. retrieval_question jest samodzielnym pytaniem do izolowanego R3. initial_history opisuje jawne wejście historii. applicable_criteria wyznacza kryteria, które rzeczywiście mają sens w tym przypadku. Puste forbidden_claims nie znosi ogólnych zasad pracy aplikacji; oznacza, że kontrakt nie dodaje własnych szczegółowych zakazów. Możesz je doprecyzować przed pomiarem, np. zakazać twierdzenia, że sprawdzanie stanu samo restartuje usługę.

Jak czytać grupy źródeł

Każdy obiekt expected_sources jest jedną wymaganą grupą dowodów. Wszystkie required_chunk_ids tej grupy muszą być obecne, chyba że w kontrakcie wskazano pojedynczy alternatywny fragment, który samodzielnie zastępuje całą grupę. Fragment pomocniczy nie jest takim substytutem. W dostarczonym zestawie listy alternatyw są puste.

Rozważ dwie grupy: procedurę restartu i procedurę przywrócenia kopii. Znalezienie pierwszej grupy daje częściowe pokrycie. Nie oznacza, że pytanie o obie sytuacje ma już pełną podstawę odpowiedzi. Jeśli informacja jest rozbita na dwa fragmenty jednej grupy, znalezienie tylko jednego może dać Hit@k, ale jeszcze nie spełnia tej grupy.

Dwa przypadki, których nie wolno zlewać

M6-T101 pyta o czynności po zmianie konfiguracji oraz postępowanie po nieudanym uruchomieniu. Wymaga restartu, kontroli stanu, interpretacji active, przywrócenia zatwierdzonej kopii i zgłoszenia administratorowi. Przywrócenie kopii jest warunkiem krytycznym. To szersze pytanie niż historyczne „Co zrobić po zmianie konfiguracji DocAssist?”. Zmiana samej etykiety starego wyniku nie czyni go próbą T101.

M6-T106 pyta o TLS i narzuca similarity_threshold=1.0. Test zakłada, że żaden score z danego przebiegu nie osiąga 1,0. Po spełnieniu tej przesłanki cały kontekst zostaje odrzucony i oczekujesz insufficient_context z below_threshold. Nie oczekujesz generacji odpowiedzi RAG. Selektor narzędzia może wcześniej wykonać własne wywołanie modelu. Jeśli score osiągnie próg, oznacz niespełniony warunek testu, zamiast przypisywać systemowi niepowodzenie.

Pytanie bez odpowiedzi przy wyłączonym progu to inny test. System może pobrać tematycznie podobne fragmenty i dopiero w wygenerowanej treści poprawnie stwierdzić brak informacji. Techniczny status answered nie wyklucza takiej poprawnej odpowiedzi ograniczającej zakres.

Scenariusz wieloturowy

M6-S001 zaczyna nową sesję. Pierwsza tura pyta o zmianę konfiguracji, druga o „jej stan”, a trzecia o źródła odpowiedzi. Każda tura ma osobne oczekiwania i osobną recenzję. W drugiej turze prawidłowo rozwiązane pytanie samodzielne powinno prowadzić do nowego RAG. W trzeciej show_last_sources korzysta z zapisanych źródeł ostatniego RAG bez ponownego wyszukiwania.

Podczas wykonania R4 historia zawiera rzeczywiste odpowiedzi aplikacji. Nie zastępuj błędnej odpowiedzi wzorcem, żeby dalsza tura wyglądała poprawnie. W R3 używasz jawnego retrieval_question ze scenariusza: izolujesz wyszukiwanie od błędu rozwiązywania odniesienia. Wyniki obu doświadczeń odpowiadają na różne pytania.

Ćwiczenie R2

Wymyśl parafrazę pytania o informacje wymagane w zgłoszeniu. Na podstawie DOC-REG zbuduj kontrakt: fakty, źródło, status, narzędzie i twierdzenie zabronione. Nadaj nowy identyfikator i wersję zestawu. Zapisz też, dlaczego nowe pytanie może wymagać trybu Ollama.

Sprawdź się: nie wpisujesz oczekiwanego fragmentu do testu braku danych tylko po to, aby obliczyć Hit@k. Potrafisz wskazać różnicę między pojedynczym przypadkiem a scenariuszem, zachowując osobne oczekiwania dla tur.

Lokalne chatboty, agenci i systemy RAG z własną bazą wiedzy · Moduł 6 · Wydanie 29.09.2026