RAG e la sua implementazione pratica con LangChain, Bun, Ollama e Qdrant

I modelli linguistici di grandi dimensioni (LLM) moderni sono impressionanti, ma hanno una limitazione importante: la loro conoscenza è fissata nei loro pesi, rendendo difficile aggiornare ed estendere il loro sapere. Il Retrieval-Augmented Generation (RAG) è un approccio progettato per affrontare questo problema. Introdotto da Meta nel 2020, collega un modello linguistico a una base di conoscenza esterna (ad esempio, un insieme di documenti) in modo che possa incorporare informazioni aggiornate e specifiche nelle sue risposte. In pratica, per ogni domanda posta, il sistema RAG estrae prima contenuti rilevanti dalla sua base documentale, quindi genera una risposta combinando questo contesto recuperato con le capacità linguistiche del LLM.

Nota: Il codice sorgente completo del progetto di esempio menzionato in questo articolo è disponibile su GitHub.

Struttura dell'articolo

1. Cos'è RAG e perché utilizzarlo?

   • Principio di funzionamento
   • Vantaggi rispetto agli approcci classici
   • Casi d'uso concreti

2. Architettura di un sistema RAG

   • Componenti essenziali
   • Flusso di dati
   • Scelta tecnologica

3. Implementazione pratica con TypeScript

   • Configurazione del progetto con Bun
   • Integrazione di LangChain
   • Configurazione di Ollama e Qdrant

4. Analisi del codice e best practices

   • Indicizzazione dei documenti
   • Ricerca semantica
   • Generazione di risposte

5. Vantaggi dello stack tecnologico

   • Prestazioni di Bun vs. Node.js
   • Semplicità di LangChain
   • Flessibilità di Ollama
   • Scalabilità di Qdrant

6. Argomenti avanzati

   • Ottimizzazioni avanzate
   • Valutazione e metriche
   • Alternative tecnologiche

Cos'è RAG e perché utilizzarlo?

Retrieval-Augmented Generation (RAG) significa letteralmente "generazione aumentata dal recupero". L'idea è di separare la conoscenza dal modello. Invece di cercare di incorporare tutte le informazioni nei parametri di un LLM (attraverso costosi fine-tuning) o progettare un modello classico che prevedrebbe risposte dai dati, lasciamo che il modello principale generi testo e lo aumentiamo con una fase intermedia di recupero delle informazioni. Una tipica pipeline RAG funziona come segue:

1. Richiesta dell'utente – L'utente pone una domanda o inserisce una richiesta in linguaggio naturale (ad es. "A cosa serve la classe X in questo progetto?").
2. Ricerca di documenti rilevanti – Il sistema trasforma questa domanda in una rappresentazione vettoriale (embedding) e quindi interroga un database vettoriale per recuperare documenti o passaggi semanticamente più simili alla query. Questo identifica il contesto rilevante (ad es. un estratto dalla documentazione, codice o un articolo che corrisponde alla domanda).
3. Combinazione contesto + domanda – I documenti o estratti recuperati vengono quindi forniti al modello linguistico come contesto. In pratica, vengono inseriti nel prompt del LLM, tipicamente tramite un messaggio di sistema o aggiungendo il testo dei documenti trovati alla domanda dell'utente.
4. Generazione della risposta – Il modello linguistico (LLM) genera quindi una risposta basata sia sulla domanda che sul contesto fornito. La risposta dovrebbe contenere informazioni dai documenti, formulate in modo coerente grazie alle capacità del LLM.

Questo processo consente al modello di basarsi su conoscenze esterne specifiche al momento della generazione, senza doverle memorizzare permanentemente. Può essere paragonato a un essere umano che, di fronte a una domanda, consulterebbe libri o documenti di riferimento prima di rispondere: il LLM "consulta la sua biblioteca" prima di parlare.

Casi d'uso concreti per RAG

