Capítulo 36 — Busca, Vetores e Indexação Semântica

36.1 Objetivo do Capítulo

Este capítulo detalha a arquitetura de busca textual, busca vetorial (semântica) e indexação para a Plataforma de Relacionamento Digital com o Cidadão. Descreve como dados estruturados e não estruturados são indexados, consultados e recuperados com relevância, segregação por tenant e conformidade com LGPD.

O capítulo aborda: busca textual com mecanismo especializado (ex.: ElasticSearch), busca vetorial para RAG e assistente de IA, embeddings, modelos de similaridade, índices como projeções reconstruíveis, isolamento multi-tenant, qualidade de busca, observabilidade e operação.

36.2 Contexto e Papel da Busca na Plataforma

A busca ocorre em dois contextos distintos com tecnologias e governança diferentes:

36.2.1 Busca Textual (Administrativa e Catálogo)

Interfaces administrativas e de catálogo exigem busca textual rápida e relevante:

• catálogo de serviços (por nome, descrição, categoria);
• pesquisa em documentos e conteúdo (OCR + metadados);
• busca de workflows, tarefas, protocolos em padrões específicos;
• pesquisa administrativa de cidadãos, empresas, solicitações.

Tecnologia: ElasticSearch (ou equivalente especializado em busca textual).

Característica: índice é projeção reconstruível a partir do banco operacional. Falta de dados no índice não afeta a consistência transacional.

36.2.2 Busca Vetorial (IA e RAG)

A busca semântica alimenta o copiloto de IA e o RAG:

• recuperação de documentos e artigos relevantes para uma pergunta;
• busca por similaridade em base de conhecimento do tenant;
• contexto para a geração de respostas pelo LLM;
• classificação automática de manifestações.

Tecnologia: Vector Store segregado por tenant (Weaviate, Pinecone, Milvus ou equivalente).

Característica: vetores (embeddings) são reconstruíveis a partir do conteúdo original. O modelo de embedding é versionado para permitir reindexação quando o modelo evolui.

36.3 Busca Textual — Arquitetura

36.3.1 Pipeline de Indexação

Conteúdo (serviço, documento, manifesto)
    │
Document Service valida e classifica
    │
Enriquecimento (metadados, OCR quando necessário)
    │
Serialização para índice
    │
ElasticSearch indexa em tenant namespace
    │
Publicação de search.indexed.v1
    │
Frontend atualiza com índice fresco

36.3.2 Estrutura do Índice

Cada tenant tem namespace próprio no ElasticSearch:

platform-v1-tenant-{tenantId}-catalog
platform-v1-tenant-{tenantId}-documents
platform-v1-tenant-{tenantId}-requests

A versão do índice (v1) permite invalidar todo um índice sem afetar outros. Quando o schema do índice muda de forma incompatível, um novo índice (v2) é criado em paralelo, dados são reindexados, e o alias aponta para o novo índice.

36.3.3 Campos Indexados

{
  "tenantId": "tenant-uuid",
  "entityType": "service",
  "entityId": "service-uuid",
  "title": "Habilitação de Motorista",
  "description": "...",
  "category": "habilitação",
  "keywords": ["habilitação", "cnh", "motorista"],
  "content": "...",
  "createdAt": "2026-07-16T10:30:00Z",
  "updatedAt": "2026-07-16T10:30:00Z",
  "acl": ["role:CITIZEN", "unit:central"]
}

36.3.4 Consultas com Relevância

A relevância é configurada por tipo de entidade:

{
  "query": {
    "bool": {
      "must": [
        { "term": { "tenantId": "tenant-uuid" } }
      ],
      "should": [
        { "match": { "title": { "query": "habilitação", "boost": 3 } } },
        { "match": { "description": { "query": "habilitação", "boost": 1 } } },
        { "match": { "keywords": { "query": "habilitação", "boost": 2 } } }
      ]
    }
  }
}

36.3.5 Paginação e Performance

Consultas no ElasticSearch usam paginação com limit+offset para interfaces administrativas, e search_after para consumidores em lote.

