Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Käyttötapaus: Koodin upotukset

Oppitunti 8 / 18 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Haun tuolla puolen
  2. Repository-analytiikka
  3. Duplikaattien tunnistus
  4. Toiminnallisuuspohjainen klusterointi
  5. Kontekstuaalinen koodiavustaja
  6. Koodin laatumittarit
  7. Keskeiset asiat

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