Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Cas d'usage : Embeddings de code

Nodarbība 8 no 18 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Au-delà de la recherche
  2. Analytique de dépôt
  3. Détection de doublons
  4. Clustering par fonctionnalité
  5. Assistant de code contextuel
  6. Métriques de qualité du code
  7. Galvenās atziņas

Au-delà de la recherche

Les embeddings de code ne servent pas uniquement à la recherche sémantique. Ils ouvrent la porte à des applications avancées : analytique de dépôt, clustering, détection de doublons et assistants de développement. Dans cette leçon, tu exploreras ces cas d’usage avec du code Python concret.

Ces quatre cas d’usage partagent une caractéristique commune : ils exploitent la géométrie de l’index plutôt qu’une requête. Une fois tes fichiers placés dans l’espace vectoriel, leurs positions relatives racontent une histoire sur le projet lui-même : ce qui ressemble à quoi, ce qui se répète et ce qui se distingue.

Analytique de dépôt

Analyse la structure sémantique d’un projet pour comprendre comment le code est organisé. K-Means regroupe les fichiers en cinq familles basées sur leur proximité vectorielle, sans jamais regarder l’arborescence des dossiers. Le résultat est souvent instructif : sur un projet désorganisé, tu verras des fichiers provenant de répertoires très différents atterrir dans le même cluster car ils traitent en réalité du même sujet.

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

Le paramètre random_state=42 fige l’initialisation : sans lui, deux exécutions successives produiraient des numéros de clusters différents, rendant impossible la comparaison des analyses dans le temps.

Détection de doublons

Identifie le code dupliqué ou quasi-dupliqué dans ta base. Contrairement à un outil de détection classique qui compare le texte, cette approche repère aussi les duplications réécrites : le fichier copié d’un module à un autre, renommé, avec des variables différentes mais la même logique.

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

La boucle interne commence à i + 1 pour comparer chaque paire une seule fois. Sois toutefois vigilant face au coût : la matrice de similarité est quadratique, et au-delà de quelques milliers de fichiers, tu devras passer à un index approximatif plutôt qu’à un calcul exhaustif. Abaisser le seuil de 0,95 à 0,92 élargit le filet pour capturer les duplications retravaillées, au prix de quelques faux positifs à trier manuellement.

Clustering par fonctionnalité

K-Means exige de connaître à l’avance le nombre de groupes, ce qui est rarement le cas lors de la découverte d’un projet. DBSCAN pallie cette limitation : il détermine lui-même le nombre de groupes et, surtout, permet à un fichier de n’appartenir à aucun groupe, ce qui correspond au libellé « Unclassified » dans le code ci-dessous.

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

La conversion via 1 - cosine_similarity transforme la similarité en distance, le format attendu par DBSCAN avec metric="precomputed". Le paramètre eps=0.3 signifie donc que deux fichiers sont voisins à partir d’une similarité cosinus de 0,7.

Assistant de code contextuel

Ce dernier exemple assemble les briques précédentes en un véritable système RAG pour le code : recherche de fichiers pertinents, construction d’un contexte, puis appel au LLM. Le seuil de 0,5 filtre en amont : il vaut mieux donner au modèle deux fichiers vraiment liés à la question que trois, dont un hors-sujet qui l’égarerait.

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)

Le chemin du fichier est injecté sous forme de commentaire au-dessus de chaque extrait. Ce n’est pas décoratif : le modèle l’utilise pour citer ses sources, et le développeur qui lit la réponse sait immédiatement où aller vérifier.

Métriques de qualité du code

Enfin, les embeddings aident à repérer ce qui sort de l’ordinaire. La fonction calcule le centroïde de l’index – le « fichier moyen » du projet – puis mesure l’écart de chacun par rapport à celui-ci. Un z-score supérieur à 2 signale un fichier qui ne ressemble à rien d’autre : parfois un morceau de code généré ou copié de l’extérieur, parfois simplement le seul fichier écrit dans un ancien style. Dans les deux cas, c’est un bon candidat pour une revue.

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

Rappelle-toi que « atypique » ne signifie pas « mauvais ». L’outil te fournit une liste de fichiers à examiner, pas un verdict : c’est un point de départ pour une revue humaine, jamais une métrique à afficher sur un tableau de bord de qualité.

Galvenās atziņas

  • Les embeddings de code permettent un clustering automatique par fonctionnalité
  • La détection de doublons utilise un seuil de similarité cosinus (0,92–0,95)
  • Un assistant de code combine la recherche sémantique avec un LLM pour du RAG de code
  • Les fichiers atypiques (outliers) peuvent signaler du code nécessitant une revue
  • DBSCAN est préférable à K-Means lorsque le nombre de groupes est inconnu