GET /search?query=habilitação&page=0&size=20

Response: 
{
  "items": [...20 resultados],
  "totalHits": 1234,
  "page": 0,
  "size": 20,
  "searchAfter": [1234, "service-uuid-xyz"]
}

36.4 Busca Vetorial — Arquitetura

36.4.1 Pipeline de Embedding

Conteúdo autorizado (documento, artigo, FAQ, manifesto)
    │
Validação de acesso e classificação
    │
Sanitização e chunking (split em segmentos de ~500 tokens)
    │
Geração de embedding via modelo (ex.: multilingual-e5-large)
    │
Armazenamento no Vector Store do tenant
    │
Publicação de ai.knowledge-indexed.v1
    │
RAG Service busca vetorial e compõe contexto para LLM

36.4.2 Modelo de Embedding

O modelo de embedding é escolhido conforme: suporte a idioma (português, múltiplos idiomas), dimensionalidade, performance, e conformidade com política de dados (modelos locais vs. externos).

Opções:

• sentence-transformers/multilingual-e5-large — multilíngue, 1024 dimensões, local
• OpenAI text-embedding-3-small — 1536 dimensões, excelente qualidade, requer API externa
• Outros modelos especializados por domínio (legal, saúde)

O modelo é registrado no Vector Store com metadado de versão. Quando o modelo evolui, uma reindexação é planejada e executada sem impacto na busca corrente (versão antiga mantida até nova estar pronta).

36.4.3 Estrutura do Vector Store

Cada tenant tem coleção segregada:

Coleção: platform-tenant-{tenantId}-knowledge
  │
  Documentos:
  {
    "id": "chunk-uuid",
    "tenantId": "tenant-uuid",
    "sourceId": "document-uuid",
    "sourceType": "document|faq|article|guide",
    "chunkIndex": 0,
    "text": "Conteúdo do chunk...",
    "embedding": [0.123, -0.456, ...1024 valores],
    "metadata": {
      "title": "...",
      "classification": "public|internal|confidential",
      "tags": ["habilitação", "cnh"],
      "createdAt": "2026-07-16T10:30:00Z",
      "acl": ["role:CITIZEN", "unit:central"]
    }
  }

36.4.4 Consulta Vetorial (Semantic Search)

A busca por similaridade recupera chunks relevantes semanticamente:

Pergunta: "Quais documentos preciso para tirar a habilitação?"
    │
Geração de embedding da pergunta
    │
Busca de top-k chunks mais similares
    │
Filtragem por ACL (usuário pode acessar?)
    │
Retorno de chunks ordenados por similaridade
    │
Contexto composto para LLM

36.4.5 Chunking e Overlapping

Documentos são divididos em chunks de tamanho consistente (ex.: ~500 tokens, ~2000 caracteres) com overlapping (ex.: 50 tokens) para manter continuidade semântica entre chunks.

Documento original (10.000 caracteres)
    │
Chunk 1: caracteres 0-2000
Chunk 2: caracteres 1950-3950  (overlap de 50 chars)
Chunk 3: caracteres 3900-5900
...

O overlapping melhora a recuperação de informações que ficam próximas da borda de um chunk.

36.4.6 Similaridade e Threshold

A busca retorna chunks com score de similaridade acima de threshold configurável (ex.: 0.7):

Top-5 chunks:
1. score: 0.89 ← acima do threshold, incluído
2. score: 0.82 ← acima do threshold, incluído
3. score: 0.75 ← acima do threshold, incluído
4. score: 0.62 ← abaixo do threshold, excluído
5. score: 0.58 ← abaixo do threshold, excluído

Quando nenhum chunk passa no threshold, o RAG informa ao LLM que não há conteúdo relevante e o modelo responde com base em seu conhecimento implícito com ressalva.

36.5 Isolamento Multi-Tenant em Busca

36.5.1 Segregação Estrutural

A segregação não é apenas por filtro de aplicação. Cada tenant tem:

Busca Textual:

