Búsqueda semántica de código
En esta página
Búsqueda de código por significado
La búsqueda tradicional de código se basa en palabras clave: escribes el nombre de una función o una palabra extraída de un comentario. La búsqueda semántica de código va más allá: localiza código por su significado o intención, aunque los términos exactos no coincidan.
Con codestral-embed, puedes buscar código usando lenguaje natural. Una consulta como «función que ordena una lista» encontrará una implementación de quicksort aunque la palabra «sort» no aparezca nunca en el código. Esto refleja la realidad diaria de un desarrollador que se incorpora a un proyecto existente: sabes lo que buscas, pero no tienes ni idea de cómo lo nombró el equipo anterior.
Indexación de un directorio de código
El primer paso consiste en extraer y codificar cada archivo o función de un proyecto. La siguiente función recorre el árbol de directorios y filtra las carpetas que ensuciarían el índice. Solo node_modules puede ser diez veces más grande que el código que has escrito realmente, y ninguno de sus archivos es relevante para tu búsqueda.
import os
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
def extract_code_files(directory, extensions=(".py", ".js", ".ts")):
"""Extrae todos los archivos de código de un directorio."""
code_files = []
for root, dirs, files in os.walk(directory):
# Ignorar directorios irrelevantes
dirs[:] = [d for d in dirs if d not in ("node_modules", ".git", "__pycache__", "venv")]
for f in files:
if any(f.endswith(ext) for ext in extensions):
filepath = os.path.join(root, f)
with open(filepath, "r", encoding="utf-8", errors="ignore") as fh:
content = fh.read()
if content.strip():
code_files.append({
"path": filepath,
"content": content[:4000], # Truncar si es demasiado largo
})
return code_files
# Extraer archivos
code_files = extract_code_files("./my-project/")
print(f"{len(code_files)} code files found")
Dos detalles de implementación merecen atención. Modificar dirs[:] in situ no es solo una abreviatura; es la única forma de evitar que os.walk descienda a esos directorios. Reasignar la variable sin usar la rebanada no tendría ningún efecto. En cuanto al truncamiento a 4.000 caracteres, esto te protege de archivos monstruosos que harían explotar la solicitud, al tiempo que conserva la cabecera del archivo (importaciones, definiciones principales), que contiene la señal más significativa.
Codificación e indexación
La codificación se realiza en lotes de veinte archivos, con un indicador de progreso. En un repositorio con varios cientos de archivos, este bucle tarda varios minutos. Sin un contador, no hay manera de distinguir entre un procesamiento lento y una llamada bloqueada.
def index_code_files(code_files, batch_size=20):
"""Crea embeddings para todos los archivos de código."""
all_embeddings = []
for i in range(0, len(code_files), batch_size):
batch = code_files[i:i + batch_size]
inputs = [f["content"] for f in batch]
response = client.embeddings.create(
model="codestral-embed",
inputs=inputs,
)
all_embeddings.extend([d.embedding for d in response.data])
print(f"Encoded {min(i + batch_size, len(code_files))}/{len(code_files)}")
return np.array(all_embeddings)
embeddings = index_code_files(code_files)
print(f"Index: {embeddings.shape}")
El orden de los embeddings en la matriz coincide exactamente con el orden de code_files. Esta correspondencia implícita es el eje de todo lo que sigue: permite que un índice devuelto por la clasificación apunte a una ruta de archivo específica.
Búsqueda en lenguaje natural
La gran ventaja de codestral-embed es que puedes buscar mediante una pregunta en francés o en inglés. La función codifica la consulta con el mismo modelo, calcula las similitudes frente a todo el índice y devuelve los top_k mejores resultados junto con una vista previa del contenido.
from sklearn.metrics.pairwise import cosine_similarity
def search_code(query, code_files, embeddings, top_k=5):
"""Busca código usando descripciones en lenguaje natural."""
# Codificar la consulta
response = client.embeddings.create(
model="codestral-embed",
inputs=[query],
)
query_emb = np.array(response.data[0].embedding)
# Calcular similitudes
sims = cosine_similarity([query_emb], embeddings)[0]
# Resultados top-k
top_indices = np.argsort(sims)[::-1][:top_k]
results = []
for idx in top_indices:
results.append({
"path": code_files[idx]["path"],
"score": float(sims[idx]),
"preview": code_files[idx]["content"][:200],
})
return results
# Búsquedas en lenguaje natural
queries = [
"email validation function",
"database connection",
"HTTP error handling",
"sorting algorithm",
]
for query in queries:
print(f"\n--- Query: '{query}' ---")
results = search_code(query, code_files, embeddings, top_k=3)
for r in results:
print(f" [{r['score']:.3f}] {r['path']}")
El campo preview tiene una utilidad práctica inmediata: te evita tener que abrir cinco archivos para averiguar cuál coincide realmente. En una integración con el editor, estos doscientos caracteres se convierten en la línea de vista previa que se muestra bajo cada resultado.
Búsqueda entre lenguajes
codestral-embed entiende la lógica independientemente del lenguaje. Puedes buscar un patrón en Python y encontrar su equivalente en JavaScript:
# Buscar usando un ejemplo de código en un lenguaje...
query_python = "def authenticate(username, password): check credentials and return token"
# ...y encontrar el equivalente en otro lenguaje
results = search_code(query_python, code_files, embeddings)
# Puede devolver un archivo .js con una función similar
Esta capacidad es invaluable para aplicaciones divididas entre un backend en Python y un frontend en TypeScript, donde la misma regla de negocio a veces se implementa en ambos lados. Encontrar ambas implementaciones desde una única consulta te ayuda a detectar divergencias antes de que un bug las revele en producción.
Búsqueda por firma de función
También puedes buscar por forma esperada en lugar de por dominio funcional. Describir la estructura (una función asíncrona, una clase, un middleware, un test) orienta la búsqueda hacia un tipo de objeto de código en lugar de hacia un tema concreto.
technical_queries = [
"async function that fetches data from API and handles errors",
"class with CRUD methods for database operations",
"middleware that checks authentication token",
"unit test for user registration",
]
for q in technical_queries:
results = search_code(q, code_files, embeddings, top_k=2)
print(f"\n{q}:")
for r in results:
print(f" -> {r['path']} (score: {r['score']:.3f})")
Prueba estas cuatro consultas en tu propio repositorio antes de continuar. Observarás que los resultados se degradan significativamente en archivos muy largos, donde el truncamiento de 4.000 caracteres ha eliminado la parte útil. Este es el momento de decidir si indexar archivos completos o, mejor aún, funciones desglosadas una a una.
Puntos clave
- codestral-embed te permite buscar código usando descripciones en lenguaje natural
- La indexación implica codificar todos los archivos de código en vectores
- La búsqueda entre lenguajes funciona: un patrón en Python encuentra el equivalente en JS
- Filtra los directorios irrelevantes (node_modules, .git, venv) durante la extracción
- Trunca los archivos muy largos para mantenerte dentro de los límites del modelo