O modelo codestral-embed
Nesta página
Embeddings Especializados para Código
Enquanto o mistral-embed foi concebido para linguagem natural, o codestral-embed é um modelo de embeddings otimizado especificamente para linguagens de programação. Este modelo compreende a sintaxe, a semântica e a lógica do código, tornando-o significativamente superior a um modelo de texto genérico para qualquer tarefa que envolva código-fonte.
Pode observar a diferença num caso simples. Duas funções que fazem exatamente a mesma coisa — uma escrita com um ciclo for e outra utilizando compreensão de listas — não partilham quase nenhuns tokens. Um modelo de texto vê-as como dois blocos distintos de pontuação; um modelo treinado em código agrupa-as porque aprendeu que estas duas formas expressam a mesma intenção.
Especificações Técnicas
O modelo codestral-embed difere do mistral-embed em vários aspetos fundamentais:
| Funcionalidade | codestral-embed | mistral-embed |
|---|---|---|
| Dimensões Padrão | 1536 | 1024 |
| Dimensões Máximas | 3072 (o dobro do padrão) | — |
| Tipos de Saída | float, int8, uint8, binary, ubinary | — |
| Otimização | Treinado em código-fonte multilingue | Linguagem natural |
Esta flexibilidade nas dimensões e nos tipos de saída é o que realmente distingue os dois modelos na prática. Um índice de código atinge rapidamente o milhão de vetores, e a capacidade de reduzir o seu peso em quatro vezes altera drasticamente a fatura da infraestrutura.
Utilização Básica
A API é idêntica à do mistral-embed, exceto pelo nome do modelo codestral-embed. Nada mais muda no seu código de chamada, o que lhe permite executar ambos os modelos no mesmo projeto ajustando apenas um parâmetro.
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
# Codificar excertos de código
response = client.embeddings.create(
model="codestral-embed",
inputs=[
"def fibonacci(n): return n if n <= 1 else fibonacci(n-1) + fibonacci(n-2)",
"function fibonacci(n) { return n <= 1 ? n : fibonacci(n-1) + fibonacci(n-2); }",
"public int fibonacci(int n) { return n <= 1 ? n : fibonacci(n-1) + fibonacci(n-2); }",
],
)
for i, data in enumerate(response.data):
print(f"Snippet {i+1}: vector of {len(data.embedding)} dimensions")
# Snippet 1: vector of 1536 dimensions
# Snippet 2: vector of 1536 dimensions
# Snippet 3: vector of 1536 dimensions
Note que os três excertos implementam a mesma lógica (Fibonacci) em três linguagens diferentes. Os seus embeddings serão muito próximos, apesar das diferenças sintáticas. Esta propriedade permite a pesquisa entre linguagens: numa base de código poliglota, um programador Python pode encontrar a implementação Java de que necessita sem saber uma palavra de Java.
O Parâmetro output_dimension
Pode reduzir o tamanho do vetor para poupar espaço de armazenamento, ao custo de uma ligeira perda de precisão:
# Dimensões reduzidas (512 em vez de 1536)
response = client.embeddings.create(
model="codestral-embed",
output_dimension=512,
inputs=["def hello(): print('Hello, World!')"],
)
embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}") # 512
As primeiras dimensões do vetor são as mais informativas. O modelo foi desenhado para que as primeiras n dimensões retenham a quantidade máxima de informação, permitindo esta redução sem uma perda catastrófica. Por outras palavras, truncar um vetor não é como deitar fora aleatoriamente um terço do significado: mantém o sinal central e perde a nuance, o que permanece perfeitamente viável para uma passagem de filtragem inicial.
Escolher uma Dimensão
Utilize os seguintes valores como diretrizes com base no contexto do seu projeto. Uma pesquisa de alta precisão num corpus modesto requer definições diferentes de um índice executado numa máquina com recursos limitados:
# Recomendações por caso de uso
DIMENSIONS = {
"high_precision_search": 3072, # Qualidade máxima
"general_use": 1536, # Padrão, bom compromisso
"large_volume": 768, # Compromisso armazenamento/qualidade
"prototype": 512, # Desenvolvimento rápido
"embedded": 256, # Restrições estritas de memória
}
O Parâmetro output_dtype
O tipo de saída controla a precisão e o tamanho dos valores. Enquanto o output_dimension reduz o número de valores, o output_dtype reduz o peso de cada um. Estas duas alavancas são independentes e cumulativas.
# Float (padrão) - precisão máxima
response_float = client.embeddings.create(
model="codestral-embed",
output_dtype="float",
inputs=["def add(a, b): return a + b"],
)
# Int8 - 4x mais compacto que float32
response_int8 = client.embeddings.create(
model="codestral-embed",
output_dtype="int8",
inputs=["def add(a, b): return a + b"],
)
# Binary - extremamente compacto
response_binary = client.embeddings.create(
model="codestral-embed",
output_dtype="binary",
inputs=["def add(a, b): return a + b"],
)
Combinar Dimensão e Dtype
Pode combinar ambos os parâmetros para um controlo preciso. As duas chamadas abaixo codificam a mesma consulta SQL e ilustram os extremos do espetro: a primeira visa um índice leve consultado continuamente, enquanto a segunda serve uma pesquisa de referência onde cada ponto de precisão conta.
# Compacto e rápido: 512 dimensões em int8
response = client.embeddings.create(
model="codestral-embed",
output_dimension=512,
output_dtype="int8",
inputs=["SELECT * FROM users WHERE active = true"],
)
# Alta qualidade: 3072 dimensões em float
response = client.embeddings.create(
model="codestral-embed",
output_dimension=3072,
output_dtype="float",
inputs=["SELECT * FROM users WHERE active = true"],
)
Eis uma regra a estabelecer desde já: os vetores no seu índice e os vetores nas suas consultas devem partilhar exatamente os mesmos parâmetros. Codificar um corpus em 512 dimensões e depois consultar em 1536 não produz apenas resultados fracos; gera um erro ou pontuações sem sentido.
Linguagens Suportadas
O codestral-embed funciona com todas as linguagens de programação comuns. Do lado da aplicação, cobre Python, JavaScript e TypeScript, bem como Java, C, C++, C#, Go e Rust. Para dados e apresentação, o modelo gere SQL, HTML e CSS. Para ferramentas e configuração, gere Shell/Bash, YAML e JSON — e muitas outras, efetivamente qualquer linguagem presente nos dados de treino. Na prática, um repositório típico que mistura Python, modelos HTML, migrações SQL e manifestos YAML pode ser totalmente indexado com um único modelo.
Pontos-chave
- O
codestral-embedé otimizado para código-fonte, não para linguagem natural - 1536 dimensões por padrão, escalável até 3072
- O parâmetro
output_dimensionpermite reduzir o tamanho do vetor - O parâmetro
output_dtypecontrola a precisão (float, int8, binary, etc.) - O modelo compreende a semântica do código independentemente da linguagem