LlamaIndex — Data Framework per LLM e Knowledge Base | Meteora Web • Meteora Web Agency

Hai un LLM che allucina perché non trova i dati giusti. Oppure hai centinaia di PDF, database SQL e API REST che vorresti rendere accessibili a un chatbot, ma ogni tentativo si perde in chunk sbagliati e risposte fuori contesto. Conosci il problema: un modello addestrato su dati generici non sa nulla della tua azienda, dei tuoi prodotti, delle tue procedure interne. E il fine-tuning? Troppo costoso, troppo lento, non sempre serve.

Noi, di Meteora Web, lavoriamo su questi scenari da anni. E quando abbiamo iniziato a integrare dati reali con LLM, ci siamo scontrati subito con il muro: come si fa a passare da una risposta vaga a una risposta fondata su documenti verificabili? La risposta è un data framework. E LlamaIndex è quello che usiamo in produzione per clienti con volumi seri.

Questa guida parte da un presupposto: hai già un minimo di dimestichezza con Python e con il concetto di RAG (Retrieval-Augmented Generation). Se non è così, ti consigliamo di dare un’occhiata alla nostra Pillar Guide su LangChain e LLM prima di proseguire. Qui entriamo nel vivo con LlamaIndex.

Perché LlamaIndex e non solo un database vettoriale?

Un database vettoriale (Pinecone, Weaviate, Qdrant) ti permette di fare similarity search su embedding. Ma da solo non basta: devi decidere come suddividere i documenti (chunking), come indicizzare metadati, come gestire aggiornamenti e cancellazioni, come recuperare informazioni strutturate (SQL, API). LlamaIndex nasce proprio per risolvere questo ecosistema: è un framework che orchestri dati, indici, query e LLM in un unico flusso.

Cosa fa concretamente LlamaIndex per te

Immagina di avere una knowledge base con 10.000 pagine di manuali tecnici, un database PostgreSQL con ordini clienti e un’API esterna per lo stato delle spedizioni. Con LlamaIndex crei un unico "motore di query" in grado di: indicizzare ogni fonte (PDF, SQL, API), suddividere in chunk intelligenti (anche con parser specifici come Unstructured o PDFPlumber), generare embedding (con il modello che preferisci: OpenAI, HuggingFace, locale), recuperare i chunk più rilevanti combinando ricerca semantica e filtri per metadati, e infine passarli al LLM per generare una risposta citando le fonti. Risultato: zero allucinazioni, risposte certificate.

Noi lo abbiamo usato per un cliente logistico che voleva un assistente virtuale per i corrieri. Il sistema doveva rispondere a domande del tipo: "Qual è la procedura per un pacco danneggiato in transito?" e recuperare la norma esatta dal PDF del regolamento. Con LlamaIndex abbiamo costruito l’indice in un pomeriggio. Senza, avremmo dovuto scrivere centinaia di righe di plumbing per chunking, embedding e retrieval.

Come si installa e configura LlamaIndex per un progetto reale?

Partiamo da un ambiente Python 3.10+. LlamaIndex è un pacchetto pip con modulazione: installi il core e poi i cosiddetti "llama-packs" per integrazioni specifiche.

pip install llama-index-core llama-index-readers-file llama-index-embeddings-openai llama-index-llms-openai

Imposta le tue variabili d’ambiente (OPENAI_API_KEY, oppure usa modelli locali con Ollama). Poi scrivi il file principale. Ecco un esempio minimo che carica un PDF e risponde a una domanda:

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# Carica tutti i PDF dalla cartella 'data'
documents = SimpleDirectoryReader("data").load_data()

# Costruisce l'indice (di default usa OpenAI embedding)
index = VectorStoreIndex.from_documents(documents)

# Crea il motore di query
query_engine = index.as_query_engine()

# Fai una domanda
response = query_engine.query("Cosa dice il regolamento sui rimborsi?")
print(response)

In 10 righe hai un RAG funzionante. Ma non fermarti qui: la potenza sta nelle personalizzazioni.

Configurazione del chunking e dei parser

Il chunking di default (split per caratteri) va bene solo per demo. In produzione devi scegliere una strategia adatta al tipo di documento. LlamaIndex supporta SentenceSplitter (basato su NLP, mantiene frasi intere), TokenTextSplitter (per finestre di token), e parser specializzati come PDFNodeParser o MarkdownNodeParser.

from llama_index.core.node_parser import SentenceSplitter

parser = SentenceSplitter(
    chunk_size=512,
    chunk_overlap=100
)
nodes = parser.get_nodes_from_documents(documents)

