Filtros de metadados em RAG: como implementar

Uma resposta pode usar o documento certo no contexto errado

Uma empresa indexa contratos, políticas e chamados para responder dúvidas internas. A pergunta menciona um produto conhecido. A busca semântica encontra uma cláusula muito parecida, mas o trecho pertence a outro cliente e a uma versão contratual anterior.

O resultado parece relevante porque o texto fala do assunto correto. Operacionalmente, ele está fora do escopo da consulta.

Filtros de metadados em RAG restringem quais registros podem participar da recuperação. Cliente, unidade, produto, idioma, versão, vigência, classificação e permissão deixam de ser observações anexas e passam a definir o universo pesquisável.

Essa camada tem dois trabalhos. Ela reduz ruído para melhorar a precisão da busca e impede que conteúdo inadequado chegue ao reranker, ao modelo de resposta ou aos logs. Os dois objetivos precisam de testes separados, porque um filtro pode melhorar relevância média e ainda falhar numa fronteira de acesso.

O que são metadados em um sistema RAG

Cada trecho indexado carrega o conteúdo usado na busca e campos que descrevem sua identidade e seu escopo. Esses campos são os metadados.

Um registro pode incluir:

chunk_id: ctr_841_v3_sec_12_p2
document_id: ctr_841
cliente_id: cli_209
produto: manutencao-premium
versao: 3
vigente_desde: 2026-04-01
vigente_ate: null
classificacao: confidencial
grupo_acesso: contratos-cli-209
idioma: pt-BR
status: aprovado

O vetor representa proximidade semântica. Os metadados preservam condições que não deveriam depender dessa proximidade. Um contrato de outro cliente pode ser semanticamente excelente para a pergunta e continuar proibido.

A documentação da Pinecone sobre filtros por metadados mostra consultas que limitam a pesquisa por expressões sobre campos associados aos registros. O recurso técnico varia entre fornecedores. A responsabilidade de definir campos, autoridade e política continua com a empresa.

Separe identidade, elegibilidade e ranking

Três decisões costumam ser misturadas numa única consulta.

Identidade

Define quem pergunta e sobre qual objeto. Usuário, empresa, cliente, contrato, pedido e produto precisam de identificadores confirmados quando alteram o escopo.

Um nome extraído da pergunta pode ajudar a localizar candidatos. Para autorizar acesso, use identidade autenticada e vínculos registrados em fonte oficial. O texto digitado pelo usuário não concede permissão.

Elegibilidade

Decide quais documentos podem entrar na busca. Essa etapa aplica cliente, ambiente, classificação, vigência, finalidade e status editorial.

O resultado é um conjunto permitido. Conteúdo fora desse conjunto deve ficar indisponível para as etapas seguintes, mesmo que possua score semântico alto.

Ranking

Ordena os registros elegíveis por relevância. Busca textual, vetorial, híbrida e reranking trabalham aqui.

O artigo sobre busca híbrida para RAG explica como combinar sinais de texto e vetores. O filtro vem antes como política de universo. Ranking não corrige autorização.

Quais campos merecem virar filtros

Inclua um campo quando ele muda a elegibilidade do conteúdo ou permite investigar uma resposta. Evite copiar todos os atributos da fonte sem função definida.

Cliente e unidade organizacional

Ambientes com várias empresas, filiais ou projetos precisam de uma chave estável de isolamento. Nome comercial é frágil. Prefira identificadores internos que não mudem com abreviação ou grafia.

Quando um documento pode ser compartilhado, registre essa condição de forma explícita. Não use ausência de cliente_id como sinônimo de conteúdo público. Campo vazio também pode indicar falha de ingestão.

Documento, versão e vigência

Cada trecho deve apontar para documento e versão. Datas ajudam a selecionar o conteúdo aplicável, mas precisam de uma regra para sobreposição, retroatividade e casos sem data final.