L'approccio RAG è particolarmente utile quando un assistente conversazionale deve gestire una base di conoscenza in evoluzione o estesa. Ecco alcuni esempi di casi d'uso concreti in cui RAG eccelle rispetto ai metodi classici:

Chatbot documentali: Un assistente alimentato dalla documentazione tecnica di un'azienda, in grado di rispondere alle domande degli sviluppatori o dei clienti attingendo direttamente da manuali, knowledge base interne o persino codice sorgente. Ad esempio, il modello può essere collegato alle specifiche API o al codice di un progetto open source per spiegare come funziona una funzione o perché è stato scelto un determinato design.

FAQ dinamiche: In un contesto di servizio clienti, un chatbot RAG può rispondere a domande frequenti (FAQ) basandosi sulle ultime politiche o dati di prodotto. Se una politica (ad es. condizioni di reso) cambia, è sufficiente aggiornare il documento di riferimento e il bot lo terrà immediatamente in considerazione, senza necessità di riaddestramento. Questo porta a FAQ sempre aggiornate con la possibilità di citare la fonte dell'informazione a supporto della risposta.

Assistenti legali: Un assistente può aiutare avvocati o giuristi trovando passaggi rilevanti in un database di leggi, giurisprudenza o contratti per una determinata domanda, e poi formulando la risposta in linguaggio naturale. Il modello non ha bisogno di conoscere a memoria l'intero codice civile; deve solo cercare gli articoli pertinenti. Lo stesso vale per un assistente medico che potrebbe interrogare database di pubblicazioni scientifiche o protocolli medici per fornire risposte basate sulle più recenti conoscenze cliniche.

Assistente di programmazione: Questo è il caso del nostro progetto di esempio – un assistente che conosce il contenuto di un repository di codice e può rispondere a domande su questo codice (architettura, ruolo di un modulo, potenziali bug, ecc.). Invece di addestrare un modello specializzato nella programmazione, utilizziamo un LLM generalista aumentato dalla ricerca di file di codice rilevanti nel repository.

Architettura di un sistema RAG

Componenti essenziali

Un sistema RAG completo tipicamente include i seguenti componenti:

1. Indicizzazione e archiviazione

   • Processore di documenti (estrazione, pulizia, chunking)
   • Generatore di embedding (trasformazione in vettori)
   • Database vettoriale (archiviazione e ricerca)

2. Pipeline di query

   • Preprocessore di query
   • Motore di ricerca semantica
   • Generatore di prompt

3. Generazione e post-elaborazione

   • Interfaccia LLM
   • Valutatore di risposte
   • Formattatore di output

Flusso di dati

typescript
1// Esempio semplificato del flusso di dati in un sistema RAG
2async function processQuery(query: string): Promise<string> {
3  // 1. Trasforma la query in un embedding
4  const queryEmbedding = await embedder.embedQuery(query);
5  
6  // 2. Cerca documenti rilevanti
7  const relevantDocs = await vectorStore.similaritySearch(queryEmbedding);
8  
9  // 3. Costruisci il prompt con il contesto
10  const prompt = buildPromptWithContext(query, relevantDocs);
11  
12  // 4. Genera la risposta con il LLM
13  const response = await llm.generate(prompt);
14  
15  return response;
16}

Scelta tecnologica

Per la nostra implementazione, abbiamo scelto uno stack moderno e potente:

• Bun: Runtime JavaScript ultraveloce, ideale per applicazioni server
• TypeScript: Tipizzazione statica per una migliore manutenibilità
• LangChain: Framework per la creazione di applicazioni basate su LLM
• Ollama: Strumento per eseguire modelli linguistici localmente
• Qdrant: Database vettoriale potente e facile da implementare

Questa combinazione offre un eccellente equilibrio tra prestazioni, comfort di sviluppo e flessibilità.

Implementazione pratica con TypeScript

Configurazione del progetto con Bun

Iniziamo con l'inizializzazione del nostro progetto:

