Generar embeddings para tus datos
En esta página
Objetivos
- Preparar tus datos de texto para la generación de embeddings
- Generar embeddings de forma eficiente a gran escala
- Almacenar los vectores para su uso posterior
Preparar tus datos
La calidad de tus embeddings depende directamente de la calidad de tus datos. Un texto plagado de espacios sobrantes, caracteres de control procedentes de una exportación mal configurada o saltos de línea erráticos produce un vector ligeramente desviado. Ese desvío se acumula en cada búsqueda. La limpieza no es cosmética: es la primera y más barata optimización de la relevancia.
import re
def limpiar_texto(texto: str) -> str:
"""Prepara el texto para la generación de embeddings."""
# Eliminar múltiples espacios
texto = re.sub(r"\s+", " ", texto)
# Eliminar caracteres de control
texto = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", texto)
# Recortar espacios al inicio y final
texto = texto.strip()
return texto
# Ejemplo
bruto = " Texto con espacios\n\n\nde sobra "
limpio = limpiar_texto(bruto)
print(limpio) # "Texto con espacios de sobra"
Enriquecer el contexto
Un extracto de documentación aislado pierde parte de su significado sin su título. Toma un párrafo que empieza con «Descarga el paquete desde el sitio oficial»: fuera de contexto, nada indica que se refiere a PostgreSQL, y el vector resultante nunca coincidirá con una consulta sobre PostgreSQL. Al prefijar el contenido con su título y sección, reinyectas esa información en el texto que ve el modelo.
def enriquecer_documento(titulo: str, seccion: str, contenido: str) -> str:
"""Crea texto enriquecido para mejorar el embedding."""
return f"Título: {titulo}\nSección: {seccion}\n\n{contenido}"
texto_enriquecido = enriquecer_documento(
titulo="Instalación de PostgreSQL",
seccion="Guía de inicio rápido",
contenido="Descarga el paquete desde el sitio oficial..."
)
Generar embeddings por lotes
En un corpus real de cientos o miles de documentos, el procesamiento debe dividirse en fragmentos y ser resistente a fallos de red. La función siguiente itera sobre los textos en porciones, ordena sistemáticamente la respuesta por index para asegurar que el vector nº 7 corresponde al documento nº 7, y reintenta una vez tras una pausa si ocurre un error.
from openai import OpenAI
import time
import json
client = OpenAI()
def generar_embeddings(
textos: list[str],
model: str = "text-embedding-3-large",
batch_size: int = 100
) -> list[list[float]]:
"""Genera embeddings por lotes con gestión de errores."""
todos_los_embeddings = []
for i in range(0, len(textos), batch_size):
lote = textos[i:i + batch_size]
print(f"Procesando lote {i // batch_size + 1}/"
f"{(len(textos) - 1) // batch_size + 1}")
try:
response = client.embeddings.create(
input=lote,
model=model
)
# Ordenar por índice para garantizar el orden
embeddings_lote = sorted(
response.data, key=lambda x: x.index
)
todos_los_embeddings.extend(
[item.embedding for item in embeddings_lote]
)
except Exception as e:
print(f"Error en el lote {i}: {e}")
# Reintentar tras una pausa
time.sleep(5)
response = client.embeddings.create(
input=lote,
model=model
)
embeddings_lote = sorted(
response.data, key=lambda x: x.index
)
todos_los_embeddings.extend(
[item.embedding for item in embeddings_lote]
)
return todos_los_embeddings
Ordenar por index es una precaución que nunca debes omitir. Un desplazamiento silencioso de una sola fila basta para asociar cada documento con el vector de su vecino. El síntoma que observarás es que «la búsqueda devuelve basura», sin ningún error técnico que te oriente en la dirección correcta.
Almacenar embeddings
Para un corpus pequeño de unos pocos miles de documentos, un archivo JSON simple que contenga textos, metadatos y vectores funciona perfectamente. Tiene la ventaja de ser legible por humanos cuando necesitas depurar un resultado extraño.
import json
documentos = [
{"id": 1, "texto": "Primer documento...", "metadata": {"source": "faq"}},
{"id": 2, "texto": "Segundo documento...", "metadata": {"source": "docs"}},
]
# Generar embeddings
textos = [d["texto"] for d in documentos]
embeddings = generar_embeddings(textos)
# Añadir vectores a los documentos
for doc, emb in zip(documentos, embeddings):
doc["embedding"] = emb
# Guardar
with open("corpus_embeddings.json", "w") as f:
json.dump(documentos, f)
Más allá de esa escala, JSON se convierte en un cuello de botella: cada número se escribe completo, hinchando el archivo e imponiendo un análisis costoso en cada carga. NumPy almacena los mismos valores en binario en 4 bytes y se recarga al instante.
import numpy as np
# Convertir a matriz NumPy
matriz = np.array(embeddings, dtype=np.float32)
print(f"Forma: {matriz.shape}") # (n_docs, 3072)
# Guardar en formato binario
np.save("embeddings.npy", matriz)
# Cargar
matriz_cargada = np.load("embeddings.npy")
Pipeline completo: de archivos de texto a embeddings
Vamos a unir estos elementos en una función que lee una carpeta, limpia cada archivo, genera los vectores y divide el almacenamiento en dos: metadatos en JSON (legible y editable) y la matriz en NumPy (compacta y rápida).
from openai import OpenAI
from pathlib import Path
import json
import numpy as np
client = OpenAI()
def pipeline_embeddings(carpeta: str, model: str = "text-embedding-3-large"):
"""Pipeline completo: archivos → embeddings → almacenamiento."""
ruta_carpeta = Path(carpeta)
# 1. Leer archivos
documentos = []
for archivo in sorted(ruta_carpeta.glob("*.txt")):
contenido = archivo.read_text(encoding="utf-8")
contenido = limpiar_texto(contenido)
if contenido:
documentos.append({
"id": archivo.stem,
"archivo": archivo.name,
"texto": contenido
})
print(f"{len(documentos)} documentos encontrados")
# 2. Generar embeddings
textos = [d["texto"] for d in documentos]
embeddings = generar_embeddings(textos, model=model)
# 3. Guardar
# Metadatos en JSON
meta = [{"id": d["id"], "archivo": d["archivo"]} for d in documentos]
with open("metadata.json", "w") as f:
json.dump(meta, f, ensure_ascii=False, indent=2)
# Vectores en NumPy
np.save("embeddings.npy", np.array(embeddings, dtype=np.float32))
print(f"Embeddings guardados: {len(embeddings)} vectores "
f"de {len(embeddings[0])} dimensiones")
return documentos, embeddings
# Uso
documentos, embeddings = pipeline_embeddings("./mis_documentos/")
Observa el sorted() en el glob: sin él, el orden de los archivos depende del sistema de archivos, y tus dos archivos de salida corren el riesgo de desincronizarse tras un simple cambio de máquina.
Estimar costes
Antes de lanzar un trabajo masivo, cuenta los tokens localmente con tiktoken. La operación tarda unos segundos y te evita descubrir demasiado tarde que un corpus mal filtrado contenía diez veces el volumen esperado.
import tiktoken
encoder = tiktoken.get_encoding("cl100k_base")
def estimar_coste(textos: list[str], model: str = "text-embedding-3-large"):
"""Estima el coste de los embeddings para una lista de textos."""
total_tokens = sum(len(encoder.encode(t)) for t in textos)
# Precios aproximados por millón de tokens (consulta las tarifas actuales)
precios = {
"text-embedding-3-large": 0.13,
"text-embedding-3-small": 0.02,
}
coste = total_tokens / 1_000_000 * precios.get(model, 0.13)
print(f"Tokens estimados: {total_tokens:,}")
print(f"Coste estimado: ${coste:.4f}")
return total_tokens, coste
Los precios del diccionario son indicativos y envejecen rápido: consulta siempre las tarifas actuales antes de presentar un presupuesto a un cliente.
Resumen
- Limpia y enriquece tus textos antes de generar embeddings
- Usa procesamiento por lotes para corpus grandes
- Almacena los metadatos en JSON y los vectores en NumPy
- Estima tus costes antes de lanzar un trabajo masivo