Prípadová štúdia: Vkladanie kódu (Code Embeddings)
Na tejto strane
Viac než len vyhľadávanie
Vkladanie kódu (code embeddings) nie je určené len na sémantické vyhľadávanie. Otvárajú dvere pokročilým aplikáciám: analytika repozitárov, zhlukovanie, detekcia duplikátov a asistenti pre vývojárov. V tejto lekcii preskúmaš tieto prípady použitia na konkrétnych príkladoch v Pythone.
Tieto štyri prípady majú spoločnú črtu: využívajú geometriu indexu namiesto dotazu. Akonáhle sú tvoje súbory umiestnené vo vektorovom priestore, ich relatívne pozície rozprávajú príbeh o samotnom projekte: čo sa čomu podobá, čo sa opakuje a čo vyčnieva.
Analytika repozitára
Analyzuj sémantickú štruktúru projektu, aby si pochopil, ako je kód organizovaný. Algoritmus K-Means zoskupí súbory do piatich rodín na základe ich vektorovej blízkosti, bez toho, aby sa vôbec pozrel na strom priečinkov. Výsledok je často poučný: v neprehľadnom projekte uvidíš súbory z úplne odlišných adresárov skončiť v rovnakom zhluku, pretože sa v skutočnosti zaoberajú rovnakou témou.
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}")
Parameter random_state=42 fixuje inicializáciu: bez neho by dva po sebe idúce behy vyústili do rôznych čísel zhlukov, čo by znemožnilo porovnávať analýzy v čase.
Detekcia duplikátov
Identifikuj duplicitný alebo takmer duplicitný kód vo svojej báze. Na rozdiel od klasického nástroja na detekciu, ktorý porovnáva text, tento prístup odhalí aj prepísané duplikáty – súbor skopírovaný z jedného modulu do druhého, premenovaný, s inými premennými, ale s rovnakou logikou.
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']}")
Vnútorná slučka začína na i + 1, aby sa každý pár porovnal len raz. Maj však na pamäti náklady: matica podobnosti je kvadratická a pri viac než niekoľkých tisíc súborov budeš musieť prejsť na približný index namiesto vyčerpávajúceho výpočtu. Zníženie prahu z 0,95 na 0,92 zachytí širšiu sieť prepísaných duplikátov, za cenu niekoľkých falošne pozitívnych výsledkov, ktoré budeš musieť triediť manuálne.
Zhlukovanie podľa funkcionality
K-Means vyžaduje, aby si vopred poznal počet skupín, čo je pri objavovaní projektu zriedkavé. DBSCAN rieši toto obmedzenie: sám určí počet skupín a čo je kľúčové, dovoľuje, aby súbor nepatril do žiadnej – čo je význam štítku „Unclassified“ v kóde nižšie.
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}")
Konverzia pomocou 1 - cosine_similarity mení podobnosť na vzdialenosť, čo je formát, ktorý DBSCAN očakáva pri metric="precomputed". Parameter eps=0.3 teda znamená, že dva súbory sú susedmi od kosínusovej podobnosti 0,7.
Kontextový asistent pre kód
Tento posledný príklad spája predchádzajúce stavebné kamene do skutočného systému RAG pre kód: vyhľadávanie relevantných súborov, zostavenie kontextu a následné volanie LLM. Prah 0,5 filtruje dopredu – je lepšie dať modelu dva súbory skutočne súvisiace s otázkou než tri, z ktorých jeden je mimo témy a zmätie ho.
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)
Cesta k súboru je vložená ako komentár nad každý úryvok. Nie je to len dekorácia: model ju používa na citovanie zdrojov a vývojár čítajúci odpoveď okamžite vie, kam sa má ísť pozrieť overiť si informácie.
Metriky kvality kódu
Nakoniec, vkladania pomáhajú odhaliť to, čo vyčnieva ako nezvyčajné. Funkcia vypočíta ťažisko indexu – „priemerný súbor“ projektu – a potom zmeria, ako ďaleko sa každý z nich odchyľuje. Z-skóre väčšie ako 2 signalizuje súbor, ktorý sa nepodobá na nič iné: niekedy ide o kód vygenerovaný alebo skopírovaný zvonku, niekedy jednoducho o jediný súbor napísaný v starom štýle. V oboch prípadoch je to dobrý kandidát na revíziu.
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']}")
Pamätaj, že „atypický“ neznamená „zlý“. Nástroj ti dáva zoznam súborov na pozretie, nie verdikt: je to východiskový bod pre ľudskú revíziu, nikdy nie metrika na zobrazenie na dashboarde kvality.
Kľúčové poznatky
- Vkladania kódu umožňujú automatické zhlukovanie podľa funkcionality
- Detekcia duplikátov využíva prah kosínusovej podobnosti (0,92–0,95)
- Asistent pre kód kombinuje sémantické vyhľadávanie s LLM pre kódový RAG
- Atypické súbory (odľahlé hodnoty) môžu signalizovať kód potrebný na revíziu
- DBSCAN je vhodnejší ako K-Means, keď je počet skupín neznámy