Smarte dokumentasjonsdatabaser for AI-assistenter

Når du mater rå dokumentasjon rett inn i en AI-agent, blir det fort som å lete etter en nål i en høystakk. Alt fra juridiske tekster til navigasjonssider og endringslogger skaper bare støy som drukner det som faktisk er nyttig. Hos NameOcean har vi jobbet med hvordan man best forbereder dokumentasjon til AI-drevne utviklingsflyter, og her er en praktisk tilnærming.

Ikke alle sider er like verdifulle

Mange utviklere overser en viktig detalj: en stor del av teknisk dokumentasjon finnes kun for struktur og compliance. Oversiktssider, personvernerklæringer, endringslogger og lister over API-referanser er nyttige for mennesker som klikker seg rundt, men de tilfører lite verdi når en AI skal lære fra innholdet.

Dytter du alt rett inn i en vektordatabase uten filtrering, må AI-en bruke tid på materiale som ikke lærer den noe. Resultatet blir tregere søk, unødvendig store embeddings og svar som peker til feil sider.

To-trinns klassifisering

Den mest effektive metoden kombinerer enkle regler med selektiv LLM-klassifisering. Tenk på det som en sortering av dokumentasjonen.

Første pass: Enkle filtre

Start med å se på URL-mønstre og grunnleggende struktur. Dette fanger opp det åpenbare:

• Juridiske sider: Søk etter /legal/, /privacy, /terms og lignende
• Navigasjonssider: Sider med under 200 ord som hovedsakelig inneholder lenker
• Endringslogger: Ofte følger de forutsigbare URL-mønstre
• Referansesider: Kan ofte identifiseres ut fra oppbygging alene

Dette kjøres lokalt, koster ingenting, og tar seg av 40–60 % av sidene.

Andre pass: LLM-klassifisering

For resten sender du et lett vektet utvalg til en lokal LLM. Du inkluderer URL, tittel, de første 200 ordene og overskriftshierarkiet. Be modellen klassifisere etter Diátaxis-rammeverket:

• Conceptual: Forklaringer og bakgrunn
• Tutorial: Veiledede gjennomganger
• How-to: Oppgaveorienterte guider
• Examples: Kodeeksempler
• Structural: Navigasjon, referanser og juridiske tekster

Smart embedding av innhold

Når støyen er filtrert bort, blir embedding av sider langt mer effektivt. Men mange dokumentasjonssider overskrider token-grenser.

I stedet for å kutte vilkårlig, deler du på overskrifter og tar gjennomsnittet av embeddingsene. Markdown-strukturen gir naturlige brytpunkter. Bruk en lokal sentence transformer-modell – det sparer både kostnader og latens, og for teknisk innhold holder kvaliteten seg god.

Hybrid kunnskapsgraf

Den virkelige styrken kommer når du kombinerer to typer relasjoner:

• Eksplisitte lenker: Hyperlenker som forfatterne selv har lagt inn. Disse er høykvalitetsforbindelser.
• Semantiske kanter: Relasjoner oppdaget via cosine similarity. Sider med score over 0.75 kobles selv om de ikke lenker til hverandre.

Begrens antall naboer per side til rundt 20, og utelat navigasjons-, juridiske- og referansesider fra den semantiske grafen.

Alt i én SQLite-database

Resultatet er en bærbar SQLite-database som inneholder:

• Renset markdown-innhold
• Sideklassifiseringer
• Embeddings
• Grafkanter med vekter
• URL-er og metadata

Databasen er enkel å flytte, kan spørres med SQL, lar deg filtrere på sidetyper og lar agenter navigere via grafen.

Praktisk pipeline

1. Crawl dokumentasjonssiden (håndter redirects og JavaScript)
2. Konverter HTML til ren markdown
3. Klassifiser med regler, deretter LLM for usikre tilfeller
4. Embed med lokal modell, delt på overskrifter
5. Bygg graf med både eksplisitte og semantiske koblinger
6. Lagre alt i SQLite

Nå har AI-agenten en strukturert og filtrert kunnskapsbase i stedet for en rå haug med HTML.

Hvorfor dette lønner seg

Enten du bygger en intern kodeassistent, integrerer AI i IDE-en eller lager et kunnskapssystem for teamet ditt, blir dokumentasjonskvalitet en kraftmultiplikator. Med god struktur bruker AI-en tid på relevant innhold i stedet for støy. Søk går raskere, svarene blir bedre, og du beholder full kontroll uten tredjepartsavhengighet.