Para consultar documentos confidenciais no Weaviate, combine autenticação, permissões por função e uma separação de dados coerente com as fronteiras de acesso. O modelo de linguagem deve receber apenas trechos que o usuário já está autorizado a ler. Uma instrução no prompt para “respeitar o sigilo” não substitui a autorização aplicada antes da busca.
Em um acervo jurídico, a equipe de engenharia precisa traduzir a matriz de acesso aprovada pela organização em coleções, tenants e papéis. Este guia trata dessa implementação técnica, incluindo ingestão, consulta e testes de isolamento. Não determina quem deve ter acesso a cada documento nem estabelece critérios jurídicos para retenção ou compartilhamento.
Resumo rápido
- Autenticação identifica o usuário; RBAC define suas permissões.
- O papel de consulta deve alcançar somente os recursos necessários.
- Tenants ajudam a separar conjuntos de dados, mas a aplicação deve selecionar o tenant autorizado.
- Permissões concedidas por vários papéis se acumulam; uma ausência de permissão não funciona como veto.
- Teste tentativas de acesso indevido também por IDs, citações e cache.
- Proteja originais, vetores, logs e cópias de segurança como partes do mesmo sistema.
Desenhe a fronteira antes de criar o banco
Comece por uma matriz que cruze identidade, conjunto documental e operação. Separe consulta, ingestão, administração e recuperação de backup. Um profissional pode consultar determinado assunto sem poder enviar novos documentos; um serviço de ingestão pode escrever em um conjunto específico sem administrar usuários. Defina os responsáveis por aprovar mudanças nessa matriz.
Os embeddings representam conteúdo para permitir busca por proximidade de significado. Eles não carregam, por si, uma autorização confiável. Preserve no registro a origem, a versão e a classificação de acesso recebida do sistema responsável. Se a origem não informa quem pode consultar um arquivo, deixe-o fora do índice até resolver a classificação.
Escolha uma unidade de isolamento que corresponda à operação real. Separar por cliente pode funcionar quando todos os documentos de um cliente têm a mesma fronteira. Se houver equipes distintas dentro desse cliente, a divisão precisa ser mais fina ou complementada por um mecanismo de autorização adequado. Um campo chamado “confidencial” apenas descreve o conteúdo; não impede acesso.
Documente também as rotas de saída: resposta do chat, download, prévia, exportação e link de citação. O usuário não deve recuperar um arquivo restrito por um endereço direto depois de ter sua consulta negada. Trate cada rota como um ponto de autorização, inclusive operações de suporte e depuração.
Combine identidade, RBAC e isolamento por tenant
A documentação de autenticação do Weaviate descreve os mecanismos disponíveis, incluindo chaves de API e OIDC. Escolha o fluxo de identidade antes de configurar os papéis. Em uma aplicação com login corporativo, verifique como a identidade autenticada chega ao banco e como a revogação se propaga.
O RBAC do Weaviate associa usuários a papéis com permissões sobre recursos. As permissões distinguem definições de coleções, dados e tenants. Ter acesso à definição de uma coleção não equivale a receber todas as operações sobre seus objetos. Evite o papel amplo de leitura quando a pessoa deveria enxergar somente uma parte do acervo.
Na arquitetura multitenant documentada, cada tenant usa um shard separado e seus dados não ficam visíveis a outro tenant. Isso organiza a separação do armazenamento e das consultas. Ainda assim, o backend precisa validar qual tenant a identidade pode selecionar. Copiar um identificador enviado pelo navegador diretamente para a busca cria uma brecha na aplicação.
| Camada | Pergunta respondida | Controle proposto |
|---|---|---|
| Autenticação | Quem está fazendo a chamada? | Identidade verificada e credencial válida |
| Autorização | Que ações essa identidade pode executar? | Papéis com menor privilégio |
| Isolamento | Em qual conjunto a busca acontece? | Tenant ou coleção com fronteira definida |
| Entrega | Quais trechos podem sair do sistema? | Validação de resposta e citações |
Use uma identidade administrativa apenas na configuração controlada. O serviço que atende perguntas não precisa criar papéis, atribuir privilégios ou gerenciar backups. Registre separadamente as credenciais de ingestão e consulta. Rotação deve ser uma operação prevista, com teste de revogação da chave anterior.
Estruture a ingestão com origem e versão
Monte uma coleção de trechos com identificador estável, documento de origem, versão, página, texto e referência de acesso. A seleção do tenant ocorre antes de inserir os objetos. O serviço recebe essa informação de uma fonte confiável e valida se o destino existe. Para documentos confidenciais, prefira criar destinos por um fluxo administrativo explícito, evitando que um erro de digitação abra um conjunto novo.
Divida os documentos em trechos que preservem contexto suficiente para recuperação. Uma cláusula cortada antes da ressalva pode gerar uma resposta enganosa. Mantenha títulos e localização de página quando isso ajudar a interpretação. A qualidade da divisão e a precisão do OCR devem ser avaliadas separadamente das permissões: um índice isolado ainda pode devolver conteúdo mal extraído.
Não use o nome de cliente ou o título sensível como identificador exposto desnecessariamente. IDs opacos reduzem informações em URLs e logs, embora não substituam autorização. Guarde o mapeamento para o original em um serviço que também valide acesso ao download. As referências devolvidas ao usuário devem passar por esse mesmo serviço.
Quando uma versão muda, defina como remover trechos antigos e como invalidar respostas em cache. Registre o estado da ingestão para não misturar versões incompletas. Um mecanismo simples é publicar a nova versão somente depois de conferir quantidade de trechos, metadados e permissões, mantendo o lote anterior recuperável para diagnóstico interno.
Implemente consulta e teste as negações
O fluxo recomendado começa no login, resolve os conjuntos permitidos e só então executa a busca. Depois, seleciona trechos, monta o contexto e chama o modelo. O desenho básico de RAG com bancos vetoriais permanece, mas a autorização participa da recuperação. Filtrar uma resposta depois de enviar conteúdo proibido ao modelo já é tarde para impedir a exposição.
A página oficial de gerenciamento de papéis traz exemplos para criar permissões e atribuí-las a usuários. Use os exemplos correspondentes às versões instaladas do servidor e do cliente. Transforme a matriz aprovada em configuração revisável, com nomes explícitos e sem curingas amplos por conveniência.
Um roteiro de implementação pode ser expresso sem depender de uma assinatura específica de SDK:
identidade = autenticar_requisicao()
conjuntos = resolver_acessos_no_servidor(identidade)
alvo = validar_destino_solicitado(conjuntos)
resultados = buscar_com_credencial_restrita(alvo, pergunta)
contexto = montar_contexto_com_fontes(resultados)
resposta = gerar_resposta(contexto)
validar_acesso_as_citacoes(identidade, resposta)
Esse pseudocódigo não é uma implementação pronta. O ponto central é a ordem: resolver autorização antes de acessar conteúdo. Se usar uma conta técnica compartilhada, reconheça que o banco verá essa conta, e a distinção entre usuários dependerá dos controles da aplicação. Uma conta com acesso a todo o acervo torna um erro no backend mais grave.
Crie documentos sintéticos com marcadores exclusivos para dois conjuntos. Teste uma identidade que só lê o primeiro, outra que só lê o segundo e uma sem acesso. Consulte pelos termos do conteúdo, pelo identificador do objeto e pelo link de origem. Verifique também busca híbrida, exportação e caminhos de erro que existam no produto.
Inclua mudança de equipe e revogação no teste. Uma sessão já aberta não deve continuar recebendo conteúdo novo após perder a autorização conforme o comportamento definido para o sistema. Documente tempos de expiração, invalidação de cache e revalidação. Um teste de segurança incompleto pode aprovar o login e esquecer toda a vida útil da sessão.
Exemplo: acervo de um escritório em Belo Horizonte
Imagine um escritório em Belo Horizonte com equipes que atendem empresas diferentes. O cenário é ilustrativo. A administração fornece uma matriz aprovada em que a equipe Alfa consulta um conjunto e a equipe Beta consulta outro. A engenharia começa com documentos fictícios e dois tenants para validar essa separação.
O serviço de ingestão recebe cada arquivo com o destino já aprovado. Ele extrai o texto, identifica páginas e prepara os vetores. A consulta utiliza uma identidade sem poderes administrativos. No portal, o seletor de acervo exibe somente opções resolvidas pelo servidor; alterar o identificador na requisição não deve liberar um terceiro destino.
Durante a validação, a equipe inclui uma frase exclusiva no conjunto Beta e tenta recuperá-la com o acesso Alfa. O teste deve falhar também quando a pergunta pede “todos os contratos semelhantes”, quando conhece o ID do objeto e quando tenta abrir a citação diretamente. O resultado esperado é ausência de conteúdo restrito, sem revelar títulos ou trechos nos detalhes do erro.
Antes de ampliar o piloto, a organização simula a saída de uma pessoa da equipe. A engenharia verifica revogação, sessões e cache. A aprovação do piloto depende dessas evidências e da qualidade das referências, não da fluência do resumo. O assistente devolve passagens localizáveis para revisão profissional; não decide a interpretação jurídica do material.
Erros comuns
Usar um papel de leitura global. Ler sem editar ainda permite exposição. Aplique escopo aos recursos necessários e confira a combinação de papéis. No modelo documentado pelo Weaviate, permissões concedidas se acumulam: deixar uma permissão falsa em um papel não cancela a concessão feita por outro.
Confundir filtro de busca com fronteira de segurança. Um filtro de metadados pode fazer parte da implementação, mas precisa ser obrigatório e aplicado em todas as rotas relevantes. Se outra chamada consulta diretamente um objeto sem passar por ele, a proteção está incompleta. Valide a arquitetura inteira com credenciais reais de teste.
Compartilhar cache apenas pela pergunta. Duas pessoas podem fazer a mesma pergunta e ter direitos diferentes. Inclua identidade ou escopo autorizado, versão documental e versão da política na estratégia de cache. Se não conseguir demonstrar o isolamento, desative o reaproveitamento entre usuários.
Registrar trechos sensíveis em logs. Prefira IDs de requisição, recursos consultados, decisão de autorização e códigos de erro. Defina acesso e retenção para os registros. Backups, métricas e ferramentas de observabilidade também devem entrar no inventário técnico de dados do projeto.
Entregar o acervo inteiro a um serviço externo. Embeddings e geração podem envolver processadores diferentes. Mapeie o destino do texto em cada etapa e aprove a arquitetura conforme os requisitos da organização. Não presuma que executar o banco internamente significa executar todo o processamento no mesmo ambiente.
Perguntas frequentes
RBAC resolve autorização por documento?
Não presuma que toda regra de acesso documental corresponde diretamente a um recurso nativo do banco. A documentação descreve escopos de coleção e tenant para permissões de dados. Quando a política exige granularidade diferente, redesenhe a separação ou implemente uma camada adicional e teste todas as rotas.
Preciso criar uma coleção para cada cliente?
Não necessariamente. Multitenancy permite separar conjuntos dentro de uma coleção. A escolha depende da estrutura dos dados, da política de acesso e da operação. Use uma coleção separada quando houver motivo claro, evitando multiplicar estruturas antes de definir a fronteira necessária.
Posso usar uma chave administrativa no backend?
Ela pode ser necessária em tarefas administrativas isoladas, mas não deve ser a credencial cotidiana do chat. Separe provisionamento, ingestão e consulta. Se o backend for comprometido, a credencial disponível limita ou amplia o impacto.
Como comprovar que o isolamento funciona?
Monte testes negativos com documentos sintéticos exclusivos, identidades distintas e tentativas por cada rota. Guarde resultados reproduzíveis e repita após mudanças em papéis, clientes, servidor ou cache. Uma demonstração manual bem-sucedida de busca autorizada não substitui esses testes.
