Módulo 2 · Parte B de 3

O Agente de Índice

Os dados assumem várias formas, e cada uma exige uma estratégia de recuperação diferente. Escolher uma estratégia incompatível com os dados é a causa mais comum de falhas silenciosas de um agente de índice em produção.

O Agente de Índice aplica essa ideia de workflow ao conhecimento externo com um pipeline definido pelo desenvolvedor. Ele incorpora e indexa um corpus antecipadamente, então recupera passagens correspondentes e gera uma resposta a partir de um pacote de contexto limitado. O exemplo percorre esse caminho para prosa não estruturada e depois encapsula a recuperação como uma ferramenta que um ciclo ReAct externo pode chamar. Para as outras formas de dados, a página indica os caminhos de aprofundamento.

Construa a sequência de recuperação na ordem.

Geração sem recuperação responde com o contexto atual e o treinamento do modelo.
RAG tradicional executa uma etapa fixa de recuperação antes de cada resposta gerada.
Recuperação controlada pelo agente expõe a recuperação como ferramenta, para que o loop decida se outra consulta é necessária.

Os exercícios mantêm o corpus e a pergunta visíveis enquanto muda quem controla a recuperação.

Profundo · HistóriaAcompanhar a evolução do RAG do treinamento conjunto à recuperação?

De onde veio o RAG: um sistema, treinado de ponta a ponta

A versão de RAG mais comum hoje descarta boa parte do design original. Entender essa diferença muda a forma de pensar sobre o recuperador que você está prestes a conectar.

Quando Lewis e colegas nomearam a geração aumentada por recuperação em 2020, não era um modelo com uma caixa de pesquisa acoplada. O recuperador e o gerador foram treinados juntos na tarefa que tinham que realizar. Leia a figura da esquerda para a direita antes de olhar para a seta no topo.

A arquitetura original, de Lewis et al. 2020, com o rótulo de retropropagação na linha superior que a maioria dos sistemas construídos hoje deixa de fora.

O design vive na seta rotulada como "Retropropagação de Ponta a Ponta por q e p_θ". Uma perda atualizou ambas as metades de uma vez. O codificador de consulta aprendeu quais passagens o gerador poderia usar, e o gerador aprendeu a se apoiar em evidências recuperadas em vez da sua própria memória.

O recuperador começou como parte do modelo, moldado pela tarefa que precisava realizar, muito antes de ser descrito como uma ferramenta de busca posicionada à frente de um modelo.

Por que o RAG de hoje descarta o treinamento conjunto

Hoje, quase ninguém treina RAG dessa forma por duas razões práticas. Não é possível retropropagar por um modelo de fronteira acessado por API; mesmo quando auto-hospedado, o treinamento conjunto de recuperação e geração é caro e instável.

A prática convergiu para uma montagem mais simples: usar um modelo existente e congelado, colocar um recuperador à sua frente e enviar ao prompt as evidências recuperadas, sem novo treinamento. As partes são construídas separadamente e depois acopladas. Com o tempo, "RAG" passou a significar esse acoplamento, não o sistema otimizado em conjunto descrito no artigo.

O custo do acoplamento. Um recuperador que nunca recebe o sinal de perda do gerador precisa inferir o que ele necessita. Por isso, a qualidade da recuperação depende de quanto o modelo de incorporação se ajusta aos dados. Reclassificação, reescrita de consultas e um modelo de incorporação ajustado recuperam parte do benefício antes obtido pelo treinamento de ponta a ponta. Uma pilha de recuperação robusta adiciona estágios para reduzir o restante da diferença. Encare o acoplamento como um substituto pragmático para um sistema antes unificado: isso revela seu limite e os controles capazes de elevá-lo.

O pipeline recuperar-e-gerar que você constrói

Com esse limite em mente, observe a montagem completa. Um recuperador opera à frente do modelo congelado em duas linhas do tempo. Uma constrói o índice antecipadamente; a outra atende às solicitações em tempo de execução usando esse índice. A figura abaixo mostra as duas.

