[Projeto] Minha Jornada: Análise de Dados com LlamaIndex + Groq + Pandas [`QueryPipeline`]

Oi, pessoal!

Quero compartilhar um pouco da experiência que tive ao estudar e experimentar e combinar o LlamaIndex + Groq + Pandas. Foi uma jornada de tentativa e erro, mas cheguei a um workflow funcional que gera código Pandas a partir de consultas em linguagem natural, além de explicar os resultados. Ao final segue o link do notebook.

#O Primeiro Obstáculo: ModuleNotFoundError:

ModuleNotFoundError: No module named 'llama_index.core.query_engine.query_pipeline

Inicialmente tentei instalar versões antigas do llama-index para acompanhar a aula.

from llama_index.core.query_pipeline import QueryPipeline

recebi:

ModuleNotFoundError: No module named 'llama_index.core.query_pipeline'

Conferindo o Forum descobri que o QueryPipeline foi descontinuado nas versões recentes do LlamaIndex. Segui o site oficial recomendado pela Nathalia Queiroz informando: O LlamaIndex descontinuou o módulo QueryPipeline em favor de uma nova abordagem chamada Workflows. Essa mudança foi implementada na versão 0.11 do LlamaIndex, com o objetivo de oferecer uma arquitetura mais flexível e escalável, visando casos de uso mais complexos e dinâmicos .:
Documentação oficial de Workflow

Mudança para Workflow

A documentação mostrou a possibilidade de usar o Workflow de forma assíncrona. Tenho familiaridade com o Prefect então resolvi me desafiar:

from llama_index.core.workflow import Workflow, Event, StartEvent, StopEvent, step
from llama_index.llms.openai import OpenAI

Contudo, ao rodar no Colab, o uso do await causava problemas de looping ou retorno vazio, um comportamento que já tinha observado antes. O workflow ficava repetindo o mesmo passo sem avançar.
Por exemplo, o workflow ficava repetindo:

Running step execute_code
Step execute_code produced event Event

--

Refatorando com Pydantic + segurança + limpeza

Para resolver, decidi refatorar e construir o workflow do zero:

• Pydantic_v2 para validar configuração, eventos e retorno.
• Função de limpeza de código para evitar loops e execução inválida.
• Controle de erros Adicionei controle de exceções na execução do eval() para lidar com falhas
• LLM Groq via Settings, integrando com PandasQueryEngine.

Exemplo do workflow refatorado:

class PandasWorkflow(Workflow):
    llm = Settings.llm
    workflow_steps = ["start_query", "generate_code", "execute_code", "synthesize_response"]

    @step
    async def start_query(self, ev: StartEvent) -> CodeEvent:
        ...

    @step
    async def generate_code(self, ev: CodeEvent) -> OutputEvent:
        ...

    @step
    async def execute_code(self, ev: OutputEvent) -> ExecutedEvent:
        ...

    @step
    async def synthesize_response(self, ev: ExecutedEvent) -> ResponseEvent:
        ...

O workflow garante que:

• Apenas uma linha de código Pandas válido seja gerada.
• Erros de execução sejam tratados e reportados.
• O LLM gera uma explicação clara sobre os resultados.

Resultado final

Rodando a consulta:

query = "Qual é a média gasta por cada tipo de cliente?"
result = await executar_consulta(query)

Obtive:

Query: Qual é a média gasta por cada tipo de cliente?
Código: df.groupby('tipo_cliente')['gasto'].mean()
Resultado: tipo_cliente
Cliente A    230.5
Cliente B    340.7
...

E a explicação gerada pelo LLM foi clara, concisa e interpretativa, focando nos insights dos dados, sem repetir valores brutos ou código.

Aprendizados

• Sempre verifique a documentação oficial: alguns módulos podem ser descontinuados.
• Use Pydantic para validar dados e eventos em workflows complexos, é um verdadeiro gamechanger.
• Ao usar LLMs para gerar código, é essencial ter validação e limpeza de strings antes de executar eval(). Assim como declarar com clareza as instruções, é uma forma de orientar o modelo(Programar).
• No Colab/Jupyter, workflows assíncronos devem ser rodados com await, evitando asyncio.run() que quebra a célula.

Espero que minha experiência ajude outros a evitarem os mesmos erros. O projeto completo com todo o código e mais exemplos de testes está no meu GitHub. Ainda estou alterando conforme reviso e continuo as aulas e pretendo postar como projeto final

Link para o meu Notebook no GitHub

Boa sorte a todos!