• índice dedicado no ElasticSearch (ex.: platform-v1-tenant-{tenantId}-catalog)

Busca Vetorial:

• coleção dedicada no Vector Store (ex.: platform-tenant-{tenantId}-knowledge)

Benefício: uma falha na query de um tenant não expõe dados de outro; reindexação isolada por tenant.

36.5.2 Filtro de Tenant em Queries

Mesmo com segregação estrutural, toda query inclui filtro explícito de tenant como camada adicional:

{
  "query": {
    "bool": {
      "must": [
        { "term": { "tenantId": "abc-def-ghi-jkl" } }
      ],
      "filter": [
        { "match": { "content": "habilitação" } }
      ]
    }
  }
}

O tenantId validado vem sempre do Tenant Context — nunca de parâmetro enviado pelo cliente.

36.5.3 ACL em Documentos Indexados

Documentos indexados podem ter ACL (access control list) codificada:

{
  "tenantId": "tenant-uuid",
  "title": "Roteiro Interno",
  "acl": ["role:ADMIN", "unit:central"]
}

A query filtra por ACL do usuário:

{
  "bool": {
    "must": [
      { "term": { "tenantId": "tenant-uuid" } }
    ],
    "filter": [
      { "terms": { "acl": ["role:CITIZEN", "unit:central", "ANY_USER"] } }
    ]
  }
}

36.6 Índice como Projeção Reconstruível

36.6.1 Princípio

O índice de busca não é fonte de verdade. É uma projeção otimizada do banco de dados operacional. Em caso de inconsistência:

1. o banco operacional prevalece;
2. o índice é reconstruído (reindexação).

Implicação: perda ou corrupção de dados no índice não afeta a consistência transacional.

36.6.2 Reindexação

Reindexação completa é executada quando:

• schema do índice muda de forma incompatível;
• modelo de embedding evolui (busca vetorial);
• corrupção é detectada;
• migração de plataforma de busca (ex.: ElasticSearch → Opensearch).

Processo:

1. Criar novo índice (ex.: v2)
2. Ler dados do banco operacional em batches
3. Indexar chunks no novo índice
4. Validar cobertura e amostras
5. Testar queries em v2 em paralelo com v1
6. Atualizar alias para apontar para v2
7. Manter v1 por período de rollback (24h)
8. Deletar v1

A reindexação não bloqueia buscas — v1 permanece operacional enquanto v2 é construído.

36.6.3 Indexação Incremental

A maioria das alterações são incrementais:

Documento atualizado no Document Service
    │
Evento document.updated.v1 publicado
    │
Search Indexer consome evento
    │
Atualiza chunks afetados no índice
    │
Publica search.indexed.v1

A indexação incremental é rápida (segundos) e mantém o índice próximo ao estado real.

36.7 Observabilidade de Busca

36.7.1 Métricas de Qualidade

• Cobertura: % de documentos indexados em relação aos documentos no banco operacional
• Latência: p50, p95, p99 de tempo de busca
• Taxa de erro: % de queries que falharam ou retornaram erro
• Taxa de sem resultado: % de queries que não retornaram hits (pode indicar problema de índice ou pouca cobertura)
• Relevância: score médio dos hits retornados

36.7.2 Alertas

• índice com cobertura < 95%;
• latência de busca p99 > 2000ms;
• falha de reindexação;
• tamanho de índice crescendo anormalmente;
• taxa de sem resultado > 10% (possível degradação).

36.7.3 Logs Estruturados

{
  "timestamp": "2026-07-16T10:30:00Z",
  "event": "search.executed",
  "tenantId": "tenant-uuid",
  "query": "habilitação",
  "indexType": "catalog",
  "resultCount": 23,
  "latencyMs": 145,
  "scoreMin": 0.72,
  "scoreMax": 0.95,
  "userId": "user-uuid",
  "correlationId": "corr-xyz"
}

36.8 Governance e Evolução

36.8.1 Versionamento de Índices

Schema de índice é versionado:

