Codestral Embed: Code Embeddings
In questa pagina
Codestral Embed: Ricerca semantica per il codice
Generare e completare il codice non basta. Devi anche trovare, in un repository di centinaia di file, quello che risolve già il tuo problema. È questo il compito del terzo strumento specializzato di Mistral AI: Codestral Embed (v25.05). Questo modello di embedding trasforma frammenti di codice in vettori numerici, abilitando la ricerca semantica attraverso i repository.
Cos’è un embedding di codice?
Un embedding è una rappresentazione vettoriale densa di testo o di un frammento di codice. La proprietà fondamentale è semplice: due frammenti semanticamente simili producono vettori vicini nello spazio vettoriale, anche se la loro sintassi è completamente diversa. Considera le due funzioni seguenti. Hanno nomi diversi, nomi di variabili diversi e implementazioni diverse.
# 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)
Una ricerca con grep non troverebbe mai la seconda funzione partendo dalla prima. Codestral Embed, invece, genera vettori vicini per entrambe perché risolvono lo stesso problema.
Specifiche tecniche
L’ID del modello è codestral-embed-latest (v25.05). Lo chiami sull’endpoint /v1/embeddings. Gestisce codice sorgente in tutti i linguaggi supportati da Codestral. La sua caratteristica distintiva sono le dimensioni configurabili, che vanno da 1536 a 3072. L’impostazione a 1536 dimensioni offre un ottimo rapporto qualità-costo e funziona per la maggior parte dei casi d’uso. L’impostazione a 3072 dimensioni punta alla massima qualità per le ricerche più esigenti. La regola è costante: più dimensioni significano una migliore precisione semantica, ma anche costi di archiviazione più elevati e maggior calcolo per ogni confronto. Per un repository di medie dimensioni, inizia con 1536 e aumenta solo se i risultati sembrano imprecisi.
Utilizzo dell’API
La chiamata di base assomiglia all’endpoint di chat: istanzia il client, passa un frammento e ricevi un vettore.
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]}")
Nota che il parametro inputs è una lista. Questo dettaglio è importante: per indicizzare un intero repository, invii più frammenti in una singola richiesta invece di fare una richiesta per file. Su un repository reale, la differenza si traduce in minuti risparmiati.
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]
Ricerca semantica in un codebase
Il caso d’uso principale deriva direttamente da questo: invece di cercare per parole chiave, cerchi per intento. La pipeline ha due passaggi. Primo, indicizza il codebase una volta sola, allegando un embedding a ogni file. Poi, trasforma la query in un vettore e classifica i file per similarità del coseno, la misura standard di prossimità tra due vettori.
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
)
Osserva la query finale: “function that validates an email address”. Non contiene identificatori di progetto, nomi di file né parole chiave del codice. È qui che sta tutta la differenza rispetto alla ricerca testuale, rendendo lo strumento utilizzabile anche da chi non conosce il repository.
Casi d’uso avanzati
La combinazione più potente concatena Codestral Embed con Codestral o un modello generico come Mistral Small 4. È il pattern RAG (Retrieval-Augmented Generation) applicato al codice. Recuperi prima i file rilevanti, li inietti nel messaggio di sistema e poi poni la tua domanda. Il modello risponde quindi basandosi sul tuo codebase, non solo sulla sua conoscenza generale del linguaggio.
# 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?"}
],
)
Lo stesso indice serve anche per un compito meno appariscente ma molto prezioso: il rilevamento di codice duplicato. Confrontando ogni coppia di funzioni e segnalando quelle con una similarità superiore a una soglia, ottieni una lista di candidati al refactoring che nessuno nel team aveva notato.
# 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']}")
Dovresti regolare la soglia 0.90 sul tuo codice prima di trarre conclusioni. Impostala troppo bassa e segnalerai funzioni che si assomigliano ma fanno cose diverse. Impostala troppo alta e catturerai solo copia-incolla letterali, quelli che avresti trovato comunque.
Punti chiave
- Codestral Embed (v25.05) trasforma il codice in vettori per la ricerca semantica
- Supporta da 1536 a 3072 dimensioni in base alle tue esigenze di precisione
- La ricerca semantica ti permette di cercare per intento, non per parole chiave
- Il pattern RAG (recupero + generazione) è il caso d’uso più potente
- Gli embedding abilitano anche il rilevamento di duplicati e il clustering del codice