Crear incrustaciones
En esta página
Codificar fragmentos en vectores
Tus documentos ya están divididos en fragmentos limpios. El siguiente paso es transformarlos en incrustaciones (embeddings) mediante la API mistral-embed y almacenar estos vectores en un almacén vectorial que actuará como tu motor de búsqueda. Este es el momento en que tu corpus deja de ser texto plano para convertirse en geometría consultable. Unas pocas precauciones de ingeniería —lotes, reintentos y persistencia— marcan la diferencia entre un prototipo frágil y un índice fiable.
Para un corpus pequeño, digamos menos de cien fragmentos, basta con una única llamada directa. Extrae el texto de tus diccionarios de fragmentos, pásalos tal cual a la API y recupera la matriz completa. La forma (87, 1024) que se muestra al final de la ejecución es tu primera comprobación de sanidad: tantas filas como fragmentos y 1024 columnas, ya que esa es la dimensión de mistral-embed. Si el número de filas no coincide, es que se ha colado algún fragmento vacío en el lote.
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
# Supongamos que chunks es la lista de nuestros fragmentos preparados
chunk_texts = [c["text"] for c in chunks]
# Codificar en una única llamada
response = client.embeddings.create(
model="mistral-embed",
inputs=chunk_texts,
)
embeddings = np.array([d.embedding for d in response.data])
print(f"Incrustaciones: {embeddings.shape}")
# Incrustaciones: (87, 1024) por ejemplo
Codificación por lotes
Más allá de unas pocas docenas de fragmentos, una única llamada choca con los límites de la API. La solución consiste en dividir la lista en lotes y concatenar los resultados. La función siguiente procesa porciones de 25 elementos y muestra el progreso. Esto no es cosmético: en un corpus de varios miles de fragmentos, la codificación lleva varios minutos, y querrás saber en qué punto está el proceso en lugar de mirar fijamente un terminal silencioso. El orden se preserva, de modo que cada vector sigue alineado con su fragmento correspondiente en tu lista original.
def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
"""Codificar una lista de fragmentos por lotes."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
print(f" Codificando lote {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
f"({len(batch)} fragmentos)...")
response = client.embeddings.create(
model=model,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
return np.array(all_embeddings)
# Codificar todos los fragmentos
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectores de {embeddings.shape[1]} dimensiones")
Sobrevivir a errores de red
En producción, una llamada a la API acabará fallando: caída de red, límite de tasa alcanzado o interrupción temporal. Sin protección, tu indexación se detiene en el lote 180 de 400 y vuelves a empezar de cero. La versión robusta envuelve cada lote en un bucle de reintentos con retroceso exponencial: un segundo, luego dos, luego cuatro. Este espaciado creciente importa: reintentar inmediatamente tras un rechazo por cuota solo empeora las cosas. Tras tres fallos consecutivos, la función lanza una excepción explícita que nombra el lote defectuoso, en lugar de devolver una matriz truncada donde solo descubrirías el hueco durante la búsqueda.
import time
def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
"""Codificación robusta con gestión de errores."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
for attempt in range(max_retries):
try:
response = client.embeddings.create(
model="mistral-embed",
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
break # Éxito, salir del bucle de reintentos
except Exception as e:
wait_time = 2 ** attempt # Retroceso exponencial: 1s, 2s, 4s
print(f" Error en el lote {i // batch_size + 1}, "
f"intento {attempt + 1}/{max_retries}: {e}")
if attempt < max_retries - 1:
print(f" Esperando {wait_time}s antes de reintentar...")
time.sleep(wait_time)
else:
raise RuntimeError(
f"Fallo tras {max_retries} intentos para el lote {i // batch_size + 1}"
)
return np.array(all_embeddings)
Guardar el índice en disco
Cada ejecución de codificación consume tiempo y llamadas a la API con coste asociado. Recalcular vectores cada vez que se inicia tu aplicación es un desperdicio puro, especialmente porque el corpus en sí no ha cambiado. El guardado se realiza en dos archivos complementarios: los vectores van a NumPy, un formato binario compacto que se carga al instante, mientras que los metadatos —texto, fuente, posición— van a un JSON legible que puedes abrir para inspeccionar un fragmento sospechoso. Ambos archivos son interdependientes y están vinculados por el orden de línea: nunca regeneres uno sin el otro, o tus resultados de búsqueda apuntarán a textos incorrectos.
import json
def save_index(chunks, embeddings, filepath="rag_index"):
"""Guardar fragmentos e incrustaciones."""
# Guardar incrustaciones (NumPy)
np.save(f"{filepath}_embeddings.npy", embeddings)
# Guardar metadatos (JSON)
metadata = []
for c in chunks:
metadata.append({
"text": c["text"],
"source": c.get("source", ""),
"chunk_index": c.get("chunk_index", 0),
})
with open(f"{filepath}_metadata.json", "w", encoding="utf-8") as f:
json.dump(metadata, f, ensure_ascii=False, indent=2)
print(f"Índice guardado: {len(chunks)} fragmentos, {embeddings.shape}")
def load_index(filepath="rag_index"):
"""Cargar fragmentos e incrustaciones desde disco."""
embeddings = np.load(f"{filepath}_embeddings.npy")
with open(f"{filepath}_metadata.json", "r", encoding="utf-8") as f:
metadata = json.load(f)
print(f"Índice cargado: {len(metadata)} fragmentos, {embeddings.shape}")
return metadata, embeddings
# Guardar
save_index(chunks, embeddings)
# Cargar (en el siguiente inicio)
chunks_loaded, embeddings_loaded = load_index()
Verificar antes de continuar
Un índice corrupto de forma silenciosa se manifiesta tarde, normalmente cuando un usuario reporta una respuesta absurda. Unas pocas comprobaciones fuera de línea llevan treinta segundos y te evitan ese descubrimiento. La función de verificación muestra primero métricas básicas —número de fragmentos, dimensión, norma media— y luego mide la similitud entre fragmentos vecinos: como provienen del mismo documento, deberían mostrar valores significativamente más altos que dos pasajes aleatorios. La última prueba es la más simple y reveladora: un fragmento comparado consigo mismo debe dar exactamente 1,0. Cualquier otro valor indica un problema de alineación o de conversión numérica.
from sklearn.metrics.pairwise import cosine_similarity
def verify_embeddings(chunks, embeddings, n_tests=5):
"""Verificar la calidad de las incrustaciones con pruebas simples."""
print("=== Verificando incrustaciones ===")
print(f"Número de fragmentos: {len(chunks)}")
print(f"Dimensiones: {embeddings.shape[1]}")
print(f"Norma media: {np.linalg.norm(embeddings, axis=1).mean():.4f}")
# Prueba: los fragmentos del mismo documento deberían estar más cerca
for i in range(min(n_tests, len(chunks) - 1)):
sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
print(f" Similitud fragmento {i} <-> {i+1}: {sim:.4f}")
# Prueba: un fragmento comparado consigo mismo = 1,0
self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
print(f" Autosimilitud (debe ser 1,0): {self_sim:.6f}")
verify_embeddings(chunks, embeddings)
En conjunto, el flujo de trabajo se reduce a cuatro líneas útiles. Preparas los fragmentos con la canalización de la lección anterior, codificas en modo robusto, verificas y guardas. Este es el script que volverás a ejecutar cada vez que se actualice el corpus.
# 1. Preparar fragmentos (lección anterior)
chunks = prepare_documents(raw_docs)
# 2. Codificar
embeddings = encode_chunks_robust(chunks, batch_size=25)
# 3. Verificar
verify_embeddings(chunks, embeddings)
# 4. Guardar
save_index(chunks, embeddings)
print("¡Índice listo para búsqueda!")
Puntos clave
- Usa lotes para codificar corpus grandes (lotes de 25–50 fragmentos)
- Añade lógica de reintentos con retroceso exponencial para robustez
- Guarda las incrustaciones en disco (NumPy) para evitar recálculos
- Mantén los metadatos (texto, fuente, posición) en un archivo JSON separado
- Verifica la calidad de las incrustaciones antes de usarlas en producción