Codestral Embed: Incorporações de Código
Nesta página
Codestral Embed: Pesquisa Semântica para Código
Gerar e completar código não é suficiente. Precisa também de encontrar, num repositório com centenas de ficheiros, aquele que já resolve o seu problema. Essa é a função da terceira ferramenta especializada da Mistral AI: Codestral Embed (v25.05). Este modelo de incorporação transforma excertos de código em vetores numéricos, permitindo uma pesquisa semântica em repositórios.
O que é uma Incorporação de Código?
Uma incorporação é uma representação vetorial densa de texto ou de um excerto de código. A propriedade fundamental é simples: dois excertos semanticamente semelhantes geram vetores próximos no espaço vetorial, mesmo que a sua sintaxe seja completamente diferente. Considere as duas funções abaixo. Têm nomes diferentes, nomes de variáveis distintos e implementações diversas.
# Function 1
def calculer_moyenne(nombres):
return sum(nombres) / len(nombres)
# Function 2
def average(values):
total = 0
for v in values:
total += v
return total / len(values)
Uma pesquisa com grep nunca encontraria a segunda função partindo da primeira. O Codestral Embed, no entanto, produz vetores próximos para ambas, pois resolvem o mesmo problema.
Especificações Técnicas
O ID do modelo é codestral-embed-latest (v25.05). Chama-o no endpoint /v1/embeddings. Processa código fonte em todas as linguagens suportadas pelo Codestral. A sua característica distintiva são as dimensões configuráveis, que variam de 1536 a 3072. A configuração de 1536 dimensões oferece uma sólida relação qualidade-custo e funciona para a maioria dos casos de uso. A configuração de 3072 dimensões visa a máxima qualidade para as pesquisas mais exigentes. A regra é constante: mais dimensões significam maior precisão semântica, mas também custos de armazenamento mais elevados e maior computação para cada comparação. Para um repositório de dimensão média, comece com 1536 e aumente apenas se os resultados parecerem imprecisos.
Utilização da API
A chamada básica assemelha-se ao endpoint de chat: instancie o cliente, passe um excerto e receba um vetor de volta.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
code_snippet = """
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
"""
response = client.embeddings.create(
model="codestral-embed-latest",
inputs=[code_snippet],
)
embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")
print(f"First values: {embedding[:5]}")
Note que o parâmetro inputs é uma lista. Este detalhe é importante: para indexar um repositório inteiro, envia vários excertos num único pedido, em vez de um pedido por ficheiro. Num repositório real, a diferença soma minutos poupados.
code_snippets = [
"def tri_bulle(liste): ...",
"def tri_rapide(liste): ...",
"def tri_fusion(liste): ...",
"def recherche_binaire(liste, cible): ...",
]
response = client.embeddings.create(
model="codestral-embed-latest",
inputs=code_snippets,
)
embeddings = [item.embedding for item in response.data]
Pesquisa Semântica numa Base de Código
O caso de uso principal decorre diretamente disto: em vez de pesquisar por palavras-chave, pesquisa por intenção. O pipeline tem dois passos. Primeiro, indexe a base de código uma vez, anexando uma incorporação a cada ficheiro. Depois, transforme a consulta num vetor e classifique os ficheiros por similaridade de cosseno, a medida padrão de proximidade entre dois vetores.
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Index the codebase (do this once)
def index_codebase(files: list[dict]) -> list[dict]:
"""Indexes a list of files with their embeddings."""
contents = [f["content"] for f in files]
response = client.embeddings.create(
model="codestral-embed-latest",
inputs=contents,
)
for i, file in enumerate(files):
file["embedding"] = response.data[i].embedding
return files
# 2. Search by intent
def search_code(query: str, index: list[dict], top_k: int = 5) -> list[dict]:
"""Semantic search in the indexed codebase."""
response = client.embeddings.create(
model="codestral-embed-latest",
inputs=[query],
)
query_vector = np.array(response.data[0].embedding)
# Calculate cosine similarity
results = []
for file in index:
file_vector = np.array(file["embedding"])
similarity = np.dot(query_vector, file_vector) / (
np.linalg.norm(query_vector) * np.linalg.norm(file_vector)
)
results.append({**file, "score": similarity})
results.sort(key=lambda x: x["score"], reverse=True)
return results[:top_k]
# 3. Usage
results = search_code(
"function that validates an email address",
index=my_index
)
Observe a consulta final: “function that validates an email address”. Não contém identificadores do projeto, nomes de ficheiros nem palavras-chave de código. Essa é toda a diferença em relação à pesquisa de texto, tornando a ferramenta utilizável mesmo para quem é novo no repositório.
Casos de Uso Avançados
A combinação mais poderosa associa o Codestral Embed ao Codestral ou a um modelo de propósito geral como o Mistral Small 4. Este é o padrão RAG (Retrieval-Augmented Generation) aplicado ao código. Primeiro, recupera os ficheiros relevantes, injeta-os na mensagem do sistema e depois faz a sua pergunta. O modelo responde então com base na sua base de código, e não apenas no seu conhecimento geral da linguagem.
# 1. Find relevant files with Codestral Embed
results = search_code("HTTP error handling", index)
# 2. Build context
context = "\n\n".join([r["content"] for r in results[:3]])
# 3. Generate a response with Codestral
response = client.chat.complete(
model="codestral-latest",
messages=[
{"role": "system", "content": f"Here is the relevant code from the project:\n{context}"},
{"role": "user", "content": "How can I improve HTTP error handling in this project?"}
],
)
O mesmo índice serve para uma tarefa menos vistosa, mas altamente valiosa: deteção de código duplicado. Ao comparar cada par de funções e assinalar aquelas com similaridade acima de um limiar, obtém uma lista de candidatos a refatorização que ninguém na equipa tinha detetado.
# Compare every pair of functions
for i, func_a in enumerate(functions):
for j, func_b in enumerate(functions):
if i >= j:
continue
similarity = cosine(func_a["embedding"], func_b["embedding"])
if similarity > 0.90:
print(f"Potential duplication: {func_a['name']} <-> {func_b['name']}")
Deve ajustar o limiar de 0.90 no seu próprio código antes de tirar conclusões. Se o definir demasiado baixo, assinalará funções que parecem semelhantes mas fazem coisas diferentes. Se o definir demasiado alto, detetará apenas cópias literais — aquelas que já teria encontrado de qualquer forma.
Pontos-chave
- O Codestral Embed (v25.05) transforma código em vetores para pesquisa semântica
- Suporta de 1536 a 3072 dimensões, dependendo das suas necessidades de precisão
- A pesquisa semântica permite pesquisar por intenção, não por palavras-chave
- O padrão RAG (recuperação + geração) é o caso de uso mais poderoso
- As incorporações também permitem a deteção de duplicados e o agrupamento de código