Come usare LlamaIndex: Una guida pratica da zero alla produzione
Se hai mai provato a creare un'app di generazione aumentata dal recupero (RAG) e hai pensato: "Perché collegare embedding, vector store e prompt è così complicato?", non sei il solo. LlamaIndex esiste per rendere questa pipeline veloce, sensata e pronta per la produzione. In questa guida pratica e orientata alla soluzione, esamineremo come utilizzare LlamaIndex end-to-end: acquisizione dei dati, indicizzazione, interrogazione, valutazione e implementazione, in modo da poter rilasciare qualcosa di affidabile senza perderti in codice collante.
Utilizzeremo una struttura guidata dalle domande con passaggi progressivi, snippet eseguibili e suggerimenti reali. Che tu stia prototipando un chatbot per documenti interni o implementando un assistente di conoscenza per i clienti, imparare a utilizzare LlamaIndex in modo efficace ti farà risparmiare giorni.
: LlamaIndex è un framework che ti aiuta a connettere i tuoi dati a modelli linguistici di grandi dimensioni con strumenti di indicizzazione, recupero e orchestrazione, ideale per RAG, agenti e output strutturati.
Cos'è LlamaIndex e perché usarlo?
- LlamaIndex è un framework di dati per app LLM. Fornisce elementi costitutivi per:
- Acquisizione: Carica file, pagine web, database e API.
- Chunking e indicizzazione: Trasforma il contenuto grezzo in strutture interrogabili (indici vettoriali, di parole chiave, di grafi).
- Recupero: Recupera il contesto con strategie flessibili (BM25, ibrido, reranking).
- Query Engines e Agents: Componi recupero, strumenti e prompt in un'esperienza QA coerente.
- Valutazione e monitoraggio: Valuta la qualità del recupero e la rilevanza della risposta.
- Desideri uno stack RAG robusto senza reinventare chunking, embedding e recupero.
- Hai bisogno di combinare più origini dati (PDF + Notion + SQL).
- Ti piacerebbe sperimentare con recupero ibrido, reranking o output strutturati.
- Modello mentale di base quando impari a usare LlamaIndex:
- Dati → Nodi → Indice → Retriever → Query Engine → App
Guida rapida: Il ciclo RAG minimo
Questo è il percorso più veloce per un prototipo funzionante. Caricheremo documenti, creeremo un indice vettoriale e porremo domande.
# 1) Installa
# pip install llama-index llama-index-embeddings-openai llama-index-llms-openai
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
# 2) Configura il tuo modello + embedding
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # o usa qualsiasi provider LLM/embedding supportato
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Carica documenti (es., ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Costruisci un indice
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Crea un query engine e poni una domanda
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("What are the key security practices mentioned in the docs?")
print(response)
Questa è l'essenza. Da qui, le app reali aggiungono chunking migliore, reranking, prompt strutturati e osservabilità.
Acquisizione: Porta i tuoi dati (BYOD) nel modo giusto
Quando decidi come utilizzare LlamaIndex per dati reali, scegli i loader che corrispondono alle tue origini e preservano la struttura.
- File:
SimpleDirectoryReader, lettori PDF/HTML/Markdown
- Web:
BeautifulSoupWebReader, lettori di sitemap
- SaaS: Notion, Confluence, Slack, Google Drive (tramite connettori)
- Database: SQL e DB vettoriali (Pinecone, Weaviate, Chroma, Elasticsearch)
- Suggerimento: Normalizza i metadati (titolo, autore, URL, created_at). I buoni metadati sovralimentano il reranking e il filtraggio in seguito.
from llama_index.core import SimpleDirectoryReader
from llama_index.readers.web import SimpleWebPageReader
file_docs = SimpleDirectoryReader("./policies").load_data
web_docs = SimpleWebPageReader(html_to_text=True).load_data
all_docs = file_docs + web_docs
Chunking e Node Parser: Se entra spazzatura, esce spazzatura
Ottenere il chunking giusto è uno dei passaggi più importanti quando si impara a utilizzare LlamaIndex in modo efficace.
- Perché il chunking è importante: Troppo grande → token bloat e recupero irrilevante. Troppo piccolo → frammentazione del contesto.
- Valori predefiniti: Ragionevoli per molti casi, ma ottimizza per il tuo tipo di contenuto.
- Documenti tecnici: chunk di 512–1024 token con sovrapposizione del 10–20%.
- FAQ: Chunk più piccoli (256–512) per mantenere intatti le coppie Q/A.
- Legale/Politiche: Chunk più grandi (1024–1536) per preservare definizioni + clausole.
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core import Document
parser = SentenceSplitter(chunk_size=800, chunk_overlap=100)
nodes = []
for d in all_docs:
nodes.extend(parser.get_nodes_from_documents([Document(text=d.text, metadata=d.metadata)]))
Strategie di indicizzazione: Vettoriale, per parole chiave o ibrida?
Scegliere l'indice giusto è fondamentale. La buona notizia: LlamaIndex ti consente di combinarli.
- Indice vettoriale: Ottimo per la ricerca semantica. Migliore per "spiega X" o query vaghe.
- Parola chiave (BM25): Forte per termini esatti, ID, codici di errore, log.
- Ibrido: Combina entrambi; riordina i migliori candidati con un LLM o cross‑encoder.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Indice vettoriale da nodi pre-parsati
v_index = VectorStoreIndex(nodes)
# Retriever di parole chiave BM25
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Ibrido: unisci i candidati, quindi riordina
from llama_index.core.retrievers import RouterRetriever
from llama_index.retrievers.merge import MergerRetriever
v_retriever = v_index.as_retriever(similarity_top_k=6)
hybrid = MergerRetriever(retrievers=[v_retriever, bm25_retriever], top_k=8)
query_engine = RetrieverQueryEngine.from_args(retriever=hybrid)
Reranking e filtri: aumenta la precisione senza strapagare
Il reranking migliora la qualità della risposta riordinando i chunk recuperati in base alla rilevanza.
- Quando riordinare: Se gli utenti segnalano citazioni fuori tema o contesti lunghi e imbottiti.
- Cross‑encoders (ricerca di embedding bi‑encoder → reranking cross‑encoder)
- Reranking basato su LLM (più costoso, a volte più intelligente su testi sfumati)
- Filtri di metadati (es.,
source == 'handbook', created_at > 2024-01-01)
from llama_index.postprocessor.flag_embedding_reranker import FlagEmbeddingReranker
from llama_index.core.query_engine import RetrieverQueryEngine
reranker = FlagEmbeddingReranker(top_n=5, model="BAAI/bge-reranker-base")
query_engine = v_index.as_query_engine(
similarity_top_k=12,
node_postprocessors=[reranker]
)
Prompting e Query Engines: Dalla ricerca alle risposte
Un query engine è dove il recupero incontra la generazione. Per padroneggiare come utilizzare LlamaIndex in produzione, progetta attentamente prompt e sintesi della risposta.
- Strategie di sintesi della risposta:
- "Stuff" semplice (concatenazione) per contesti piccoli
- Tree o map‑reduce per contesti più lunghi
- Modalità citazione per mostrare le fonti
from llama_index.core.response_synthesizers import get_response_synthesizer
from llama_index.core import ServiceContext
synth = get_response_synthesizer(response_mode="tree_summarize")
query_engine = v_index.as_query_engine(response_synthesizer=synth)
ans = query_engine.query("Summarize the onboarding steps and cite sources.")
print(ans)
- Prompt personalizzati: Adatta il tono, gli output strutturati o le protezioni.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
<a4>"""
Sei un assistente conciso e basato sulle prove. Usa solo il contesto fornito.Agenti e strumenti: quando il recupero non è sufficiente
A volte le risposte richiedono azioni: eseguire SQL, chiamare API o navigare. Gli agenti LlamaIndex coordinano strumenti e ragionamento con la tua pipeline di recupero.
- Casi d'uso: Dashboard KPI (strumento SQL), bot di supporto (API di ricerca ticket), agenti di ricerca (web + RAG).
from llama_index.core.agent import ReActAgent
from llama_index.tools.sql import SQLQueryEngineTool
from sqlalchemy import create_engine
engine = create_engine("sqlite:///analytics.db")
sql_tool = SQLQueryEngineTool.from_engine(engine)
agent = ReActAgent.from_tools([sql_tool], llm=llm, verbose=True)
agent.chat("What was monthly churn in Q2 2025? If needed, query the DB.")
)</a11>Valutazione: Non rilasciare alla cieca
Imparare a usare LlamaIndex in modo responsabile significa convalidare sia il recupero che le risposte prima del rilascio.
- Valutazione offline: Valuta il richiamo/precisione del recupero su un set etichettato.
- Valutazione online: Registra i prompt degli utenti, misura la soddisfazione, i tassi di deflection e le allucinazioni.
- Funzionalità integrate: LlamaIndex fornisce helper di valutazione per la fedeltà e la rilevanza della risposta.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("List SOC 2 control families in our policy.")
print("faithful?", faith.evaluate_response(pred))
print("relevant?", rel.evaluate_response(pred))
- Barra pratica: Per gli assistenti interni, punta a una valutazione "utile" >80% sulle principali query prima del lancio su larga scala.
Persistenza e Vector Store: Rendilo scalabile
Gli indici creati in memoria non saranno sufficienti per carichi di lavoro reali. Persisti in un DB vettoriale e abilita aggiornamenti incrementali.
- Backend popolari: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Suggerimento: Usa namespace per tenant o dipartimento; mantieni i metadati ricchi.
# Esempio: Chroma
# pip install chromadb llama-index-vector-stores-chroma
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext
import chromadb
chroma_client = chromadb.PersistentClient(path="./chroma_store")
collection = chroma_client.get_or_create_collection("company_knowledge")
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(all_docs, storage_context=storage_context)
Sicurezza e governance: la parte che tutti dimenticano
- Gestione PII: Redigere o eseguire l'hashing dei campi sensibili durante l'acquisizione.
- Controlli di accesso: Filtra per ruoli utente con vincoli di metadati.
- Freschezza del contenuto: Pianifica la riacquisizione; contrassegna le versioni.
- Sicurezza: Aggiungi criteri di rifiuto e vincoli solo di origine nei prompt.
# Esempio: filtraggio basato sui metadati al momento della query
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Dal prototipo alla produzione: modelli di implementazione
- Modello server: Esporre un endpoint
/query; mantieni l'indice caldo in memoria.
- Avvertenza serverless: Avvii a freddo + modelli di grandi dimensioni possono danneggiare la latenza; considera l'inferenza gestita.
- Caching: Memorizza nella cache gli embedding e i risultati delle query frequenti; abilita gli aggiornamenti parziali.
- Osservabilità: Registra i nodi recuperati, l'utilizzo dei token, la lunghezza della risposta e il feedback degli utenti.
# Wrapper FastAPI minimo
# pip install fastapi uvicorn
from fastapi import FastAPI
app = FastAPI
qe = index.as_query_engine(llm=llm)
@app.post("/query")
async def query(payload: dict):
q = payload.get("q", "")
resp = qe.query(q)
return {"answer": str(resp), "sources": [s.node.metadata for s in resp.source_nodes]}
Progetti del mondo reale: scegli il tuo percorso
- Assistente per le politiche interne
- Indice: Ibrido (BM25 + Vettoriale) con reranking
- Guardrail: Modalità solo origine; fallback "Non lo so"
- KPI: Tasso di risoluzione per le domande sulle politiche
- Copilota per l'assistenza clienti
- Indice: Documenti del prodotto + note di rilascio + ticket
- Agenti: Strumento API per controllare lo stato dell'ordine/ticket
- KPI: Risoluzione al primo contatto, deflection, CSAT
- Indice: Web + PDF + note; forte deduplicazione
- Rerank: Cross‑encoder; sintesi: map‑reduce
- KPI: Tempo per l'intuizione; accuratezza delle citazioni
- Strumenti: Motore SQL + RAG sulle definizioni delle metriche
- Governance: Politiche a livello di riga; audit delle query
- KPI: Correttezza vs. verità di base
Costo e latenza: mantienilo veloce (e economico)
- Embedding: Batch dove possibile; usa modelli più piccoli per il richiamo, riordina selettivamente.
- Dimensione del contesto: Punta a 1–2k token dei chunk più rilevanti.
- Caching: Memorizza nella cache il recupero top‑K per le query frequenti; memorizza le chiamate LLM con prompt con hash.
- Parallelismo: Fan‑out recupero → fan‑in riordina per ridurre la latenza di coda.
Errori comuni quando si impara a usare LlamaIndex
- Over‑chunking, che porta a un recupero superficiale e rumoroso
- Nessun filtro di metadati, che causa l'inserimento di fonti irrilevanti
- Affidarsi a un singolo tipo di indice per tutti i contenuti
- Saltare la valutazione; rilasciare senza una barra di qualità
- Lasciare che gli indici diventino obsoleti; nessun aggiornamento pianificato
A proposito: velocizzare il flusso di lavoro nell'editor
Mentre iteri su prompt, chunker e impostazioni di recupero, vale la pena notare che una barra laterale di codifica e ricerca AI come Sider.ai può accelerare il ciclo. Puoi tenere a portata di mano snippet, prompt e note di valutazione, generare diff delle modifiche dei prompt e testare rapidamente le variazioni senza uscire dal browser. Questo è particolarmente utile quando stai modificando come utilizzare LlamaIndex su diverse strategie di recupero. Checklist passo-passo: da zero alla produzione
- Acquisisci le origini e normalizza i metadati
- Ottimizza le dimensioni dei chunk in base al tipo di contenuto
- Crea indici vettoriali + BM25; abilita il recupero ibrido
- Aggiungi reranking e filtri di metadati
- Personalizza i prompt; abilita le citazioni e la politica di rifiuto
- Valuta la fedeltà e la rilevanza su un set di test
- Persisti in un vector store; abilita gli aggiornamenti incrementali
- Aggiungi osservabilità, caching e filtri RBAC
- Avvolgi in un'API e imposta gli SLA; documenta le modalità di errore
Punti chiave
- Se desideri un'app RAG robusta, imparare a usare LlamaIndex ti farà risparmiare settimane di ingegneria collante.
- Inizia in modo semplice, quindi sovrapponi recupero ibrido, reranking e prompt strutturati.
- Valuta prima di scalare; persisti gli indici e monitora la qualità in produzione.
- Progetta per la governance fin dal primo giorno: la sicurezza non è un'aggiunta successiva.
Passaggi successivi
- Prototipa la guida rapida su un piccolo set di documenti.
- Sperimenta con il recupero ibrido e un reranker.
- Aggiungi valutazione e citazioni; traccia le metriche di qualità.
- Passa a un vector store persistente e implementa un'API.
FAQ
D1: A cosa serve LlamaIndex nelle applicazioni RAG?
LlamaIndex ti aiuta a connettere i tuoi dati agli LLM con componenti di acquisizione, indicizzazione e recupero. Semplifica la creazione di sistemi RAG gestendo chunking, indici vettoriali/di parole chiave e orchestrazione delle query.
D2: Come scelgo il tipo di indice giusto in LlamaIndex?
Usa un indice vettoriale per le query semantiche, BM25 per corrispondenze esatte come ID o codici e un approccio ibrido per il miglior richiamo e precisione complessivi. Molti team combinano entrambi e aggiungono reranking per i risultati top‑K.
Q3: Come posso migliorare la precisione quando utilizzo LlamaIndex?
Ottimizza le dimensioni dei chunk, includi metadati ricchi, abilita il recupero ibrido e aggiungi un reranker. Implementa anche la valutazione per la fedeltà e la rilevanza e utilizza la modalità di citazione per mostrare le fonti.
Q4: LlamaIndex può funzionare con il mio database vettoriale esistente?
Sì. LlamaIndex si integra con i più diffusi archivi vettoriali come Pinecone, Weaviate, Chroma, Qdrant ed Elasticsearch. Persisti gli indici per la scalabilità e gli aggiornamenti incrementali.
Q5: Come posso distribuire un'app LlamaIndex in produzione?
Integra il tuo motore di query in un'API (ad esempio, FastAPI), archivia i dati in un archivio vettoriale, aggiungi caching e osservabilità e valuta continuamente la qualità. Applica filtri di metadati e controllo degli accessi per la sicurezza.