Navigare il codice con l'AI: i grafi semantici con LLM superano gli embeddings

Navigare il codice con l'AI: i grafi semantici con LLM superano gli embeddings

Gli strumenti di coding assistiti dall'intelligenza artificiale promettono di rivoluzionare lo sviluppo software, ma la loro efficacia è spesso limitata dalla capacità di comprendere e richiamare in modo efficiente il contesto di una codebase complessa. La sfida principale risiede nella creazione di una "memoria strutturata persistente" per il codice, che vada oltre la semplice rilettura dell'intero repository ad ogni sessione, un approccio che spreca risorse e token. Un team di sviluppatori ha condiviso le proprie scoperte dopo un anno di sperimentazioni, evidenziando come i metodi tradizionali di retrieval si siano rivelati insufficienti, mentre un approccio basato su grafi di conoscenza arricchiti da Large Language Models (LLM) abbia dimostrato un'efficacia superiore.

La discussione attuale nel settore tende a semplificare eccessivamente le soluzioni, suggerendo spesso l'uso di "soli embeddings" o "solo Tree-sitter". Tuttavia, l'esperienza pratica rivela che queste tecniche, sebbene utili in altri contesti, presentano limiti significativi quando applicate alla comprensione profonda del codice. Per le aziende che valutano l'implementazione di soluzioni AI per lo sviluppo, comprendere questi trade-off è cruciale per ottimizzare il Total Cost of Ownership (TCO) e garantire la sovranità dei dati, aspetti centrali per AI-RADAR.

Le sfide della ricerca semantica nel codice

Le sperimentazioni hanno messo in luce le carenze di due approcci ampiamente discussi. Il primo, l'uso di embeddings vettoriali su frammenti di codice, si è dimostrato inefficace. Funzioni con nomi simili, come un process() in un servizio di pagamenti e un process() in una pipeline di immagini, generano vettori simili a causa della somiglianza dei token. Tuttavia, queste funzioni non hanno alcuna relazione semantica o contestuale. I vettori tendono a "appiattire" le relazioni strutturali fondamentali del codice, come i grafi di chiamata, l'ereditarietà e le importazioni, rendendo la precisione del retrieval troppo bassa per essere utile. Questo approccio è stato completamente abbandonato.

Il secondo metodo testato è stato il parsing di AST (Abstract Syntax Tree) tramite Tree-sitter. Questo strumento è rapido e preciso nel fornire la struttura sintattica del codice, identificando l'esistenza di una funzione e le sue chiamate. Tuttavia, non è in grado di estrarre il significato o il contesto di business. Non può, ad esempio, indicare che "questa funzione gestisce i tentativi di webhook per i pagamenti Stripe falliti". Per rispondere a domande poste in linguaggio di business, un puro AST si rivela insufficiente, mancando la capacità di colmare il divario tra sintassi e semantica.

La soluzione: grafi di conoscenza arricchiti da LLM

La soluzione che ha dimostrato di funzionare efficacemente si basa su un'analisi per file eseguita da un LLM. Questo processo genera per ogni file uno scopo (purpose), un riassunto (summary) e un contesto di business (businessContext), che vengono poi archiviati come nodi in un grafo Neo4j. Gli edge di questo grafo collegano i nodi a classi, funzioni, parole chiave e importazioni. La ricerca avviene quindi tramite full-text search su questi campi semantici, anziché tramite similarità vettoriale.

Questo approccio è in linea con le recenti scoperte accademiche. Studi come RepoGraph (ICLR 2025) hanno mostrato un miglioramento del +32.8% su SWE-bench con metodologie basate su grafi, mentre Code-Craft ha registrato un aumento dell'82% nella precisione di retrieval top-1 utilizzando riassunti bottom-up da grafi di codice generati da LLM. Il principale trade-off di questa metodologia è il costo di indicizzazione iniziale, poiché ogni file richiede una chiamata a un LLM. Tuttavia, l'uso di un sistema di diffing basato su SHA-256 consente di reindicizzare solo i file modificati, rendendo il processo gestibile nel tempo.

Implicazioni per i deployment on-premise e la sovranità dei dati

La soluzione proposta, denominata Bytebell, è stata rilasciata come Open Source e si distingue per il suo orientamento ai deployment self-hosted. L'architettura prevede un daemon Bun locale e l'utilizzo dell'infrastruttura del cliente (BYO infra), con storage basato su Neo4j e MongoDB. Le chiamate esterne per l'analisi per file sono indirizzate a OpenRouter, ma il sistema si lega all'interfaccia 127.0.0.1, offrendo la possibilità di instradare queste richieste a un modello locale, garantendo così il controllo completo sui dati.

Questo modello di deployment è particolarmente rilevante per CTO, DevOps lead e architetti di infrastruttura che prioritizzano la sovranità dei dati, la compliance e la gestione del TCO. La capacità di mantenere il codice e le sue analisi all'interno dell'ambiente locale, potenzialmente anche in configurazioni air-gapped, elimina i rischi associati all'invio di codice sorgente a servizi cloud esterni. Sebbene Bytebell non sia un prodotto multi-tenant o un'interfaccia chat, la sua enfasi su un'architettura locale e la gestione granulare del contesto semantico lo posizionano come una soluzione promettente per le organizzazioni che cercano alternative self-hosted per i carichi di lavoro AI/LLM. Per chi valuta deployment on-premise, AI-RADAR offre framework analitici su /llm-onpremise per valutare i trade-off tra controllo, costi e performance.