Recriação para o curso do pipeline de duas etapas mostrado em Hayden Wolff, RAG 101 (NVIDIA, 2023) e Amit Bleiweiss, tips for building a RAG pipeline (NVIDIA, 2024).

Offline: construa o índice uma vez, incorporando cada passagem e armazenando-a para busca rápida.

Ao vivo: incorpore a pergunta, recupere as passagens top-K e entregue-as ao modelo junto com a pergunta.

O restante desta página constrói o caminho ao vivo uma etapa de cada vez.

Aplicado · EscopoEscolher pacotes, fronteiras e formatos de dados?

Definir o pacote de contexto antes de escolher o armazenamento

Antes de escolher um primitivo de recuperação, defina um pacote: o conjunto completo e limitado de contexto que deve atravessar o pipeline.

Para um sistema de resposta a perguntas de um único turno simples, o pacote pode permanecer pequeno: a pergunta do usuário, os poucos pedaços recuperados para respondê-la e a resposta em si.
Para um agente autônomo, o pacote é a memória de trabalho que ele carrega em muitos turnos. Essa memória armazena as restrições do agente, decisões anteriores, resultados parciais, superfícies de ferramentas e regras de operação.
Para um agente de índice arbitrário, o pacote retornado pode conter apenas os trechos recuperados, suas fontes, pontuações de relevância e talvez um resumo. Um pacote interno separado pode representar o pipeline linear de processamento em tempo de execução mostrado acima ou um ciclo no estilo ReAct, que avalia a relevância e tenta novamente até acumular contexto suficiente.

O princípio do pacote é uma disciplina de planejamento: defina o pacote antes de escolher o banco de dados. Escolher primeiro um armazenamento de vetores e esperar que ele cubra tudo costuma produzir o resultado "funcionou na demonstração, mas falhou em produção". A taxonomia de quatro formas abaixo ajuda a verificar se o primitivo candidato consegue entregar o pacote exigido pela tarefa.

Onde o MCP se encaixa nos sistemas de recuperação

O MCP fornece a um sistema de recuperação uma fronteira para descobrir e chamar fontes de contexto externas. O agente ainda precisa de um runtime que decide quando recuperar, valida o resultado e compõe com o restante do estado da tarefa ativa. Outras fronteiras podem transportar outras partes do mesmo sistema: pacotes de habilidades, instruções de capacidade reutilizável, A2A pode encaminhar trabalho para especialistas remotos e protocolos de UI podem transmitir o estado gerado de volta para um aplicativo.

A figura abaixo separa essas fronteiras. Leia da esquerda para a direita para acompanhar a entrada de contexto pelo MCP e a entrega de tarefas pelo A2A; leia de baixo para cima para acompanhar a oferta de capacidades por habilidades, a execução no runtime e a UX gerada.

Quatro limites do sistema em torno de um runtime de recuperação: MCP para entrada de contexto, A2A para entrega de tarefas e habilidades/runtime/UX para fluxo de capacidade.

Associando um primitivo de recuperação à forma dos seus dados

Cada forma de dados exige um primitivo de recuperação adequado. Escolha a linha errada, e o sistema continuará retornando resultados plausíveis enquanto deixa de encontrar o que a consulta realmente pede, sem emitir erro. A tabela abaixo relaciona cada forma ao primitivo correspondente.

Forma	Exemplos	Primitivo correto
Prosa não estruturada	Documentos, artigos, comentários de código, transcrições	Vetor denso + reclassificação com cross-encoder
Documentos hierárquicos	Contratos legais, manuais técnicos, especificações aninhadas	Índice de árvore com ponteiros de pai
Tabelas estruturadas / governadas	Registros de clientes, livros-razão financeiros, tabelas de RH	Camada semântica sobre a fonte de verdade
Relacional / grafo	Quadros organizacionais, dependências de código, grafos de conhecimento	Travessia de grafos (Cypher, GraphQL, personalizado)

Este módulo segue a forma de prosa não estruturada do corpus para a resposta e executa o fluxo básico de recuperação e geração para nossos propósitos de exemplo.

Cada solicitação percorre os mesmos quatro passos:

