Okos dokumentációs adatbázisok építése AI-alapú fejlesztői segédeknek

Ha nyers dokumentációt adsz át egy AI-ügynöknek, azzal tűt keresel a szénakazalban. Minden jogi oldal, changelog és navigációs lap csak zajt kelt, és elnyomja a lényeget. A NameOcean-nál sokat foglalkoztunk azzal, hogyan készítsük elő a dokumentációt az AI-alapú fejlesztéshez, ezért most egy konkrét módszert mutatunk be.

A probléma: nem minden oldal egyforma

Sok fejlesztőt meglep, de a technikai dokumentáció jelentős része pusztán strukturális vagy jogi okokból létezik. Az indexoldalak, adatvédelmi szabályzatok, changelogok és API-listák ugyan megkönnyítik az emberek számára a navigálást, de az AI számára haszontalanok.

Ha szűretlenül töltöd fel a teljes oldalt egy vektoradatbázisba, az AI kénytelen átrágni magát olyan tartalmakon, amelyek semmit sem tanítanak neki. Ez lassabb lekérdezéseket, feleslegesen nagy embeddingeket és pontatlan válaszokat eredményez.

Kétlépcsős osztályozási stratégia

A leghatékonyabb megoldás a szabályalapú szűrés és a szelektív LLM-osztályozás kombinációja. Ez tulajdonképpen egyfajta triage-rendszer a dokumentációdhoz.

Első kör: gyors szűrés

Kezdd URL-minták és egyszerű tartalmi jellemzők alapján. Így azonnal kiszűrheted a legegyszerűbb eseteket:

• Jogi oldalak: keresd a /legal/, /privacy, /terms mintákat
• Navigációs központok: 200 szónál rövidebb oldalak, amelyek főleg linkeket tartalmaznak
• Changelogok: gyakran kiszámítható URL-szerkezettel rendelkeznek
• Referenciaoldalak: néha már a szerkezetük alapján felismerhetők

Ez a lépés helyben fut, ingyenes, és a dokumentáció 40–60 százalékát kezeli.

Második kör: LLM-osztályozás

A maradék oldalakhoz küldj egy könnyű csomagot egy helyi LLM-nek. Tartalmazza az URL-t, a címet, az első 200 szót és a címsor-hierarchiát. Kérd meg, hogy a Diátaxis rendszer alapján sorolja be az oldalt:

• Conceptual – magyarázatok, háttér-információk
• Tutorial – lépésről lépésre történő tanulás
• How-to – konkrét feladatot megoldó útmutatók
• Examples – kódrészletek, bemutatók
• Structural – navigációs, jogi és referenciaoldalak

Az LLM csak azokat az oldalakat látja, amelyeket a szabályok nem tudtak eldönteni.

Okos embedding

A zaj kiszűrése után az embeddingek sokkal hatékonyabbá válnak. A gond csak az, hogy sok dokumentációs oldal meghaladja a token-limiteket.

Ne csonkítsd az oldalt – inkább bontsd címsorok mentén, és átlagold ki az így kapott embeddingeket. Így megmarad a szemantikai szerkezet: a címsorok, kódrészletek és listák megőrzik a kontextust.

Hosszabb oldalaknál a markdown természetes töréspontokat biztosít. Használj helyi sentence-transformer modellt – így elkerülöd az API-költségeket és a késleltetést, miközben a technikai dokumentációkhoz ezek a modellek teljesen megfelelőek.

Hibrid tudásgráf építése

A valódi erő akkor jelenik meg, amikor kétféle kapcsolatot kombinálsz:

• Explicit linkek – a dokumentációban már meglévő hiperhivatkozások. Ezek nagy megbízhatóságú kapcsolatok.
• Szemantikai élek – embedding-hasonlóság alapján felfedezett kapcsolatok. Ha két oldal koszinusz-hasonlósága meghaladja a 0,75-ös küszöböt, akkor tartalmilag kapcsolódnak, még ha nincs is közöttük közvetlen link.

Tárold ezeket irányított élekként a gráfban. A szemantikai éleket súlyozd a hasonlósági értékkel, a link-éleket pedig hagyományos módon.

Fontos optimalizálás: korlátozd az oldalankénti szomszédok számát (20 jó kiindulópont), és zárd ki a navigációs, jogi és referenciaoldalakat a szemantikai gráfépítésből.

A végeredmény: önálló SQLite-adatbázis

Minden egy hordozható SQLite-fájlban landol:

• a megtisztított markdown-tartalom
• az oldal-osztályozások
• az embeddingek
• a gráf-élek súlyokkal együtt
• az URL-ek és metaadatok

Ez azért erős, mert:

• bárhová vihető és offline is használható
• SQL-lel lekérdezhető – az LLM-ek remekül bánnak vele
• szűrhető: „csak a tutorial és how-to oldalak az autentikációról”
• navigálható: az ügynök követheti a gráfot egyik releváns oldalról a másikra

Gyakorlati folyamat

A teljes pipeline így néz ki:

1. Crawl – dokumentációs oldal bejárása (redirectek, robots.txt, JavaScript-tartalom kezelése)
2. Tisztítás – HTML-ből olvasható markdown előállítása
3. Osztályozás – szabályok, majd LLM a bizonytalan esetekre
4. Embedding – helyi modellel, hosszú oldalaknál címsorok mentén történő bontással
5. Gráf építése – explicit linkek és szemantikai élek
6. Tárolás – minden SQLite-ban

Ezután az AI-ügynök már nem nyers HTML-kupaccal dolgozik, hanem egy gondosan összeállított, strukturált és lekérdezhető tudásbázissal.

Miért számít ez a fejlesztőknek

Legyen szó belső kódségédről, IDE-be integrált AI-ról vagy céges tudás-visszakereső rendszerről, a dokumentáció minősége megsokszorozza az eredményt. Ha okosan strukturálod a tartalmat, az AI nem a zajjal foglalkozik, hanem a lényeggel. Gyorsabbak lesznek a lekérdezések, relevánsabbak a válaszok, és teljes kontrollod marad a tudásbázis felett – nincs vendor-függőség, API-költség vagy adatvédelmi kockázat.