Il mio motore di query LlamaIndex gestisce dati complessi

Ciao a tutti, famiglia tech! Nina Torres di nuovo da agntbox.com. Oggi esploreremo qualcosa che sta facendo scalpore nella comunità AI, specialmente per coloro di noi che si cimentano nella creazione di esperienze AI più personalizzate e consapevoli del contesto. Sto parlando di LlamaIndex, e in particolare di come il suo motore di query si sia evoluto per gestire interazioni con dati sempre più complessi. Dimenticatevi di lanciargli semplicemente un PDF e sperare per il meglio; stiamo esaminando come farlo davvero pensare attraverso più fonti di dati diverse.

La mia casella di posta, come quella di molti di voi, è stata sommersa da domande su come andare oltre le configurazioni base di RAG (Retrieval-Augmented Generation). Le persone stanno costruendo applicazioni incredibili, ma si trovano di fronte a un muro quando la loro AI deve rispondere a domande che richiedono di sintetizzare informazioni da un database, un insieme di documenti, e un’API live. Non si tratta più di un semplice problema di “trovare questo testo”. È un problema di “capire cosa chiedere dove, per poi combinare le risposte”. E onestamente, è un problema con cui ho dovuto confrontarmi in un progetto personale per un cliente che gestisce un sito e-commerce di nicchia – immaginate un assistente AI che deve controllare l’inventario dei prodotti (database), recuperare le recensioni degli utenti (documenti) e suggerire articoli correlati in base ai prezzi live (API). La mia configurazione iniziale di LlamaIndex, pur essendo decente per la parte delle recensioni, è completamente mancata nella sintesi di più fonti.

Quindi, oggi esploreremo le capacità avanzate del motore di query di LlamaIndex per la sintesi di dati multi-sorgente. Non si tratta solo di indicizzare diversi tipi di dati; si tratta di costruire un motore di query che orchestrerà intelligentemente il recupero delle informazioni attraverso quelle fonti diverse per rispondere a domande complesse e articolate. Parliamo di passare da un semplice recuperatore a un sistema sofisticato di instradamento e pianificazione.

L’Evoluzione del “Porre una Domanda” in LlamaIndex

Ricordate quando LlamaIndex è arrivato sulla scena? Era fantastico per trasformare dati non strutturati in qualcosa con cui un LLM poteva dialogare. Caricavi documenti, creavi un indice e iniziavi a chiedere. Semplice, efficace. Ma la vita non è sempre semplice. I nostri dati non sono sempre in file di testo ben organizzati. Sono sparsi in database SQL, archivi noSQL, API e un mucchio di PDF.

Il primo approccio prevedeva spesso di creare indici separati per ogni fonte di dati. Avevi il tuo indice di documenti, il tuo indice SQL, forse uno strumento API. Poi decidevi manualmente quale interrogare in base all’input dell’utente. Questo funziona per casi semplici, ma che dire di una domanda come “Quali sono le valutazioni medie per i prodotti lanciati nell’ultimo trimestre e ce ne sono alcuni con ticket di supporto aperti?”

Quella domanda richiede:

1. Interrogare un database per le date di lancio dei prodotti e le valutazioni medie.
2. Interrogare un altro sistema (forse un archivio di documenti separato o un’API) per i ticket di supporto aperti relativi a quei prodotti.
3. Sintetizzare entrambi i pezzi di informazione per fornire una risposta coerente.

È qui che LlamaIndex ha davvero elevato il proprio livello, passando da recuperatori isolati a motori di query integrati in grado di comprendere e agire su tali interrogazioni multiformi.

Oltre il Recupero Base: Pianificazione e Instradamento delle Query

La magia avviene con ciò che LlamaIndex chiama “pianificazione delle query” e “instradamento”. Invece di limitarsi a recuperare pezzi di testo, il motore di query, spesso alimentato da un LLM stesso, cerca prima di capire l’intento dell’utente e poi decide la miglior strategia per rispondere. Questo comporta:

• Identificazione delle Sotto-Domande: Scomporre una domanda complessa in domande più piccole e indipendenti.
• Abbinamento delle Sotto-Domande a Strumenti/Indici: Determinare quale fonte di dati specifica (ad esempio, un database SQL, un indice vettoriale di documenti, un endpoint API) è meglio adatta per rispondere a ciascuna sotto-domanda.
• Esecuzione delle Query: Eseguire quelle sotto-query contro gli strumenti scelti.
• Sintesi dei Risultati: Prendere le risposte individuali e combinarle in una risposta unica e approfondita.

