Il mio motore di query LlamaIndex gestisce dati complessi.

Ciao famiglia tech! Nina Torres di nuovo su agntbox.com. Oggi esploreremo qualcosa che sta facendo discutere la comunità AI, soprattutto per coloro di noi che stanno cercando di creare esperienze AI più personalizzate e consapevoli del contesto. Sto parlando di LlamaIndex, e più precisamente di come il suo motore di query si sia evoluto per gestire interazioni di dati sempre più complesse. Dimenticate l’idea di lanciare semplicemente un PDF e sperare nel meglio; vedremo come farlo davvero pensare attraverso diverse fonti di dati.

La mia casella di posta, come quella di molti di voi, è stata inondata di domande su come andare oltre le configurazioni RAG di base (Retrieval-Augmented Generation). La gente sta costruendo applicazioni incredibili, ma si scontra con un muro quando la loro AI deve rispondere a domande che richiedono di sintetizzare informazioni provenienti da un database, da un insieme di documenti, e da un’API live. Non si tratta più di un semplice problema di “trovare quel testo”. È un problema di “scoprire cosa chiedere dove, e poi combinare le risposte”. E onestamente, è un problema con cui sto lottando per un progetto personale per un cliente che gestisce un sito di e-commerce di nicchia – immaginate un’assistente AI che deve controllare l’inventario dei prodotti (database), consultare le recensioni degli utenti (documenti) e suggerire articoli correlati in base ai prezzi in tempo reale (API). La mia configurazione iniziale di LlamaIndex, sebbene adeguata per la parte recensioni, è completamente fallita nella sintesi multi-sorgente.

Oggi, quindi, 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 orchestri in modo intelligente il recupero di informazioni attraverso queste diverse fonti per rispondere a domande complesse e multifattoriali. Stiamo parlando di passare da un semplice recuperatore a un sistema sofisticato di instradamento e pianificazione.

L’Evoluzione di “Porre una Domanda” in LlamaIndex

Ricordate la prima apparizione di LlamaIndex? Era fantastico per trasformare dati non strutturati in qualcosa con cui un LLM potesse discutere. Caricavi documenti, costruivi un indice e ponevi domande. Semplice ed efficace. Ma la vita non è sempre semplice. I nostri dati non sono sempre in file di testo ben ordinati. Sono sparsi attraverso database SQL, negozi noSQL, API e una moltitudine di PDF.

L’approccio iniziale consisteva spesso nel 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 agli input dell’utente. Questo funziona per casi semplici, ma cosa dire di una domanda come: “Quali sono le valutazioni medie dei prodotti lanciati nell’ultimo trimestre, e ce ne sono che hanno ticket di supporto aperti?”

Questa domanda richiede:

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

È qui che LlamaIndex ha davvero migliorato la sua offerta, passando da recuperatori isolati a motori di query integrati capaci di comprendere e agire su tali richieste multifattoriali.

Oltre al Recupero di Base: Pianificazione e Instradamento di 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 comprendere l’intento dell’utente, quindi determina la migliore strategia per rispondere. Questo comporta:

• Identificare le Sotto-Domande: Scomporre una domanda complessa in domande più piccole e indipendenti.
• Abbinare le Sotto-Domande agli Strumenti/Indici: Determinare quale fonte di dati specifica (ad esempio, un database SQL, un indice di documenti vettoriali, un endpoint API) è la più adatta a rispondere a ciascuna sotto-domanda.
• Eseguire le Query: Eseguire queste sotto-query sugli strumenti scelti.
• Sintetizzare i Risultati: Prendere le risposte individuali e combinarle in una risposta unica e completa.

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

Configurazione per la Sintesi Multi-Sorgente: Un Esempio Pratico

Passiamo in rassegna 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 identificatori di prodotti, nomi, prezzi e date di lancio.
2. Documenti di Recensioni: Una raccolta di recensioni degli utenti (PDF, file di testo) per ogni prodotto.
3. API di Inventario: Una semplice API che restituisce i livelli di stock attuali per un identificatore di prodotto dato.

Il nostro obiettivo è rispondere a una domanda come: “Parlami di ‘Fancy Widget Pro’ – qual è il suo prezzo, cosa dicono gli utenti al riguardo, e è attualmente 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 “strumento”.

A. Strumento di Database SQL

