Ricerca semantica del codice
In questa pagina
Cercare il codice per significato
La ricerca tradizionale del codice si basa sulle parole chiave: digiti il nome di una funzione o una parola tratta da un commento. La ricerca semantica del codice va oltre: trova il codice in base al suo significato o alla sua intenzione, anche se i termini esatti non corrispondono.
Con codestral-embed, puoi cercare codice utilizzando linguaggio naturale. Una query come “funzione che ordina una lista” troverà un’implementazione di quicksort anche se la parola “sort” non appare mai nel codice. Questo rispecchia la realtà quotidiana di uno sviluppatore che si unisce a un progetto esistente: sai cosa stai cercando, ma non hai idea di come il team precedente l’abbia nominato.
Indicizzazione di una directory di codice
Il primo passo consiste nell’estrarre e codificare ogni file o funzione di un progetto. La funzione seguente percorre l’albero delle directory ed esclude le cartelle che appesantirebbero l’indice. Solo node_modules può essere dieci volte più grande del codice che hai effettivamente scritto, e nessuno dei suoi file è rilevante per la tua ricerca.
import os
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
def extract_code_files(directory, extensions=(".py", ".js", ".ts")):
"""Extract all code files from a directory."""
code_files = []
for root, dirs, files in os.walk(directory):
# Ignore irrelevant directories
dirs[:] = [d for d in dirs if d not in ("node_modules", ".git", "__pycache__", "venv")]
for f in files:
if any(f.endswith(ext) for ext in extensions):
filepath = os.path.join(root, f)
with open(filepath, "r", encoding="utf-8", errors="ignore") as fh:
content = fh.read()
if content.strip():
code_files.append({
"path": filepath,
"content": content[:4000], # Truncate if too long
})
return code_files
# Extract files
code_files = extract_code_files("./my-project/")
print(f"{len(code_files)} code files found")
Due dettagli implementativi meritano attenzione. Modificare dirs[:] in loco non è solo una scorciatoia; è l’unico modo per impedire a os.walk di scendere in quelle directory. Riassegnare la variabile senza lo slicing non avrebbe alcun effetto. Per quanto riguarda il troncamento a 4.000 caratteri, questo ti protegge da file mostruosi che farebbero esplodere la richiesta, mantenendo al contempo l’intestazione del file—import, definizioni principali—che trasporta il segnale più significativo.
Codifica e indicizzazione
La codifica avviene in batch di venti file, con una visualizzazione dell’avanzamento. Su un repository con diverse centinaia di file, questo ciclo dura diversi minuti. Senza un contatore, non avresti modo di distinguere un’elaborazione lenta da una chiamata bloccata.
def index_code_files(code_files, batch_size=20):
"""Create embeddings for all code files."""
all_embeddings = []
for i in range(0, len(code_files), batch_size):
batch = code_files[i:i + batch_size]
inputs = [f["content"] for f in batch]
response = client.embeddings.create(
model="codestral-embed",
inputs=inputs,
)
all_embeddings.extend([d.embedding for d in response.data])
print(f"Encoded {min(i + batch_size, len(code_files))}/{len(code_files)}")
return np.array(all_embeddings)
embeddings = index_code_files(code_files)
print(f"Index: {embeddings.shape}")
L’ordine degli embedding nella matrice corrisponde esattamente all’ordine di code_files. Questa corrispondenza implicita è il perno di tutto ciò che segue: permette a un indice restituito dal ranking di puntare a uno specifico percorso di file.
Ricerca in linguaggio naturale
Il vantaggio principale di codestral-embed è la possibilità di cercare utilizzando una domanda in francese o in inglese. La funzione codifica la query con lo stesso modello, calcola le similarità rispetto all’intero indice e restituisce i migliori risultati top_k insieme a un’anteprima del contenuto.
from sklearn.metrics.pairwise import cosine_similarity
def search_code(query, code_files, embeddings, top_k=5):
"""Search for code using natural language descriptions."""
# Encode the query
response = client.embeddings.create(
model="codestral-embed",
inputs=[query],
)
query_emb = np.array(response.data[0].embedding)
# Calculate similarities
sims = cosine_similarity([query_emb], embeddings)[0]
# Top-k results
top_indices = np.argsort(sims)[::-1][:top_k]
results = []
for idx in top_indices:
results.append({
"path": code_files[idx]["path"],
"score": float(sims[idx]),
"preview": code_files[idx]["content"][:200],
})
return results
# Natural language searches
queries = [
"email validation function",
"database connection",
"HTTP error handling",
"sorting algorithm",
]
for query in queries:
print(f"\n--- Query: '{query}' ---")
results = search_code(query, code_files, embeddings, top_k=3)
for r in results:
print(f" [{r['score']:.3f}] {r['path']}")
Il campo preview ha un’utilità pratica immediata: ti evita di aprire cinque file per capire quale corrisponda effettivamente. In un’integrazione con l’editor, questi duecento caratteri diventano la riga di anteprima visualizzata sotto ogni risultato.
Ricerca cross-lingua
codestral-embed comprende la logica indipendentemente dal linguaggio. Puoi cercare un pattern in Python e trovare l’equivalente in JavaScript:
# Search using a code example in one language...
query_python = "def authenticate(username, password): check credentials and return token"
# ...and find the equivalent in another language
results = search_code(query_python, code_files, embeddings)
# May return a .js file with a similar function
Questa capacità è preziosa per le applicazioni divise tra un backend Python e un frontend TypeScript, dove la stessa regola di business è talvolta implementata su entrambi i lati. Trovare entrambe le implementazioni da una singola query ti aiuta a individuare divergenze prima che un bug le riveli in produzione.
Ricerca per firma di funzione
Puoi anche cercare in base alla forma attesa piuttosto che al dominio funzionale. Descrivere la struttura—una funzione asincrona, una classe, un middleware, un test—orienta la ricerca verso un tipo di oggetto codice piuttosto che verso un argomento.
technical_queries = [
"async function that fetches data from API and handles errors",
"class with CRUD methods for database operations",
"middleware that checks authentication token",
"unit test for user registration",
]
for q in technical_queries:
results = search_code(q, code_files, embeddings, top_k=2)
print(f"\n{q}:")
for r in results:
print(f" -> {r['path']} (score: {r['score']:.3f})")
Prova queste quattro query sul tuo repository prima di procedere. Noterai che i risultati degradano significativamente su file molto lunghi, dove il troncamento a 4.000 caratteri ha eliminato la parte utile. Questo è il momento di decidere se indicizzare interi file o, meglio ancora, funzioni scomposte una per una.
Punti chiave
- codestral-embed ti permette di cercare codice usando descrizioni in linguaggio naturale
- L’indicizzazione comporta la codifica di tutti i file di codice in vettori
- La ricerca cross-lingua funziona: un pattern Python trova l’equivalente JS
- Filtra le directory irrilevanti (node_modules, .git, venv) durante l’estrazione
- Tronca i file molto lunghi per rimanere entro i limiti del modello