platform-v1-tenant-{tenantId}-catalog
  └─ schema v1 (estrutura atual)

platform-v2-tenant-{tenantId}-catalog
  └─ schema v2 (compatível com queries antigas via alias)

Mudanças no schema que mantêm compatibilidade (ex.: novo campo adicional) usam v1. Mudanças incompatíveis usam nova versão.

36.8.2 Evolução de Modelos de Embedding

Quando o modelo de embedding evolui:

Modelo v1: multilingual-e5-large
    │
Deprecado por: multilingual-e5-large-v2 (melhor qualidade, dimensionalidade diferentes)
    │
Novo índice criado com embeddings v2
    │
Perfeito para novos chunks
    │
Chunks antigos mantêm embeddings v1 (compatível)
    │
Gradualmente reindexados com v2
    │
Após cobertura 100%, v1 é descontinuado

36.8.3 Política de Depreciação

Versões antigas de índice ou modelo são descontinuadas após período:

• v1 suportada por 90 dias após v2 GA (disponibilidade geral);
• v1 descontinuada em data pública (ex.: 2026-10-15);
• clients com v1 recebem aviso de depreciação.

36.9 Performance e Custo

36.9.1 Sizing

O tamanho do índice depende de: volume de documentos, média de bytes por documento, fatores de compressão do mecanismo de busca.

Estimativa:

• 1 milhão de documentos, 10KB médio → ~50GB em ElasticSearch (com compressão)
• 1 milhão de chunks vetoriais, 1024 dimensões → ~4GB em vector store

36.9.2 Resource Allocation

ElasticSearch requer: memória JVM para heap, espaço em disco para índices, rede para replicação. Vector store requer: memória para índice em memória (HNSW), espaço para persistência.

Ambos devem ser dimensionados por tenant isoladamente (modelo de banco/schema por tenant garante isso).

36.9.3 Custo Total

ElasticSearch: nós (CPU, RAM, disco) + operação
Vector Store: cluster ou SaaS (ex.: Pinecone com preço por milhão de embeddings)
Modelo de Embedding: local (CPU/GPU) ou API externa (por token)
Operação: monitoring, backups, reindexação

36.10 Rastreabilidade com o Anexo III

36.11 Benefícios

• busca textual rápida em catálogos e documentos;
• busca semântica inteligente para IA e RAG;
• isolamento estrutural de dados por tenant;
• índice reconstruível garante consistência;
• observabilidade detalhada de qualidade e performance;
• evolução gradual de modelos e schemas sem downtime.

36.12 Riscos e Mitigações

36.13 Decisões Arquiteturais

36.14 Considerações Finais

A busca é um multiplicador de experiência: uma busca rápida e relevante aumenta drasticamente a capacidade do cidadão e do gestor de encontrar informações e tomar decisões. Uma busca lenta ou imprecisa frustra e afasta usuários.

A arquitetura de busca descrita prioriza: isolamento por tenant, qualidade de índice, observabilidade, e capacidade de evolução sem impacto em disponibilidade. O índice é tratado como projeção — o que significa que o sistema é resiliente a falhas de busca e capaz de se recuperar rapidamente.

O Capítulo 37 detalha Infraestrutura e Computação em Nuvem, que hospeda esses mecanismos de busca.

36.15 Controle de Versão

36.16 Rastreabilidade PRODEMGE

• [ANX-III] Bloco 5 — Busca semântica e IA: item 5.2 (RAG com base vetorial); 5.1 (busca de documentos).
• [ANX-III] Bloco 2 — Busca de serviços: item 1.1 (catálogo); 1.2 (descoberta de serviços).
• [ANX-IV] — Capacidades de busca textual e vetorial; isolamento multi-tenant; observabilidade.
• [ANX-V] Item 2.3 — Proteção de dados: minimização de PII em índices; redaction conforme classificação.
• [PNR] — Busca como capacidade transversal da plataforma: catálogo, documentos, IA.
• [EDITAL] — Busca integrada em todos os módulos; RAG para assistente de IA; relevância semântica para experiência do cidadão.