Status como rascunho, em_revisao, aprovado, substituido e revogado reduz o risco de uma minuta aparecer como política vigente. O sistema deve bloquear estados desconhecidos em tarefas que exigem fonte aprovada.

Produto, processo e tipo documental

Esses campos reduzem ruído quando a mesma linguagem aparece em domínios diferentes. "Cancelamento" pode existir em contrato, pedido, assinatura, chamado e política de acesso.

Use taxonomias pequenas o bastante para serem mantidas. Uma classificação detalhada que chega vazia em metade do acervo oferece pouca proteção e cria falsa precisão.

Classificação e finalidade

A classificação de dados para agentes de IA define o tratamento exigido ao longo do fluxo. No RAG, parte dessa política se transforma em campos e condições de recuperação.

A finalidade importa porque o mesmo usuário pode consultar um documento para atendimento e não ter autorização para reutilizá-lo em prospecção ou treinamento. A política precisa receber tarefa e finalidade, além da identidade.

Idioma e região

Idioma pode melhorar recuperação e apresentação. Região pode determinar política, contrato ou obrigação aplicável. Nenhum deles deve ser inferido apenas pela língua da pergunta quando a consequência depende de jurisdição ou unidade de negócio.

Pré-filtro e pós-filtro produzem riscos diferentes

No pré-filtro, a restrição reduz o conjunto antes da busca vetorial. No pós-filtro, o mecanismo encontra candidatos num universo mais amplo e filtra o resultado depois.

A documentação do Azure AI Search sobre índices vetoriais registra modos de aplicação do filtro antes ou depois da busca. O comportamento exato depende do produto e da configuração.

Pré-filtro é a opção mais segura para fronteiras de cliente, permissão e classificação, pois o conteúdo inelegível não participa da recuperação. Ele pode reduzir a quantidade de candidatos em segmentos muito pequenos, o que exige ajuste de índice e teste de cobertura.

Pós-filtro pode retirar todos os primeiros resultados depois da busca. A aplicação recebe poucos itens ou nenhum, embora existam documentos permitidos mais abaixo. Aumentar o número de candidatos pode aliviar cobertura, mas amplia custo e não resolve o problema de exposição se os registros proibidos já atravessaram componentes intermediários.

Para acesso, a regra prática é simples: aplique a restrição antes que o conteúdo chegue a qualquer componente sem autorização. Pós-filtro pode servir para preferências de apresentação de baixo risco, desde que a empresa entenda seu efeito sobre a recuperação.

Modele a política fora do prompt

Uma instrução como "responda somente com documentos deste cliente" chega depois que o modelo recebeu os trechos. Ela também depende de interpretação probabilística para cumprir uma regra objetiva.

A aplicação deve construir um filtro a partir de atributos confirmados:

identidade autenticada
+ cliente e unidade autorizados
+ finalidade da tarefa
+ classes de dados permitidas
+ versões e vigência aplicáveis
+ estado editorial aceito
= expressão de elegibilidade

Valide a expressão antes da consulta. Campos obrigatórios ausentes devem bloquear ou encaminhar o caso, conforme o risco. Não retire silenciosamente uma condição para evitar resultado vazio.

A política pode viver num serviço de autorização, no orquestrador ou numa camada de policy as code. O ponto central é produzir uma decisão observável, testável e igual para busca textual, vetorial e híbrida.

Trate ausência, conflito e atraso de metadados

Metadados também falham. Uma atualização troca a versão do documento, mas parte dos trechos permanece com o status anterior. Um contrato recebe novo cliente durante migração. Uma permissão é revogada no sistema oficial e continua ativa no índice.

Defina como o fluxo reage a quatro estados:

• campo presente e válido;
• campo obrigatório ausente;
• valores conflitantes entre fontes;
• metadado vencido ou sem confirmação recente.

Em conteúdo sensível, ausência não deve ampliar acesso. Encaminhe para correção, use uma fonte alternativa autorizada ou informe que a base não possui evidência elegível.