Utilizzeremo il `SQLTableRetrieverTool` di LlamaIndex per questo. Supponiamo di avere 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

# Creare un database e una tabella fittizi per la dimostrazione
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 interrogare informazioni sui prodotti come nome, prezzo e data di lancio. "
 "L'input deve essere una query SQL per la tabella 'products'."
 )
)

Le Recensioni di Nina: Questo `SQLTableRetrieverTool` è un salvatore. Prima di lui, scrivevo funzioni personalizzate per interagire con i database, e avevo l’impressione di reinventare la ruota ogni volta. Questo strumento rende le cose molto più semplici, anche se devi comunque prestare attenzione all’ingegneria delle richieste per assicurarti che il LLM generi buone query SQL.

B. Strumento di Indice di Documenti di Recensioni

Per le recensioni, creeremo un indice vettoriale a partire da alcuni documenti di recensioni fittizie.

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

# Creare una directory e dei file di recensioni fittizie
os.makedirs("reviews", exist_ok=True)
with open("reviews/FWP001_reviews.txt", "w") as f:
 f.write("Recensioni su 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 ne vale la pena per la qualità.' - Utente B\n")
 f.write("3. 'Migliora notevolmente il mio flusso di lavoro.' - Utente C\n")

with open("reviews/MGS002_reviews.txt", "w") as f:
 f.write("Recensioni su 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")

# Caricare i documenti e creare un indice
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 a partire dai documenti di feedback degli utenti. "
 "L'input deve essere un nome o un identificativo di prodotto specifico."}
)

Le Recensioni di Nina : Il `QueryEngineTool` è il tuo strumento di scelta per avvolgere qualsiasi motore di query di LlamaIndex esistente in un tool. È incredibilmente flessibile. Assicurati solo che la tua `description` sia molto chiara affinché il LLM sappia quando usarlo.

C. Strumento API Inventario

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

from llama_index.core.tools import FunctionTool

# Simulare un'API di inventario
def get_stock_level(product_id: str) -> str:
 """
 Restituisce il livello di stock attuale per un identificativo di prodotto dato.
 Args:
 product_id (str) : L'identificativo del prodotto.
 Returns:
 str : Una stringa che indica il livello di stock, ad esempio, "Disponibile", "Stock Basso", "Esaurito".
 """
 if product_id == "FWP001":
 return "Disponibile"
 elif product_id == "MGS002":
 return "Stock Basso"
 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 deve essere un identificativo di prodotto (ad esempio, 'FWP001')."
 ))

Le Recensioni di Nina : `FunctionTool` è un genio puro. Puoi incapsulare quasi qualsiasi funzione Python ed esporla al tuo LLM. È così che ti colleghi a vere API, servizi interni, o addirittura esegui script locali. È un cambiamento significativo per integrare azioni esterne nelle capacità della tua AI.

Passo 2 : Costruire il Router del Motore di Query

Ora che abbiamo i nostri strumenti singoli, abbiamo bisogno di un metodo affinché LlamaIndex li scelga e li utilizzi in modo intelligente. È qui che il `RouterQueryEngine` entra in gioco. Usa 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 # Presumendo che tu abbia configurato una chiave API OpenAI

# Inizializzare LLM (ad esempio, OpenAI) per il routing e la sintesi
llm = OpenAI(model="gpt-3.5-turbo") # O gpt-4, a seconda delle tue esigenze e budget

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

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

Punto di vista di Nina : Il `LLMSingleSelector` è il metodo predefinito, spesso sufficiente, per indicare al router quale strumento utilizzare. Per scenari più complessi, LlamaIndex offre altri selettori o puoi anche crearne uno su misura. Il `verbose=True` è assolutamente essenziale durante lo sviluppo – ti mostra cosa il LLM sta “pensando” mentre cerca di instradare la tua richiesta, il che è prezioso per il debugging.

Passo 3 : Interrogare il motore multi-sorgente

Poniamo la nostra domanda complessa :

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

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

• Identificherà che “prezzo” richiede il `sql_tool`.
• “Cosa dicono gli utenti” richiede il `review_tool`.
• “Attualmente disponibile in stock” richiede il `inventory_tool`.

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

Un’uscita tipica potrebbe apparire così :

> Selezione dello strumento del motore di query : sql_tool
> Selezione dello strumento del motore di query : review_tool
> Selezione dello strumento del motore di query : inventory_tool

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

