Lab 85 — Recuperação híbrida e reranking

{
  "requisicaoRerank": {
    "query": "qual a garantia do item EL-4471-B?",
    "sources": [
      {"chunkId": "garantia-eletronicos-geral.md#chunk-2", "texto": "Garantia padrão de itens eletrônicos: 90 dias, sem cobrir mau uso."},
      {"chunkId": "garantia-material-eletrico.md#chunk-7", "texto": "Item EL-4471-B: garantia de 180 dias por exigência do fornecedor, mediante nota fiscal."},
      {"chunkId": "politica-frete-sul.md#chunk-1", "texto": "Frete para a região Sul segue tabela própria, revisada trimestralmente."}
    ],
    "numberOfResults": 5
  },
  "respostaRerank": {
    "resultados": [
      {"chunkId": "garantia-material-eletrico.md#chunk-7", "score": 0.94, "posicaoOriginal": 8},
      {"chunkId": "garantia-eletronicos-geral.md#chunk-2", "score": 0.31, "posicaoOriginal": 1},
      {"chunkId": "politica-frete-sul.md#chunk-1", "score": 0.02, "posicaoOriginal": 14}
    ]
  },
  "_comentario": "posicaoOriginal e a posicao no ranking fundido por RRF, antes do rerank. O chunk certo (chunk-7) estava na posicao 8 do ranking so-vetorial, subiu para o topo depois da fusao com BM25, e o cross-encoder confirma com score 0.94 — muito acima do segundo colocado."
}

# dominio-hibrido.tf — OpenSearch Service Multi-AZ, com o campo de texto (BM25) e o
# campo de vetor (k-NN) no MESMO índice. O search pipeline de fusão é criado por
# fora do Terraform — a API do OpenSearch para pipelines não tem recurso nativo no
# provider; confira a versão do provider antes de assumir isso mudou.

resource "aws_opensearch_domain" "recuperacao_hibrida" {
  domain_name    = "cadencia-recuperacao-hibrida"
  engine_version = "OpenSearch_2.19" # confira a versão GA mais recente antes de aplicar

  cluster_config {
    instance_type            = "r6g.large.search"
    instance_count            = 4          # 2 por AZ — sobrevive à perda de 1 zona
    zone_awareness_enabled    = true
    zone_awareness_config {
      availability_zone_count = 2
    }
    dedicated_master_enabled  = true
    dedicated_master_type     = "r6g.medium.search"
    dedicated_master_count    = 3
  }

  vpc_options {
    subnet_ids         = [aws_subnet.privada[0].id, aws_subnet.privada[1].id]
    security_group_ids = [aws_security_group.opensearch_hibrido.id]
  }

  encrypt_at_rest       { enabled = true }
  node_to_node_encryption { enabled = true }

  # Sem isto, quem alcança a porta (security group) e quem pode ler cada documento
  # (autorização) seriam a mesma pergunta — e não são. O usuário mestre vem do
  # Secrets Manager, nunca de senha fixa em variável de ambiente.
  advanced_security_options {
    enabled                        = true
    internal_user_database_enabled = false
    master_user_options {
      master_user_arn = aws_iam_role.opensearch_admin.arn
    }
  }
}

# pipeline-rrf.sh — cria o search pipeline de fusão no domínio já provisionado.
# O nome do processor de RRF mudou entre versões do OpenSearch — confira o nome
# exato disponível na versão do seu domínio antes de aplicar isto em produção.

DOMINIO="https://$(terraform output -raw opensearch_endpoint)"

curl -s -X PUT "$DOMINIO/_search/pipeline/hibrido-rrf" \
  -H "Content-Type: application/json" \
  --aws-sigv4 "aws:amz:us-east-1:es" \
  -d '{
    "description": "funde BM25 (campo texto) e k-NN (campo embedding) por RRF",
    "phase_results_processors": [
      {
        "score-ranker-processor": {
          "combination": { "technique": "rrf", "rank_constant": 60 }
        }
      }
    ]
  }'

# Confirma que o pipeline existe antes de referenciá-lo numa consulta
curl -s "$DOMINIO/_search/pipeline/hibrido-rrf" | jq .

