Ir al contenido principal
Español— Elegir un idioma
Menú

Caso de uso: Embeddings de código

Lección 8 de 18 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Más allá de la búsqueda
  2. Analítica de repositorios
  3. Detección de duplicados
  4. Agrupación por funcionalidad
  5. Asistente de código contextual
  6. Métricas de calidad de código
  7. Puntos clave

Más allá de la búsqueda

Los embeddings de código no sirven solo para la búsqueda semántica. Habilitan aplicaciones avanzadas: analítica de repositorios, agrupación (clustering), detección de duplicados y asistentes de desarrollo. En esta lección, explorarás estos casos de uso con código Python concreto.

Estos cuatro casos comparten una característica común: aprovechan la geometría del índice en lugar de depender de una consulta. Una vez que tus archivos se sitúan en el espacio vectorial, sus posiciones relativas cuentan una historia sobre el propio proyecto: qué se parece a qué, qué se repite y qué destaca.

Analítica de repositorios

Analiza la estructura semántica de un proyecto para comprender cómo está organizado el código. K-Means agrupa los archivos en cinco familias basándose en su proximidad vectorial, sin mirar nunca el árbol de carpetas. El resultado suele ser instructivo: en un proyecto desordenado, verás archivos de directorios muy distintos acabar en el mismo clúster porque, en realidad, tratan el mismo asunto.

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):
    """Analiza la estructura semántica de un repositorio."""
    # Codifica todos los archivos
    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])

    # Agrupación K-Means
    kmeans = KMeans(n_clusters=n_clusters, random_state=42, n_init=10)
    labels = kmeans.fit_predict(embeddings)

    # Agrupa archivos por clúster
    clusters = {}
    for i, label in enumerate(labels):
        if label not in clusters:
            clusters[label] = []
        clusters[label].append(code_files[i]["path"])

    return clusters

# Uso
clusters = analyze_repo(code_files, n_clusters=5)
for cluster_id, files in clusters.items():
    print(f"\nClúster {cluster_id} ({len(files)} archivos):")
    for f in files[:5]:
        print(f"  - {f}")

El parámetro random_state=42 fija la inicialización: sin él, dos ejecuciones sucesivas producirían números de clúster diferentes, lo que haría imposible comparar análisis a lo largo del tiempo.

Detección de duplicados

Identifica código duplicado o casi duplicado en tu base. A diferencia de una herramienta de detección clásica que compara texto, este enfoque también detecta duplicaciones reescritas: el archivo copiado de un módulo a otro, renombrado, con variables distintas pero la misma lógica.

from sklearn.metrics.pairwise import cosine_similarity

def find_duplicates(code_files, embeddings, threshold=0.95):
    """Encuentra pares de archivos casi idénticos."""
    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]),
                })

    # Ordena por similitud decreciente
    duplicates.sort(key=lambda x: x["similarity"], reverse=True)
    return duplicates

# Encuentra duplicados
dupes = find_duplicates(code_files, embeddings, threshold=0.92)
print(f"{len(dupes)} pares de duplicados potenciales encontrados:")
for d in dupes[:10]:
    print(f"  {d['similarity']:.3f} : {d['file_a']} <-> {d['file_b']}")

El bucle interno comienza en i + 1 para comparar cada par solo una vez. Ten cuidado con el coste, sin embargo: la matriz de similitud es cuadrática y, más allá de unos pocos miles de archivos, tendrás que cambiar a un índice aproximado en lugar de un cálculo exhaustivo. Bajar el umbral de 0,95 a 0,92 lanza una red más amplia para captar duplicaciones reelaboradas, a costa de algunos falsos positivos que habrá que filtrar manualmente.

Agrupación por funcionalidad

K-Means exige conocer de antemano el número de grupos, algo que rara vez ocurre al descubrir un proyecto. DBSCAN soluciona esta limitación: determina él mismo el número de grupos y, lo que es más importante, permite que un archivo no pertenezca a ninguno, que es el significado de la etiqueta «Unclassified» (Sin clasificar) en el código siguiente.

