Lab 94 — Busca de produto com IA: híbrida, rerank e geração

{
  "requisicaoApresentacao": {
    "termoBusca": "parafuso 3/4",
    "produtosNaOrdemFinal": [
      {"sku": "PRF-3025", "nome": "Parafuso 3/4 pol aço inox, cabeça sextavada", "posicao": 1},
      {"sku": "PRF-3031", "nome": "Parafuso 0,75\" inox, rosca soberba", "posicao": 2},
      {"sku": "PRF-1180", "nome": "Parafuso 1/2 pol aço carbono zincado", "posicao": 3}
    ]
  },
  "respostaApresentacao": {
    "produtosComDestaque": [
      {"sku": "PRF-3025", "posicao": 1, "destaque": "medida exata da busca, em aço inox"},
      {"sku": "PRF-3031", "posicao": 2, "destaque": "mesma medida, rosca soberba (fixação mais firme)"},
      {"sku": "PRF-1180", "posicao": 3, "destaque": "medida diferente — 1/2 polegada, não 3/4"}
    ]
  },
  "_comentario": "a funcao compara produtosNaOrdemFinal.map(p => p.sku) com produtosComDestaque.map(p => p.sku) ANTES de aceitar a resposta — se a ordem ou a lista de SKUs mudou, a chamada e rejeitada e a grade original (sem destaque) e servida, nunca uma lista reordenada pelo LLM"
}

# dominio-busca-produto.tf — OpenSearch Service Multi-AZ dedicado ao
# catalogo, com campo de texto (BM25) e campo de vetor (k-NN) no MESMO
# indice de produto. O search pipeline de fusao e criado por fora do
# Terraform, igual ao L85 — confira a versao do provider antes de assumir
# que isso mudou.

resource "aws_opensearch_domain" "busca_produto" {
  domain_name    = "cadencia-busca-produto"
  engine_version = "OpenSearch_2.19" # confira a versao GA mais recente antes de aplicar

  cluster_config {
    instance_type            = "r6g.xlarge.search" # maior que o do L85: volume de catalogo e maior
    instance_count            = 6          # 3 por AZ — sobrevive a perda de 1 zona
    zone_awareness_enabled    = true
    zone_awareness_config {
      availability_zone_count = 2
    }
    dedicated_master_enabled  = true
    dedicated_master_type     = "r6g.large.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_produto.id]
  }

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

  # Mesmo principio do L85: security group decide QUEM alcanca a porta,
  # fine-grained access control decide QUEM le cada indice depois disso.
  advanced_security_options {
    enabled                        = true
    internal_user_database_enabled = false
    master_user_options {
      master_user_arn = aws_iam_role.opensearch_admin.arn
    }
  }

  tags = {
    Squad  = "catalogo"
    Custo  = "busca-produto" # rateio distinto do dominio de atendimento do L85
  }
}

# pipeline-rrf-produto.sh — cria o search pipeline de fusao no dominio de
# catalogo. Mesmo processor do L85; confira o nome exato disponivel na
# versao do seu dominio antes de aplicar em producao.

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

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

curl -s "$DOMINIO/_search/pipeline/hibrido-produto-rrf" | jq .

// BuscaProdutoHibridaService.cs — dispara a consulta hybrid contra o
// indice de produto, combinando BM25 (campo "nomeDescricao") com k-NN
// (campo "embedding"), usando o search pipeline criado acima.

public sealed class BuscaProdutoHibridaService
{
    private readonly OpenSearchClient _cliente;

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

    public async Task<IReadOnlyList<ProdutoCandidato>> BuscarAsync(
        string termoBusca, float[] embeddingTermo, int candidatosPorMotor = 50)
    {
        var resposta = await _cliente.SearchAsync<ProdutoDocumento>(s => s
            .Index("catalogo-produtos")
            .Pipeline("hibrido-produto-rrf")
            .Size(candidatosPorMotor)
            .Query(q => q
                .Hybrid(h => h.Queries(
                    // Sub-busca 1: BM25 lexica — resolve ordenacao de busca generica
                    qq => qq.Match(m => m.Field(f => f.NomeDescricao).Query(termoBusca)),
                    // Sub-busca 2: k-NN vetorial — resolve variacao de formatacao/medida
                    qq => qq.Knn(k => k
                        .Field(f => f.Embedding)
                        .Vector(embeddingTermo)
                        .K(candidatosPorMotor))
                ))));

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

        // A ordem ja vem fundida por RRF — sem score bruto comparavel aqui,
        // so a posicao relativa que o pipeline calculou.
        return resposta.Hits
            .Select((h, i) => new ProdutoCandidato(h.Source.Sku, h.Source.Nome, posicaoFundida: i))
            .ToList();
    }
}

