Spoločný výstupný kontrakt RAG a GraphRAG

Kontrakt v1 zjednocuje polia pre hlavného agenta a budúce OpenWebUI nástroje. Vyhľadávanie naďalej vracia svoje pôvodné dáta. Klasický RAG zachováva context, instructions, answer_format a rozšírené zdroje; GraphRAG zachováva facts, paths, documents, aggregation a rozpoznané entity. Historické evaluačné súbory ani zmrazené manifesty sa neprepisujú.

Spoločné polia

Pole	Význam
`status`	`ok`, `no_answer`, `ambiguous` alebo `error`
`reason`	Stabilný strojový dôvod; pri úspechu `null`
`sources`	Zoznam zdrojov s `source_id`, `document_path`, `source_url`, `title`
`index_version`	Spoločná generácia indexov vrátane Git revízie; `null`, ak nie je známa
`complete`	`true`: úplné vyhľadanie v rozsahu nástroja; `false`: neúplné; `null`: úplnosť nemožno zaručiť
`truncated`	Nástroj preukázateľne narazil na limit výberu alebo výstupu
`truncation_reasons`	Konkrétne limity; prázdne pole, ak žiadny nebol zistený

source_id má tvar S1, S2, … v rámci jednej odpovede. URL a názov môžu byť null, ak ich zdroj neposkytuje; nesmú sa domýšľať. RAG si v každom zdroji ponecháva aj text, sekcie a retrieval metadáta. GraphRAG pridáva sources popri pôvodnom documents, takže existujúci evaluator môže ďalej používať pôvodné polia. Zdrojový dokument je identifikovaný cestou.

ok znamená úspešné získanie dôkazov alebo výsledku agregácie. Neznamená, že LLM už odpovedal ani že vie zo zdrojov zodpovedať každú časť otázky. Nulová, korektne vykonaná agregácia môže mať status=ok, count=0 a žiadne zdroje. no_answer označuje nenájdenie požadovaných faktov alebo entity; ambiguous označuje nejednoznačné rozpoznanie; error zlyhanie nástroja.

Význam úplnosti

Úplnosť nevyjadruje percento presnosti ani pravdivosť odpovede.

RAG je radený výber kandidátov. Ak sa preukáže orezanie, uvádza complete=false; inak null, pretože nemôže zaručiť vyčerpávajúci zoznam všetkých významovo relevantných informácií. Hlási candidate_limit, per_document_limit a result_limit. Dodatočný kandidát slúži na detekciu orezania a nezaraďuje sa do pôvodného radeného výberu. Rozšírenia kontextu ďalej používajú svoje existujúce limity; truncated=false preto nie je zárukou úplnosti kontextu ani pokrytia celej wiki.

GraphRAG vyjadruje úplnosť v rámci podporovaných štruktúrovaných dotazov a nakonfigurovaných grafových prechodov. Hlási entity_limit, evidence_limit, fact_limit a path_limit. Pri prechádzaní grafu overí aj jeden výsledok nad limitom, aby rozpoznal orezanie už na úrovni Cypher. complete=true neznamená neobmedzený prechod celým grafom: všeobecné prechody naďalej používajú pôvodnú povolenú dĺžku ciest. Pri nejednoznačnosti alebo chybe je complete=false, aj keď truncated=false.

aggregation.complete ostáva osobitným príznakom úplnosti výpočtu. Príklad: presne napočítané 2 osoby, ale limit=1 pre zobrazené dôkazy:

{
  "status": "ok",
  "reason": null,
  "aggregation": {"count": 2, "complete": true},
  "complete": false,
  "truncated": true,
  "truncation_reasons": ["fact_limit", "path_limit"]
}

Príklad je skrátený. Agent môže uviesť presný počet podľa agregácie, ale nesmie tvrdiť, že zobrazený výpis obsahuje všetky dôkazy.

Nenájdenie a chyby

Nenájdenie používa napríklad no_matching_sources, no_matching_facts, unknown_person, unknown_keyword alebo unknown_title. Nejednoznačnosť používa napríklad ambiguous_person. Zostávajú zachované aj podrobnejšie grafové reasons a dôkazy zamietnutých kandidátov.

API /rag a /search vracia pri chybách rovnakú obálku; pôvodné HTTP kódy a detail zostávajú zachované. Dôvody zahŕňajú invalid_query (400), unauthorized (401), invalid_request (422), retrieval_unavailable (503) a internal_error (500). Validačné chyby nevracajú hodnoty zaslaných polí.

{
  "status": "error",
  "reason": "retrieval_unavailable",
  "sources": [],
  "index_version": null,
  "complete": false,
  "truncated": false,
  "truncation_reasons": [],
  "detail": "Vyhľadávací index alebo embeddingový model momentálne nie je dostupný."
}

Po chybe sa neuvádza verzia dát, ktorú nástroj úspešne neprečítal. Chybová obálka neobsahuje text interných výnimiek, heslá ani interné cesty.

Python knižničné funkcie naďalej vyhadzujú výnimky, aby existujúci kód mohol riešiť chyby pomocou try/except. Transportné rozhrania ich prevádzajú na obálku cez spoločné error_result(): HTTP API, grafový CLI a RAG CLI v režime --json. Chybový CLI skončí návratovým kódom 1. Pre budúci MCP/HTTP adaptér grafu sa použije ten istý prevod; nový grafový HTTP endpoint tento krok nepridáva.

Použitie

python -m tools.rag.search_db 'strojový preklad' --json --limit 5
python -m tools.graphrag.graph_search 'Aký názov práce má Ján Holp?' --limit 5

Spoločné Pydantic modely aj tvorba obálky sú v tools/retrieval_contract.py. OpenAPI pre /rag používa spoločné polia aj model chybovej odpovede.

Overenie 25. 10. 2026

Kompletná sada projektu: 506 úspešných testov, 4 preskočené. Nové testy overujú spoločné polia, zachovanie rozšírených zdrojov RAG, detekciu limitov, nejednoznačnosť, nenájdenie a chyby vrátane neplatného výstupu backendu. Grafové testy používajú skutočný Neo4j v izolovanej transakcii s rollbackom.

Na nasadenom API sa overili /rag, /search, chyby autentifikácie a validácie aj OpenAPI schéma. Skutočný GraphRAG napočítal 15 osôb s prácou v roku 2024; počet bol rovnaký pri limite 1 a 100. Pri limite 1 správne označil dôkazy za orezané, pričom samotný počet zostal úplný. Overilo sa tiež nenájdenie neexistujúcej osoby a JSON chybové výstupy oboch CLI s návratovým kódom 1.

Nasadenie nevyžadovalo reindexáciu: verzia dát zostala nezmenená. Toto overenie kontraktu nepredstavuje nové meranie presnosti LLM odpovedí. Strojový záznam je v vystupny_kontrakt_overenie.json.

6.2 KiB Raw Blame History