Módulo 2 · Parte B de 3

O Agente de Índice

Um sistema de recuperação precisa retornar as evidências exigidas pela pergunta. A estrutura dos dados ajuda a escolher como pesquisá-los.

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.

Acompanhar a evolução do RAG do treinamento conjunto à recuperação?

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

Quando Lewis e colegas deram o nome de geração aumentada por recuperação ao método em 2020, treinaram o recuperador e o gerador em conjunto para a tarefa. Leia a figura da esquerda para a direita antes de observar a seta na parte superior.

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.

Uso de modelos pré-treinados para RAG

Uma API de inferência não fornece acesso para atualizar os pesos do modelo. Treinar em conjunto um recuperador e um gerador hospedados por você exige os pesos do modelo, dados de treinamento e recursos computacionais.

O fluxo de trabalho deste exemplo usa modelos pré-treinados sem atualizar seus pesos. Um recuperador seleciona passagens para incluir no prompt de geração. Você pode alterar a recuperação e inspecionar seus resultados sem treinar o gerador.

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

O recuperador atua antes do modelo congelado em dois momentos distintos. Primeiro, o índice é construído; depois, as solicitações são atendidas consultando esse índice. A figura abaixo mostra as duas fases.

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.

Escolher 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 de contexto orienta o planejamento: defina o pacote antes de escolher o banco de dados. A tabela abaixo ajuda a verificar se o mecanismo escolhido pode fornecer o contexto necessário para a 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: skills empacotam instruções de capacidades reutilizáveis; 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

A tabela lista abordagens de recuperação a considerar para diferentes formatos de dados. Escolha com base em perguntas representativas, nas evidências necessárias para cada resposta e no custo de recuperá-las; avalie se os resultados retornados cobrem essas evidências.

Forma	Exemplos	Abordagem a considerar
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)

O exemplo de prosa não estruturada recupera passagens de um corpus e pede ao modelo que responda com base nelas. Verifique se essas passagens sustentam a resposta.

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 com uma instrução para usar essas passagens.

Outros recuperadores podem usar busca por palavras-chave ou consultas estruturadas. Escolha o método de recuperação adequado aos seus dados e depois inspecione quais evidências ele fornece ao gerador.

Representar texto com embeddings para busca por similaridade

Este recuperador vetorial representa trechos de texto e consultas como embeddings. Um embedding é uma representação numérica aprendida de um trecho de texto: um vetor de comprimento fixo posicionado de modo que textos semanticamente semelhantes fiquem próximos no espaço vetorial. Isso tem 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.

Ambas as operações usam o modelo de embeddings, chamado por helpers.embed neste curso. Configure o endpoint de embeddings e a credencial exigida no painel do modelo. O navegador envia seu texto pela rota selecionada. Se o serviço de embeddings estiver indisponível, inspecione a solicitação e o erro retornado.

Revisar 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 contém um array data. Cada entrada inclui um campo embedding do tipo number[].

O modelo de embeddings da NVIDIA usa input_type para distinguir consultas de passagens. Seu treinamento para recuperação busca associar perguntas a passagens que as respondem. Inverter "query" e "passage" pode alterar as pontuações e reduzir a qualidade da recuperação sem causar um erro de API. Verifique os tipos e avalie as passagens retornadas.

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/nemotron-3-embed-1b, servido por integrate.api.nvidia.com por meio do proxy do curso.

Recuperar 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:

Chunks curtos concentram o embedding em uma passagem mais restrita, mas podem omitir o contexto necessário para responder à pergunta.
Documentos longos incluem mais contexto, mas representar vários tópicos em um único embedding pode diluir a correspondência com uma pergunta específica.

Uma abordagem indexa em dois níveis. Chunks pequenos recebem embeddings para a recuperação; uma correspondência seleciona o documento pai para fornecer mais contexto a uma etapa posterior de geração.

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

Geramos embeddings e pesquisamos os pequenos trechos filhos; cada correspondência seleciona o documento pai completo como contexto para uma etapa posterior de geração.

Deixar 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.

Você pode manter a interface da ferramenta e substituir a busca por cosseno em memória por um executor no servidor com FAISS+BM25+reranking. Valide seus resultados e seu comportamento em caso de falha antes de usá-lo no ciclo.

Comparar 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.

Explorar 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.

Com K definido como 3, top-K retorna três correspondências do exemplo com mil passagens. A geração recebe essas passagens selecionadas, que podem não cobrir temas presentes em outras partes do corpus. GraphRAG (Edge et al. 2024) muda a forma do problema em vez de aumentar K. Usa um LLM durante a indexação 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 compara, em um corpus pequeno, a recuperação top-K com a etapa de resumos de comunidades usada no GraphRAG. Os grupos são rótulos definidos pelo autor, não um grafo extraído pelo modelo. A rota de resumos recebe todos os grupos e seus nomes; top-K recebe apenas as passagens selecionadas. Verifique quais afirmações cada resposta sustenta e depois altere K, os grupos ou a pergunta.

Uma seleção top-K pequena pode omitir evidências necessárias para perguntas sobre todo o corpus. Resumos de comunidades podem ampliar a cobertura, mas seus agrupamentos e resumos também precisam ser avaliados. Este exemplo gera resumos a cada execução; um sistema maior pode criá-los e armazená-los antes das consultas.

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?

Rastrear 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). Uma biblioteca de busca por similaridade entre vetores densos.
Gao et al., HyDE: Precise Zero-Shot Dense Retrieval without Relevance Labels (2022). Gera uma resposta hipotética e calcula seu embedding para a recuperação.
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 →