Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Interný AI asistent mal pomáhať supportu pri riešení problémov s objednávkami. Do znalostnej bázy sme preto pridali dokument, ktorý opisoval celý proces platby:
- vytvorenie objednávky,
- výber spôsobu platby,
- komunikáciu s platobnou bránou,
- zmeny stavov objednávky,
- opakovanie neúspešnej platby,
- zákaznícke výnimky,
- diagnostiku chýb.
Dokument bol aktuálny a obsahoval všetky potrebné informácie. Napriek tomu AI odpovedala nesprávne.
Pracovník supportu sa opýtal:
„Čo sa má stať s objednávkou po neúspešnej platbe kartou?“
AI odpovedala:
„Objednávka sa po neúspešnej platbe zruší.“
V dokumentácii však bolo uvedené, že objednávka má prejsť do stavu Čaká na platbu a používateľ môže platbu zopakovať. Automatické zrušenie sa týkalo iba objednávok, pri ktorých nebola platba dokončená do 24 hodín.
Keď sme skontrolovali zdrojový dokument, obe pravidlá v ňom boli zapísané správne.
Problém vznikol až pri jeho spracovaní pre znalostnú bázu. Dlhý dokument bol automaticky rozdelený na rovnako veľké textové bloky. Jeden blok končil vetou:
„Ak platobná brána vráti neúspešný výsledok, systém objednávku neuzavrie.“
Nasledujúci blok začínal:
„Objednávka prejde do stavu Čaká na platbu a používateľ môže platbu zopakovať najviac trikrát.“
Podmienka a jej výsledok sa ocitli v dvoch samostatných blokoch. Do odpovede sa dostal iba prvý z nich spolu s inou časťou dokumentu, ktorá opisovala automatické zrušenie objednávky po 24 hodinách.
Dokumentácia bola správna. Jej technické rozdelenie však zničilo vzťah medzi podmienkou, výsledkom a časovou výnimkou.
Čo sa tu vlastne pokazilo (analýza systému)
Pri príprave dokumentácie pre RAG systém sa dlhšie dokumenty zvyčajne rozdeľujú na menšie časti. Tieto časti sa často označujú ako chunky alebo obsahové bloky.
AI pri odpovedi spravidla nedostane celý dokument. Vyhľadávacia časť systému nájde niekoľko blokov, ktoré považuje za najbližšie otázke používateľa, a tie poskytne AI ako podklad na odpoveď.
Samotné rozdelenie dokumentu teda nie je problém. Problémom je rozdelenie podľa technickej dĺžky bez ohľadu na význam.
Ak systém vytvorí nový blok po určitom počte znakov, slov alebo tokenov, hranica môže vzniknúť uprostred:
- podmienky a jej výsledku,
- kroku a očakávaného správania,
- všeobecného pravidla a zákazníckej výnimky,
- chybového kódu a jeho vysvetlenia,
- tabuľky a poznámky, ktorá určuje jej platnosť,
- nadpisu a obsahu, ktorý pod neho patrí,
- rozhodovacieho postupu,
- upozornenia a činnosti, ktorej sa týka.
Každý vytvorený blok môže byť jazykovo zrozumiteľný. Nemusí však byť významovo úplný.
V našom prípade boli v dokumente tri odlišné pravidlá:
- Po neúspešnej platbe objednávka prejde do stavu Čaká na platbu.
- Používateľ môže platbu zopakovať najviac trikrát.
- Ak platba nie je dokončená do 24 hodín, objednávka sa automaticky zruší.
Tieto pravidlá spolu tvoria jeden rozhodovací celok. Ak sa vyhľadajú oddelene, AI môže zameniť okamžitý výsledok neúspešnej platby za neskoršiu časovú podmienku.
Príčinou teda nebola iba nepresná odpoveď AI. Znalostná báza jej poskytla neúplnú kombináciu informácií.
Chunkovanie podľa významu znamená, že hranice blokov nevznikajú iba podľa ich veľkosti. Vznikajú predovšetkým podľa toho, ktoré informácie musia zostať spolu, aby sa dali správne pochopiť a použiť.
Veľkosť bloku je stále dôležitá. Príliš veľký blok môže obsahovať viac tém a zhoršiť presnosť vyhľadávania. Príliš malý blok zasa nemusí niesť dostatok kontextu. Samotný počet znakov však nedokáže určiť, kde sa končí jedna použiteľná informácia a začína ďalšia.
Skutočné náklady (čas, chaos, riziko)
Zlé chunkovanie sa ťažko odhaľuje, pretože pôvodný dokument môže byť správny a dobre napísaný.
Autor skontroluje dokumentáciu a nenájde chybu. Testerka porovná odpoveď AI so zdrojom a zistí, že požadovaná informácia v ňom existuje. Tím potom začne hľadať problém v modeli, prompte alebo spôsobe formulovania otázky.
V skutočnosti sa informácia stratila medzi zdrojovým dokumentom a odpoveďou.
Dôsledkom je ďalšia práca:
- testerka opakovane skúša rovnakú otázku s inými formuláciami,
- analytik kontroluje správnosť pôvodného pravidla,
- vývojár upravuje prompt, hoci problém vznikol pri delení dokumentu,
- support porovnáva odpoveď s viacerými zdrojmi,
- senior vysvetľuje súvislosť, ktorá bola v dokumentácii pôvodne zapísaná,
- tím prestáva dôverovať celej znalostnej báze.
Vzniká aj riziko nebezpečne neúplných odpovedí. AI môže nájsť správny krok, ale nenájde podmienku, za ktorej sa má vykonať. Môže nájsť všeobecné pravidlo, ale nie zákaznícku výnimku. Môže citovať aktuálny postup spolu s ukončením starej verzie procesu.
Takáto odpoveď nemusí pôsobiť očividne nesprávne. Často je plynulá, konkrétna a obsahuje text zo schváleného dokumentu. Chyba je vo vzťahoch medzi nájdenými časťami.
Pri supporte môže byť výsledkom nesprávna rada zákazníkovi. Pri administrátorskej dokumentácii môže človek použiť príkaz bez potrebných vstupných podmienok. Pri testovaní môže testerka vynechať dôležitú výnimku. Pri interných procesoch môže AI priradiť úlohu nesprávnej roli.
Zlá hranica jedného bloku sa tak môže zmeniť na chybný pracovný postup.
Minimálny model riešenia
Dokument netreba deliť po každom odseku ani ponechať celý v jednom veľkom bloku. Potrebujeme nájsť najmenšiu časť, ktorá má samostatný pracovný význam.
V prípade procesu platby môže jeden obsahový blok vyzerať takto:
Názov bloku
Neúspešná platba kartou a ďalší stav objednávky
Kontext
Platí pre objednávky vytvorené v mobilnej aplikácii od verzie 4.8. Ide o Core správanie systému.
Pravidlo
Ak platobná brána vráti neúspešný výsledok, objednávka prejde do stavu Čaká na platbu. Nezruší sa okamžite.
Nadväzujúce správanie
Používateľ môže platbu zopakovať najviac trikrát.
Časová podmienka
Ak platba nie je úspešne dokončená do 24 hodín, objednávka sa automaticky zruší.
Výnimka
Pri zákazníkovi ABC platí časový limit 48 hodín. Táto informácia je Custom a nesmie sa použiť ako všeobecné pravidlo.
Takýto blok je dostatočne krátky na presné vyhľadanie, ale zároveň obsahuje všetky informácie potrebné na vysvetlenie jedného rozhodovacieho bodu.
Pri určovaní hraníc blokov možno použiť tieto praktické pravidlá:
- Jeden blok má riešiť jednu otázku, úlohu, stav alebo rozhodnutie.
- Nadpis musí zostať spojený s obsahom, ktorý vysvetľuje.
- Podmienka musí zostať spolu s výsledkom.
- Krok musí zostať spolu s očakávaným výsledkom, ak bez neho nie je jednoznačný.
- Výnimka musí zostať pri pravidle, ktoré mení alebo obmedzuje.
- Upozornenie musí zostať pri činnosti, ktorej sa týka.
- Chybový kód musí zostať spolu s významom a odporúčaným riešením.
- Core a Custom pravidlo musia byť jasne označené, aj keď sa nachádzajú v rovnakom bloku.
- Dôležitý kontext z nadradeného nadpisu sa musí preniesť aj do samostatne uloženého bloku.
- Tabuľka sa nemá rozdeliť bez zachovania názvov stĺpcov a vysvetľujúcej poznámky.
Ak je významový celok príliš dlhý, možno ho rozdeliť na menšie bloky. Každý z nich však musí dostať potrebný kontext.
Namiesto blokov s názvami:
- Postup, časť 1
- Postup, časť 2
- Postup, časť 3
je použiteľnejšie vytvoriť bloky:
- Neúspešná platba a stav objednávky
- Opakovanie neúspešnej platby
- Automatické zrušenie nezaplatenej objednávky
- Custom časový limit zákazníka ABC
Medzi blokmi možno zachovať primerané prekrývanie textu. Prekrývanie však nie je náhradou za správne určenie významovej hranice. Ak iba mechanicky zopakujeme posledných niekoľko viet, nemusí sa preniesť práve podmienka alebo výnimka, ktorú ďalší blok potrebuje.
Pred zaradením dokumentu do znalostnej bázy možno použiť krátku kontrolu:
- Dá sa každý blok pochopiť bez prečítania predchádzajúceho bloku?
- Je z bloku jasné, pre ktorý modul, verziu a situáciu platí?
- Zostali podmienky, výsledky a výnimky spolu?
- Obsahuje blok iba jednu hlavnú tému?
- Nestratil sa pri rozdelení význam nadradeného nadpisu?
- Neoddelila sa poznámka od tabuľky alebo postupu?
- Je rozlíšené Core a Custom správanie?
- Dokáže človek z každého bloku určiť, čo má urobiť a kedy?
- Dokáže AI blok správne použiť bez domýšľania chýbajúcej súvislosti?
Ak blok potrebuje predchádzajúci odsek na to, aby dával správny význam, ešte nie je samostatne použiteľný.
Prepojenie na kvalitu a workflow
Chunkovanie nemá byť jednorazová technická operácia, ktorú tím vykoná po dokončení dokumentácie bez účasti jej autora.
Hranice významových celkov pozná najlepšie človek, ktorý rozumie procesu. Autor dokumentácie, analytik, testerka alebo vlastník funkcionality by preto mali určiť, ktoré informácie sa pri spracovaní nesmú oddeliť.
Technické rozdelenie potom môže byť automatizované, ale musí rešpektovať štruktúru dokumentu:
- hlavné a vnorené nadpisy,
- odseky,
- číslované postupy,
- rozhodovacie vetvy,
- tabuľky,
- upozornenia,
- príklady,
- výnimky,
- súvisiace pravidlá.
Dôležitá je aj následná kontrola. Nestačí overiť, že sa dokument úspešne načítal do znalostnej bázy. Treba otestovať, aké bloky systém vytvoril a ktoré z nich vyhľadá pri konkrétnej otázke.
Pre scenár s platbou by testovacie otázky mohli znieť:
- Čo sa stane bezprostredne po neúspešnej platbe kartou?
- Koľkokrát môže používateľ platbu zopakovať?
- Kedy sa nezaplatená objednávka automaticky zruší?
- Aký časový limit platí pre zákazníka ABC?
- Platí limit zákazníka ABC aj pre ostatných zákazníkov?
Kontrola nemá hodnotiť iba konečnú formuláciu odpovede. Mala by oddelene overiť:
- či systém našiel správny blok,
- či našiel aj súvisiacu podmienku alebo výnimku,
- či neprimiešal pravidlo z inej verzie alebo od iného zákazníka,
- či mala AI dostatok podkladov na jednoznačnú odpoveď,
- či odpoveď zodpovedá obsahu nájdených blokov.
Do Definition of Done pre zaradenie dokumentu do znalostnej bázy možno doplniť formuláciu:
„Dokument bol rozdelený podľa významových celkov. Podmienky, výsledky, výnimky a obmedzenia zostali v spoločnom alebo jednoznačne prepojenom kontexte. Vytvorené bloky boli skontrolované a vyhľadávanie bolo overené pomocou referenčných otázok pre všeobecné aj zákaznícke scenáre.“
Ak sa zmení systém alebo dokumentácia, nestačí aktualizovať pôvodný súbor. Treba znova vytvoriť obsahové bloky a zopakovať aspoň základné vyhľadávacie testy.
Inak môže znalostná báza naďalej používať staré rozdelenie, neplatné pravidlo alebo blok, v ktorom po úprave chýba potrebná súvislosť.
Krátke zhrnutie
Chunkovanie nie je iba technické rozdelenie dlhého dokumentu na menšie časti.
Použiteľný obsahový blok musí zachovať:
- jednu hlavnú tému alebo rozhodnutie,
- potrebný kontext,
- podmienku a jej výsledok,
- súvisiace výnimky a obmedzenia,
- význam nadradeného nadpisu,
- rozlíšenie Core a Custom,
- údaje potrebné na samostatné pochopenie informácie.
Príliš veľký blok môže zhoršiť presnosť vyhľadávania. Príliš malý blok môže stratiť význam. Správna veľkosť preto nevzniká iba počítaním znakov alebo tokenov.
Rozhodujúce je, či nájdená časť dokumentácie poskytne človeku aj AI úplný podklad na správne rozhodnutie.
Ak AI nájde správnu vetu, ale bez podmienky, výnimky alebo nadväzujúceho kroku, nenašla správnu odpoveď. Našla iba jej časť.