Caso d'uso: Embedding di codice
In questa pagina
Oltre la ricerca
Gli embedding di codice non servono solo per la ricerca semantica. Sbloccano applicazioni avanzate: analisi del repository, clustering, rilevamento di duplicati e assistenti allo sviluppo. In questa lezione, esplorerai questi casi d’uso con codice Python concreto.
Questi quattro casi d’uso condividono una caratteristica comune: sfruttano la geometria dell’indice piuttosto che una query. Una volta che i tuoi file sono posizionati nello spazio vettoriale, le loro posizioni relative raccontano una storia sul progetto stesso: cosa assomiglia a cosa, cosa si ripete e cosa spicca.
Analisi del Repository
Analizza la struttura semantica di un progetto per capire come è organizzato il codice. K-Means raggruppa i file in cinque famiglie basandosi sulla loro prossimità vettoriale, senza mai guardare l’albero delle cartelle. Il risultato è spesso istruttivo: su un progetto disordinato, vedrai file provenienti da directory molto diverse finire nello stesso cluster perché trattano effettivamente lo stesso argomento.
import numpy as np
from sklearn.cluster import KMeans
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
def analyze_repo(code_files, n_clusters=5):
"""Analyze the semantic structure of a repository."""
# Encode all files
inputs = [f["content"][:3000] for f in code_files]
response = client.embeddings.create(
model="codestral-embed",
inputs=inputs,
)
embeddings = np.array([d.embedding for d in response.data])
# K-Means Clustering
kmeans = KMeans(n_clusters=n_clusters, random_state=42, n_init=10)
labels = kmeans.fit_predict(embeddings)
# Group files by cluster
clusters = {}
for i, label in enumerate(labels):
if label not in clusters:
clusters[label] = []
clusters[label].append(code_files[i]["path"])
return clusters
# Usage
clusters = analyze_repo(code_files, n_clusters=5)
for cluster_id, files in clusters.items():
print(f"\nCluster {cluster_id} ({len(files)} files):")
for f in files[:5]:
print(f" - {f}")
Il parametro random_state=42 fissa l’inizializzazione: senza di esso, due esecuzioni successive produrrebbero numeri di cluster diversi, rendendo impossibile confrontare le analisi nel tempo.
Rilevamento di Duplicati
Identifica codice duplicato o quasi duplicato nella tua base. A differenza di uno strumento di rilevamento classico che confronta il testo, questo approccio individua anche le duplicazioni riscritte: il file copiato da un modulo all’altro, rinominato, con variabili diverse ma la stessa logica.
from sklearn.metrics.pairwise import cosine_similarity
def find_duplicates(code_files, embeddings, threshold=0.95):
"""Find pairs of near-identical files."""
sim_matrix = cosine_similarity(embeddings)
duplicates = []
for i in range(len(code_files)):
for j in range(i + 1, len(code_files)):
if sim_matrix[i][j] >= threshold:
duplicates.append({
"file_a": code_files[i]["path"],
"file_b": code_files[j]["path"],
"similarity": float(sim_matrix[i][j]),
})
# Sort by decreasing similarity
duplicates.sort(key=lambda x: x["similarity"], reverse=True)
return duplicates
# Find duplicates
dupes = find_duplicates(code_files, embeddings, threshold=0.92)
print(f"{len(dupes)} potential duplicate pairs found:")
for d in dupes[:10]:
print(f" {d['similarity']:.3f} : {d['file_a']} <-> {d['file_b']}")
Il ciclo interno inizia da i + 1 per confrontare ogni coppia una sola volta. Fai però attenzione al costo: la matrice di similarità è quadratica e, oltre qualche migliaio di file, dovrai passare a un indice approssimativo piuttosto che a un calcolo esaustivo. Abbassare la soglia da 0,95 a 0,92 allarga la rete per le duplicazioni rielaborate, al costo di qualche falso positivo da smistare manualmente.
Clustering per Funzionalità
K-Means richiede di conoscere in anticipo il numero di gruppi, cosa che raramente accade quando si scopre un progetto. DBSCAN affronta questo limite: determina autonomamente il numero di gruppi e, soprattutto, permette a un file di non appartenere a nessuno, che è il significato dell’etichetta «Unclassified» nel codice sottostante.
from sklearn.cluster import DBSCAN
def cluster_by_functionality(code_files, embeddings, eps=0.3, min_samples=2):
"""Group code by functionality using DBSCAN."""
# DBSCAN on cosine distances
distance_matrix = 1 - cosine_similarity(embeddings)
clustering = DBSCAN(eps=eps, min_samples=min_samples, metric="precomputed")
labels = clustering.fit_predict(distance_matrix)
# Organize by cluster
groups = {}
for i, label in enumerate(labels):
group_name = f"Group {label}" if label >= 0 else "Unclassified"
if group_name not in groups:
groups[group_name] = []
groups[group_name].append(code_files[i]["path"])
return groups
groups = cluster_by_functionality(code_files, embeddings)
for name, files in groups.items():
print(f"\n{name} ({len(files)} files):")
for f in files[:3]:
print(f" - {f}")
La conversione tramite 1 - cosine_similarity trasforma la similarità in distanza, il formato che DBSCAN si aspetta con metric="precomputed". Il parametro eps=0.3 significa quindi che due file sono vicini a partire da una similarità del coseno di 0,7.
Assistente al Codice Contestuale
Questo ultimo esempio assembla i mattoni precedenti in un vero sistema RAG per il codice: ricerca di file pertinenti, costruzione di un contesto, quindi chiamata all’LLM. La soglia di 0,5 filtra a monte: è meglio dare al modello due file davvero legati alla domanda piuttosto che tre, di cui uno fuori tema che lo fuorvierebbe.
def code_assistant(question, code_files, embeddings, top_k=3):
"""Find relevant code to answer a question."""
# Encode the question
response = client.embeddings.create(
model="codestral-embed",
inputs=[question],
)
query_emb = np.array(response.data[0].embedding)
# Find the most relevant code
sims = cosine_similarity([query_emb], embeddings)[0]
top_indices = np.argsort(sims)[::-1][:top_k]
context_parts = []
for idx in top_indices:
if sims[idx] > 0.5: # Minimum threshold
context_parts.append(
f"# File: {code_files[idx]['path']}\n"
f"{code_files[idx]['content'][:1500]}"
)
context = "\n\n---\n\n".join(context_parts)
# Build the prompt for the LLM
prompt = f"""Here is relevant code from our project:
{context}
Developer question: {question}
Answer based on the code above."""
# Call the LLM with context
chat_response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}],
)
return chat_response.choices[0].message.content
# Usage
answer = code_assistant(
"How does authentication work in this project?",
code_files,
embeddings,
)
print(answer)
Il percorso del file viene iniettato come commento sopra ogni snippet. Non è decorativo: il modello lo usa per citare le sue fonti e lo sviluppatore che legge la risposta sa immediatamente dove andare a verificare.
Metriche di Qualità del Codice
Infine, gli embedding aiutano a individuare ciò che spicca come insolito. La funzione calcola il centroide dell’indice, il «file medio» del progetto, e misura quanto ciascuno se ne discosta. Uno z-score superiore a 2 segnala un file che non assomiglia a nient’altro: a volte un pezzo di codice generato o copiato dall’esterno, a volte semplicemente l’unico file scritto in uno stile vecchio. In entrambi i casi, è un buon candidato per una revisione.
def detect_outliers(code_files, embeddings, threshold=2.0):
"""Detect atypical code files."""
# Calculate the centroid (mean vector)
centroid = embeddings.mean(axis=0)
# Distance of each file to the centroid
distances = np.linalg.norm(embeddings - centroid, axis=1)
# Files beyond N standard deviations
mean_dist = distances.mean()
std_dist = distances.std()
outliers = []
for i, dist in enumerate(distances):
z_score = (dist - mean_dist) / std_dist
if z_score > threshold:
outliers.append({
"path": code_files[i]["path"],
"z_score": float(z_score),
})
outliers.sort(key=lambda x: x["z_score"], reverse=True)
return outliers
outliers = detect_outliers(code_files, embeddings)
print(f"{len(outliers)} atypical files:")
for o in outliers:
print(f" z={o['z_score']:.2f} : {o['path']}")
Ricorda che «atipico» non significa «cattivo». Lo strumento ti fornisce una lista di file da esaminare, non un verdetto: è un punto di partenza per una revisione umana, mai una metrica da esporre su una dashboard di qualità.
Punti chiave
- Gli embedding di codice consentono il clustering automatico per funzionalità
- Il rilevamento dei duplicati utilizza una soglia di similarità del coseno (0,92–0,95)
- Un assistente al codice combina la ricerca semantica con un LLM per il code RAG
- I file atipici (outlier) possono segnalare codice che necessita di revisione
- DBSCAN è preferibile a K-Means quando il numero di gruppi è sconosciuto