A página sobre freshness de dados para agentes ajuda a definir a janela em que um atributo ainda sustenta uma decisão. Para versões e permissões, eventos de mudança devem atualizar o índice e também invalidar caches relacionados.

Teste relevância e isolamento separadamente

Um conjunto de avaliação precisa cobrir perguntas comuns e tentativas de atravessar fronteiras.

Testes de relevância

Inclua consultas em que:

• vários produtos usam vocabulário parecido;
• uma política genérica compete com um procedimento específico;
• documentos vigentes e substituídos possuem redação próxima;
• o usuário descreve o caso sem usar a taxonomia interna;
• um filtro muito restrito retira a evidência necessária.

Meça se a evidência correta aparece no conjunto recuperado e se sobrevive à seleção final. Compare a linha de base sem filtro apenas para entender o efeito, nunca para sugerir que uma configuração insegura pode ir à produção.

Testes de isolamento

Use identidades e permissões reais de teste, com dados sintéticos ou anonimizados. Tente consultar:

• outro cliente;
• unidade sem vínculo;
• versão revogada;
• rascunho não aprovado;
• classe acima da autorização;
• conteúdo permitido para outra finalidade;
• registro sem metadado obrigatório;
• trecho presente em cache após revogação.

Um único vazamento crítico deve aparecer como falha impeditiva, não diluído numa média de relevância. O isolamento entre clientes precisa alcançar índice, cache, reranker, logs e interface administrativa.

Observe o filtro em produção sem registrar conteúdo demais

Registre o suficiente para reconstruir a decisão:

• identidade da política e sua versão;
• usuário, aplicação e finalidade em identificadores protegidos;
• campos e operadores aplicados;
• quantidade de candidatos elegíveis;
• motivo de bloqueio ou resultado vazio;
• versões dos índices e componentes;
• documento escolhido em identificador;
• rota adotada quando faltou evidência.

Evite copiar o texto de documentos proibidos para explicar por que foram filtrados. O log pode registrar que uma regra retirou candidatos sem guardar título, trecho ou metadado sensível.

Monitore aumento de resultados vazios, consultas sem campo obrigatório, uso de versões substituídas, divergência entre autorização e índice e latência adicionada pelos filtros. Uma queda brusca após mudança de taxonomia pode indicar ingestão incompleta, não falta de conhecimento na base.

Checklist para liberar filtros de metadados em RAG

• [ ] Cada trecho possui identidade de documento e versão?
• [ ] Cliente, unidade e ambiente usam identificadores estáveis?
• [ ] Rascunhos, versões substituídas e documentos revogados ficam fora da busca?
• [ ] Permissão e finalidade são resolvidas por política, fora do prompt?
• [ ] A mesma restrição alcança busca textual, vetorial e híbrida?
• [ ] Conteúdo inelegível fica fora do reranker, do modelo e dos logs?
• [ ] Campos ausentes bloqueiam em vez de ampliar o universo?
• [ ] Atualizações invalidam índice e caches dentro da janela exigida?
• [ ] Os testes cobrem relevância, resultado vazio e travessia entre clientes?
• [ ] Falhas críticas de isolamento impedem a liberação?
• [ ] Logs preservam a decisão sem copiar conteúdo sensível?
• [ ] Existe um responsável por taxonomia, política e correção de metadados?

O filtro transforma contexto em regra executável

Uma biblioteca empresarial reúne documentos semanticamente parecidos que pertencem a clientes, versões e finalidades diferentes. A qualidade do RAG depende de recuperar o trecho útil dentro do universo permitido.

Filtros de metadados transformam essas condições em política aplicada antes da geração. Quando identidade, elegibilidade e ranking ficam separados, a equipe consegue melhorar a busca sem negociar fronteiras de acesso a cada ajuste de modelo.

Comece por um caso, poucos campos obrigatórios e testes de isolamento. Depois amplie a taxonomia conforme novas decisões exigirem contexto adicional. O índice deve refletir a arquitetura operacional da empresa, com fonte, escopo e responsabilidade visíveis.