LlamaIndex: Context-Augmented LLM Applications

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Context-Augmented, episódio 1 de 14. Os modelos pré-treinados são brilhantes, mas não sabem absolutamente nada sobre os documentos privados que criaste esta manhã. Pedes a um LLM para resumir o teu novo slide deck financeiro do Q3, e ele ou adivinha às cegas ou diz-te que não pode ajudar. O Context-Augmentation Imperative é como resolves isto. Os Large Language Models possuem capacidades de raciocínio incríveis, mas o seu conhecimento está congelado no tempo e limitado a dados públicos. Eles não têm acesso às tuas wikis internas, aos teus tickets de suporte ao cliente ou aos teus relatórios financeiros privados. O LlamaIndex existe para preencher exatamente esta lacuna. Serve como o tecido conectivo entre os foundational models e os teus dados privados e localizados. Quando pedes a um modelo para resumir aquele slide deck do Q3, não podes simplesmente enviar a pergunta. Precisas de um sistema que encontre os slides relevantes, extraia o texto e forneça essa informação específica ao modelo juntamente com o teu prompt. Este processo é o context augmentation. Estás a dar ao modelo o contexto exato de que ele precisa para aplicar as suas capacidades de raciocínio aos teus dados privados. O LlamaIndex fornece a infraestrutura para fazer o ingest, organizar e recuperar os teus dados para que o context augmentation aconteça de forma fiável. Ir buscar texto e responder a uma única pergunta é apenas a baseline. As aplicações modernas exigem mais autonomia. Isto leva-nos às agentic applications. Uma agentic application não segue simplesmente uma linha reta de uma pergunta para uma base de dados e depois para uma resposta. Toma decisões ao longo do caminho para lidar com intenções complexas do utilizador. A primeira parte disto é o routing. Quando um utilizador faz uma pergunta, o sistema precisa de decidir qual a data source ou tool apropriada. Se o utilizador pedir um resumo corporativo high-level, o router direciona a query para o index do slide deck do Q3. Se o utilizador pedir a discriminação numérica exata das vendas regionais, o router pode antes enviar a query para uma base de dados SQL estruturada. O routing garante que o modelo usa a tool certa para o trabalho com base no input. A segunda parte é o prompt chaining. Tarefas complexas falham frequentemente quando pedes a um modelo para lidar com elas num único prompt massivo. O prompt chaining divide um objetivo complexo em tarefas menores e sequenciais. O sistema pode correr um prompt para extrair os valores de receita do slide deck, passar esses valores para um segundo prompt que os compara com dados históricos, e enviar esse output para um terceiro prompt que redige um resumo executivo. O output de uma etapa torna-se o contexto exato para a etapa seguinte. É aqui que a coisa fica interessante. Mesmo com os dados certos e uma chain estruturada, os modelos cometem erros. Isto introduz a reflection. A reflection é um passo automatizado de controlo de qualidade. Antes de entregar o resumo final do deck do Q3 ao utilizador, a agentic application usa um prompt separado para avaliar o seu próprio rascunho. Verifica se o texto gerado é totalmente suportado pelos slides recuperados. Se o passo de reflection detetar uma hallucination ou uma métrica-chave omitida, rejeita o rascunho e aciona uma correção. O verdadeiro poder das context-augmented applications não é apenas dar um documento a um LLM para ler, mas sim dar-lhe um workflow estruturado e autocorretivo para raciocinar com segurança sobre os teus dados privados. Se quiseres ajudar a manter o programa no ar, podes procurar por DevStoriesEU no Patreon e apoiar-nos por lá. É tudo por este episódio. Obrigado por ouvires, e continua a construir!

