Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Codestral Embed: Incorporações de Código

Aula 11 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Codestral Embed: Pesquisa Semântica para Código
  2. O que é uma Incorporação de Código?
  3. Especificações Técnicas
  4. Utilização da API
  5. Pesquisa Semântica numa Base de Código
  6. Casos de Uso Avançados
  7. Pontos-chave

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