Budowa asystenta dokumentów

Lokalne chatboty, agenci i systemy RAG z własną bazą wiedzy

Orientacyjny czas: 20 min · Tryb pracy: najpierw własna próba, potem przykład

Przejrzyj scenariusze.json przed uruchomieniem. Oczekiwane statusy opisują kontrakt przykładu. W szczególności scenariusz TLS oczekuje zakończonego RAG, a zasadność odmowy jest oceniana ręcznie. Jeśli włączysz próg odrzucania kontekstu, świadomie zaktualizuj plan testu i zachowaj poprzednią wersję.

Plik: ewaluacja.py. Poniżej znajduje się kompletna wersja do porównania po własnej próbie.

"""Scenariusze przebiegu; ocena treści pozostaje jawnie do uzupełnienia."""
import argparse
import json
import re
from lokalny import ROOT
from indeks import load_index
from narzedzia import katalog_dokumentow
from pamiec import nowy_stan
from asystent import krok
from konsola import nowy_zapis, zapisz


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--wybor", choices=("reguly", "model"), default="reguly")
    args = parser.parse_args()
    scenarios = json.loads((ROOT / "scenariusze.json").read_text(encoding="utf-8"))
    records, index = load_index()
    catalog = katalog_dokumentow(records)
    folder = nowy_zapis("ewaluacja", args.wybor)
    zapisz(folder / "scenariusze.json", scenarios)
    rows = []
    for scenario in scenarios:
        if not re.fullmatch(r"[A-Z0-9_-]+", scenario["id"]):
            raise ValueError("Niedozwolony identyfikator scenariusza.")
        state = nowy_stan()
        for number, expected in enumerate(scenario["turns"], 1):
            result = krok(expected["question"], state, records, index, catalog, args.wybor)
            actual_tool = result["tool"].get("name") if result["tool"].get("executed") else None
            checks = {"status": result["status"] == expected["status"], "tool": actual_tool == expected["tool"]}
            if "origin_turn" in expected:
                checks["origin_turn"] = (result["source_origin"] or {}).get("turn_id") == expected["origin_turn"]
            row = {"scenario": scenario["id"], "turn": number, "checks": checks,
                "technical_pass": all(checks.values()), "result_id": result["result_id"],
                "manual": {"answer_supported": None, "complete": None, "citations_correct": None,
                           "refusal_appropriate": None, "notes": "Do oceny przez uczestnika; null nie oznacza zaliczenia."}}
            rows.append(row)
            zapisz(folder / f"{scenario['id']}_{number:02d}.json", {"expected": expected, "assessment": row, "result": result})
            print(scenario["id"], number, result["status"], actual_tool, "OK" if row["technical_pass"] else "SPRAWDŹ", flush=True)
    zapisz(folder / "podsumowanie.json", {"technical_pass": sum(r["technical_pass"] for r in rows),
        "turns": len(rows), "manual_assessment_complete": False, "rows": rows})
    print("Wyniki:", folder)


if __name__ == "__main__":
    main()

Scenariusze do uruchomienia

Plik: scenariusze.json. Poniżej znajduje się kompletna wersja do porównania po własnej próbie.

[
  {"id":"S01","cel":"Pytanie, dopowiedzenie i źródła tej samej odpowiedzi","turns":[
    {"question":"Jak sprawdzić stan usługi docassist-api?","status":"answered","tool":"answer_from_documents"},
    {"question":"A jeśli po tej zmianie pojawia się failed?","status":"answered","tool":"answer_from_documents"},
    {"question":"Pokaż źródła","status":"answered","tool":"show_last_sources","origin_turn":2}]},
  {"id":"S02","cel":"Źródła przed pytaniem do dokumentów","turns":[
    {"question":"Pokaż źródła","status":"clarification_needed","tool":null}]},
  {"id":"S03","cel":"Jawne ID dokumentu","turns":[
    {"question":"Pokaż metadane DOC-INSTR","status":"answered","tool":"get_document_metadata"}]},
  {"id":"S04","cel":"Brak ID","turns":[
    {"question":"Pokaż metadane dokumentu","status":"clarification_needed","tool":null}]},
  {"id":"S05","cel":"Nieznany dokument","turns":[
    {"question":"Pokaż metadane DOC-999","status":"rejected","tool":null}]},
  {"id":"S06","cel":"Operacja poza zakresem","turns":[
    {"question":"Zrestartuj usługę docassist-api","status":"rejected","tool":null}]},
  {"id":"S07","cel":"Niejasne odwołanie bez historii","turns":[
    {"question":"Jak sprawdzić jej stan?","status":"clarification_needed","tool":null}]},
  {"id":"S08","cel":"Metadane nie zastępują ostatnich źródeł RAG","turns":[
    {"question":"Jak sprawdzić stan usługi docassist-api?","status":"answered","tool":"answer_from_documents"},
    {"question":"Pokaż metadane DOC-INSTR","status":"answered","tool":"get_document_metadata"},
    {"question":"Pokaż źródła","status":"answered","tool":"show_last_sources","origin_turn":1}]},
  {"id":"S09","cel":"Brak informacji o TLS — ręczna ocena odmowy","turns":[
    {"question":"Jak skonfigurować certyfikat TLS dla docassist-api?","status":"answered","tool":"answer_from_documents"}]},
  {"id":"S10","cel":"Zmiana tematu i niejednoznaczność","turns":[
    {"question":"Jak sprawdzić stan usługi docassist-api?","status":"answered","tool":"answer_from_documents"},
    {"question":"Gdzie znajduje się baza danych?","status":"answered","tool":"answer_from_documents"},
    {"question":"Jak sprawdzić jej stan?","status":"clarification_needed","tool":null}]},
  {"id":"S11","cel":"Puste wejście","turns":[
    {"question":"  ","status":"rejected","tool":null}]},
  {"id":"S12","cel":"Dwa dokumenty naraz","turns":[
    {"question":"Pokaż metadane DOC-INSTR i DOC-HELP","status":"clarification_needed","tool":null}]}
]

Jeśli liczysz odsetki, podawaj mianownik. Dla zgodności przebiegu użyj wszystkich 18 tur kontraktowych; dla jakości odpowiedzi użyj tylko tur merytorycznych. Błędy i brak wyniku raportuj osobno, a nie usuwaj ich bez komentarza ze zbioru. Ten zestaw służy nauce i poprawianiu projektu; po dostrojeniu dodaj oddzielny zbiór nowych pytań, aby ocenić uogólnianie.

Raport uczestnika
Tryb i katalog wyników:
Modele / wersja danych / konfiguracja:
Poprawne przebiegi: __ / __ tur
Ocenione odpowiedzi merytoryczne: __ / __
Przykład dobrego uzasadnienia źródłem:
Przykład błędu i warstwa, w której powstał:
Jedna proponowana poprawka:
Wynik po zmianie na tym samym zbiorze:

Materiał uzupełniający do modułów 1–6 · wersja 1.0 · 30.09.2026