Por Que Atualizamos a Busca de Código para o voyage-4-large

Os números de benchmark neste post refletem os rankings do RTEB no momento da publicação (junho de 2026). Rankings mudam; trate as classificações como um retrato de um momento, não um fato permanente.

A busca semântica só é tão boa quanto os embeddings por baixo dela.

Quando um agente pergunta ao Maguyva “onde tratamos retries”, ele não está fazendo grep pela palavra “retry”. Ele está pedindo o significado — o loop de backoff, o circuit breaker, a coisa que envolve uma chamada instável. Essa pergunta é respondida por um modelo vetorial que transforma código em um ponto no espaço e encontra os vizinhos. Escolha um modelo melhor e cada consulta semântica no produto fica silenciosamente mais afiada.

Então mudamos o nosso. A partir de junho de 2026, os embeddings de código do Maguyva rodam em voyage-4-large, substituindo voyage-code-3.

O Benchmark

Não tomamos essa decisão com base em achismo. O Retrieval Embedding Benchmark (RTEB) público ranqueia modelos de embedding em tarefas reais de retrieval, e no seu ranking de Código o voyage-4-large está em 1º lugar geral (90,86) — à frente do gemini-embedding-2-preview (90,26) e, notavelmente, à frente do modelo que já usávamos, o voyage-code-3 (89,73, 3º lugar).

É uma diferença absoluta pequena. Mas é uma diferença na direção certa, em um benchmark público, na tarefa exata com que nos importamos: recuperar código por significado.

O Trade-off Que Aceitamos: Quantização Binária

Aqui está a parte que a maioria dos posts de “atualizamos nosso modelo” deixa de fora.

O Maguyva não armazena vetores de precisão completa. Armazenamos embeddings quantizados em binário: cada vetor de 2048 dimensões colapsa em uma assinatura de 2048 bits — 256 bytes por vetor. Essas assinaturas são buscadas com distância de Hamming, indexadas e particionadas por tenant.

É um trade-off deliberado. A quantização binária abre mão de um pouco de precisão de retrieval em troca de um armazenamento drasticamente menor e matemática de distância rápida e barata, sem precisar operar um banco de dados vetorial separado. Para um produto que indexa repositórios inteiros por workspace, essa economia importa mais do que espremer a última fração de um ponto de benchmark.

O voyage-4-large se encaixa nesse design sem forçar uma migração da camada de armazenamento: ele produz saída de 2048 dimensões, igual ao voyage-code-3, então nossas colunas bit(2048) e o caminho de busca por Hamming não mudaram. O modelo melhorou; o schema ficou no lugar.

Código Foi Só o Começo

O Maguyva é uma ferramenta de inteligência de código. Mas também somos o cliente zero, e apontamos ele para outra coisa: o markdown que vive nos nossos repositórios ao lado do código. Registros de decisão de arquitetura, runbooks, contratos, documentos financeiros e de política — tudo isso versionado no Git, tudo isso por trás do mesmo servidor MCP, um índice semântico sobre os documentos, não apenas sobre o código-fonte.

É exatamente por isso que a amplitude do voyage-4-large importa. Na mesma família de rankings do RTEB, ele é 1º lugar em finanças, 1º lugar em saúde, e 1º lugar em retrieval de texto geral — à frente do Gemini Embedding do Google, do Embed v4 da Cohere, e do text-embedding-3-large da OpenAI. (A Voyage é cocriadora do RTEB, então lemos isso como um sinal público forte, mas não como um árbitro perfeitamente neutro — ainda assim, é comparado diretamente com todos os principais modelos comerciais, em conjuntos de dados privados de validação.) O mesmo índice que encontra a função certa para um agente encontra a cláusula certa em um contrato ou a linha certa em uma política — e nesses domínios, o voyage-4-large não é um meio-termo, é o líder.

Por Que Pagamos por Embeddings Premium

Existe uma forma mais barata de fazer busca, e boa parte dela é gratuita. A busca lexical — BM25 e afins — corresponde a palavras-chave, roda localmente e não custa nada. Modelos de embedding de código aberto como BGE, Nomic e embeddinggemma oferecem um retrieval semântico genuinamente decente, e você pode hospedá-los por conta própria pelo preço de uma GPU. O Maguyva também usa o lado gratuito: toda consulta funde busca textual, de AST, de grafo e semântica. Onde não economizamos é na camada semântica.

Pagamos por token por embeddings premium — voyage-4-large — em vez de autoexecutar um modelo gratuito, por dois motivos. Primeiro, a busca por palavra-chave sozinha não consegue responder “onde tratamos retries” quando o código diz backoff e circuit breaker e nunca diz a palavra “retry” — significado é o ponto inteiro do embedding, e nos domínios que atendemos, os modelos abertos ficam atrás dos premium: alguns pontos atrás em texto geral, e ainda mais atrás em nichos como código, contratos e finanças. Segundo, na nossa experiência, a qualidade do retrieval molda a resposta final mais do que o modelo do outro lado — um agente forte recebendo o contexto errado ainda responde errado, e nunca vê o documento que nunca lhe foi dado.

Então embeddings premium são uma conta por token que escala com cada repositório e documento que indexamos — e pagamos essa conta de propósito. Pelo resultado que os nossos usuários obtêm, a função certa ou a cláusula certa, achamos que esse trade-off vale a pena.

A Parte Honesta

A própria documentação da Voyage ainda rotula o voyage-code-3 como o modelo otimizado para código. Então por que mudar?

Porque lemos o benchmark público, não apenas a tabela de modelos do fornecedor, e o benchmark colocou o voyage-4-large no topo para retrieval de código. Essa foi uma decisão olhando para frente: pegar o modelo mais novo, geralmente mais forte, e validá-lo contra um ranking público nas tarefas que importam. Estamos confortáveis em fazer essa aposta porque a evidência é ampla — o voyage-4-large não vence só em código, ele também lidera em finanças, saúde e retrieval geral.

O Piso Silencioso

Toda ferramenta que expomos — busca semântica, coleta de contexto de tarefa, perguntas e respostas fundamentadas — desemboca no retrieval. Quando o retriever melhora, o agente do outro lado obtém evidências melhores, comete menos desvios errados, e fundamenta suas respostas no código certo — ou na cláusula certa, ou na política certa. Um modelo de embedding mais afiado não é um recurso vistoso. É o piso sob tudo o mais, e acabamos de elevá-lo. Você não vai notar. Esse é o ponto.