// ServicoApresentacaoRestrita.cs — chama o Bedrock so para escrever um
// destaque de atributo por produto, e REJEITA qualquer resposta que mude
// a lista de SKUs ou a ordem recebida do rerank. Isto e o contrato central
// deste laboratorio, imposto em codigo, nao so em instrucao de prompt.

public class ServicoApresentacaoRestrita
{
    private readonly AmazonBedrockRuntimeClient _cliente = new();

    // ID de inference profile do modelo de geracao — restrito por IAM na
    // secao de seguranca abaixo, igual ao padrao do L85.
    private const string ModeloArn =
        "arn:aws:bedrock:us-east-1:111122223333:inference-profile/us.anthropic.claude-sonnet-4-20250514-v1:0";

    public async Task<IReadOnlyList<ProdutoComDestaque>> ApresentarAsync(
        string termoBusca, IReadOnlyList<ProdutoReordenado> produtosNaOrdemFinal)
    {
        var skusEsperados = produtosNaOrdemFinal.Select(p => p.Sku).ToList();

        var prompt = MontarPromptApresentacao(termoBusca, produtosNaOrdemFinal);
        var resposta = await _cliente.InvokeModelAsync(new()
        {
            ModelId = ModeloArn,
            Body = SerializarPedido(prompt),
        });

        var destaques = DesserializarDestaques(resposta.Body);

        // O CONTRATO: a lista de SKUs que volta tem de ser EXATAMENTE a mesma,
        // na MESMA ordem, que entrou. Qualquer divergencia — produto a mais, a
        // menos, ou fora de ordem — e um sinal de que o modelo tentou decidir
        // a lista, e a resposta e descartada.
        var skusRecebidos = destaques.Select(d => d.Sku).ToList();
        if (!skusRecebidos.SequenceEqual(skusEsperados))
        {
            _logger.LogWarning(
                "Bedrock devolveu SKU ou ordem diferente do rerank para {Termo} — " +
                "servindo grade sem destaque, geracao NUNCA decide a lista",
                termoBusca);
            return produtosNaOrdemFinal
                .Select(p => new ProdutoComDestaque(p.Sku, p.Nome, Destaque: null))
                .ToList();
        }

        return produtosNaOrdemFinal
            .Zip(destaques, (p, d) => new ProdutoComDestaque(p.Sku, p.Nome, d.Destaque))
            .ToList();
    }
}

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

# teste-ab-busca-produto.sh — split 50/50 por hash do ID de sessao (nao
# por usuario logado, para nao vazar tratamento entre abas), rodado por 14
# dias corridos sobre todo o trafego de busca do catalogo.

# ── Braco controle: busca antiga (ILIKE) ────────────────────────────────
python3 medir_conversao.py --braco controle --periodo 14d \
  --saida resultado-controle.json
# Buscas no braco: 1.284.312
# Compras atribuidas a busca em ate 30 min: 29.668
# Conversao de busca: 2,31%
# Buscas sem nenhum resultado (zero-result): 7,9%
# Latencia p95: ~180 ms

# ── Braco tratamento: hibrida + RRF + rerank + apresentacao ─────────────
python3 medir_conversao.py --braco tratamento --periodo 14d \
  --saida resultado-tratamento.json
# Buscas no braco: 1.291.048
# Compras atribuidas a busca em ate 30 min: 46.220
# Conversao de busca: 3,58%
# Buscas sem nenhum resultado (zero-result): 2,4%
# Latencia p95: ~340 ms sem cache; ~45 ms para termo popular via CloudFront

# ── Significancia: teste Z de duas proporcoes ───────────────────────────
python3 significancia_ab.py \
  --controle resultado-controle.json --tratamento resultado-tratamento.json
# uplift absoluto: +1,27 p.p. | uplift relativo: +55,0%
# z = 60,3 | p < 0,0001 — muito acima do limiar de significancia,
# esperado dado o tamanho de amostra tipico de busca de e-commerce

# ── Confirmacao: geracao nunca alterou SKU nem ordem ─────────────────────
python3 auditar_apresentacao.py --periodo 14d
# Chamadas ao Bedrock de apresentacao: 1.291.048
# Divergencias de SKU/ordem detectadas e rejeitadas: 214 (0,017%)
# Todas as 214 serviram grade sem destaque, NUNCA lista reordenada pelo LLM

# limpeza.sh — ordem importa: o search pipeline referencia o dominio, e o
# dominio Multi-AZ com dedicated master NAO e gratuito parado.

# 1) Apagar o search pipeline antes do dominio
DOMINIO="https://$(terraform output -raw opensearch_produto_endpoint)"
curl -s -X DELETE "$DOMINIO/_search/pipeline/hibrido-produto-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-busca-produto 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-produto-master \
  --force-delete-without-recovery

# 5) A distribuicao CloudFront e a mesma do L20 — NAO destrua aqui, ela
#    continua servindo o catalogo. Só confirme que a origem de busca
#    dinamica (behavior sem cache) foi removida se o dominio de busca
#    saiu do ar.