// BuscaHibridaService.cs — dispara a consulta hybrid contra o mesmo índice,
// combinando a sub-busca BM25 (campo "texto") com a sub-busca k-NN (campo
// "embedding"), usando o search pipeline "hibrido-rrf" criado acima.

public sealed class BuscaHibridaService
{
    private readonly OpenSearchClient _cliente;

    public BuscaHibridaService(OpenSearchClient cliente) => _cliente = cliente;

    public async Task<IReadOnlyList<ChunkCandidato>> BuscarAsync(
        string pergunta, float[] embeddingPergunta, int candidatosPorMotor = 50)
    {
        var resposta = await _cliente.SearchAsync<ChunkDocumento>(s => s
            .Index("politica-atendimento")
            .Pipeline("hibrido-rrf") // aplica a fusao RRF no proprio OpenSearch
            .Size(candidatosPorMotor)
            .Query(q => q
                .Hybrid(h => h.Queries(
                    // Sub-busca 1: BM25 léxica — o que resolve código exato
                    qq => qq.Match(m => m.Field(f => f.Texto).Query(pergunta)),
                    // Sub-busca 2: k-NN vetorial — o que resolve paráfrase
                    qq => qq.Knn(k => k
                        .Field(f => f.Embedding)
                        .Vector(embeddingPergunta)
                        .K(candidatosPorMotor))
                ))));

        if (!resposta.IsValid)
            throw new BuscaIndisponivelException(resposta.DebugInformation);

        // A ordem já vem fundida por RRF — nao ha score bruto comparavel aqui,
        // so a posicao relativa que o pipeline calculou.
        return resposta.Hits
            .Select((h, i) => new ChunkCandidato(h.Source.ChunkId, h.Source.Texto, posicaoFundida: i))
            .ToList();
    }
}

// ServicoRerank.cs — chama o Bedrock Rerank sobre o top-N já fundido por RRF, e
// devolve só os 5 melhores para entrar no prompt de geração.

public class ServicoRerank
{
    private readonly AmazonBedrockAgentRuntimeClient _cliente = new();

    // Confira o ID do modelo de rerank disponível na sua região antes de fixar
    // este ARN em produção — a AWS adiciona modelo de rerank novo com frequência.
    private const string ModeloRerankArn =
        "arn:aws:bedrock:us-east-1::foundation-model/amazon.rerank-v1:0";

    public async Task<IReadOnlyList<ChunkReordenado>> RerankearAsync(
        string pergunta, IReadOnlyList<ChunkCandidato> candidatosFundidos)
    {
        var pedido = new RerankRequest
        {
            Queries = new List<RerankQuery> { new() { TextQuery = new() { Text = pergunta } } },
            Sources = candidatosFundidos.Select(c => new RerankSource
            {
                InlineDocumentSource = new() { TextDocument = new() { Text = c.Texto } },
            }).ToList(),
            RerankingConfiguration = new RerankingConfiguration
            {
                BedrockRerankingConfiguration = new()
                {
                    ModelConfiguration = new() { ModelArn = ModeloRerankArn },
                    // So os 5 melhores voltam — rerankear e descartar o resto e
                    // deliberado: o cross-encoder ja fez o trabalho caro sobre TODOS
                    // os candidatos, o corte e so no que entra no prompt final.
                    NumberOfResults = 5,
                },
            },
        };

        var resposta = await _cliente.RerankAsync(pedido);

        // O indice de origem aponta de volta para o candidato ANTES do rerank —
        // e o que permite logar "posicaoOriginal" para auditoria depois.
        return resposta.Results
            .Select(r => new ChunkReordenado(
                candidatosFundidos[r.Index].ChunkId,
                candidatosFundidos[r.Index].Texto,
                r.RelevanceScore))
            .ToList();
    }
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BuscarNoDominioHibridoEspecifico",
      "Effect": "Allow",
      "Action": ["es:ESHttpPost", "es:ESHttpGet"],
      "Resource": "arn:aws:es:us-east-1:111122223333:domain/cadencia-recuperacao-hibrida/*"
    },
    {
      "Sid": "ChamarRerankRestritoAoModelo",
      "Effect": "Allow",
      "Action": ["bedrock:Rerank"],
      "Resource": "arn:aws:bedrock:us-east-1::foundation-model/amazon.rerank-v1:0"
    },
    {
      "Sid": "ChamarModeloDeGeracaoRestrito",
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel"],
      "Resource": "arn:aws:bedrock:us-east-1:111122223333:inference-profile/us.anthropic.claude-sonnet-4-20250514-v1:0"
    },
    {
      "Sid": "LerCredencialDoDominioHibrido",
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:cadencia/opensearch-hibrido-*"
    }
  ]
}

