Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Każ ta' Użu: Embeddings tal-Kodiċi

Lezzjoni 8 / 18 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Lil Hinn mit-Tfittxija
  2. Analiżi tar-Repożitorju
  3. Detezzjoni ta’ Duplikati
  4. Clustering skont il-Funzjonalità
  5. Assistent tal-Kodiċi Kuntestwali
  6. Metriki tal-Kwalità tal-Kodiċi
  7. Punti Ewlenin

Lil Hinn mit-Tfittxija

L-embeddings tal-kodiċi mhumiex biss għat-tfittxija semantika. Dawn jiftħu l-bieb għal applikazzjonijiet avvanzati: analiżi tar-repożitorju, klustering, detezzjoni ta’ duplikati, u assistenti tal-iżvilupp. F’din il-lezzjoni, se tesplora dawn il-każijiet ta’ użu b’kodiċi Python konkret.

Dawn l-erba’ każijiet ta’ użu jaqsmu karatteristika komuni: jisfruttaw il-ġeometrija tal-indiċi minflok query. Ladarba l-fajls tiegħek ikunu ppożizzjonati fl-ispazju vettorjali, il-pożizzjonijiet relattivi tagħhom jirrakkontaw storja dwar il-proġett innifsu: x’ixbah lil x’, x’jirrepeti ruħu, u x’joħroġ mill-ordinarju.

Analiżi tar-Repożitorju

Analiżża l-istruttura semantika ta’ proġett biex tifhem kif il-kodiċi huwa organizzat. K-Means jiggruppa l-fajls f’ħames familji bbażati fuq il-prossimità vettorjali tagħhom, mingħajr qatt ma jħares lejn is-siġra tal-folder. Ir-riżultat spiss ikun instruttiv: fuq proġett imħawwad, tara fajls minn direttorji differenti ħafna jispiċċaw fl-istess cluster għax fil-fatt jittrattaw l-istess suġġett.

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-random_state=42 jiffissa l-inizjalizzazzjoni: mingħajru, żewġ eżekuzzjonijiet suċċessivi jagħtu numri ta’ cluster differenti, u jagħmluha impossibbli li tqabbel l-analiżijiet maż-żmien.

Detezzjoni ta’ Duplikati

Identifika kodiċi duplikat jew kważi duplikat fil-bażi tiegħek. Minflok għodod klassiċi ta’ detezzjoni li jqabblu t-test, dan l-approċċ jiskopri wkoll id-duplikazzjonijiet miktuba mill-ġdid—il-fajl ikkupjat minn modulu għal ieħor, imsemmi mill-ġdid, b’varjabbli differenti iżda bl-istess loġika.

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']}")

Iċ-ċiklu intern jibda minn i + 1 biex iqabbel kull par darba biss. Madankollu, oqgħod attent għall-ispiża: il-matriċi tas-similarità hija kwadratika, u wara ftit eluf ta’ fajls ikollok tbiddel għal indiċi approssimattiv minflok kalkolu eżawrjenti. It-tnaqqis tal-limitu (threshold) minn 0.95 għal 0.92 jwessa’ n-net għal duplikazzjonijiet rielaborati, bl-ispiża ta’ ftit pożittivi foloz li trid tisseparahom manwalment.

Clustering skont il-Funzjonalità

K-Means jeħtieġ li tkun taf in-numru ta’ gruppi minn qabel, li rari huwa l-każ meta tiskopri proġett. DBSCAN jindirizza din il-limitazzjoni: jiddetermina n-numru ta’ gruppi huwa stess u, l-aktar importanti, jippermetti li fajl ma jappartjeni għal ebda grupp—li huwa t-tifsira tat-tikketta “Unclassified” fil-kodiċi hawn taħt.

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}")

Il-konverżjoni permezz ta’ 1 - cosine_similarity tbiddel is-similarità f’distanza, il-format li DBSCAN jistenna b’metric="precomputed". Għalhekk, il-parametru eps=0.3 ifisser li żewġ fajls huma ġirien jibdew minn similarità kosinus ta’ 0.7.

Assistent tal-Kodiċi Kuntestwali

Dan l-aħħar eżempju jgħaqqad il-blokki tal-kostruzzjoni preċedenti f’sistema RAG vera għall-kodiċi: tfittxija għal fajls rilevanti, bini ta’ kuntest, u mbagħad sejħa tal-LLM. Il-limitu ta’ 0.5 jiffiltra minn qabel—aħjar tagħti lill-mudell żewġ fajls verament marbuta mal-mistoqsija milli tlieta, li waħda minnhom tkun barra mit-tema u tqarraq miegħu.

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-mogħdija tal-fajl tiġi inġettata bħala kumment fuq kull framment. Dan mhuwiex dekorattiv: il-mudell jużah biex jikkowta s-sorsi tiegħu, u l-iżviluppatur li jaqra t-tweġiba jaf immedjatament fejn imur biex jivverifika.

Metriki tal-Kwalità tal-Kodiċi

Fl-aħħar nett, l-embeddings jgħinu biex tiskopri x’joħroġ bħala mhux tas-soltu. Il-funzjoni tikkalkula ċ-ċentrojde tal-indiċi—il-”fajl medju” tal-proġett—imbagħad tkejjel kemm kull wieħed jiddevja. Z-score akbar minn 2 jissinjala fajl li ma jixbah lil xejn ieħor: kultant biċċa kodiċi ġġenerata jew ikkupjata minn barra, kultant sempliċiment l-uniku fajl miktub f’stil antik. Fiż-żewġ każijiet, huwa kandidat tajjeb għal reviżjoni.

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']}")

Ftakar li “atipiku” ma jfissirx “ħażin”. L-għodda tagħtik lista ta’ fajls biex tħares lejhom, mhux verdett: huwa punt tat-tluq għal reviżjoni umana, qatt metrika biex turi fuq dashboard tal-kwalità.

Punti Ewlenin

  • L-embeddings tal-kodiċi jippermettu clustering awtomatiku skont il-funzjonalità
  • Id-detezzjoni ta’ duplikati tuża limitu ta’ similarità kosinus (0.92–0.95)
  • Assistent tal-kodiċi jgħaqqad it-tfittxija semantika ma’ LLM għal RAG tal-kodiċi
  • Fajls atipiċi (outliers) jistgħu jissinjalaw kodiċi li jeħtieġ reviżjoni
  • DBSCAN huwa preferibbli għal K-Means meta n-numru ta’ gruppi mhux magħruf