bash
1# Creazione del progetto
2mkdir rag-code-assistant
3cd rag-code-assistant
4bun init
5
6# Installazione delle dipendenze
7bun add langchain @langchain/community @langchain/openai
8bun add qdrant-js ollama
9bun add -d typescript @types/node

Configurazione di base

typescript
1// src/config.ts
2export const CONFIG = {
3  // Configurazione Ollama
4  OLLAMA_BASE_URL: 'http://localhost:11434',
5  OLLAMA_MODEL_NAME: 'llama3',
6  
7  // Configurazione Qdrant
8  QDRANT_URL: 'http://localhost:6333',
9  QDRANT_COLLECTION_NAME: 'code_repository',
10  
11  // Configurazione indicizzazione
12  CHUNK_SIZE: 1000,
13  CHUNK_OVERLAP: 200,
14  
15  // Percorso del repository di codice da indicizzare
16  REPOSITORY_PATH: './repository',
17};

Indicizzazione dei documenti

L'indicizzazione è una fase cruciale in un sistema RAG. Comporta la conversione di documenti grezzi in chunk di dimensioni appropriate e poi la generazione di embedding per ogni chunk.

typescript
1// src/indexer.ts
2import { DirectoryLoader } from 'langchain/document_loaders/fs/directory';
3import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';
4import { OllamaEmbeddings } from '@langchain/community/embeddings/ollama';
5import { QdrantClient } from 'qdrant-js';
6import { CONFIG } from './config';
7
8export async function indexRepository() {
9  // 1. Caricamento dei file del repository
10  const loader = new DirectoryLoader(
11    CONFIG.REPOSITORY_PATH,
12    {
13      '.ts': (path) => new TextLoader(path),
14      '.js': (path) => new TextLoader(path),
15      '.tsx': (path) => new TextLoader(path),
16      '.jsx': (path) => new TextLoader(path),
17      '.md': (path) => new TextLoader(path),
18    }
19  );
20  
21  const docs = await loader.load();
22  console.log(`Caricamento di ${docs.length} file completato`);
23  
24  // 2. Suddivisione in chunk
25  const textSplitter = new RecursiveCharacterTextSplitter({
26    chunkSize: CONFIG.CHUNK_SIZE,
27    chunkOverlap: CONFIG.CHUNK_OVERLAP,
28  });
29  
30  const chunks = await textSplitter.splitDocuments(docs);
31  console.log(`Creazione di ${chunks.length} chunk completata`);
32  
33  // 3. Generazione di embedding
34  const embeddings = new OllamaEmbeddings({
35    baseUrl: CONFIG.OLLAMA_BASE_URL,
36    model: CONFIG.OLLAMA_MODEL_NAME,
37  });
38  
39  // 4. Salvataggio in Qdrant
40  const qdrant = new QdrantClient({ url: CONFIG.QDRANT_URL });
41  
42  // Creazione della collection se non esiste
43  try {
44    await qdrant.createCollection(CONFIG.QDRANT_COLLECTION_NAME, {
45      vectors: {
46        size: 1536, // Dimensione dei vettori di embedding
47        distance: 'Cosine',
48      },
49    });
50  } catch (e) {
51    console.log('Collection già esistente o errore:', e.message);
52  }
53  
54  // Inserimento dei documenti con i loro embedding
55  for (let i = 0; i < chunks.length; i += 100) {
56    const batch = chunks.slice(i, i + 100);
57    const batchEmbeddings = await embeddings.embedDocuments(
58      batch.map(chunk => chunk.pageContent)
59    );
60    
61    await qdrant.upsert(CONFIG.QDRANT_COLLECTION_NAME, {
62      points: batchEmbeddings.map((vector, idx) => ({
63        id: `${i + idx}`,
64        vector,
65        payload: {
66          text: batch[idx].pageContent,
67          metadata: batch[idx].metadata,
68        },
69      })),
70    });
71    
72    console.log(`Elaborazione del batch ${i}-${i + batch.length} completata`);
73  }
74  
75  console.log('Indicizzazione completata con successo!');
76}

