Премини към основното съдържание
Български— Изберете език
Меню

Случай на употреба: Вграждания на код

Урок 8 от 18 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Отвъд търсенето
  2. Анализ на хранилището
  3. Откриване на дубликати
  4. Клъстериране по функционалност
  5. Контекстуален асистент за код
  6. Метрики за качество на кода
  7. Ключови изводи

Отвъд търсенето

Вгражданията на код не служат само за семантично търсене. Те отключват усъвършенствани приложения: анализ на хранилища, клъстериране, откриване на дубликати и асистенти за разработка. В този урок ще разгледате тези случаи на употреба с конкретен Python код.

Тези четири случая имат обща черта: те използват геометрията на индекса, а не заявка. След като файловете Ви бъдат разположени във векторно пространство, относителните им позиции разказват история за самия проект: кое прилича на кое, кое се повтаря и кое се откроява.

Анализ на хранилището

Анализирайте семантичната структура на даден проект, за да разберете как е организиран кодът. K-Means групира файловете в пет семейства въз основа на тяхната векторна близост, без никога да разглежда дървото с папки. Резултатът често е поучителен: при объркан проект ще видите файлове от много различни директории да попадат в един и същи клъстер, защото всъщност се занимават с една и съща тема.

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 фиксира инициализацията: без него две последователни изпълнения биха дали различни номера на клъстерите, което прави невъзможно сравняването на анализите във времето.

Откриване на дубликати

Идентифицирайте дублиран или почти дублиран код във Вашата база. За разлика от класически инструмент за откриване, който сравнява текст, този подход забелязва и пренаписани дубликати – файл, копиран от един модул в друг, преименуван, с различни променливи, но със същата логика.

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 + 1, за да сравни всяка двойка само веднъж. Внимавайте обаче с разходите: матрицата на сходството е квадратична и над няколко хиляди файла ще трябва да преминете към приблизителен индекс, вместо към изчерпателно изчисление. Намаляването на прага от 0.95 на 0.92 хвърля по-широка мрежа за преработени дубликати, за сметка на няколко фалшиви положителни резултата, които трябва да сортирате ръчно.

Клъстериране по функционалност

K-Means изисква предварително да знаете броя на групите, което рядко е така, когато откривате даден проект. DBSCAN решава това ограничение: той сам определя броя на групите и, което е най-важно, позволява един файл да не принадлежи към никоя – това е значението на етикета „Unclassified“ в кода по-долу.

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

Преобразуването чрез 1 - cosine_similarity превръща сходството в разстояние, форматът, който DBSCAN очаква с metric="precomputed". Параметърът eps=0.3 следователно означава, че два файла са съседи, започвайки от косинусно сходство от 0.7.

Контекстуален асистент за код

Този последен пример сглобява предишните строителни блокове в истинска RAG система за код: търсене на подходящи файлове, изграждане на контекст и след това извикване на LLM. Прагът от 0.5 филтрира предварително – по-добре е да дадете на модела два файла, наистина свързани с въпроса, отколкото три, един от които е извън темата и ще го подведе.

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)

Пътят до файла се инжектира като коментар над всеки фрагмент. Това не е декоративно: моделът го използва, за да цитира източниците си, а разработчикът, четящ отговора, веднага знае къде да отиде да провери.

Метрики за качество на кода

Накрая, вгражданията помагат да се открие онова, което се откроява като необичайно. Функцията изчислява центроида на индекса – „средния файл“ на проекта – и след това измерва колко далеч се отклонява всеки от тях. Z-оценка, по-голяма от 2, сигнализира за файл, който не прилича на нищо друго: понякога това е код, генериран или копиран отвън, понякога просто единственият файл, написан в стар стил. И в двата случая това е добър кандидат за преглед.

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

Не забравяйте, че „атипичен“ не означава „лош“. Инструментът Ви дава списък с файлове за разглеждане, а не присъда: това е отправна точка за човешки преглед, никога метрика за показване на таблото за качество.

Ключови изводи

  • Вгражданията на код позволяват автоматично клъстериране по функционалност
  • Откриването на дубликати използва праг на косинусно сходство (0.92–0.95)
  • Асистентът за код комбинира семантично търсене с LLM за код RAG
  • Атипичните файлове (отклонения) могат да сигнализират за код, нуждаещ се от преглед
  • DBSCAN е за предпочитане пред K-Means, когато броят на групите е неизвестен