from sklearn.cluster import DBSCAN

def cluster_by_functionality(code_files, embeddings, eps=0.3, min_samples=2):
    """Agrupa código por funcionalidad usando DBSCAN."""
    # DBSCAN sobre distancias coseno
    distance_matrix = 1 - cosine_similarity(embeddings)
    clustering = DBSCAN(eps=eps, min_samples=min_samples, metric="precomputed")
    labels = clustering.fit_predict(distance_matrix)

    # Organiza por clúster
    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)} archivos):")
    for f in files[:3]:
        print(f"  - {f}")

La conversión mediante 1 - cosine_similarity transforma la similitud en distancia, el formato que DBSCAN espera con metric="precomputed". El parámetro eps=0.3 significa, por tanto, que dos archivos son vecinos a partir de una similitud coseno de 0,7.

Asistente de código contextual

Este último ejemplo ensambla los bloques anteriores en un verdadero sistema RAG para código: búsqueda de archivos relevantes, construcción de un contexto y llamada al LLM. El umbral de 0,5 filtra aguas arriba: es mejor dar al modelo dos archivos realmente relacionados con la pregunta que tres, uno de los cuales esté fuera de tema y lo desvíe.

def code_assistant(question, code_files, embeddings, top_k=3):
    """Encuentra código relevante para responder a una pregunta."""
    # Codifica la pregunta
    response = client.embeddings.create(
        model="codestral-embed",
        inputs=[question],
    )
    query_emb = np.array(response.data[0].embedding)

    # Encuentra el código más relevante
    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:  # Umbral mínimo
            context_parts.append(
                f"# Archivo: {code_files[idx]['path']}\n"
                f"{code_files[idx]['content'][:1500]}"
            )

    context = "\n\n---\n\n".join(context_parts)

    # Construye el prompt para el LLM
    prompt = f"""Aquí tienes código relevante de nuestro proyecto:

{context}

Pregunta del desarrollador: {question}

Responde basándote en el código anterior."""

    # Llama al LLM con contexto
    chat_response = client.chat.complete(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}],
    )

    return chat_response.choices[0].message.content

# Uso
answer = code_assistant(
    "¿Cómo funciona la autenticación en este proyecto?",
    code_files,
    embeddings,
)
print(answer)

La ruta del archivo se inyecta como un comentario encima de cada fragmento. Esto no es decorativo: el modelo lo usa para citar sus fuentes, y el desarrollador que lee la respuesta sabe inmediatamente dónde ir a verificar.

Métricas de calidad de código

Por último, los embeddings ayudan a detectar lo que destaca como inusual. La función calcula el centroide del índice —el «archivo promedio» del proyecto— y luego mide cuánto se desvía cada uno. Un valor z superior a 2 señala un archivo que no se parece a nada más: a veces es un trozo de código generado o copiado desde fuera, otras veces simplemente es el único archivo escrito en un estilo antiguo. En ambos casos, es un buen candidato para revisión.

def detect_outliers(code_files, embeddings, threshold=2.0):
    """Detecta archivos de código atípicos."""
    # Calcula el centroide (vector medio)
    centroid = embeddings.mean(axis=0)

    # Distancia de cada archivo al centroide
    distances = np.linalg.norm(embeddings - centroid, axis=1)

    # Archivos más allá de N desviaciones estándar
    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)} archivos atípicos:")
for o in outliers:
    print(f"  z={o['z_score']:.2f} : {o['path']}")

Recuerda que «atípico» no significa «malo». La herramienta te da una lista de archivos que debes mirar, no un veredicto: es un punto de partida para la revisión humana, nunca una métrica que mostrar en un cuadro de mandos de calidad.

Puntos clave

  • Los embeddings de código permiten la agrupación automática por funcionalidad
  • La detección de duplicados usa un umbral de similitud coseno (0,92–0,95)
  • Un asistente de código combina la búsqueda semántica con un LLM para RAG de código
  • Los archivos atípicos (valores atípicos) pueden señalar código que necesita revisión
  • DBSCAN es preferible a K-Means cuando se desconoce el número de grupos