Olá, daqui fala o Alex da DEV STORIES DOT EU. LlamaIndex: Context-Augmented LLM Applications, episódio 2 de 14. Não podes simplesmente enfiar um PDF de 500 páginas numa context window de um LLM e esperar uma resposta precisa. O modelo vai perder-se, ter alucinações, ou simplesmente rejeitar o payload por exceder os seus limites. Para tornares ficheiros enormes úteis, tens de os desfazer em pedaços minúsculos e traduzi-los para um formato matemático que a máquina consiga pesquisar. Esse processo é exatamente o que Data Ingestion: Documents and Nodes aborda hoje. Pensa em digerir um manual de recursos humanos enorme. O texto vive num PDF gigante, que se estende por dezenas de capítulos complexos. O primeiro passo numa pipeline de Retrieval-Augmented Generation é a fase de loading. É aqui que os Data Connectors, frequentemente chamados de Readers, entram em ação. Um connector pega na tua fonte de dados bruta — seja um PDF local, uma tabela de uma base de dados remota, ou uma resposta de uma API externa — e encapsula-a numa estrutura de dados chamada Document. As pessoas costumam tropeçar neste termo. Nesta framework, um Document não significa um ficheiro Word ou um PDF. Um Document é simplesmente um container genérico para qualquer fonte de dados ingerida. Ele guarda o texto bruto juntamente com algumas propriedades básicas. No entanto, um único Document a representar um manual de 500 páginas é completamente inútil para pesquisas precisas e rápidas. Tens de o dividir. Isto leva-nos aos Nodes. Um Node é a verdadeira unidade atómica de dados no LlamaIndex. É um chunk mais pequeno e gerível de um Document pai — talvez um único parágrafo a detalhar a política de licença parental. Quando processas o manual de RH, a framework pega no Document massivo e corta-o em milhares de Nodes. Aqui está o ponto-chave. Os Nodes não guardam apenas texto isolado. Eles carregam metadados ricos e relações estruturais. Um Node sabe exatamente de que Document pai veio. Também sabe que Node o precede logicamente e que Node se lhe segue. Esta estrutura interligada é o que permite ao sistema sintetizar um contexto maior mais tarde, caso um único chunk não contenha a resposta toda. Assim que tiveres os teus dados cortados em Nodes precisos, passas para a fase de indexing. Precisas de uma forma robusta de encontrar o Node correto quando um utilizador fizer uma pergunta mais tarde. Isto requer traduzir a linguagem humana para um formato numérico chamado embedding. Um embedding é um array de números de vírgula flutuante que representa o significado semântico do texto dentro do Node. Passas cada Node por um modelo de embedding. O modelo lê o chunk e devolve um vetor de alta dimensão. Se dois Nodes discutirem tópicos concetualmente semelhantes — como baixa médica e férias pagas — os seus vetores numéricos vão ficar matematicamente próximos um do outro no espaço. Com estes vetores gerados, constróis um Index. O Index é o componente estrutural central que organiza os teus Nodes para que possam ser consultados. Para a maioria das aplicações, este Index é suportado por uma Vector Store. A Vector Store atua como uma base de dados especializada, desenhada explicitamente para guardar estas representações matemáticas e realizar cálculos de similaridade altamente eficientes sobre elas. O fluxo lógico é altamente previsível. Primeiro, configuras um data connector para apontar para o teu manual de RH. O connector lê o ficheiro e devolve um único objeto Document. A seguir, um parser pega nesse Document e divide-o num array de objetos Node independentes. Finalmente, passas esse array de Nodes para um Index, que coordena a criação de vector embeddings e faz o commit deles para a Vector Store. Toda a pipeline de ingestion existe para resolver uma limitação fundamental. Os Large Language Models não conseguem ler livros inteiros de uma só vez de forma fiável, mas conseguem calcular instantaneamente a distância matemática entre dois arrays de números. Traduzir os teus ficheiros brutos para Documents, cortá-los em Nodes interligados, e codificá-los em vector indexes é o que preenche essa lacuna. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui fala o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 3 de 14. Pegas no chunk de documento certo, envias para o modelo de linguagem, e mesmo assim recebes uma má resposta porque estava enterrada debaixo de dez chunks irrelevantes. Encontrar o texto é apenas metade da batalha. Filtrar, fazer o ranking e decidir como ir buscá-lo em primeiro lugar é onde o sistema realmente tem sucesso ou falha. Hoje vamos olhar para a fase de execução de RAG, especificamente a Query Pipeline: Retrievers e Routers. Nesta fase, os teus dados já estão carregados e indexados. Um utilizador submete uma query. O primeiro componente a intercetar esta query é muitas vezes um router. Um router é um motor de decisão. Ele olha para a pergunta recebida e determina qual a tool ou index subjacente mais adequado para lhe responder. Imagina que um utilizador faz uma pergunta complexa sobre um evento histórico específico que também inclui acrónimos muito específicos. Uma vector search normal pode captar o significado semântico do evento, mas falhar os acrónimos. Uma keyword search vai acertar em cheio nos acrónimos, mas perder o contexto mais amplo. O router avalia a query e decide enviá-la por dois caminhos em simultâneo. Ele faz o route do pedido tanto para uma vector search como para uma keyword search. Isto leva-nos aos retrievers. Um retriever é responsável por definir exatamente como ir buscar o contexto relevante a um index. Ele não gera respostas. Apenas vai buscar dados. Seguindo o nosso cenário, o vector retriever converte a query do utilizador num embedding e extrai os nodes matematicamente mais semelhantes, que são apenas chunks dos teus documentos de origem. Ao mesmo tempo, o keyword retriever extrai os nodes que contêm correspondências de texto exatas para esses acrónimos. Agora tens duas pilhas distintas de nodes. Não podes simplesmente adicioná-los às cegas ao prompt do teu modelo de linguagem. As context windows são limitadas, e os modelos distraem-se facilmente com dados irrelevantes. É aqui que os node postprocessors entram em ação. Aqui está a ideia principal. Os node postprocessors atuam como um guardião entre os retrievers e o modelo de linguagem. Eles aplicam transformações, filtragem ou lógica de re-ranking aos nodes recuperados. Por exemplo, um postprocessor pode impor um cutoff de similaridade, descartando quaisquer nodes que tenham tido uma pontuação abaixo de um threshold específico. Pode desduplicar nodes se a vector search e a keyword search tiverem ido buscar exatamente o mesmo parágrafo. Também pode fazer o re-ranking dos nodes restantes para que o chunk absolutamente mais relevante fique no topo da context window. Assim que o postprocessor limpa e ordena os dados, o sistema passa-os para o response synthesizer. O synthesizer tem apenas um trabalho. Pega na lista refinada de nodes e na query original do utilizador, combina-as num prompt estruturado, e envia-as para o modelo de linguagem. O modelo de linguagem gera então a resposta final legível por humanos com base exclusivamente nesse contexto fornecido. A fase de execução da query é estritamente uma pipeline. Fazes o route da query, recuperas os nodes brutos, filtras e fazes o ranking desses nodes com um postprocessor, e finalmente sintetizas o texto. Se controlares o que o modelo de linguagem vê, controlas a qualidade do output. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui fala o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 4 de 14. Estás a construir um agent que lida com tickets de suporte de TI, mas metade das submissões são apenas fotos de smartphones com luzes de erro a piscar. O processamento apenas de texto obriga-te a construir pipelines de visão separados ou a descartar completamente o contexto visual. Hoje, vamos abordar a Interação com LLMs e inputs multimodais, o que resolve este problema logo na layer do modelo. No LlamaIndex, a interação com um modelo de linguagem passa pela base class LLM. Esta funciona como uma interface unificada. Quer estejas a chamar um modelo da OpenAI, um modelo da Anthropic ou de um provider diferente, os core methods que usas são idênticos. Esta abstração protege a lógica da tua aplicação de alterações na API específicas do provider. Quando queres uma resposta do modelo, escolhes entre dois métodos principais. O primeiro é o método complete. Passas-lhe uma única string de texto com o teu prompt, e ele devolve uma única resposta de texto. Isto foi construído para tarefas diretas e single-shot, como resumir um documento ou extrair um facto específico. O segundo método é o método chat. Este foi desenhado para conversas ou interações estruturadas. Em vez de uma única string, passas uma lista de objetos chat message. Cada mensagem tem um role específico associado, tipicamente system, user ou assistant. Ao passar uma lista, o método chat dá ao modelo o contexto completo de uma troca de mensagens antes de gerar a sua próxima resposta. Tanto o complete como o chat esperam que o modelo termine toda a sua geração antes de devolver o output. Se o modelo estiver a escrever uma resposta longa, a tua aplicação fica idle. Para resolver isto, usas streaming. Em vez disso, chamas stream complete ou stream chat. Estes métodos devolvem um generator. À medida que o modelo produz tokens, o teu código recebe-os em pequenos chunks. Fazes um loop por este generator para imprimir a resposta numa user interface em tempo real, eliminando a perceção de latência. Agora, a segunda parte disto é lidar com dados não textuais. É aqui que a coisa fica interessante. Os LLMs modernos fazem parse de informação visual, e o LlamaIndex suporta isto através de content blocks. Em vez de passares uma simples string de texto dentro de uma user chat message, podes passar uma lista de blocks. Lembra-te do ticket de suporte de TI com o server rack avariado. Precisas que o modelo olhe para a foto e leia as tuas instruções de diagnóstico. Primeiro, crias um ImageBlock. Forneces a este block os dados da imagem. O LlamaIndex permite-te passar um file path local, um URL direto, ou raw bytes codificados em base sessenta e quatro. A seguir, crias um TextBlock. Dás-lhe o teu prompt de texto, a pedir ao modelo para identificar a falha de hardware mostrada na imagem. Colocas tanto o ImageBlock como o TextBlock numa única lista, e anexas essa lista a uma nova user chat message. Quando passas esta mensagem para o método chat de um modelo com capacidade de visão, o LLM processa o layout visual do server rack em conjunto com as tuas instruções de texto. Ele devolve um diagnóstico com base em ambos os inputs combinados. Aqui está o ponto chave. O verdadeiro poder desta arquitetura é a sua consistência. Quer estejas a enviar uma string de uma linha, a fazer streaming de uma resposta em tempo real, ou a passar um array complexo de text e image blocks, o padrão de interação com a classe LLM permanece completamente padronizado em toda a tua codebase. Ficamos por aqui neste episódio. Até à próxima!