È un miglioramento significativo rispetto all’interrogazione manuale di ciascuna fonte. Il 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 uno strumento unico per rispondere a una sotto-domanda. Ma cosa succede se l’output di uno strumento deve essere utilizzato come input per un altro? O se hai bisogno di una sequenza specifica di operazioni che non può essere gestita da una semplice selezione di strumento unico?

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

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

1. Interrogare il database SQL per i prodotti lanciati negli ultimi 6 mesi.
2. Per ciascun ID di prodotto del passo 1, verificare il livello di stock tramite l’API. Filtrare per “Stock Basso”.
3. Per i prodotti rimanenti, interrogare i documenti di valutazione per il sentiment. Filtrare per “recensioni positive”.
4. Sintetizzare la lista finale.

È un processo condizionale in più fasi. Potresti creare un `QueryPipeline` per questo, dove l’output di un passo diventa l’input del successivo, eventualmente con un LLM tra i due per elaborare i risultati intermedi o decidere il passo successivo.

Anche se non stiamo costruendo un esempio completo di `QueryPipeline` qui (è un argomento a parte!), sappi che offre la flessibilità per una vera automazione di flussi di lavoro complessi all’interno della tua applicazione LlamaIndex. Puoi persino integrare un `RouterQueryEngine` all’interno di un `QueryPipeline` per una decisione ricorsiva.

Punti da tenere a mente per il tuo prossimo progetto AI

1. Mappate le vostre fonti di dati: Prima di scrivere una sola riga di codice, identificate chiaramente tutte le fonti di dati con cui la vostra IA deve interagire. Comprendete la loro struttura (strutturata, non strutturata, pilotata da API).
2. Definite strumenti chiari: Per ogni fonte di dati, create un LlamaIndex `Tool` specifico (ad esempio, `SQLTableRetrieverTool`, `QueryEngineTool`, `FunctionTool`). Scrivete `metadata` chiari e descrittivi per ogni strumento. Questa descrizione è ciò che il LLM utilizza per decidere quando invocarlo. Prendetevi il tempo per farlo; è l’ingegneria degli inviti per i vostri strumenti!
3. Iniziate con il `RouterQueryEngine`: Per i progetti iniziali a più fonti, il `RouterQueryEngine` è spesso il punto d’ingresso più semplice. Gestisce la presa di decisione basata sul LLM per voi.
4. Usate `verbose=True` ampiamente: Davvero, è il vostro migliore amico. Questo vi dà un’idea del ragionamento del LLM e vi aiuta a perfezionare le vostre descrizioni degli strumenti quando il router prende decisioni inaspettate.
5. Considerate `QueryPipeline` per i flussi di lavoro: Se le vostre domande comportano passaggi sequenziali, logica condizionale, o dove l’uscita di uno strumento alimenta direttamente un altro, iniziate a pensare a `QueryPipeline`. È più complesso da impostare, ma offre un controllo senza precedenti sulle interazioni multistep.
6. Iterate sulle descrizioni degli strumenti: La capacità del LLM di scegliere lo strumento giusto dipende enormemente da come avete descritto lo scopo di ogni strumento e le sue entrate/uscite attese. Non abbiate paura di sperimentare con diverse formulazioni.

La capacità di LlamaIndex di orchestrare inteligentemente query attraverso diverse fonti di dati rappresenta un grande passo avanti per la creazione di agenti veramente intelligenti. Ci allontana da una logica rigida e codificata per avvicinarci a sistemi capaci di ragionare sui bisogni informativi e di recuperare dati dinamicamente dai luoghi più appropriati. L’assistente e-commerce del mio cliente è ora molto più intelligente, capace di estrarre i prezzi dal database, il sentimento degli utenti dalle recensioni e i livelli di stock tramite l’API, il tutto da una singola richiesta in linguaggio naturale. È davvero qualcosa da vedere!

È tutto per oggi, amici! Andate avanti e costruite agenti IA incredibilmente intelligenti e multi-sorgente. Fatemi sapere cosa state costruendo nei commenti!

Articoli correlati

• **TITOLO: Gli strumenti CLI che adoro e perché dovreste amarli anche voi**
• Come integrare i SDK di IA
• Migliori pratiche nello sviluppo di agenti IA

🕒 Published: April 4, 2026