Questo non è solo un concetto teorico; è praticamente implementato attraverso strumenti come `QueryPipeline`, `RouterQueryEngine` di LlamaIndex e la capacità di definire `Tools` personalizzati.

Prepararsi alla Sintesi Multi-Sorgente: Un Esempio Pratico

Passiamo a una versione semplificata del problema del mio cliente e-commerce. Immaginate di avere tre fonti di dati:

1. Database dei Prodotti: Un database SQL con ID dei prodotti, nomi, prezzi e date di lancio.
2. Documenti delle Recensioni: Una raccolta di recensioni degli utenti (PDF, file di testo) per ciascun prodotto.
3. API di Inventario: Un’API semplice che restituisce i livelli di stock attuali per un dato ID prodotto.

Il nostro obiettivo è rispondere a una domanda come: “Dimmi di ‘Fancy Widget Pro’ – qual è il suo prezzo, cosa dicono gli utenti al riguardo e è attualmente disponibile in stock?”

Passo 1: Preparare le Vostre Fonti di Dati e Strumenti

Prima di tutto, dobbiamo rendere ogni fonte di dati accessibile a LlamaIndex come uno “strumento”.

A. Strumento Database SQL

Utilizzeremo `SQLTableRetrieverTool` di LlamaIndex per questo. Supponendo che abbiate un semplice database SQLite chiamato `products.db` con una tabella `products`.

from llama_index.core import SQLDatabase
from sqlalchemy import create_engine, text
from llama_index.core.tools import SQLTableRetrieverTool

# Create a dummy database and table for demonstration
engine = create_engine("sqlite:///products.db")
with engine.connect() as connection:
 connection.execute(text("""
 CREATE TABLE IF NOT EXISTS products (
 product_id TEXT PRIMARY KEY,
 name TEXT,
 price REAL,
 launch_date TEXT
 );
 """))
 connection.execute(text("""
 INSERT OR IGNORE INTO products (product_id, name, price, launch_date) VALUES
 ('FWP001', 'Fancy Widget Pro', 129.99, '2025-01-15'),
 ('MGS002', 'Mega Gadget Super', 249.00, '2024-11-01');
 """))
 connection.commit()

sql_database = SQLDatabase(engine=engine)

sql_tool = SQLTableRetrieverTool.from_instances(
 sql_database=sql_database,
 table_names=["products"],
 description=(
 "Utile per recuperare informazioni sui prodotti come nome, prezzo e data di lancio. "
 "L'input dovrebbe essere una query SQL per la tabella 'products'."
 )
)

Commento di Nina: Questo `SQLTableRetrieverTool` è una salvezza. Prima di averlo, scrivevo funzioni personalizzate per interagire con i database, e sembrava di reinventare la ruota ogni volta. Questo strumento rende tutto molto più pulito, anche se devi comunque prestare attenzione all’ingegneria dei prompt per assicurarti che l’LLM generi buone query SQL.

B. Strumento Indice Documenti delle Recensioni

Per le recensioni, creeremo un indice vettoriale da alcuni documenti di recensione fittizi.

import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.tools import QueryEngineTool

# Create a dummy reviews directory and files
os.makedirs("reviews", exist_ok=True)
with open("reviews/FWP001_reviews.txt", "w") as f:
 f.write("Recensioni di Fancy Widget Pro:\n")
 f.write("1. 'Adoro assolutamente il Fancy Widget Pro! Così veloce e affidabile.' - Utente A\n")
 f.write("2. 'Un po' costoso, ma vale la pena per la qualità.' - Utente B\n")
 f.write("3. 'Ha migliorato significativamente il mio flusso di lavoro.' - Utente C\n")

with open("reviews/MGS002_reviews.txt", "w") as f:
 f.write("Recensioni di Mega Gadget Super:\n")
 f.write("1. 'La durata della batteria è incredibile!' - Utente X\n")
 f.write("2. 'Processo di configurazione confuso.' - Utente Y\n")

# Load documents and create an index
documents = SimpleDirectoryReader("reviews").load_data()
review_index = VectorStoreIndex.from_documents(documents)
review_query_engine = review_index.as_query_engine()

review_tool = QueryEngineTool(
 query_engine=review_query_engine,
 metadata={"name": "review_tool", 
 "description": "Utile per rispondere a domande sulle recensioni dei prodotti provenienti da documenti di feedback degli utenti. "
 "L'input dovrebbe essere un nome di prodotto o un ID specifico."}
)

Commento di Nina: Il `QueryEngineTool` è il tuo strumento ideale per incapsulare qualsiasi motore di query esistente di LlamaIndex in uno strumento. È incredibilmente flessibile. Assicurati solo che la tua `description` sia molto chiara in modo che l’LLM sappia quando utilizzarlo.