Incorporar a consulta em um vetor.
Pesquisar o índice de passagens para as K passagens mais próximas.
Concatenar essas passagens ao prompt.
Gerar uma resposta fundamentada nelas.

Agentes de índice que coordenam esses primitivos geralmente seguem a mesma estrutura e variam apenas a lógica de busca, incorporação e verificação. Experimente a forma que melhor corresponde aos seus dados.

A incorporação, o primitivo sobre o qual tudo o mais é construído

Cada agente de índice de prosa não estruturada começa do mesmo primitivo. Uma incorporação é uma representação numérica aprendida para um trecho de texto: um vetor de comprimento fixo, posicionado de modo que textos semanticamente semelhantes fiquem próximos no espaço vetorial. Disso decorrem duas consequências práticas:

Comparar: a similaridade cosseno entre dois vetores usa um produto escalar e duas magnitudes.

Armazenar: um índice vetorial organiza textos pela posição nesse espaço para buscar os vizinhos mais próximos com eficiência.

Ambos se baseiam em um único primitivo: o modelo de incorporação. Este curso encaminha as chamadas por helpers.embed ao endpoint de incorporação hospedado da NVIDIA, permitindo executar tudo no navegador sem depender de um ambiente de laboratório ou servidor local.

Aplicado · ContratoRevisar o contrato da solicitação de embeddings?

Contrato da API de Incorporações.

O endpoint de incorporações aceita uma solicitação JSON com três campos e retorna um array de vetores:

input é o lote de textos para incorporar, tipado string[].
model nomeia o modelo de incorporação, tipado string.
input_type é "query" ou "passage".
A resposta carrega um array data cujas entradas cada uma contém uma embedding de number[].

Os modelos de incorporação da NVIDIA atribuem vetores diferentes ao mesmo texto conforme o input_type informado. O objetivo de treinamento aproxima uma pergunta em direção às passagens que a respondem em vez de em direção a textos que apenas repetem suas palavras. Assim, a pontuação cosseno entre entradas tipadas corretamente acompanha bem a relevância. Incorporar uma consulta como "passage", ou uma passagem como "query", prejudica silenciosamente a pontuação e reduz a revocação sem emitir erro.

Um recuperador completo em trinta linhas de cosseno de top-K

Um "banco de dados vetorial" dá uma interface mais completa a uma tarefa simples. Ele armazena cada passagem ao lado de sua incorporação e retorna, por similaridade cosseno, as passagens mais próximas da incorporação da consulta. No navegador, o núcleo dessa operação cabe em trinta linhas de JavaScript.

A célula abaixo constrói um agente de índice sobre um punhado de documentos e o consulta. Edite o corpus e a consulta, então observe quais passagens surgem no topo e por quê.

Modo de falha: embeddings desatualizados.

Um índice vetorial armazena em cache as saídas de um modelo de incorporação. Sistemas de produção precisam se proteger contra falhas específicas:

Ao trocar o modelo de incorporação, cada vetor em cache perde o significado até que todas as passagens sejam incorporadas novamente.
Se o provedor atualizar o modelo silenciosamente, as pontuações podem mudar sem erro.
Se dois serviços compartilharem um índice, mas fixarem IDs de modelo diferentes, o índice produzirá resultados inválidos para um deles.

Um índice confiável registra o ID do modelo de incorporação ao lado de cada vetor em cache e se recusa a misturar versões. O modelo fixado neste curso é nvidia/llama-nemotron-embed-1b-v2, servido por meio do proxy hospedado do curso em build.nvidia.com.

Aplicado · FragmentosRecuperar fragmentos pequenos com o contexto do documento pai?

Pesquisando pequenos pedaços, mas retornando o documento pai

Um agente de índice top-K simples enfrenta uma troca entre revocação e precisão que nenhum modelo de incorporação elimina. Você deve escolher entre trechos curtos e documentos longos:

Um trecho curto representa uma ideia focada, e o vetor resultante fica preciso. Falta-lhe contexto, e uma frase raramente basta para responder.
Documentos longos preservam o contexto, mas produzem incorporações difusas; o vetor representa a média de muitas ideias.

