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

Canonical source: https://maguyva.ai/pt-br/blog/upgrading-code-search-to-voyage-4-large

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-06-09 · Author: Maguyva Team

> Migramos nossos embeddings de código para o voyage-4-large — atualmente no topo do ranking público RTEB de retrieval de código. A versão honesta: o trade-off que fazemos, o que realmente indexamos, e por que pagamos por embeddings premium.

> *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 precisa.

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)](https://embedding-benchmark-rteb.hf.space/code) 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 — busca correspondências com 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 hospedar um modelo gratuito por conta própria, 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" — captar o significado é a razão de ser 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.

## A Base Discreta

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, toma menos decisões equivocadas, e fundamenta suas respostas no código certo — ou na cláusula certa, ou na política certa. Um modelo de embedding mais preciso não é um recurso vistoso. É a base de todo o resto, e acabamos de aprimorá-la. Você não vai notar. Esse é o ponto.