Un errore comune è usare chunk troppo piccoli: il LLM perde il contesto. Noi partiamo da 512 token con overlap 100 e poi lo taramo in base ai risultati. Per documenti tecnici, preferiamo chunk di 1024 token.

Come indicizzare dati strutturati (SQL, API) con LlamaIndex?

LlamaIndex non si limita a file. Ha connettori per database SQL, API REST, Google Drive, Notion, e molto altro. L’idea è trasformare ogni fonte in una "tabella logica" interrogabile via linguaggio naturale.

Indicizzare un database PostgreSQL

from llama_index.core import SQLDatabase
from sqlalchemy import create_engine

engine = create_engine("postgresql://user:pass@host/dbname")
sql_database = SQLDatabase(engine, include_tables=["orders", "products"])

from llama_index.core.query_engine import NLSQLTableQueryEngine
query_engine = NLSQLTableQueryEngine(
    sql_database=sql_database,
    tables=["orders", "products"]
)
response = query_engine.query("Quanti ordini ha fatto il cliente Mario Rossi nell'ultimo mese?")
print(response)

Attenzione: LlamaIndex genera una query SQL basata sul LLM, poi la esegue e restituisce il risultato. Questo significa che devi avere permessi di sola lettura per sicurezza, e che il LLM deve capire lo schema. Noi consigliamo di passare un prompt con la descrizione delle tabelle per ridurre errori.

Per le API, esiste il RequestsReader o implementi un custom reader. Un caso reale: abbiamo indicizzato un’API di tracking spedizioni tramite un reader personalizzato che chiama l’API e converte il JSON in Documento LlamaIndex. Poi l’indice combinava PDF di regolamenti e questi dati live.

Quale strategia di retrieval scegliere per una knowledge base aziendale?

LlamaIndex offre diversi retriever: base, con filtri, con reranking, ibrido (keyword + vettoriale). La scelta dipende dal tipo di domande e dalla qualità dei dati.

Retriever semplice: usa la similarità coseno sugli embedding. Veloce, ma può perdere chunk marginali.
Retriever con filtri: aggiungi filtri per metadati (es. solo documenti del 2025, solo categoria "tecnica").
Retriever ibrido: combina BM25 (ricerca testuale) con embedding. Serve per termini rari o neologismi non ben rappresentati nell’embedding.
Retriever con reranker (CrossEncoder): recupera top-k con embedding, poi riordina con un modello di reranking più preciso. Aumenta la qualità ma costa più risorse.

from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.core.query_engine import RetrieverQueryEngine

retriever = VectorIndexRetriever(
    index=index,
    similarity_top_k=5,
    filters=MetadataFilters(
        filters=[ExactMatchFilter(key="category", value="tecnica")]
    )
)
query_engine = RetrieverQueryEngine.from_args(retriever=retriever)

Noi usiamo spesso un hybrid retriever con un piccolo modello di reranking locale (BAAI/bge-reranker-v2-m3) per bilanciare costo e qualità. In un progetto per un’azienda di 200 dipendenti, abbiamo ridotto le risposte errate del 40% rispetto al solo embedding.

Come gestire aggiornamenti e versioni dei documenti?

Nei sistemi reali i documenti cambiano: nuovi PDF, aggiornamenti di procedure, cancellazioni. LlamaIndex fornisce indicizzazione incrementale tramite DocumentStore e IndexStore persistenti. Puoi salvare l’indice su disco o su un database (PostgreSQL, DynamoDB).

# Salva indice su disco
index.storage_context.persist(persist_dir="./storage")

# Carica indice esistente
from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)

Per aggiornare, puoi cancellare un nodo specifico e reinserire il documento modificato. LlamaIndex gestisce lo stale index detection con hash dei documenti. Noi abbiamo integrato un trigger su Git: ogni volta che un repository di documentazione viene aggiornato, una GitHub Action rigenera l’indice per il chatbot interno.

Cosa fare adesso

Ecco tre azioni concrete per partire subito con LlamaIndex:

Installa l’ambiente: Python 3.10, pip, e la libreria core con il reader per il tuo formato (PDF, CSV, SQL).
Crea un indice di prova: prendi 3-5 documenti reali della tua azienda (es. fogli informativi, policy) e costruisci un motore di query base. Verifica che le risposte siano fedeli al testo.
Sperimenta con il chunking e il retrieval: prova SentenceSplitter con diverse dimensioni, poi confronta i risultati con retriever ibrido o reranking. Tieni traccia dei tempi di risposta e della qualità percepita.

Se vuoi approfondire come orchestrare più agenti con LlamaIndex e LangChain, leggi la nostra guida su AutoGen e CrewAI. E se hai un progetto concreto, contattaci: costruiamo knowledge base che funzionano davvero, non demo.