Jak připravit dokumentaci pro AI asistenta, aby z ní měl opravdu užitek

Když naházíte do AI agenta celý web s dokumentací najednou, často mu spíš přiděláte zmatek než pomůžete. Spousta stránek tam totiž není proto, aby něco vysvětlovaly, ale jen proto, aby web držel pohromadě. A přesně tyhle stránky AI zbytečně rozptylují.

Problém: ne všechny stránky jsou stejně užitečné

Na většině technických webů narazíte na stránky, které slouží hlavně k navigaci nebo plnění právních povinností. Indexy, odkazy na další sekce, podmínky používání nebo seznamy API – to všechno je pro člověka užitečné, ale pro AI agenta představuje spíš šum.

Když takovou dokumentaci vložíte do vektorové databáze bez filtru, AI pak hledá relevantní informace uprostřed spousty zbytečného obsahu. Výsledkem jsou pomalejší dotazy a méně přesné odpovědi.

Dvousměrný přístup k třídění obsahu

Nejlepší výsledky přináší kombinace jednoduchých pravidel a selektivního použití lokálního LLM modelu.

První kolo: rychlé filtrování

Začněte jednoduchými pravidly na základě URL a struktury stránky. Tímto způsobem snadno odhalíte:

• Právní stránky podle typických cest jako /legal/, /privacy nebo /terms
• Navigační stránky s málo textem a převahou odkazů
• Changelogy, které často mají předvídatelnou strukturu URL
• Referenční stránky, které poznáte podle specifického uspořádání

Tento krok probíhá lokálně, nic nestojí a zpracuje zhruba polovinu obsahu.

Druhé kolo: klasifikace pomocí LLM

Na zbývající stránky pošlete jen základní informace – URL, titulek, prvních 200 slov a seznam nadpisů. Model pak stránky roztřídí podle systému Diátaxis na konceptuální vysvětlení, tutoriály, návody, příklady a strukturální obsah.

Díky tomu LLM pracuje jen s tím, co pravidla nezachytila.

Vkládání obsahu do databáze

Po odfiltrování zbytečného obsahu se vyplatí věnovat pozornost tomu, jak stránky rozdělit před vytvořením embeddings. Dlouhé stránky je lepší rozdělit podle nadpisů a následně průměrovat výsledné vektory. Zachováte tak logickou strukturu dokumentace.

Pro tento účel stačí lokální sentence transformer model – je rychlý, nic nestojí a na technickou dokumentaci plně dostačuje.

Hybridní znalostní graf

Skutečnou přidanou hodnotu přináší propojení dvou typů vazeb mezi stránkami.

První typ tvoří explicitní odkazy, které autoři dokumentace sami vytvořili. Druhý typ představují sémantické vazby – stránky, které jsou si podobné podle cosine similarity. Tyto vazby se ukládají jako hrany v grafu s váhou odpovídající míře podobnosti.

Důležité je omezit počet sousedů na stránku (kolem 20) a vyřadit navigační a právní stránky z tohoto procesu.

Výsledek: přenosná SQLite databáze

Celý systém nakonec skončí v jediné SQLite databázi obsahující vyčištěný obsah, klasifikace stránek, embeddings, grafové vazby i metadata. Tato databáze je přenosná, dá se dotazovat pomocí SQL a AI agenti v ní mohou efektivně vyhledávat.

Praktický postup

Celý proces zahrnuje procházení webu, převod HTML na markdown, klasifikaci stránek, vytváření embeddings a stavbu znalostního grafu. Výsledkem je databáze, kterou můžete používat offline bez závislosti na externích službách.

Proč se to vyplatí

Kvalitně připravená dokumentace výrazně zlepšuje výkon AI asistentů při programování. AI se soustředí na relevantní obsah místo toho, aby se probírala šumem. Zároveň si zachováváte plnou kontrolu nad svými daty.