Przejdź do głównej treści
Polski— Wybierz język
Menu

Przypadek użycia: Embeddingi kodu

Lekcja 8 z 18 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Poza wyszukiwaniem
  2. Analityka repozytorium
  3. Wykrywanie duplikatów
  4. Grupowanie według funkcjonalności
  5. Kontekstowy asystent kodu
  6. Metryki jakości kodu
  7. Kluczowe wnioski

Poza wyszukiwaniem

Embeddingi kodu służą nie tylko do wyszukiwania semantycznego. Otwierają one drogę do zaawansowanych zastosowań: analityki repozytorium, grupowania, wykrywania duplikatów oraz asystentów programistycznych. W tej lekcji poznasz te przypadki użycia na konkretnych przykładach w Pythonie.

Te cztery scenariusze mają jedną wspólną cechę: wykorzystują geometrię indeksu, a nie konkretne zapytanie. Gdy pliki znajdą się już w przestrzeni wektorowej, ich wzajemne położenie opowiada historię samego projektu: co do czego jest podobne, co się powtarza i co wyróżnia się na tle reszty.

Analityka repozytorium

Przeanalizuj semantyczną strukturę projektu, aby zrozumieć, jak zorganizowany jest kod. Algorytm K-Means grupuje pliki w pięć rodzin na podstawie ich bliskości wektorowej, całkowicie ignorując drzewo folderów. Wynik bywa pouczający: w nieuporządkowanym projekcie zobaczysz, jak pliki z zupełnie różnych katalogów lądują w tym samym klastrze, ponieważ tak naprawdę dotyczą tego samego zagadnienia.

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

Parametr random_state=42 ustala inicjalizację: bez niego dwa kolejne uruchomienia dałyby różne numery klastrów, co uniemożliwiłoby porównywanie analiz w czasie.

Wykrywanie duplikatów

Zidentyfikuj zduplikowany lub niemal zduplikowany kod w swojej bazie. W przeciwieństwie do klasycznych narzędzi porównujących tekst, to podejście wykrywa również duplikaty przerobione – plik skopiowany z jednego modułu do drugiego, przemianowany, z innymi nazwami zmiennych, ale tą samą logiką.

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

Pętla wewnętrzna zaczyna się od i + 1, aby porównać każdą parę tylko raz. Miej jednak na uwadze koszt: macierz podobieństwa ma złożoność kwadratową i przy kilku tysiącach plików będziesz musiał przejść na indeks przybliżony zamiast obliczeń wyczerpujących. Obniżenie progu z 0,95 do 0,92 zarzuca szerszą sieć na przerobione duplikaty, kosztem kilku fałszywych trafień do ręcznej weryfikacji.

Grupowanie według funkcjonalności

K-Means wymaga wcześniejszej znajomości liczby grup, co rzadko ma miejsce podczas odkrywania projektu. DBSCAN rozwiązuje ten problem: sam określa liczbę grup i, co kluczowe, pozwala plikowi nie należeć do żadnej z nich – właśnie to oznacza etykieta „Unclassified“ w poniższym kodzie.

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

Konwersja przez 1 - cosine_similarity zamienia podobieństwo na odległość, czyli format oczekiwany przez DBSCAN z parametrem metric="precomputed". Parametr eps=0.3 oznacza więc, że dwa pliki są sąsiadami począwszy od podobieństwa kosinusowego wynoszącego 0,7.

Kontekstowy asystent kodu

Ten ostatni przykład łączy poprzednie elementy w prawdziwy system RAG dla kodu: wyszukiwanie odpowiednich plików, budowanie kontekstu, a następnie wywołanie LLM. Próg 0,5 filtruje dane na wstępie – lepiej podać modelowi dwa pliki naprawdę związane z pytaniem niż trzy, z których jeden jest niezgodny z tematem i wprowadzi go w błąd.

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)

Ścieżka pliku jest wstrzykiwana jako komentarz nad każdym fragmentem kodu. Nie jest to ozdobnik: model używa jej do cytowania źródeł, a programista czytający odpowiedź od razu wie, gdzie udać się po weryfikację.

Metryki jakości kodu

Na koniec embeddingi pomagają wykryć to, co wyróżnia się jako nietypowe. Funkcja oblicza centroid indeksu – „średni plik“ projektu – a następnie mierzy, jak bardzo każdy z nich odbiega od niego. Wynik z-score większy niż 2 sygnalizuje plik, który nie przypomina niczego innego: czasem jest to kod wygenerowany lub skopiowany z zewnątrz, a czasem po prostu jedyny plik napisany w starym stylu. W obu przypadkach jest to dobry kandydat do przeglądu.

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

Pamiętaj, że „nietypowy“ nie oznacza „zły“. Narzędzie dostarcza listę plików do przejrzenia, a nie wyrok: jest to punkt wyjścia do ludzkiej weryfikacji, nigdy metryka do wyświetlania na dashboardzie jakości.

Kluczowe wnioski

  • Embeddingi kodu umożliwiają automatyczne grupowanie według funkcjonalności
  • Wykrywanie duplikatów opiera się na progu podobieństwa kosinusowego (0,92–0,95)
  • Asystent kodu łączy wyszukiwanie semantyczne z LLM w ramach RAG dla kodu
  • Nietypowe pliki (odstające) mogą sygnalizować kod wymagający przeglądu
  • DBSCAN jest preferowany nad K-Means, gdy liczba grup jest nieznana