Käyttötapaus: Koodin upotukset
Tällä sivulla
Haun tuolla puolen
Koodin upotukset eivät sovellu pelkkään semanttiseen hakuun. Ne avaavat oven edistyneille sovelluksille: repository-analytiikka, klusterointi, duplikaattien tunnistus ja kehitysavustajat. Tässä oppitunnissa tutustut näihin käyttötapauksiin konkreettisen Python-koodin avulla.
Näillä neljällä käyttötapauksella on yhteinen piirre: ne hyödyntävät hakemiston geometriaa kyselyn sijaan. Kun tiedostosi on sijoitettu vektoritilaan, niiden suhteelliset sijainnit kertovat tarinan itse projektista: mikä muistuttaa mitäkin, mikä toistuu ja mikä erottuu joukosta.
Repository-analytiikka
Analysoi projektin semanttista rakennetta ymmärtääksesi, miten koodi on järjestetty. K-Means ryhmittelee tiedostot viiteen perheeseen niiden vektoriläheisyyden perusteella katsomatta koskaan hakemistorakennetta. Tulos on usein opettavainen: sekavassa projektissa näet hyvin eri hakemistoista olevien tiedostojen päätyvän samaan klusteriin, koska ne käsittelevät itse asiassa samaa aihetta.
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}")
random_state=42 lukitsee alustuksen: ilman sitä kaksi peräkkäistä ajoa tuottaisi eri klusterinumeroita, mikä tekisi analyysien vertailun ajan myötä mahdottomaksi.
Duplikaattien tunnistus
Tunnista koodikannastasi duplikaatit tai lähes duplikaatit. Toisin kuin klassinen tunnistustyökalu, joka vertaa tekstiä, tämä lähestymistapa havaitsee myös uudelleenkirjoitetut duplikaatit – tiedoston, joka on kopioitu yhdestä moduulista toiseen, nimetty uudelleen ja jossa on eri muuttujat, mutta sama logiikka.
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']}")
Sisempi silmukka alkaa kohdasta i + 1, jotta jokainen pari verrataan vain kerran. Muista kuitenkin kustannukset: samankaltaisuusmatriisi on neliöllinen, ja muutaman tuhannen tiedoston jälkeen sinun on siirryttävä likimääräiseen indeksiin tyhjentävän laskennan sijaan. Kynnyksen alentaminen arvosta 0,95 arvoon 0,92 heittää laajemman verkon uudelleenmuokattujen duplikaattien kiinniottamiseksi, mutta tämä tuo mukanaan muutaman väärän positiivisen tuloksen, jotka joudut lajittelemaan manuaalisesti.
Toiminnallisuuspohjainen klusterointi
K-Means vaatii ryhmien määrän tietämistä etukäteen, mikä on harvoin mahdollista projektia tutkittaessa. DBSCAN ratkaisee tämän rajoituksen: se määrittää ryhmien määrän itse ja mikä tärkeintä, sallii tiedoston kuulumisen mihinkään ryhmään – mikä tarkoittaa alla olevassa koodissa olevaa “Unclassified”-labelia.
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}")
Muunnos 1 - cosine_similarity muuttaa samankaltaisuuden etäisyydeksi, jonka muodossa DBSCAN odottaa sitä parametrilla metric="precomputed". Parametri eps=0.3 tarkoittaa siis, että kaksi tiedostoa ovat naapureita alkaen kosinussamankaltaisuudesta 0,7.
Kontekstuaalinen koodiavustaja
Tämä viimeinen esimerkki kokoaa edelliset rakennuspalikat todelliseksi koodin RAG-järjestelmäksi: relevanttien tiedostojen etsiminen, kontekstin rakentaminen ja sen jälkeen LLM:n kutsuminen. Kynnysarvo 0,5 suodattaa ylävirrassa – on parempi antaa mallille kaksi kysymykseen todella liittyvää tiedostoa kuin kolme, joista yksi on aiheen vierestä ja harhaanjohtaa mallia.
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)
Tiedostopolku injektoidaan kommenttina kunkin koodikatkelman yläpuolelle. Tämä ei ole koristeellista: malli käyttää sitä lähteidensä citeeraamiseen, ja vastausta lukeva kehittäjä tietää heti, mistä mennä tarkistamaan asia.
Koodin laatumittarit
Lopuksi upotukset auttavat havaitsemaan epätavallisena erottuvat kohteet. Funktio laskee hakemiston sentroidin – projektin “keskimääräisen tiedoston” – ja mittaa sitten, kuinka kaukana kukin tiedosto siitä on. Yli 2:n z-score signaloi tiedostoa, joka ei muistuta mitään muuta: joskus kyseessä on ulkopuolelta generoitu tai kopioitu koodinpätkä, joskus yksinkertaisesti ainoa vanhaan tyyliin kirjoitettu tiedosto. Molemmissa tapauksissa se on hyvä ehdokas tarkasteluun.
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']}")
Muista, että “epätavallinen” ei tarkoita “huonoa”. Työkalu antaa sinulle listan tiedostoista, jotka kannattaa tarkistaa, ei tuomiota: se on lähtökohta ihmisen tekemälle tarkastelulle, ei koskaan laatudashboardille näytettävä mittari.
Keskeiset asiat
- Koodin upotukset mahdollistavat automaattisen klusteroinnin toiminnallisuuden perusteella
- Duplikaattien tunnistus käyttää kosinussamankaltaisuuskynnystä (0,92–0,95)
- Koodiavustaja yhdistää semanttisen haun ja LLM:n koodin RAG-järjestelmäksi
- Epätavalliset tiedostot (poikkeamat) voivat signaloida tarkastelua kaipaavaa koodia
- DBSCAN on suositeltavampi kuin K-Means, kun ryhmien määrä on tuntematon