Olá, daqui fala o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 5 de 14. Nada quebra uma pipeline de produção mais rápido do que um LLM decidir adicionar Claro, aqui está o teu JSON logo antes do payload de dados real. Tu pedes um output legível por máquina, recebes texto de encher, e o teu parser crasha instantaneamente. Preencher a lacuna entre linguagem natural não estruturada e tipos programáticos fiáveis é exatamente o que a Extração de Dados Estruturados com Pydantic resolve. Pensa no cenário de fazer o parsing de uma caixa de entrada de e-mail caótica, cheia de mensagens de fornecedores, lembretes de pagamento e recibos não estruturados. O teu sistema precisa de extrair dados estruturados de faturas a partir deste texto. Se dependeres da geração de texto standard, vais obter resultados imprevisíveis. Uma resposta pode usar camel case para as keys, outra pode formatar as datas de maneira diferente, e os preços muitas vezes voltam como strings com símbolos de moeda agarrados. Acabas a escrever lógica infinita de manipulação de strings só para conseguires tirar um número utilizável da resposta. Em vez de pedires JSON ao modelo e esperares que ele obedeça, tu defines os teus requisitos exatos usando um base model do Pydantic. Crias uma classe Python chamada Invoice. Dentro desta classe, declaras os data types precisos que a tua aplicação espera. Defines a data como uma string, os itens comprados como uma lista de strings, e o preço total estritamente como um float. Aqui está o ponto chave. O LlamaIndex pega na tua classe Pydantic e serializa-a automaticamente num JSON schema estrito. Quando envias o texto do e-mail para o modelo, o LlamaIndex anexa este schema e aciona o structured output ou a API de function-calling do modelo subjacente. O schema atua como um limite rígido. O LLM já não está a gerar texto livre. Ele é obrigado a preencher os fields do JSON schema especificamente com os types que tu exigiste. Também podes guiar o raciocínio do modelo diretamente dentro das tuas estruturas de dados. Ao anexares uma field description a um atributo, dás instruções específicas ao LLM. Para o atributo do preço, podes adicionar uma field description a indicar para extrair o custo total final, ignorando as taxas de envio. O LLM lê esta descrição como parte da definição do schema e aplica essa lógica durante a fase de extração. Quando a resposta volta, o LlamaIndex não te entrega uma raw string ou um dicionário genérico. Ele processa a resposta através do Pydantic e devolve um objeto Invoice totalmente instanciado. Os dados já vêm validados. Como a framework tira partido de features nativas de structured output, o modelo sabe de avanço que tem de fornecer um float real para o preço, e não uma representação em string do mesmo. Podes aceder imediatamente ao atributo invoice dot price no teu código e fazer contas com ele. Não há necessidade de limpar texto de encher, remover cifrões, ou fazer cast de strings para números. A transição de linguagem natural para a lógica da aplicação acontece de forma fluida na camada de extração. Ao empurrares o teu data schema diretamente para o processo de extração, forças o LLM a adaptar-se ao código da tua aplicação, em vez de escreveres código de aplicação frágil para tolerar o comportamento imprevisível do LLM. É tudo por este episódio. Obrigado por ouvirem, e continuem a construir!

