130 lines
6.2 KiB
Markdown
130 lines
6.2 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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í.
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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](vystupny_kontrakt_overenie.json).
|