Ricerca e generazione di risposte

typescript
1// src/rag.ts
2import { OllamaEmbeddings } from '@langchain/community/embeddings/ollama';
3import { QdrantClient } from 'qdrant-js';
4import { Ollama } from '@langchain/community/llms/ollama';
5import { CONFIG } from './config';
6
7export async function generateResponse(query: string): Promise<string> {
8  // 1. Inizializzazione dei componenti
9  const embeddings = new OllamaEmbeddings({
10    baseUrl: CONFIG.OLLAMA_BASE_URL,
11    model: CONFIG.OLLAMA_MODEL_NAME,
12  });
13  
14  const qdrant = new QdrantClient({ url: CONFIG.QDRANT_URL });
15  
16  const llm = new Ollama({
17    baseUrl: CONFIG.OLLAMA_BASE_URL,
18    model: CONFIG.OLLAMA_MODEL_NAME,
19  });
20  
21  // 2. Generazione dell'embedding della query
22  const queryEmbedding = await embeddings.embedQuery(query);
23  
24  // 3. Ricerca di documenti rilevanti
25  const searchResults = await qdrant.search(CONFIG.QDRANT_COLLECTION_NAME, {
26    vector: queryEmbedding,
27    limit: 5,
28  });
29  
30  const relevantDocs = searchResults.map(result => result.payload.text).join('\n\n');
31  
32  // 4. Creazione del prompt con contesto
33  const prompt = `
34  Sei un assistente di programmazione esperto che aiuta a comprendere il codice sorgente di un progetto.
35  Utilizza il seguente contesto per rispondere alla domanda dell'utente.
36  Se non riesci a trovare le informazioni nel contesto, dichiaralo chiaramente.
37  
38  CONTESTO:
39  ${relevantDocs}
40  
41  DOMANDA: ${query}
42  
43  RISPOSTA:
44  `;
45  
46  // 5. Generazione della risposta
47  const response = await llm.call(prompt);
48  
49  return response;
50}

Interfaccia utente semplice

typescript
1// src/index.ts
2import { indexRepository } from './indexer';
3import { generateResponse } from './rag';
4
5async function main() {
6  // Argomento per indicizzazione o query
7  const args = process.argv.slice(2);
8  
9  if (args[0] === 'index') {
10    console.log('Avvio indicizzazione...');
11    await indexRepository();
12  } else if (args[0] === 'query') {
13    const query = args.slice(1).join(' ');
14    if (!query) {
15      console.log('Utilizzo: bun run src/index.ts query "La tua domanda sul codice"');
16      process.exit(1);
17    }
18    
19    console.log(`Domanda: ${query}`);
20    console.log('Generazione risposta...');
21    const response = await generateResponse(query);
22    console.log('\nRisposta:');
23    console.log(response);
24  } else {
25    console.log('Utilizzo: bun run src/index.ts [index|query "La tua domanda"]');
26  }
27}
28
29main().catch(console.error);

Analisi del codice e best practices

Chunking efficiente

La suddivisione dei documenti in chunk è una fase critica che influenza direttamente la qualità dei risultati. Alcune best practices:

• Dimensione appropriata: I chunk dovrebbero essere abbastanza grandi da contenere contesto, ma non troppo grandi per rimanere rilevanti (tipicamente tra 500 e 1500 caratteri).
• Sovrapposizione: La sovrapposizione tra chunk previene la perdita di contesto ai confini.
• Suddivisione semantica: Idealmente, la suddivisione dovrebbe rispettare la struttura semantica dei documenti (paragrafi, funzioni, ecc.).

Ottimizzazione della ricerca

La qualità della ricerca semantica è essenziale:

• Filtri di metadati: Utilizzare metadati (tipo di file, data, autore) per affinare le ricerche.
• Re-ranking: Applicare un secondo livello di filtro per migliorare la rilevanza.
• Diversità: Garantire la diversità dei risultati per coprire diversi aspetti della domanda.

Prompting avanzato