Olá, daqui é o Alex do DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 6 de 14. E se a tua aplicação pudesse decidir quais funções executar com base na intenção do utilizador, em vez de um conjunto rígido de instruções condicionais? Essa é a ideia central por trás da criação de agentes de função autónomos. Quando constróis um query pipeline normal, és tu que defines o caminho de execução. Um agente inverte este paradigma. Tu forneces um conjunto de tools, e um motor de raciocínio automatizado usa um large language model para decidir que tools chamar, e em que ordem, para resolver um problema. Antes de avançarmos, precisamos de esclarecer um mal-entendido comum. O próprio LLM não executa o teu código Python. Ele apenas gera um request de texto estruturado a dizer que quer chamar uma função específica com argumentos específicos. A framework de agentes do LlamaIndex interceta esse request, executa o teu código Python local e, em seguida, devolve o resultado ao LLM. Para que este routing autónomo funcione, precisas de tools. Uma tool é essencialmente uma função Python normal, envolvida numa classe do LlamaIndex chamada FunctionTool. Mas, como o LLM precisa de saber quando e como usar a tua função, a metadata do teu código torna-se uma parte crítica do sistema. A framework extrai o nome da função, as type hints e a docstring, e passa-os ao LLM como instruções. Vejamos um cenário concreto. Queres que o teu agente resolva problemas matemáticos. Escreves duas funções em Python, uma chamada add e outra chamada multiply. Para a função multiply, as tuas type hints especificam que ela recebe dois inteiros e devolve um inteiro. De forma crucial, escreves uma docstring que diz claramente que esta função multiplica dois números. Envolves ambas as funções em tools e passa-las numa lista, juntamente com o teu LLM escolhido, para inicializar o agente. É aqui que a coisa fica interessante. Perguntas ao agente: quanto é dois mais dois, multiplicado por três? O agente entra num loop de raciocínio. Primeiro, o LLM analisa o prompt e olha para as tools disponíveis. Lê as tuas docstrings e decide que precisa de somar primeiro. Gera um request para chamar a tool add com os argumentos dois e dois. A framework executa a tua função Python localmente e devolve o resultado, quatro, ao agente. O agente não fica por aqui. Olha para o resultado intermédio e para o seu objetivo original. Decide que agora precisa de multiplicar. Faz um request à tool multiply, passando o quatro que acabou de receber e o três do teu prompt original. A framework executa a multiplicação e devolve doze. Finalmente, o LLM reconhece que o problema está resolvido e gera uma resposta conversacional para o utilizador. Não há regras hardcoded nem lógica de routing explícita aqui. O agente descobriu as dependências e a ordem das operações inteiramente sozinho, com base nas tools disponíveis. Isto significa que a forma como escreves as tuas definições em Python dita diretamente a inteligência do teu agente. As tuas type hints e as tuas docstrings já não servem apenas para outros developers, elas são o prompt literal que guia a lógica autónoma do agente. Se estás a tirar valor destes episódios e queres apoiar o programa, podes procurar por DevStoriesEU no Patreon. É tudo por este episódio. Obrigado por ouvires, e continua a programar!

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 7 de 14. Estás a construir um agent que precisa de verificar cotações de ações, ir buscar mensagens ao Slack ou consultar uma base de dados. Poderias passar dias a ler documentação de APIs, a lidar com esquemas de autenticação e a escrever código boilerplate de integração. Ou podes simplesmente pegar no trabalho já concluído que um developer da comunidade já escreveu e verificou. Este episódio aborda a extensão de agents com tools do LlamaHub. Os agents dependem de tools para interagir com o mundo exterior. Embora possas escrever cada integração manualmente, o LlamaHub existe especificamente para eliminar esse trabalho redundante. Funciona como um vasto registry open-source de tool specifications pré-construídas. Uma tool specification, ou tool spec, é essencialmente uma classe Python que agrupa várias chamadas de API relacionadas num único package. Ao puxares estas integrações diretamente para o teu projeto, evitas todo o processo de escrever a lógica subjacente para serviços de terceiros. Para usares uma destas integrações, instalas o seu package específico. Se queres que o teu agent responda a perguntas sobre o preço das ações de uma empresa, não escreves um request HTTP customizado para a API do Yahoo. Em vez disso, usas o teu package manager standard para instalar o package de tools Llama Index Yahoo Finance. Após a instalação, importas a classe Yahoo Finance Tool Spec para o teu script. Aqui está o ponto crucial. Não passas a classe tool spec diretamente para o agent. Como uma tool spec é um bundle de múltiplas capacidades, tens de a desempacotar primeiro. Fazes isso criando uma instância da Yahoo Finance Tool Spec, e depois chamando um método específico nela chamado to tool list. Este método separa o bundle e retorna um array flat standard de tools individuais que o agent pode ler e executar. Este design modular significa que não estás restrito a usar apenas tools externas ou apenas tools internas. Podes combiná-las perfeitamente. Supõe que já tens uma function tool customizada e local que formata números de moeda especificamente para o dashboard interno da tua empresa. Simplesmente crias uma lista Python standard. Dentro dessa lista, colocas a tua tool customizada de formatação de moeda, e também fazes append das tools desempacotadas da tool list do Yahoo Finance. Depois, pegas neste array combinado e passas diretamente ao teu agent durante a inicialização, atribuindo-o ao parâmetro tools. Quando fazes um prompt ao agent com uma pergunta sobre o preço atual de uma ação, o agent avalia o request do utilizador em relação às descrições de todas as tools nessa lista combinada. Ele reconhece que a tool Yahoo Finance é a escolha correta para ir buscar os dados de mercado. Ele extrai o ticker symbol da empresa a partir do prompt do utilizador, executa a tool Yahoo Finance, recupera o preço em tempo real e, opcionalmente, pode fazer chain desse resultado raw para a tua tool de formatação local antes de devolver a resposta final ao utilizador. Acabaste de dar à tua aplicação capacidades complexas de pesquisa financeira ao instalar um package, instanciar uma classe e chamar um método de desempacotamento. Este architectural pattern aplica-se a centenas de integrações no LlamaHub, desde ler documentos do Google Drive até consultar a Wikipedia. A verdadeira vantagem de um agent autónomo não se encontra apenas na capacidade de raciocínio do language model subjacente, mas na enorme variedade de sistemas externos a que pode aceder instantaneamente através de tool specifications pré-construídas. É tudo por este episódio. Obrigado por ouvires, e continua a construir!

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações de LLM Aumentadas por Contexto, episódio 8 de 14. Alimentas um language model com um prompt enorme, pedindo-lhe que pesquise um tópico, escreva um relatório e reveja criticamente o seu próprio trabalho. Ele falha. A context window fica baralhada, as tools são mal usadas e o output é um compromisso superficial. A solução é dividir esse prompt enorme num swarm de especialistas usando Multi-Agent Swarms com AgentWorkflow. Um único agent sobrecarregado tem dificuldades porque tem demasiadas tools e instruções contraditórias. Tem de decidir quando pesquisar, quando fazer o rascunho e quando editar, tudo isto enquanto gere um context interno enorme. O AgentWorkflow resolve isto permitindo-te definir uma rede de agents altamente focados. Cada agent opera com um system prompt restrito, um conjunto limitado de tools e um objetivo singular. Considera um pipeline de geração de conteúdo. Em vez de um mega-agent, criamos três FunctionAgents distintos. Primeiro, o Researcher. Equipamos este agent com uma web search tool e instruímo-lo estritamente a recolher factos. Ele não escreve prosa. A seguir, definimos o Writer. Removemos as search tools por completo para evitar que se distraia. O seu único trabalho é pegar nos factos brutos e redigir parágrafos limpos. Por fim, definimos o Reviewer. Damos-lhe guidelines sobre o tom e a precisão factual, instruindo-o a criticar o texto. Aqui está o ponto-chave. Ter vários agents é inútil se eles não se conseguirem coordenar, mas dar-lhes rédea solta para falarem com qualquer um cria o caos. Tens de os ligar explicitamente. No AgentWorkflow, fazes isto definindo permissões de handoff. Ao configurares os teus agents, especificas uma property chamada can handoff to. Esta aceita uma lista de outros agents. Para o nosso pipeline, damos ao Researcher permissão para fazer handoff para o Writer. Damos ao Writer permissão para fazer handoff para o Reviewer. Também damos ao Reviewer permissão para fazer handoff de volta para o Writer se o texto precisar de revisão. Isto cria um directed graph rigoroso de agents. A framework impõe estes limites. O Researcher não pode contornar o Writer e enviar notas brutas diretamente para o Reviewer. Simplesmente não tem autorização. Para executar isto, passas a tua lista de agents para uma instância do AgentWorkflow. Inicias o processo correndo o workflow com uma user query inicial, apontando-a ao Researcher para arrancar. A framework do workflow gere o shared state e o routing automaticamente. O Researcher corre as suas search tools, compila os dados e decide internamente que o seu trabalho está feito. Depois, usa a sua handoff tool para passar o controlo, juntamente com os dados recolhidos, para o Writer. O Writer pega nesse context, faz o rascunho do relatório e faz o handoff para o Reviewer. Se o Reviewer detetar uma falha, aciona um handoff de volta para o Writer com feedback. Este loop continua até que um agent decida que o trabalho está concluído e devolva uma resposta final ao utilizador em vez de acionar outro handoff. Limitar um agent a uma única função e definir explicitamente os seus caminhos de comunicação é a maneira mais fiável de forçar raciocínio complexo e multi-step a partir de language models. É tudo por este episódio. Obrigado por ouvires, e continua a programar!

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 9 de 14. Se permitires que agentes autónomos passem o controlo peer-to-peer, facilmente acabas com loops infinitos ou perda de context. Às vezes, não podes confiar que os agentes passem o controlo uns para os outros. Precisas de um manager central responsável por toda a operação. Esse é o pattern Orchestrator Agent. Num sistema multi-agente, deixar os agentes falarem diretamente uns com os outros parece poderoso, mas rapidamente se torna num pesadelo de debugging. Perdes o rasto de quem está no comando, e gerir o state geral da aplicação torna-se incrivelmente complexo. O pattern Orchestrator resolve isto impondo estritamente um modelo hub-and-spoke. Existe um orchestrator agent de topo, e todos os outros agentes são tratados estritamente como tools para esse orchestrator usar. Vamos analisar um cenário onde o teu sistema precisa de gerar um briefing técnico com muita pesquisa. Configuras um orchestrator agent para atuar como um manager rigoroso. Este manager é o dono do state global. Ele memoriza o prompt original do utilizador, mantém o context principal e monitoriza o que foi feito até agora. Ele não faz o trabalho pesado por si mesmo. Em vez disso, forneces-lhe tools. Estas tools não são simples API wrappers ou calculadoras básicas. São sub-agentes totalmente separados e funcionais. Podes criar um sub-agente dedicado à pesquisa, equipado com capacidades de vector search e web scraping. Podes criar um segundo sub-agente dedicado à escrita, equipado com diretrizes de estilo e lógica de formatação. No LlamaIndex, pegas nestes sub-agentes e expões os seus métodos run como tools. Ao fazeres isto, estás a encapsular todos os seus loops de raciocínio internos por trás de uma tool interface standard com um nome e uma descrição. Para o orchestrator, estes sub-agentes parecem exatamente funções Python standard. Quando o utilizador pede o briefing, o orchestrator avalia o objetivo geral com base nas descrições das tools que forneceste. Ele decide chamar a tool de pesquisa primeiro e passa os parâmetros necessários. O controlo passa temporariamente para o sub-agente de pesquisa. Este sub-agente corre o seu próprio loop autónomo. Pode fazer três ou quatro tool calls internas para recolher dados, sintetizar os factos e formular uma resposta. Assim que o agente de pesquisa termina, ele consolida todo esse trabalho numa string de texto final e devolve-a. Aqui está o ponto-chave. O orchestrator nunca cede realmente o controlo do processo principal. Ele apenas espera que a tool devolva um valor. O orchestrator recebe o resumo da pesquisa, adiciona-o ao seu próprio context e avalia o próximo passo. Ele percebe que a informação precisa de ser redigida num documento, por isso chama a tool de escrita, passando a pesquisa fresca como parâmetro de input. O sub-agente de escrita assume o controlo, faz o seu próprio processamento interno e devolve o texto finalizado. O orchestrator vê que o objetivo final foi atingido e entrega a resposta ao utilizador. Esta separação estrita de concerns torna o teu sistema altamente previsível. O agente de pesquisa não precisa de saber que o agente de escrita existe. Nenhum dos sub-agentes tem de se preocupar em passar o context, formatar a resposta final do utilizador ou decidir quando o trabalho geral está concluído. O orchestrator centraliza toda a lógica de tomada de decisão de alto nível. Ao forçares os sub-agentes a operarem puramente como tools isoladas dentro do loop de um manager central, podes construir sistemas multi-agente massivamente capazes que permanecem totalmente previsíveis e fáceis de fazer debug. É tudo por este episódio. Até à próxima!

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 10 de 14. A orquestração de agentes built-in é ótima até a tua business logic começar a parecer um prato de esparguete. Quando os hand-offs standard falham em capturar as tuas regras de scheduling altamente específicas, as abstrações tornam-se um blocker. É exatamente aí que precisas de Custom Multi-Agent Planners. Um custom planner é a tua válvula de escape para power-users. Permite-te construir o teu próprio loop de orquestração do zero usando um Workflow standard do LlamaIndex. Em vez de dependeres de um supervisor pre-built para ditar qual é o agente que atua a seguir, tu controlas todo o processo de scheduling de forma imperativa em Python. Tu ditas a ordem de execução, o data routing e o state management. O processo geralmente começa dentro de uma custom class, muitas vezes chamada PlannerWorkflow. A primeira fase é o planeamento. Quando um utilizador submete um request, o teu workflow envia um prompt para um large language model. Este prompt inclui a query do utilizador e uma descrição estrita das tools ou agentes que tens disponíveis. Tu instruis explicitamente o language model a gerar um plano passo a passo num formato altamente estruturado. Por exemplo, podes dizer ao modelo para envolver cada ação dentro de um bloco XML usando step tags, ou formatá-la como um JSON array. Quando o modelo responde, tu fazes o parse desse output estruturado. Usas uma library como o Pydantic para validar o XML ou JSON e convertê-lo numa lista concreta de tasks sobre a qual o teu código pode iterar. Agora entras na fase de execução. Esta parte depende inteiramente da tua custom logic. O teu workflow itera pela lista de steps parseados, um a um. Para cada step, ele verifica a ação solicitada. Usas lógica condicional standard para decidir o que fazer a seguir. Se o step parseado especificar uma task de research, o teu código chama explicitamente o teu agente de research. Se o próximo step exigir um cálculo, tu fazes trigger ao teu agente de matemática. Aqui está o insight principal. Como és tu a escrever o loop, manténs o ownership total do estado. Normalmente, crias um dicionário de contexto partilhado que vive durante toda a run do workflow. Quando o teu agente de research termina a sua task, o teu workflow pega no resultado e escreve-o diretamente nesse dicionário. Quando o próximo step faz trigger ao agente de matemática, a tua custom logic pode passar-lhe os dados exatos necessários desse dicionário partilhado. Não ficas à espera que um orquestrador black-box passe as variáveis certas. Tu mapeias explicitamente os outputs de um agente para os inputs do próximo. Assim que o loop conclui todos os steps do teu plano validado, o teu workflow faz qualquer formatação final e devolve a resposta. Construir um custom planner significa trocares a conveniência out-of-the-box por controlo total. Se um agente falhar, podes escrever uma custom retry logic para esse step específico. Se um step precisar de validação de uma API externa, podes pausar o loop. Estás a escrever código imperativo standard que, por acaso, usa language models como funções. O grande valor de um custom planner é a previsibilidade. Ao forçares o language model a gerar um plano XML rígido e ao executá-lo com loops e dicionários standard de Python, eliminas completamente o guesswork da orquestração black-box. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações de LLM Aumentadas por Contexto, episódio 11 de 14. Crias um agent para gerir a tua infraestrutura, e ele decide que a melhor forma de resolver um erro é apagar uma base de dados de produção. Nunca permitas que um agent autónomo tome uma ação destrutiva sem antes pedir permissão explícita a um humano. Para evitar isto, precisas de workflows Human-in-the-Loop. Human-in-the-loop é um mecanismo event-driven que pausa um agent, pede um input externo e retoma a execução com base na resposta. Em vez de deixares o agent correr ininterruptamente pelo seu ciclo de pensamento e ação, intercetas operações de alto risco. Consegues fazer isto nos workflows do LlamaIndex usando três componentes específicos: o InputRequiredEvent, o método wait_for_event e o HumanResponseEvent. Considera uma tool de tarefa perigosa desenhada para apagar um recurso na cloud. O agent decide que precisa de usar esta tool e aciona o step do workflow correspondente. Se a tool for executada imediatamente, o recurso desaparece. Em vez disso, o step do workflow interceta a execução. Antes de apagar qualquer coisa, o step cria um InputRequiredEvent. Este evento carrega um payload com detalhes sobre a ação, como o nome do recurso de destino e um prompt a pedir ao utilizador para confirmar a eliminação. O step emite este evento para a aplicação principal. Aqui está o ponto chave. O step do workflow não pode simplesmente ficar num loop ativo à espera de uma resposta. Tens de suspender o seu state. Fazes isto chamando wait_for_event no context do workflow, especificando que o step está agora à escuta de um HumanResponseEvent. Esta ação devolve o controlo ao environment. O engine do workflow pausa o step por completo, congelando o agent no seu state atual sem consumir recursos computacionais enquanto espera. Fora do workflow, a tua application layer apanha o InputRequiredEvent. Lês o payload e mostras o prompt de confirmação ao utilizador na sua command-line interface. O humano lê o aviso e escreve yes ou no. Agora precisas de despausar o agent. A tua aplicação pega no input do utilizador e encapsula-o num HumanResponseEvent. Envias este novo evento diretamente de volta para o engine do workflow em execução. O engine reconhece o tipo de evento e encaminha-o para o step exato que foi suspenso. O método wait_for_event resolve, devolvendo a string de resposta humana de volta à lógica da tool. A tool avalia a resposta. Se o humano escreveu yes, a tool prossegue com a API call para apagar o recurso na cloud. Se o humano escreveu no, a tool aborta a eliminação. Em qualquer dos casos, a tool devolve uma mensagem de status final ao agent. O agent processa este resultado, percebe se a ação foi bem-sucedida ou bloqueada pelo utilizador, e decide o seu próximo passo. Ao usar eventos para pausar e retomar a execução, o teu agent mantém todo o seu context de raciocínio e memória enquanto espera horas ou até dias que um humano tome uma decisão. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 12 de 14. Quando um agente autónomo comete um erro, vasculhar os *print statements* padrão do Python para encontrar o problema é um verdadeiro pesadelo. Fazes uma pergunta simples, recebes uma resposta alucinada, e o *stack trace* padrão não te diz absolutamente nada sobre o porquê de o modelo ter mentido. Para corrigir isto, precisas de uma maneira de ver o interior da caixa preta. Este episódio aborda *Observability* e *Tracing*. As ferramentas de *debugging* tradicionais não são suficientes com *large language models*. Um *stack trace* diz-te onde o código falhou, mas os *bugs* de LLM são geralmente lógicos. O código corre perfeitamente, mas o sistema vai buscar o documento errado ou interpreta mal um *prompt*. O *logging* padrão do Python é a tua primeira linha de defesa. Ao definir o nível de *logging* para *debug*, o LlamaIndex gera um *feed* bruto de tudo o que faz. Vais ver os *prompts* exatos enviados para o modelo de linguagem e as respostas HTTP brutas. Isto é útil para verificar se uma chamada de rede falhou, mas para um *workflow* de agente com várias etapas, ler um bloco enorme de texto não estruturado é incrivelmente aborrecido. Aqui está o ponto-chave. Não precisas apenas de um *log* de eventos; precisas de ver o *call graph*. Precisas de uma visão estruturada de como os dados fluem desde a *query* inicial, passando pelos *retrievers*, até ao modelo de linguagem e o caminho de volta. O LlamaIndex lida com isto usando um sistema de *callbacks*. Os *callbacks* são *hooks* que disparam em pontos específicos do ciclo de execução. A *framework* fornece uma ferramenta integrada chamada Llama *debug handler*. Inicializas este *handler* e anexas às tuas configurações globais. A partir desse ponto, ele regista silenciosamente cada operação. Imagina que corres um *query engine*, e ele devolve um facto completamente inventado. Sem *tracing*, não tens ideia se o modelo alucinou ou se a tua base de dados o alimentou com informações incorretas. Com o *debug handler* anexado, podes pedir-lhe para fazer *print* do *trace* após a conclusão da *query*. O *trace* revela a sequência exata de eventos. Vês a *query* inicial. Vês o passo de *retrieval*. Crucialmente, vês os *text nodes* exatos que o *retriever* extraiu do teu índice. Inspecionas esses *nodes* no *trace* e descobres que foi obtido um documento desatualizado. O modelo de linguagem não alucinou; simplesmente leu dados incorretos. Corriges o índice, e o *bug* fica resolvido. Os *traces* no terminal são ótimos para desenvolvimento local, mas não escalam bem quando tens agentes complexos a executar dezenas de passos de raciocínio. Para produção, o LlamaIndex oferece o que chama de *one-click observability*. Ao definir uma variável de ambiente específica ou adicionar uma única linha de configuração, podes encaminhar todos esses dados de *callback* para uma plataforma de *observability* dedicada. Estas plataformas ingerem os dados de *trace* e geram *dashboards* visuais. Podes clicar e navegar por uma árvore visual do *workflow* do teu agente, a inspecionar a latência exata, o uso de *tokens* e o *payload* de cada passo. Não precisas de instrumentar cada função manualmente; os *callbacks* nativos da *framework* tratam do trabalho pesado. A diferença entre um protótipo frágil e uma aplicação de produção fiável é se consegues explicar exatamente o porquê de o sistema ter gerado uma resposta específica. Se achaste isto útil e queres ajudar a apoiar o programa, podes procurar por DevStoriesEU no Patreon. É tudo por agora. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui fala o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 13 de 14. Trocas o teu embedding model e, de repente, as tuas respostas parecem um pouco estranhas, mas não consegues perceber bem porquê. Se estás apenas a olhar para os outputs para verificar a qualidade, o teu pipeline está a adivinhar às escuras. Para deixares de depender de palpites e evitares regressões em produção, precisas de RAG Evaluation Metrics. Criar uma aplicação RAG é fácil, mas torná-la robusta é difícil. Vais ajustar constantemente os chunk sizes, os prompts e as estratégias de retrieval. Se dependeres da revisão humana para testar cada alteração, vais atrasar o desenvolvimento ou fazer deploy de regressões. Precisas de medições automatizadas e objetivas. Como o RAG consiste em duas etapas distintas, encontrar a informação certa e gerar uma resposta com base nela, tens de avaliar ambas as fases separadamente. Vamos olhar primeiro para a geração. A isto chama-se Response Evaluation. A métrica principal aqui é a faithfulness. O objetivo é apanhar alucinações. Uma resposta faithful é aquela em que o language model se baseia inteiramente no retrieved context, em vez de inventar factos a partir dos seus próprios dados de pre-training. No LlamaIndex, tratas disto com o FaithfulnessEvaluator. Esta ferramenta utiliza um language model por trás dos panos para atuar como juiz. Inicializas o evaluator, e depois passas-lhe a query original, o array de context nodes recuperados e o texto final gerado. O evaluator devolve um objeto de avaliação que contém um boolean binário de pass ou fail, que te diz se a resposta é estritamente suportada pelo contexto fornecido. Também fornece uma string de reasoning a explicar o motivo da decisão do juiz. Se o teu faithfulness score cair após um update, o teu prompt ou o teu language model podem estar a ficar demasiado criativos. Agora, a segunda parte disto. Mesmo o melhor language model não consegue gerar uma resposta faithful se lhe deres os documentos errados. É aqui que entra a Retrieval Evaluation. Aqui está a ideia principal. Avalias o retrieval verificando se o sistema foi buscar os source nodes exatos que esperavas para uma determinada query, ignorando completamente o texto final gerado. Tratas disto com o RetrieverEvaluator. Imagina um cenário em que queres testar um novo embedding model. Em vez de fazeres o deploy e tentares adivinhar se é melhor, crias um evaluation dataset. Este dataset contém uma lista de queries emparelhadas com os identificadores de documentos específicos que contêm as respostas corretas. Corres todo o teu batch de queries pelo RetrieverEvaluator. O evaluator calcula duas métricas cruciais, Hit Rate e MRR. O Hit Rate é simples. Verifica se o documento esperado apareceu em algum lugar nos teus top retrieved results. Se fizeres o retrieval de cinco documentos, e o correto estiver lá no meio, isso é um hit. Mede o recall puro. Mas a posição importa. Se o documento correto estiver sempre em quinto lugar, o teu language model pode ignorá-lo devido a context limits ou attention decay. É aqui que entra o Mean Reciprocal Rank, ou MRR. O MRR olha para a posição do primeiro documento relevante. Se o documento correto estiver mesmo no topo, o score é um. Se estiver em segundo, o score é um meio. Se estiver em terceiro, um terço. O evaluator faz a média destas frações em todo o teu dataset. Um MRR mais alto significa que o teu retriever está consistentemente a empurrar a informação mais relevante para o topo da context window. Ao comparar o Hit Rate e o MRR do teu embedding model antigo com o novo, obténs uma prova matemática de qual modelo tem melhor performance. Podes acompanhar estes números ao longo do tempo e correr este pipeline automaticamente em cada pull request. A coisa mais valiosa que podes fazer pelo teu pipeline de RAG é separar a avaliação daquilo que fazes retrieve da forma como geras a resposta final. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui é o Alex da DEV STORIES DOT EU. LlamaIndex: Aplicações LLM Aumentadas por Contexto, episódio 14 de 14. Para de copiar e colar a mesma API e o mesmo boilerplate React sempre que quiseres testar uma nova ideia de Retrieval-Augmented Generation. Tu já percebes a mecânica do framework, mas configurar uma interface limpa para usares os teus modelos ainda leva horas de trabalho repetitivo. Hoje, vamos falar sobre as starter tools que te permitem fazer o scaffold para produção em segundos. Construir uma aplicação funcional exige muito mais do que apenas um index e um query engine. Precisas de um servidor de backend para lidar com os requests recebidos de forma segura. Precisas de rotas de API para passar mensagens de um lado para o outro. Precisas de um cliente de frontend para mostrar o histórico do chat, fazer o render dos loading states e fazer o parse das respostas. Escrever esta infraestrutura do zero para cada novo dataset ou protótipo consome o teu tempo. Para resolver isto, o LlamaIndex fornece um utilitário de linha de comandos chamado create-llama. Esta ferramenta gera uma aplicação web full-stack completa, pré-configurada com as best practices do LlamaIndex. Abres o teu terminal e corres o comando create-llama. A ferramenta depois guia-te através de uma série de escolhas. Pergunta se queres um backend em Python a usar FastAPI, ou um backend em Node a usar Express. Pergunta se queres um frontend em Next JS para dares aos teus utilizadores uma interface web polida. Depois, pede a tua data source. Podes apontar a ferramenta diretamente para uma pasta local que contenha os teus ficheiros PDF. Assim que terminares os prompts, o create-llama assume o controlo. Instala todas as dependências necessárias. Faz o scaffold da estrutura de diretórios. Escreve o script de ingestion para fazer o parse dos teus PDFs. Liga os endpoints da API para que o teu frontend possa falar com o teu retrieval engine. Finalmente, configura as environment variables. Corres um comando de start, e tens imediatamente uma interface de chat estilizada a correr no teu browser. Podes escrever uma pergunta, e a interface vai bater no backend gerado, fazer o retrieve do contexto dos teus PDFs, e fazer o stream da resposta de volta para o teu ecrã. Passas de uma pasta vazia para um protótipo full-stack a funcionar em cerca de trinta segundos. Isto trata das aplicações web. Mas às vezes, um servidor web e uma interface gráfica são um exagero. Se acabaste de fazer o download de uma longa especificação técnica e precisas de fazer uma query imediatamente sem saíres da tua linha de comandos, usas a RAG CLI. A RAG CLI é uma ferramenta construída puramente para interação com documentos baseada no terminal. Instalas a ferramenta, e depois corres um comando para a apontar para o teu diretório local de documentos. A CLI corre automaticamente o processo de ingestion. Faz o chunk do texto, gera embeddings, e guarda-os numa vector database local, aí mesmo na tua máquina. Quando o ingestion estiver concluído, corres o comando de chat. O teu prompt de terminal padrão transforma-se numa sessão de chat. Fazes uma pergunta, a CLI faz o retrieve dos dados relevantes, faz a query ao language model, e imprime a resposta gerada diretamente na tua consola. Não há componentes visuais ou rotas web para configurar. É a maneira absolutamente mais rápida de falares com os teus dados localmente. Aqui está o ponto chave. Agora já percebes a mecânica profunda das aplicações context-augmented, desde fazer o chunk de documentos até construir agent routers complexos. Estas scaffolding tools existem para que possas parar de lutar com a infraestrutura básica e passar o teu tempo a fazer o tuning dessas core retrieval strategies. Como este é o episódio final da nossa série LlamaIndex, o melhor próximo passo é ires à documentação oficial e tentares construir estas pipelines hands-on. Se tiveres uma ideia para uma tech stack completamente diferente que queiras que nós abordemos, visita devstories dot eu para sugerires um tópico. É tudo para este episódio. Obrigado por ouvires, e continua a construir!