C. Strumento API di Inventario

Per l’API, simuleremo una semplice funzione Python come una chiamata API usando `FunctionTool`.

from llama_index.core.tools import FunctionTool

# Simulate an inventory API
def get_stock_level(product_id: str) -> str:
 """
 Restituisce il livello di stock attuale per un dato ID prodotto.
 Args:
 product_id (str): L'ID del prodotto.
 Returns:
 str: Una stringa che indica il livello di stock, ad esempio "Disponibile", "Basso Stock", "Esaurito".
 """
 if product_id == "FWP001":
 return "Disponibile"
 elif product_id == "MGS002":
 return "Basso Stock"
 else:
 return "Esaurito"

inventory_tool = FunctionTool.from_defaults(fn=get_stock_level, 
 description=(
 "Utile per controllare il livello di stock attuale di un prodotto. "
 "L'input dovrebbe essere un ID prodotto (ad esempio, 'FWP001')."
 ))

Commento di Nina: `FunctionTool` è pura invenzione. Puoi incapsulare praticamente qualsiasi funzione Python e renderla disponibile al tuo LLM. Questo è il modo per connettersi a API reali, servizi interni o persino eseguire script locali. È un cambiamento significativo per integrare azioni esterne nelle capacità della tua AI.

Passo 2: Costruire il Motore di Query Router

Ora che abbiamo i nostri strumenti individuali, abbiamo bisogno di un modo per consentire a LlamaIndex di scegliere e utilizzarli in modo intelligente. È qui che entra in gioco il `RouterQueryEngine`. Utilizza un LLM per decidere quale strumento (o sequenza di strumenti) utilizzare in base alla query dell’utente.

from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.selectors import LLMSingleSelector
from llama_index.llms.openai import OpenAI # Assuming you have OpenAI API key configured

# Inizializza LLM (es. OpenAI) per il routing e la sintesi
llm = OpenAI(model="gpt-3.5-turbo") # O gpt-4, a seconda delle tue esigenze e del tuo budget

# Combina tutti gli strumenti
all_tools = [sql_tool, review_tool, inventory_tool]

# Crea il RouterQueryEngine
router_query_engine = RouterQueryEngine(
 selector=LLMSingleSelector.from_defaults(llm=llm),
 query_engine_tools=all_tools,
 verbose=True # Imposta su True per vedere le decisioni di routing
)

Parere di Nina: Il `LLMSingleSelector` è il metodo predefinito e spesso sufficiente per indicare al router quale strumento utilizzare. Per scenari più complessi, LlamaIndex offre altri selettori o puoi anche costruirne uno personalizzato. Il `verbose=True` è assolutamente essenziale durante lo sviluppo – ti mostra cosa “pensa” l’LLM quando cerca di instradare la tua query, ed è oro per il debug.

Fase 3: Interrogazione del motore Multi-Source

Facciamo la nostra domanda complessa:

response = router_query_engine.query("Dimmi di 'Fancy Widget Pro' – qual è il suo prezzo, cosa ne dicono gli utenti e è attualmente disponibile in magazzino?")
print(response)

Quando esegui questo, vedrai l’output `verbose` che mostra il processo di pensiero dell’LLM:

• Identificherà che “prezzo” necessita del `sql_tool`.
• “Cosa dicono gli utenti” necessita del `review_tool`.
• “Attualmente disponibile in magazzino” necessita del `inventory_tool`.

L’LLM eseguirà quindi ciascuno di questi strumenti, otterrà le rispettive risposte e infine le sintetizzerà in un’unica risposta coerente. È come avere un mini-direttore d’orchestra per i tuoi dati!

Un output tipico potrebbe assomigliare a questo:

> Selezionando strumento del motore di query: sql_tool
> Selezionando strumento del motore di query: review_tool
> Selezionando strumento del motore di query: inventory_tool

Il Fancy Widget Pro (ID prodotto FWP001) costa $129.99. Gli utenti lo adorano in generale, descrivendolo come "veloce e affidabile" e affermando che "ha migliorato significativamente il loro flusso di lavoro", anche se alcuni menzionano che è "un po' costoso." È attualmente disponibile in magazzino.

Questo è un grande miglioramento rispetto all’interrogazione manuale di ciascuna fonte. L’LLM gestisce l’orchestrazione, rendendo l’interazione molto più naturale e potente.

Scenari Avanzati: Pipeline di Query e Routing Ricorsivo