O padrão de produção indexa em dois níveis. Você incorpora os trechos pequenos para manter a recuperação precisa e, quando um deles corresponde à consulta, retorna o documento pai para que o modelo veja o contexto completo.

O exercício abaixo usa três documentos pai, cada um dividido em trechos curtos, e uma consulta que retorna o documento pai correspondente.

Incorporamos e pesquisamos os trechos filhos; cada correspondência entrega ao LLM o documento pai completo.

Aplicado · AgenteDeixar o modelo decidir quando recuperar informações?

Envolvendo o índice como uma ferramenta que o modelo decide chamar

Um índice de recuperação, isoladamente, só responde quando algo o consulta. Ele se torna um agente de índice quando é encapsulado como uma ferramenta que o modelo pode escolher chamar. Assim, o modelo decide quando vale a pena recuperar dados. A célula abaixo faz isso em cinco etapas:

Um corpus é embedado uma vez e mantido em um índice na memória.
Uma ferramenta retrieve(question, k) é declarada com um esquema JSON.
O agente recebe a pergunta do usuário. Ele escolhe se chamar a ferramenta.
Se sim, a recuperação cosseno é executada sobre o índice; as principais passagens são anexadas como uma mensagem de ferramenta.
Uma segunda chamada de grande modelo de linguagem (LLM) escreve a resposta final fundamentada nas passagens recuperadas.

O padrão "recuperador como ferramenta" que você acabou de conectar escala diretamente para produção. Substituir a função de cosseno na memória por um pipeline de servidor FAISS+BM25+rerank altera apenas o executor; o esquema da ferramenta, o ciclo do agente e a etapa da resposta final permanecem idênticos.

Aplicado · FormatosComparar os demais formatos de índice?

Como as outras três formas são construídas

Você acabou de construir o caminho da prosa não estruturada, do corpus à resposta. As outras três formas aparecem aqui para que você as reconheça em sistemas reais e escolha o primitivo correto. Cada uma delas tem um padrão de produção bem estabelecido, esboçado abaixo.

Documentos hierárquicos. Um segmentador preserva a hierarquia de títulos e combina extração de tabelas atômicas, ponteiros para o pai e um índice duplo para busca estrutural e semântica. Você indexa trechos filhos pequenos para obter boa revocação e recupera o pai correspondente, permitindo que o modelo leia a cláusula junto com sua seção.
Recuperação de imagens de página para figuras e gráficos. Uma configuração com dois espaços vetoriais incorpora a página renderizada e seu texto. Assim, a consulta também pode recuperar uma figura ou um slide quando a resposta estiver nesse conteúdo visual.
Tabelas estruturadas e governadas. Não são construídas neste curso. O padrão de produção usa uma camada semântica entre o agente e os dados no nível de linha, expondo apenas as métricas selecionadas exigidas pelo pacote.
Dados relacionais ou em grafo. Em vez de um armazenamento vetorial, o agente chama uma ferramenta de travessia de grafo escrita em Cypher, GraphQL ou linguagem personalizada. O pacote recebido é um subgrafo cujas arestas explícitas seguem para o prompt, preservando as relações entre entidades.

Profundo · GraphRAGExplorar a recuperação em todo o corpus com GraphRAG?

Quando o top-K é a ferramenta errada: GraphRAG e perguntas globais

Cada recuperador nesta página responde a uma pergunta local, cuja resposta está em poucas passagens que a similaridade top-K consegue encontrar. O que um contrato diz sobre rescisão e qual artigo introduziu o HyDE são perguntas desse tipo. Outra classe de pergunta não possui resposta em uma passagem isolada. Ao perguntar pelos principais temas de mil documentos, você descobre que a resposta é difusa demais para existir em um único trecho; ela emerge do corpus inteiro.

O top-K devolve apenas as três melhores correspondências. O modelo resume esses três trechos enquanto permanece cego às outras novecentas e noventa e sete passagens no corpus. O GraphRAG (Edge et al. 2024) altera a estrutura do problema, em vez de apenas aumentar K. Durante a indexação, ele usa um LLM para:

