Älykkään dokumentaatiodatabasen rakentaminen tekoälyavustajalle

Kun syötät raakaa dokumentaatiota suoraan AI-agentille, se joutuu etsimään olennaista tietoa valtavasta määrästä epäolennaisia sivuja. Lakitekstit, muutosloki ja navigointisivut eivät auta agenttia oppimaan – ne vain hidastavat ja sekoittavat prosessia. NameOceanilla olemme kehittäneet käytännönläheisen tavan valmistella dokumentaatiota tekoälypohjaisiin kehitystyönkulkuihin.

Ongelma: Kaikki sivut eivät ole yhtä hyödyllisiä

Useimmissa dokumentaatiosivustoissa merkittävä osa sisällöstä on rakennettu ihmisten navigoitavaksi, ei tekoälyn oppimista varten. Indeksisivut, tietosuojakäytännöt ja API-viitelistat ovat tärkeitä ihmisille, mutta ne tuovat vain turhaa kohinaa vektoritietokantaan.

Kun kaiken syöttää suoraan tietokantaan ilman suodatusta, AI-agentti joutuu käsittelemään materiaalia, joka ei sisällä mitään uutta tietoa. Tuloksena on hitaampia hakuja, turhan suuria upotuksia ja vastauksia, jotka viittaavat vääriin sivuihin.

Kaksivaiheinen luokittelutapa

Tehokkain ratkaisu yhdistää sääntöpohjaisen suodatuksen ja valikoivan LLM-luokittelun. Ajattele tätä dokumentaation lajitteluna.

Ensimmäinen vaihe: Nopea suodatus

Aloita URL-osoitteiden ja sisällön rakenteen perusteella. Voit tunnistaa heti hyödyttömät sivut:

• Lakisisältö: tunnista URL-kuviot kuten /legal/, /privacy, /terms
• Navigointisivut: alle 200 sanaa sisältävät sivut, joissa on enimmäkseen linkkejä
• Muutoslokit: usein noudattavat ennakoitavia URL-malleja
• Viitesivut: tunnistettavissa rakenteen perusteella

Tämä vaihe toimii paikallisesti, on ilmainen ja hoitaa tyypillisesti 40–60 % sivuista.

Toinen vaihe: LLM-luokittelu

Jäljelle jääville sivuille lähetetään kevyt paketti paikalliselle kielimallille. Pakettiin kuuluvat URL, otsikko, ensimmäiset 200 sanaa sisällöstä sekä otsikkohierarkia.

Luokittelu perustuu Diátaxis-malliin, joka erottaa sisällön tyypit:

• Conceptual: taustatietoa ja selityksiä
• Tutorial: ohjatut harjoitukset
• How-to: tehtäväkohtaiset ohjeet
• Examples: koodiesimerkit
• Structural: navigointi-, viite- ja lakisisältö

LLM käsittelee vain ne sivut, joita säännöt eivät pystyneet luokittelemaan.

Sisällön upottaminen tehokkaasti

Kun turha sisältö on poistettu, upotukset toimivat huomattavasti paremmin. Dokumentaatiosivut ovat kuitenkin usein liian pitkiä. Ratkaisu on jakaa sisältö otsikoiden kohdalta ja laskea upotusten keskiarvo. Näin säilytetään rakenteellinen konteksti.

Paikallinen sentence transformer -malli riittää tähän työhön. Se on nopea, ilmainen ja toimii teknisessä dokumentaatiossa riittävän hyvin.

Hybriditietokannan rakentaminen

Todellinen hyöty syntyy, kun yhdistetään kaksi erilaista yhteyttä:

Selkeät linkit: dokumentaation kirjoittajien lisäämät hyperlinkit. Nämä ovat luotettavia ja heijastavat sivuston todellista rakennetta.

Semanttiset yhteydet: upotusten samankaltaisuuteen perustuvat linkit. Jos kahden sivun kosinin samankaltaisuus ylittää 0,75, ne ovat käsitteellisesti yhteydessä, vaikka linkkiä ei olisikaan.

Nämä yhteydet tallennetaan suunnattuna graafina. Semanttiset linkit painotetaan samankaltaisuuspisteillä, kun taas hyperlinkit ovat painottomia. Jokaisella sivulla pidetään enintään 20 naapuria, jotta graafi ei kasva liian raskaaksi. Navigointi-, laki- ja viitesivut jätetään semanttisesta graafista kokonaan pois.

Valmis tietokanta: SQLite

Kaikki tallennetaan yhteen kannettavaan SQLite-tietokantaan:

• puhdistettu markdown-sisältö
• sivujen luokitukset
• upotukset vektoreina tai sarjoitettuina
• graafin yhteydet painoineen
• URL:t ja metatiedot

Tämä mahdollistaa:

• Siirrettävyyden: tietokantaa voi käyttää missä tahansa, myös offline
• Kyselymahdollisuuden: agentit voivat kirjoittaa SQL-komentoja
• Suodatuksen: "näytä vain tutorial- ja how-to-sivut autentikaatiosta"
• Navigoinnin: agentti voi liikkua graafissa semanttisten yhteyksien kautta

Työnkulku käytännössä

Prosessi etenee seuraavasti:

1. Hae dokumentaatiosivusto (käsittele uudelleenohjaukset, noudata robots.txt-tiedostoa)
2. Puhdista HTML markdown-muotoon
3. Luokittele sivut ensin säännöillä, sitten LLM:llä epäselvissä tapauksissa
4. Upota sisällöt paikallisella mallilla, jakamalla pitkät sivut otsikoiden kohdalta
5. Rakenna graafi selkeistä linkeistä ja semanttisista yhteyksistä
6. Tallenna kaikki SQLite-tietokantaan

Tämän jälkeen AI-agentilla on kuratoitu, rakenteellinen ja helposti kysyttävä tietopohja raakadumpin sijaan.

Miksi tämä on tärkeää kehittäjille

Olitpa rakentamassa sisäistä koodiavustajaa, integroimassa tekoälyä IDE:hen tai kehittämässä tiimin tietojärjestelmää, dokumentaation laatu vaikuttaa suoraan lopputulokseen. Hyvin rakennettu tietokanta vapauttaa agentin keskittymään olennaiseen sisällön sijaan, nopeuttaa hakuja ja parantaa vastausten laatua. Samalla säilytät täyden hallinnan tietoihisi ilman ulkopuolisia riippuvuuksia tai tietosuojariskejä.