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

Generar embeddings para tus datos

Lección 3 de 22 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Objetivos
  2. Preparar tus datos
  3. Generar embeddings por lotes
  4. Almacenar embeddings
  5. Pipeline completo: de archivos de texto a embeddings
  6. Estimar costes
  7. Resumen

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