ler o corpus e extrair entidades e as relações entre elas em um grafo de conhecimento;
detectar as comunidades nesse grafo, os clusters de entidades densamente conectadas;
resumir cada comunidade por si só.

No momento da consulta, o sistema responde à pergunta global resumindo as comunidades relevantes e reduzindo as respostas parciais a uma só. O trabalho é um map-reduce sobre estrutura, não uma busca por similaridade.

O pipeline GraphRAG, redesenhado a partir da figura de Edge et al. 2024. As etapas azuis são construídas uma vez, offline, e as etapas verdes são executadas em cada pergunta.

A célula abaixo torna a diferença concreta em um pequeno corpus e executa o pipeline real. Ela responde a uma pergunta global de duas maneiras: recuperação top-K simples e map-reduce do GraphRAG sobre comunidades nomeadas. Observe como o top-K usa apenas os trechos cujas palavras coincidem com a pergunta, enquanto o caminho por comunidades recupera o tema do corpus inteiro. Edite o corpus, as comunidades ou a pergunta e execute novamente.

Um modelo congelado com um recuperador top-K à frente responde bem a perguntas locais, mas não a perguntas globais. Reestruturar o corpus em comunidades resumidas viabiliza a resposta global ao custo de uma etapa de indexação mais cara, executada uma única vez.

Antes de continuar

Na Parte 4, o cosseno pontua dois vetores da mesma maneira, independentemente de qual representa a consulta. Já o modelo de incorporação da NVIDIA usa input_type para distinguir consulta e passagem. O que essa assimetria oferece que o cosseno, sozinho, não poderia oferecer?
A construção do índice incorpora cada passagem do corpus uma vez, enquanto o caminho ao vivo incorpora cada nova pergunta. Quais mudanças exigem reindexar todo o corpus e quais exigem apenas uma nova incorporação da consulta?
Top-K sempre retorna K passagens, mesmo quando todas as pontuações são fracas. Qual sinal o agente deve verificar antes de incluir essas passagens no prompt?

Profundo · FontesRastrear as fontes de pesquisa sobre recuperação?

Referências

Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (NeurIPS 2020). O artigo canônico sobre recuperação seguida de geração; a figura acima foi redesenhada a partir dele.
Karpukhin et al., Dense Passage Retrieval (EMNLP 2020). A formulação de codificador duplo por trás da assimetria entre incorporações de consulta e passagem exigida pelo modelo da NVIDIA.
Johnson, Douze & Jégou, Billion-scale similarity search with GPUs (FAISS, 2017). A estrutura de índice vetorial usada pelos bancos de dados vetoriais.
Gao et al., HyDE: Precise Zero-Shot Dense Retrieval without Relevance Labels (2022). Gera uma resposta hipotética e incorpora esse texto, em vez da pergunta; uma melhoria rápida para consultas curtas ou ambíguas.
Lin et al., Pretrained Transformers for Text Ranking (2020). O padrão de reclassificação usado como segunda etapa em uma pilha de recuperação de produção.
Edge et al., From Local to Global: A Graph RAG Approach to Query-Focused Summarization (2024). Constrói um grafo de conhecimento derivado de LLM e pré-resume suas comunidades para responder a perguntas globais sobre todo o corpus; a figura do pipeline acima foi redesenhada a partir dele.

Lista abrangente em Ir Além · Referências.

Tente · recuperação, ao vivo

Faça uma pergunta. O artefato usa o mesmo endpoint desta página para incorporar a consulta e classificar, por similaridade cosseno, um pequeno corpus já incorporado. As barras mostram todas as pontuações. Em seguida, o modelo responde a partir das passagens mais relevantes e as cita. Altere a pergunta e observe a classificação mudar.

O corpus é incorporado offline e distribuído com a página como um índice pré-construído; apenas sua pergunta é incorporada em tempo de execução. Isso torna concreta a divisão entre indexação e serviço mostrada no diagrama. As perguntas de exemplo carregam vetores prontos e recuperam resultados antes mesmo de você adicionar uma chave. Ao editar uma passagem, somente ela é incorporada novamente.

← Módulo 2a: Workflows Módulo 2c: Agentes Profundos →