Caso de uso: Embeddings de código
En esta página
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