Jak przygotować dokumentację, żeby AI naprawdę z niej korzystało

Większość osób wrzuca dokumentację do bazy wektorowej i liczy, że AI samo sobie poradzi. Problem w tym, że duża część stron w dokumentacji technicznej to po prostu szum. Indeksy, polityki prywatności, changelogi czy listy endpointów – one są potrzebne ludziom, ale dla modelu to tylko dodatkowe tokeny bez wartości.

Nie wszystkie strony są sobie równe

Wystarczy przejrzeć dowolną dokumentację, żeby zauważyć schemat. Są strony, które uczą, i są strony, które tylko łączą lub informują. Gdy wrzucisz wszystko razem, model traci kontekst i zaczyna odpowiadać na podstawie przypadkowych fragmentów.

Efekt? Wolniejsze zapytania i odpowiedzi, które odwołują się do niewłaściwych sekcji.

Dwuetapowe filtrowanie

Zamiast klasyfikować wszystko od razu, warto podzielić proces na dwie fazy.

Najpierw proste reguły. Wystarczą wzorce w URL-ach i podstawowa analiza długości tekstu. Strony z /legal/, /privacy czy /terms można odrzucić od razu. Podobnie jak krótkie strony, które składają się głównie z linków.

Taki filtr działa lokalnie i usuwa zazwyczaj 40–60% zbędnych stron.

Pozostałe przypadki warto przekazać do lekkiego modelu LLM. Wystarczy URL, tytuł, pierwsze 200 słów i struktura nagłówków. Model klasyfikuje stronę według schematu Diátaxis – czy to materiał koncepcyjny, tutorial, how-to, przykład czy strona strukturalna.

Dzięki temu LLM pracuje tylko tam, gdzie reguły nie dały rady.

Osadzanie treści z głową

Po odfiltrowaniu stron przychodzi czas na embeddingi. Tu pojawia się kolejny problem – wiele stron przekracza limity tokenów.

Zamiast obcinać tekst, warto dzielić go po nagłówkach i uśredniać wyniki. Zachowujemy wtedy strukturę dokumentu i nie tracimy kontekstu. Do tego zadania świetnie sprawdzają się lokalne modele typu sentence-transformers – są szybkie i nie generują kosztów.

Graf wiedzy zamiast płaskiej bazy

Sama baza embeddingów to za mało. Warto dodać relacje między stronami.

Pierwszy typ to linki jawne – te, które autorzy dokumentacji dodali celowo. Drugi typ to powiązania semantyczne, wykrywane przez podobieństwo wektorów. Jeśli dwie strony mają podobieństwo cosinusowe powyżej 0,75, można uznać je za powiązane.

Ważne, żeby ograniczyć liczbę sąsiadów na stronę – 20 to rozsądny limit. Dzięki temu graf nie zamienia się w sieć pełną szumu.

SQLite jako finalny format

Całość trafia do jednej bazy SQLite. Znajdują się tam:

• wyczyszczona treść w markdownie
• klasyfikacje stron
• embeddingi
• krawędzie grafu z wagami
• metadane i URL-e

Taka baza jest przenośna, działa offline i pozwala agentowi AI pisać zapytania SQL bezpośrednio. Można też filtrować wyniki – na przykład pokazać tylko tutoriale i how-to dotyczące autoryzacji.

Cały proces w skrócie

1. Pobranie dokumentacji (z respektowaniem robots.txt)
2. Konwersja HTML do markdownu
3. Filtrowanie regułowe + klasyfikacja LLM
4. Osadzanie z podziałem po nagłówkach
5. Budowa grafu wiedzy
6. Zapis do SQLite

Efekt? Agent AI dostaje uporządkowaną wiedzę zamiast sterty przypadkowych stron.