Olá, família tech! Nina Torres de volta no agntbox.com. Hoje, vamos explorar algo que está fazendo ondas na comunidade de IA, especialmente para aqueles de nós que estão tentando criar experiências de IA mais personalizadas e conscientes do contexto. Estou falando do LlamaIndex, e mais especificamente, sobre como seu motor de consultas evoluiu para lidar com interações de dados cada vez mais complexas. Esqueça a ideia de simplesmente lançar um PDF e esperar o melhor; vamos ver como fazê-lo realmente refletir através de várias fontes de dados diferentes.
Minha caixa de entrada, como a de muitos de vocês, foi inundada de perguntas sobre como ir além das configurações básicas de RAG (Retrieval-Augmented Generation). As pessoas estão construindo aplicações incríveis, mas esbarram em um muro quando sua IA precisa responder a perguntas que requerem a síntese de informações provenientes de um banco de dados, de um conjunto de documentos, e de uma API ao vivo. Não é mais um simples problema de “encontrar esse texto”. É um problema de “descobrir o que perguntar aonde, e depois combinar as respostas”. E, honestamente, é um problema com o qual estou lidando em um projeto pessoal para um cliente que gerencia um site de e-commerce de nicho – imagine um assistente de IA que precisa verificar o inventário de produtos (banco de dados), consultar as avaliações dos usuários (documentos) e sugerir itens relacionados com base nos preços em tempo real (API). Minha configuração inicial do LlamaIndex, embora adequada para a parte de avaliações, falhou completamente na síntese multi-fontes.
Hoje, vamos explorar as capacidades avançadas do motor de consultas do LlamaIndex para a síntese de dados multi-fontes. Não se trata apenas de indexar diferentes tipos de dados; trata-se de construir um motor de consultas que orquestra inteligentemente a recuperação de informações através dessas diversas fontes para responder a perguntas complexas e multifatoriais. Estamos falando de passar de um simples recuperador para um sistema sofisticado de roteamento e planejamento.
A Evolução de “Fazer uma Pergunta” no LlamaIndex
Lembra da primeira aparição do LlamaIndex? Era incrível para transformar dados não estruturados em algo com o qual um LLM poderia conversar. Você carregava documentos, construía um índice e fazia perguntas. Simples e eficaz. Mas a vida nem sempre é simples. Nossos dados nem sempre estão em arquivos de texto bem organizados. Eles estão espalhados por bancos de dados SQL, lojas noSQL, APIs e uma infinidade de PDFs.
A abordagem inicial muitas vezes consistia em criar índices separados para cada fonte de dados. Você tinha seu índice de documentos, seu índice SQL, talvez uma ferramenta API. Então, você decidia manualmente qual interrogar com base nas entradas do usuário. Isso funciona para casos simples, mas e quanto a uma pergunta como: “Quais são as avaliações médias dos produtos lançados no último trimestre, e há algum com tickets de suporte abertos?”
Essa pergunta requer:
- Interrogar um banco de dados para as datas de lançamento de produtos e as avaliações médias.
- Interrogar outro sistema (talvez uma loja de documentos separada ou uma API) para os tickets de suporte abertos relacionados a esses produtos.
- Sintetizar os dois pedaços de informação para fornecer uma resposta coerente.
É aí que o LlamaIndex realmente melhorou sua oferta, passando de recuperadores isolados para motores de consultas integrados capazes de entender e agir em tais consultas multifatoriais.
Além da Recuperação Básica: Planejamento e Roteamento de Consultas
A mágica acontece com o que o LlamaIndex chama de “planejamento de consultas” e “roteamento”. Em vez de se limitar a recuperar pedaços de texto, o motor de consultas, frequentemente alimentado por um LLM, tenta primeiro entender a intenção do usuário e depois determina a melhor estratégia para respondê-la. Isso envolve:
- Identificar as Subperguntas: Decompor uma pergunta complexa em perguntas menores e independentes.
- Relacionar as Subperguntas às Ferramentas/Índices: Determinar qual fonte de dados específica (por exemplo, um banco de dados SQL, um índice de documentos vetoriais, um endpoint de API) é mais adequada para responder a cada subpergunta.
- Executar as Consultas: Lançar essas subconsultas contra as ferramentas escolhidas.
- Sintetizar os Resultados: Tomar as respostas individuais e combiná-las em uma resposta única e completa.
Não é apenas um conceito teórico; isso é praticamente implementado através de elementos como o `QueryPipeline` do LlamaIndex, o `RouterQueryEngine`, e a capacidade de definir `Tools` personalizadas.
Configuração para a Síntese Multi-Fontes: Um Exemplo Prático
Vamos rever uma versão simplificada do problema do meu cliente de e-commerce. Imagine que temos três fontes de dados:
- Banco de Dados de Produtos: Um banco de dados SQL com identificadores de produtos, nomes, preços e datas de lançamento.
- Documentos de Avaliações: Uma coleção de avaliações de usuários (PDFs, arquivos de texto) para cada produto.
- API de Inventário: Uma simples API que retorna os níveis de estoque atuais para um identificador de produto dado.
Nosso objetivo é responder a uma pergunta como: “Fale-me sobre o ‘Fancy Widget Pro’ – qual é seu preço, o que os usuários dizem sobre ele, e está atualmente em estoque?”
Etapa 1: Preparar Suas Fontes de Dados e Ferramentas
Primeiro, precisamos tornar cada fonte de dados acessível ao LlamaIndex como um “ferramenta”.
A. Ferramenta de Banco de Dados SQL
Vamos usar o `SQLTableRetrieverTool` do LlamaIndex para isso. Suponha que você tenha um banco de dados SQLite simples chamado `products.db` com uma tabela `products`.
from llama_index.core import SQLDatabase
from sqlalchemy import create_engine, text
from llama_index.core.tools import SQLTableRetrieverTool
# Criar um banco de dados e uma tabela fictícias para a demonstração
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=(
"Útil para interrogar informações sobre os produtos, como nome, preço e data de lançamento. "
"A entrada deve ser uma consulta SQL para a tabela 'products'."
)
)
A Opinião de Nina: Este `SQLTableRetrieverTool` é um salvador. Antes dele, eu escrevia funções personalizadas para interagir com os bancos de dados, e tinha a sensação de estar reinventando a roda a cada vez. Esta ferramenta torna as coisas muito mais simples, mesmo que você ainda precise tomar cuidado com a engenharia das solicitações para garantir que o LLM gere boas consultas SQL.
B. Ferramenta de Índice de Documentos de Avaliações
Para as avaliações, vamos criar um índice vetorial a partir de alguns documentos de avaliações fictícios.
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.tools import QueryEngineTool
# Criar um diretório e arquivos de avaliações fictícias
os.makedirs("reviews", exist_ok=True)
with open("reviews/FWP001_reviews.txt", "w") as f:
f.write("Avaliações sobre o Fancy Widget Pro:\n")
f.write("1. 'Eu absolutamente adoro o Fancy Widget Pro! Muito rápido e confiável.' - Usuário A\n")
f.write("2. 'Um pouco caro, mas vale a pena pela qualidade.' - Usuário B\n")
f.write("3. 'Melhora consideravelmente meu fluxo de trabalho.' - Usuário C\n")
with open("reviews/MGS002_reviews.txt", "w") as f:
f.write("Avaliações sobre o Mega Gadget Super:\n")
f.write("1. 'A duração da bateria é incrível!' - Usuário X\n")
f.write("2. 'Processo de configuração confuso.' - Usuário Y\n")
# Carregar os documentos e criar um índice
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": "Útil para responder perguntas sobre avaliações de produtos a partir dos documentos de feedback dos usuários. "
"A entrada deve ser um nome ou um identificador de produto específico."}
)
Avaliações de Nina: O `QueryEngineTool` é sua ferramenta de escolha para embalar qualquer motor de consulta existente do LlamaIndex em uma ferramenta. É incrivelmente flexível. Apenas certifique-se de que sua `description` esteja super clara para que o LLM saiba quando utilizá-la.
C. Ferramenta de API de Inventário
Para a API, vamos simular uma função Python simples como chamada API usando `FunctionTool`.
from llama_index.core.tools import FunctionTool
# Simular uma API de inventário
def get_stock_level(product_id: str) -> str:
"""
Retorna o nível de estoque atual para um identificador de produto dado.
Args:
product_id (str) : O identificador do produto.
Returns:
str : Uma string indicando o nível de estoque, por exemplo, "Em Estoque", "Estoque Baixo", "Fora de Estoque".
"""
if product_id == "FWP001":
return "Em Estoque"
elif product_id == "MGS002":
return "Estoque Baixo"
else:
return "Fora de Estoque"
inventory_tool = FunctionTool.from_defaults(fn=get_stock_level,
description=(
"Útil para verificar o nível de estoque atual de um produto. "
"A entrada deve ser um identificador de produto (por exemplo, 'FWP001')."
))
Avaliações de Nina: `FunctionTool` é uma pura genialidade. Você pode embalar quase qualquer função Python e expô-la ao seu LLM. É assim que você se conecta a APIs reais, serviços internos ou até mesmo executa scripts locais. É uma mudança significativa para integrar ações externas nas capacidades da sua IA.
Etapa 2: Construir o Motor de Consultas Router
Agora que temos nossas ferramentas individuais, precisamos de um método para que o LlamaIndex as escolha e use de maneira inteligente. É aí que o `RouterQueryEngine` entra em cena. Ele usa um LLM para decidir qual ferramenta (ou sequência de ferramentas) usar com base na consulta do usuário.
from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.selectors import LLMSingleSelector
from llama_index.llms.openai import OpenAI # Supondo que você tenha configurado uma chave API OpenAI
# Inicializar LLM (por exemplo, OpenAI) para roteamento e síntese
llm = OpenAI(model="gpt-3.5-turbo") # Ou gpt-4, conforme suas necessidades e orçamento
# Combinar todas as ferramentas
all_tools = [sql_tool, review_tool, inventory_tool]
# Criar o RouterQueryEngine
router_query_engine = RouterQueryEngine(
selector=LLMSingleSelector.from_defaults(llm=llm),
query_engine_tools=all_tools,
verbose=True # Definido como True para ver as decisões de roteamento
)
Ponto de vista de Nina: O `LLMSingleSelector` é o método padrão, muitas vezes suficiente, para indicar ao roteador qual ferramenta usar. Para cenários mais complexos, o LlamaIndex oferece outros seletores ou você pode até criar um sob medida. O `verbose=True` é absolutamente essencial durante o desenvolvimento – ele mostra o que o LLM está “pensando” ao tentar rotear sua consulta, o que é valioso para depuração.
Etapa 3: Consultar o motor multi-fontes
Vamos fazer nossa pergunta complexa:
response = router_query_engine.query("Fale-me sobre 'Fancy Widget Pro' - qual é o preço, o que os usuários dizem sobre ele e está atualmente em estoque?")
print(response)
Quando você executar isso, verá a saída `verbose` mostrando o processo de pensamento do LLM:
- Ele identificará que “preço” requer o `sql_tool`.
- “O que os usuários dizem” requer o `review_tool`.
- “Atualmente em estoque” requer o `inventory_tool`.
O LLM então executará cada uma dessas ferramentas, obterá suas respostas respectivas e, finalmente, as sintetizará em uma única resposta coerente. É como ter um pequeno maestro para seus dados!
Uma saída típica poderia se parecer com isto:
> Selecionando a ferramenta do motor de consulta: sql_tool
> Selecionando a ferramenta do motor de consulta: review_tool
> Selecionando a ferramenta do motor de consulta: inventory_tool
O Fancy Widget Pro (ID do produto FWP001) custa 129,99 $. Os usuários geralmente adoram, descrevendo-o como "rápido e confiável" e afirmando que "melhorou consideravelmente seus fluxos de trabalho", embora alguns mencionem que é "um pouco caro". Atualmente está em estoque.
Isso é uma melhoria considerável em relação à consulta manual de cada fonte. O LLM cuida da orquestração, tornando a interação muito mais natural e poderosa.
Cenários avançados: Pipelines de consulta e roteamento recursivo
O `RouterQueryEngine` é fantástico para escolher uma única ferramenta para responder a uma subpergunta. Mas o que acontece se a saída de uma ferramenta precisar ser usada como entrada para outra? Ou se você precisar de uma sequência específica de operações que não pode ser gerenciada por uma única seleção de ferramenta?
É aí que o `QueryPipeline` se torna incrivelmente poderoso. Ele permite que você conecte vários componentes, incluindo ferramentas, recuperadores, LLM e até mesmo outros motores de consulta, de forma a formar um grafo acíclico dirigido (DAG).
Imagine um cenário: “Encontre todos os produtos lançados nos últimos 6 meses que têm estoque baixo e críticas positivas.”
- Consultar o banco de dados SQL para produtos lançados nos últimos 6 meses.
- Para cada ID de produto da etapa 1, verificar o nível de estoque via API. Filtrar para “Estoque Baixo”.
- Para os produtos restantes, consultar os documentos de avaliação para o sentimento. Filtrar para “críticas positivas”.
- Sintetizar a lista final.
É um processo condicional em várias etapas. Você poderia criar um `QueryPipeline` para isso, onde a saída de uma etapa se torna a entrada da próxima, eventualmente com um LLM entre as duas para processar os resultados intermediários ou decidir a próxima etapa.
Embora não estejamos construindo um exemplo completo de `QueryPipeline` aqui (isso é um artigo à parte!), saiba que ele oferece a flexibilidade para uma verdadeira automação de fluxos de trabalho complexos dentro da sua aplicação LlamaIndex. Você pode até integrar um `RouterQueryEngine` dentro de um `QueryPipeline` para tomada de decisão recursiva.
Pontos a serem lembrados para seu próximo projeto de IA
- Cartografe suas fontes de dados: Antes de escrever uma única linha de código, identifique claramente todas as fontes de dados com as quais sua IA deve interagir. Compreenda sua estrutura (estruturada, não estruturada, dirigida por API).
- Defina ferramentas claras: Para cada fonte de dados, crie um LlamaIndex `Tool` específico (por exemplo, `SQLTableRetrieverTool`, `QueryEngineTool`, `FunctionTool`). Escreva `metadata` claras e descritivas para cada ferramenta. Essa descrição é o que o LLM usa para decidir quando invocá-la. Reserve um tempo para fazer isso; é a engenharia das convites para suas ferramentas!
- Comece com o `RouterQueryEngine`: Para projetos iniciais de múltiplas fontes, o `RouterQueryEngine` é frequentemente o ponto de entrada mais simples. Ele gerencia a tomada de decisão baseada no LLM para você.
- Use `verbose=True` de forma ampla: Sério, esse é seu melhor amigo. Isso lhe dá uma visão do raciocínio do LLM e ajuda a refinar suas descrições de ferramentas quando o roteador toma decisões inesperadas.
- Considere `QueryPipeline` para fluxos de trabalho: Se suas perguntas envolvem etapas sequenciais, lógica condicional, ou onde a saída de uma ferramenta alimenta diretamente outra, comece a pensar em `QueryPipeline`. É mais complexo de configurar, mas oferece um controle sem precedentes sobre as interações em várias etapas.
- Itere sobre as descrições das ferramentas: A capacidade do LLM de escolher a ferramenta certa depende enormemente de como você descreveu o propósito de cada ferramenta e suas entradas/saídas esperadas. Não tenha medo de experimentar com diferentes formulações.
A capacidade do LlamaIndex de orquestrar inteligentemente consultas através de diferentes fontes de dados representa um grande avanço para a criação de agentes verdadeiramente inteligentes. Isso nos afasta de uma lógica rígida e codificada em aulas e nos aproxima de sistemas capazes de raciocinar sobre as necessidades de informação e recuperar dados dinamicamente dos lugares mais apropriados. O assistente de e-commerce do meu cliente agora é muito mais inteligente, capaz de extrair preços do banco de dados, o sentimento dos usuários a partir das avaliações e os níveis de estoque via API, tudo a partir de uma única consulta em linguagem natural. É realmente algo impressionante!
Isso é tudo por hoje, pessoal! Vá em frente e construa agentes de IA incrivelmente inteligentes e multi-fontes. Deixe-me saber o que você está construindo nos comentários!
Artigos relacionados
- **TÍTULO: As ferramentas CLI que eu adoro e por que você também deveria amá-las**
- Como integrar os SDKs de IA
- Melhores práticas em desenvolvimento de agentes IA
🕒 Published: