Caz de utilizare: Embedding-uri de cod
Pe această pagină
Dincolo de căutare
Embedding-urile de cod nu servesc doar la căutarea semantică. Ele deblochează aplicații avansate: analiza depozitelor de cod, clustering, detectarea duplicatelor și asistenți de dezvoltare. În această lecție, veți explora aceste cazuri de utilizare cu ajutorul unor exemple concrete de cod Python.
Aceste patru cazuri de utilizare au o trăsătură comună: exploatează geometria indexului, nu o interogare. Odată ce fișierele dumneavoastră sunt plasate în spațiul vectorial, pozițiile lor relative spun o poveste despre proiectul însuși: ce seamănă cu ce, ce se repetă și ce iese în evidență.
Analiza depozitului de cod (Repository Analytics)
Analizați structura semantică a unui proiect pentru a înțelege cum este organizat codul. K-Means grupează fișierele în cinci familii pe baza proximității lor vectoriale, fără a privi vreodată arborele de directoare. Rezultatul este adesea instructiv: într-un proiect dezordonat, veți vedea fișiere din directoare foarte diferite ajungând în același cluster, deoarece tratează de fapt același subiect.
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}")
Parametrul random_state=42 fixează inițializarea: fără el, două rulări succesive ar produce numere de cluster diferite, făcând imposibilă compararea analizelor în timp.
Detectarea duplicatelor
Identificați codul duplicat sau aproape duplicat din baza dumneavoastră. Spre deosebire de un instrument clasic de detectare care compară textul, această abordare identifică și duplicările rescrise – fișierul copiat dintr-un modul în altul, redenumit, cu variabile diferite, dar cu aceeași logică.
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']}")
Bucla interioară începe de la i + 1 pentru a compara fiecare pereche o singură dată. Fiți totuși atent la cost: matricea de similaritate este pătratică, iar dincolo de câteva mii de fișiere, va trebui să treceți la un index aproximativ în loc de un calcul exhaustiv. Scăderea pragului de la 0,95 la 0,92 extinde plasa pentru duplicările rework-ate, cu costul unor false pozitive care trebuie sortate manual.
Clustering pe funcționalitate
K-Means necesită să cunoașteți numărul de grupuri în avans, ceea ce este rar cazul atunci când descoperiți un proiect. DBSCAN rezolvă această limitare: determină singur numărul de grupuri și, crucial, permite ca un fișier să nu aparțină niciunui grup – acesta fiind sensul etichetei „Unclassified“ din codul de mai jos.
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}")
Conversia prin 1 - cosine_similarity transformă similaritatea în distanță, formatul așteptat de DBSCAN cu metric="precomputed". Parametrul eps=0.3 înseamnă, prin urmare, că două fișiere sunt vecine începând de la o similaritate cosinus de 0,7.
Asistent de cod contextual
Acest ultim exemplu asamblează blocurile de construcție anterioare într-un sistem RAG veritabil pentru cod: căutarea fișierelor relevante, construirea unui context, apoi apelarea LLM. Pragul de 0,5 filtrează în amonte – este mai bine să oferiți modelului două fișiere cu adevărat legate de întrebare decât trei, dintre care unul este hors-sujet și îl va induce în eroare.
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)
Calea fișierului este injectată sub formă de comentariu deasupra fiecărui extras. Acest lucru nu este decorativ: modelul îl folosește pentru a-și cita sursele, iar dezvoltatorul care citește răspunsul știe imediat unde să meargă pentru verificare.
Metrici de calitate a codului
În final, embedding-urile ajută la identificarea a ceea ce iese în evidență ca fiind neobișnuit. Funcția calculează centroidul indexului – „fișierul mediu“ al proiectului – apoi măsoară cât de mult se abate fiecare fișier. Un scor z mai mare de 2 semnalează un fișier care nu seamănă cu nimic altceva: uneori o bucată de cod generată sau copiată din exterior, alteori pur și simplu singurul fișier scris într-un stil vechi. În ambele cazuri, este un bun candidat pentru revizuire.
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']}")
Amintiți-vă că „atipic“ nu înseamnă „rău“. Instrumentul vă oferă o listă de fișiere de examinat, nu un verdict: este un punct de plecare pentru o revizuire umană, niciodată o metrică de afișat pe un tablou de bord de calitate.
Puncte cheie
- Embedding-urile de cod permit clustering-ul automat pe funcționalitate
- Detectarea duplicatelor utilizează un prag de similaritate cosinus (0,92–0,95)
- Un asistent de cod combină căutarea semantică cu un LLM pentru RAG de cod
- Fișierele atipice (outliers) pot semnala cod care necesită revizuire
- DBSCAN este preferabil K-Means atunci când numărul de grupuri este necunoscut