Come Preparare la Documentazione per un AI Coding Assistant

Quando si inserisce la documentazione grezza in un agente AI, spesso si ottiene l'effetto opposto a quello desiderato. Il sistema si perde tra pagine poco rilevanti e fatica a estrarre le informazioni davvero utili.

Non Tutte le Pagine Hanno lo Stesso Valore

Molti siti di documentazione contengono pagine create solo per struttura o per motivi legali. Indici, policy sulla privacy, changelog e elenchi di API sono utili per chi naviga il sito, ma diventano zavorra quando un modello deve apprendere.

Se si carica tutto senza filtri in un database vettoriale, l'AI impiega più tempo a elaborare il contesto e rischia di restituire riferimenti sbagliati.

Un Approccio a Due Fasi per la Classificazione

La soluzione più efficace unisce regole semplici a una classificazione selettiva con LLM locale.

Prima fase: filtri rapidi

Si parte analizzando URL e struttura del contenuto. Si individuano subito le pagine inutili:

• pagine legali con pattern come /privacy o /terms
• hub di navigazione con meno di 200 parole e tanti link
• changelog e pagine di riferimento

Questo passaggio avviene in locale, è gratuito e copre una buona parte del sito.

Seconda fase: classificazione con LLM

Per le pagine restanti si invia al modello locale solo l'URL, il titolo, i primi 200 parole e la gerarchia dei titoli. Il modello classifica secondo lo schema Diátaxis: concettuale, tutorial, how-to, esempi o strutturale. Così si evita di far lavorare l'LLM su tutto il corpus.

Embedding Intelligente

Una volta eliminate le pagine inutili, le embedding diventano più precise. Le pagine lunghe vanno divise in chunk rispettando i titoli, poi si calcola la media delle rappresentazioni. Questo metodo mantiene il contesto semantico senza superare i limiti di token.

Per l'embedding si usa un modello locale come sentence-transformers: è veloce, non ha costi API e funziona bene con la documentazione tecnica.

Costruire un Knowledge Graph Ibrido

Il vero vantaggio arriva combinando due tipi di relazioni:

• Link espliciti: i collegamenti scritti dagli autori della documentazione
• Collegamenti semantici: connessioni basate sulla similarità tra embedding (soglia 0.75)

Si salvano come archi diretti in un grafo. Per i collegamenti semantici si conserva il punteggio di similarità. Per evitare hub troppo densi, si limita il numero di vicini per pagina a circa 20 e si escludono le pagine di navigazione e legali.

Il Risultato: un Database SQLite Portatile

Tutto viene salvato in un unico file SQLite:

• Contenuto pulito in markdown
• Classificazioni delle pagine
• Embedding
• Archi del grafo con pesi
• Metadati e URL

Questo approccio rende la knowledge base portatile, interrogabile con SQL e filtrabile per tipo di contenuto. L'agente AI può navigare tra pagine correlate senza dover interrogare API esterne.

Il Flusso di Lavoro Completo

Il processo prevede sei passaggi:

1. Crawl del sito rispettando robots.txt
2. Pulizia dell'HTML in markdown
3. Classificazione con regole e LLM
4. Creazione delle embedding
5. Costruzione del grafo
6. Salvataggio in SQLite

Perché Vale la Pena

Che si tratti di un assistente interno o di un sistema di retrieval per il team, una documentazione ben strutturata fa la differenza. L'AI lavora solo sui contenuti rilevanti, le risposte sono più rapide e si mantiene il pieno controllo sui dati senza dipendere da servizi di terze parti.