Så bygger du en smart dokumentationsdatabas för din AI-kodassistent

Att stoppa in rå dokumentation i en AI-agent är som att be den leta efter en nål i en höstack. Varje juridiksida, changelog och navigationssida blir bara brus som försvagar signalen. På NameOcean har vi jobbat mycket med hur man bäst förbereder dokumentation inför AI-drivna utvecklingsflöden. Här är en praktisk metod som fungerar.

Inte alla sidor är värda att spara

Många tekniska sajter innehåller en hel del innehåll som bara finns för struktur eller juridiska skäl. Det handlar om indexsidor, integritetspolicyer, changeloggar och API-listor. För en människa som surfar runt är de nödvändiga, men för en AI som ska lära sig av innehållet är de mest bara i vägen.

Slänger du in allting rakt av i en vektordatabas får AI:n ägna tid åt att sortera bort material som inte tillför något. Resultatet blir långsammare sökningar och sämre svar.

Tvåstegsfiltrering

Den effektivaste lösningen är att kombinera enkla regler med selektiv LLM-klassificering.

Steg ett: Regelbaserad rensning

Börja med att titta på URL:er och sidornas grundstruktur. Det räcker ofta för att snabbt sortera bort uppenbart oviktigt material:

• Juridiska sidor: leta efter /legal/, /privacy, /terms och liknande mönster
• Navigationssidor: korta sidor med mest länkar
• Changeloggar: ofta lätta att känna igen på URL:en
• Referenssidor: ibland går det att avgöra bara på hur sidan är uppbyggd

Detta steget körs lokalt, kostar inget och tar hand om kanske hälften av alla sidor.

Steg två: LLM-klassificering

För det som återstår skickar du en lättviktig payload till en lokal LLM. Du behöver bara URL, titel, de första 200 orden och en översikt över rubrikstrukturen. Be modellen klassificera enligt Diátaxis-modellen – alltså om sidan är konceptuell, en tutorial, en how-to-guide, ett exempel eller bara strukturellt innehåll.

Bädda in innehåll smart

När bruset är borta blir det mycket enklare att skapa embeddings. Men många dokumentsidor är för långa för att hanteras som en helhet. Lösningen är att dela upp vid rubrikgränser och sedan ta ett genomsnitt av de resulterande vektorerna. Det bevarar den semantiska strukturen bättre än att bara klippa av.

Använd en lokal sentence transformer-modell. Den är tillräckligt bra för teknisk dokumentation och slipper du både API-kostnader och fördröjningar.

Kombinera länkar och semantik i en graf

Det verkliga värdet kommer när du bygger en hybrid kunskapsgraf. Du sparar både de explicita länkarna som författarna lagt in och de semantiska kopplingarna som upptäcks via embeddings. Sidor med hög cosinuslikhet (över 0,75) kan kopplas även om de inte länkar till varandra.

Begränsa antalet grannar per sida till runt 20 stycken för att undvika att vissa noder blir för tunga. Och skippa navigations-, juridik- och referenssidor helt när du bygger den semantiska delen av grafen.

Allt i en SQLite-databas

Slutprodukten är en enda SQLite-fil som innehåller:

• Rensad markdown
• Sidklassificeringar
• Embeddings
• Grafkanter med vikter
• Metadata och URL:er

Databasen är portabel, går att köra offline och kan användas direkt av AI-agenter via SQL. Du kan filtrera på sidtyp, följa semantiska kopplingar och hålla nere svarstiderna.

Arbetsflödet i korthet

1. Crawla dokumentationen
2. Konvertera HTML till markdown
3. Klassificera sidorna
4. Skapa embeddings
5. Bygg grafen
6. Spara allt i SQLite

Då har din AI-agent en strukturerad kunskapsbas istället för en rå dump av HTML.

Varför det här spelar roll

Oavsett om du bygger en intern kodassistent, integrerar AI i din IDE eller skapar ett internt kunskapsverktyg så blir dokumentationskvaliteten en kraftmultiplikator. Med rätt struktur slipper AI:n slösa tid på brus. Svaren blir bättre, sökningarna snabbare och du behåller full kontroll över din egen data.