Il `RouterQueryEngine` è fantastico per scegliere un singolo strumento per rispondere a una sotto-domanda. Ma cosa succede se l’output di uno strumento deve essere fornito come input a un altro? O se hai bisogno di una sequenza specifica di operazioni che non possono essere gestite da una semplice selezione di uno strumento?

È qui che il `QueryPipeline` diventa incredibilmente potente. Ti consente di concatenare insieme più componenti, inclusi strumenti, recuperatori, LLM e persino altri motori di query, in modo simile a un grafo aciclico diretto (DAG).

Immagina uno scenario: “Trova tutti i prodotti lanciati negli ultimi 6 mesi che hanno scorte basse e recensioni positive.”

1. Esegui una query sul database SQL per i prodotti lanciati negli ultimi 6 mesi.
2. Per ciascun ID prodotto dal passo 1, controlla il livello di stock tramite API. Filtra per “Basso Stock”.
3. Per i prodotti rimanenti, esegui una query sui documenti di recensione per il sentiment. Filtra per “recensioni positive.”
4. Sintetizza l’elenco finale.

Questo è un processo multi-step e condizionale. Potresti costruire un `QueryPipeline` per questo, dove l’output di un passo diventa l’input per il successivo, possibilmente con un LLM in mezzo per elaborare i risultati intermedi o decidere il passo successivo.

Anche se non costruiremo un esempio completo di `QueryPipeline` qui (quello è un articolo a sé stante!), comprendi che offre la flessibilità per un’automazione del flusso di lavoro veramente complessa all’interno della tua applicazione LlamaIndex. Puoi persino incorporare un `RouterQueryEngine` all’interno di un `QueryPipeline` per decisioni ricorsive.

Takeaway Azionabili per il Tuo Prossimo Progetto AI

1. Mappa le Tue Fonti di Dati: Prima di scrivere una singola riga di codice, identifica chiaramente tutte le fonti di dati con cui la tua AI deve interagire. Comprendi la loro struttura (strutturata, non strutturata, basata su API).
2. Definisci Strumenti Chiari: Per ogni fonte di dati, crea uno specifico `Tool` di LlamaIndex (es. `SQLTableRetrieverTool`, `QueryEngineTool`, `FunctionTool`). È fondamentale scrivere metadati chiari e descrittivi per ogni strumento. Questa descrizione è ciò che l’LLM utilizza per decidere quando invocarlo. Dedica del tempo a questo; è l’ingegneria dei prompt per i tuoi strumenti!
3. Inizia con `RouterQueryEngine`: Per progetti iniziali multi-sorgente, `RouterQueryEngine` è spesso il punto di ingresso più semplice. Gestisce per te il processo decisionale basato su LLM.
4. Usa `verbose=True` Estensivamente: Seriamente, questo è il tuo migliore amico. Ti offre informazioni sul ragionamento dell’LLM e ti aiuta a perfezionare le descrizioni dei tuoi strumenti quando il router fa scelte impreviste.
5. Considera `QueryPipeline` per i Workflow: Se le tue domande coinvolgono passaggi sequenziali, logica condizionale o dove l’output di uno strumento alimenta direttamente un altro, inizia a pensare a `QueryPipeline`. È più complesso da impostare, ma offre un controllo senza pari sulle interazioni multi-step.
6. Itera sulle Descrizioni degli Strumenti: La capacità dell’LLM di scegliere lo strumento giusto dipende fortemente da quanto bene hai descritto lo scopo e l’input/output attesi di ogni strumento. Non avere paura di sperimentare con diverse formulazioni.

La capacità di LlamaIndex di orchestrare intelligentemente queries attraverso diverse fonti di dati rappresenta un grande passo avanti per la creazione di agenti davvero intelligenti. Ci allontana dalla logica rigida e codificata e ci avvicina a sistemi in grado di ragionare sulle necessità informative e recuperare dinamicamente i dati dai posti più appropriati. L’assistente e-commerce del mio cliente è ora molto più intelligente, in grado di estrarre i prezzi dal database, il sentiment degli utenti dalle recensioni e i livelli di stock dall’API, il tutto da un’unica query in linguaggio naturale. È davvero qualcosa di straordinario!

Questo è tutto per oggi, gente! Andate e costruite agenti AI incredibilmente intelligenti e multi-sorgente. Fatemi sapere cosa state costruendo nei commenti!

Articoli Correlati

• **TITOLO: Gli strumenti CLI che sto adorando e perché dovresti farlo anche tu**
• Come Integrare Gli SDK AI
• Migliori Pratiche per lo Sviluppo di Agenti AI

🕒 Published: April 4, 2026