# prova.sh — reusa o golden set de 40 perguntas do L83; mede a POSIÇÃO do chunk
# certo no ranking antes de medir taxa de acerto, para separar "nao achou" de
# "achou, mas nao no topo".

GOLDEN_SET=golden-set-politica-cadencia.jsonl  # mesmo arquivo de 40 perguntas do L83

# ── Diagnostico: onde os 3 erros residuais do L83 realmente estavam no ranking ──
python3 diagnosticar_ranking.py --golden "$GOLDEN_SET" --modo vetor-puro \
  --saida diagnostico-vetor-puro.json
# Pergunta "garantia do item EL-4471-B": chunk certo no INDICE, posicao 8 do
#   ranking vetorial puro — so o top-5 entra no prompt, fica de fora
# Pergunta "artigo 14 da norma de instalacao eletrica": chunk certo, posicao 11
# Pergunta "politica de frete Sul, versao vigente": DUAS versoes empatadas nas
#   posicoes 1 e 2 — nao e problema de RANKING, sao duas versoes vigentes no indice

# ── Rodada 1: busca so vetorial (a mesma pipeline do L83/L84, sem mudanca) ──────
python3 avaliar.py --endpoint responder-hibrido --modo vetor-puro \
  --golden "$GOLDEN_SET" --saida resultado-vetor-puro.json
# Resultado medido: 37 de 40 corretas (92,5%) — identico ao L83, porque nada
# mudou ainda na recuperacao

# ── Rodada 2: busca hibrida (BM25+vetor) + RRF + reranking cross-encoder ────────
python3 avaliar.py --endpoint responder-hibrido --modo hibrido-rerank \
  --golden "$GOLDEN_SET" --saida resultado-hibrido-rerank.json
# Resultado medido: 39 de 40 corretas (97,5%) — os 2 casos de identificador exato
# sobem ao topo do ranking fundido; o caso de versao duplicada de politica CONTINUA
# errado, porque nao e um problema de ranking — e duas versoes vigentes no acervo,
# fora do escopo deste laboratorio

# ── Confirmacao: modelo e prompt de geracao nao mudaram ─────────────────────────
diff <(jq -S .configuracaoModelo resultado-vetor-puro.json) \
     <(jq -S .configuracaoModelo resultado-hibrido-rerank.json)
# Esperado: sem diferenca — se este diff mostrar algo, o experimento nao isolou a
# recuperacao, e o ganho medido nao e atribuivel so a ela

# limpeza.sh — ordem importa: o search pipeline referencia o dominio, e o
# dominio provisionado com instancia dedicada de master NAO e gratuito parado.

# 1) Apagar o search pipeline antes do dominio
DOMINIO="https://$(terraform output -raw opensearch_endpoint)"
curl -s -X DELETE "$DOMINIO/_search/pipeline/hibrido-rrf" --aws-sigv4 "aws:amz:us-east-1:es"

# 2) terraform destroy cuida do dominio, das roles do IAM, do security group e do
#    grupo de logs — mas confira o item 4 antes de fechar o navegador
terraform destroy -auto-approve

# 3) Confirma que o dominio nao existe mais
aws opensearch describe-domain --domain-name cadencia-recuperacao-hibrida 2>&1 | grep -i "not found"

# 4) O secret do Secrets Manager tem retencao de 7-30 dias por padrao mesmo apos
#    "excluido" — force-delete se nao precisar de janela de recuperacao
aws secretsmanager delete-secret \
  --secret-id cadencia/opensearch-hibrido-master \
  --force-delete-without-recovery