La costruzione dei prompt è un'arte che influenza fortemente la qualità delle risposte:

typescript
1// Esempio di un prompt più avanzato
2const prompt = `
3# RUOLO
4Sei un assistente di programmazione esperto specializzato nell'analisi del codice sorgente.
5
6# CONTESTO
7${relevantDocs}
8
9# ISTRUZIONI
10- Rispondi alla domanda dell'utente basandoti solo sul contesto fornito
11- Se il contesto non contiene le informazioni necessarie, indicalo chiaramente
12- Cita frammenti di codice rilevanti nella tua risposta
13- Spiega il codice in modo pedagogico
14- Suggerisci miglioramenti se ne identifichi
15
16# DOMANDA
17${query}
18`;

Vantaggi dello stack tecnologico

Prestazioni di Bun vs. Node.js

Bun offre vantaggi significativi per questo tipo di applicazione:

• Avvio rapido: Tempo di avvio fino a 4 volte più veloce di Node.js
• Esecuzione ottimizzata: Prestazioni di esecuzione superiori, specialmente per operazioni I/O
• Bundler integrato: Semplificazione del flusso di lavoro di sviluppo

Semplicità di LangChain

LangChain semplifica notevolmente lo sviluppo di applicazioni basate su LLM:

• Astrazione: Interfaccia unificata per diversi modelli e provider
• Componenti riutilizzabili: Chains, Agents e Tools pronti all'uso
• Pattern consolidati: Implementazioni di riferimento per casi d'uso comuni

Flessibilità di Ollama

Ollama permette di eseguire modelli linguistici localmente con grande flessibilità:

• Modelli locali: Nessuna dipendenza da API esterne
• Privacy: I dati rimangono nella tua infrastruttura
• Personalizzazione: Possibilità di adattare i modelli alle tue esigenze

Scalabilità di Qdrant

Qdrant è un database vettoriale moderno progettato per la ricerca semantica:

• Prestazioni: Ottimizzato per ricerche di similarità rapide
• Filtraggio: Capacità di filtraggio avanzate per metadati
• Deployment flessibile: Utilizzabile in modalità embedded o come servizio

Argomenti avanzati

Ottimizzazioni avanzate

• Ricerca ibrida: Combinazione di ricerca vettoriale e ricerca per parole chiave
• Chunking gerarchico: Utilizzo di diversi livelli di granularità per i chunk
• Caching: Memorizzazione nella cache dei risultati di ricerca e delle risposte frequenti

Valutazione e metriche

Per misurare la qualità di un sistema RAG:

• Rilevanza: I documenti recuperati sono rilevanti per la domanda?
• Fedeltà: La risposta è fedele ai documenti di origine?
• Utilità: La risposta risponde efficacemente alla domanda dell'utente?

Alternative tecnologiche

• Framework: Haystack, LlamaIndex come alternative a LangChain
• Database vettoriali: Pinecone, Weaviate, Milvus come alternative a Qdrant
• Modelli: Vari modelli locali (Llama, Mistral) o API (OpenAI, Anthropic)

Conclusione

Il Retrieval-Augmented Generation rappresenta un progresso significativo nel modo in cui possiamo utilizzare i modelli linguistici per casi d'uso specifici. Separando la conoscenza dal modello di generazione, RAG consente di creare assistenti AI più accurati, aggiornati e trasparenti.

La nostra implementazione con TypeScript, Bun, LangChain, Ollama e Qdrant dimostra che è ora possibile costruire potenti sistemi RAG con tecnologie moderne e accessibili. Questo approccio apre la strada a una nuova generazione di assistenti AI in grado di ragionare su basi di conoscenza specifiche mantenendo al contempo la fluidità e la coerenza dei grandi modelli linguistici.

Non esitare a esplorare il codice sorgente completo su GitHub e adattarlo ai tuoi casi d'uso. RAG è una tecnologia in evoluzione, e ci sono numerose opportunità di innovazione in questo entusiasmante campo.