Un intermediario de API de embeddings suele presentarse como "otra dirección, un poco más barata". Pero la vectorización es una tarea por lotes: una migración puede implicar cientos de miles de textos. Si el intermediario limita el tráfico, trunca las entradas o cambia de modelo sin avisar, la pérdida no es una sola solicitud, sino la fiabilidad de todo el índice.

Este artículo aborda cuatro cuestiones: qué formas adopta un intermediario, cómo diseñar solicitudes por lotes, cómo verificar la facturación y cómo migrar y validar el servicio. Los modelos y precios concretos deben consultarse en los precios de los modelos del sitio.

Nota: OpenAI y los demás nombres de modelos y servicios son marcas de sus respectivos titulares. Este artículo no tiene relación de subordinación con los proveedores mencionados. El mercado de intermediarios cambia con rapidez y nada de lo aquí expuesto constituye un respaldo a un proveedor concreto.

1. Intermediario, proxy y pasarela no son lo mismo

  • Proxy de red: solo resuelve la accesibilidad de red y reenvía solicitudes HTTP o HTTPS; la clave la sigue gestionando el cliente.
  • Intermediario comercial: un proveedor reenvía la solicitud al servicio upstream y puede añadir facturación, límites, registros y factura. En el mercado también existen claves compartidas o revendidas, y su estabilidad depende del operador.
  • Pasarela de IA unificada: ofrece un punto de entrada compatible con OpenAI, agrupa varios modelos, emite claves independientes y proporciona consola y estadísticas de uso.
  • Proxy propio: se despliega un proxy inverso o una pasarela propia. Es la opción con más control, pero tanto la operación como las cuentas upstream corren por cuenta del equipo.

Antes de contratar, hay que confirmar qué capa de servicio ofrece la otra parte, a quién pertenece la clave y por dónde pasan los datos. Si estos conceptos no están claros, cualquier comparación posterior pierde sentido.

Aspecto Conexión directa oficial Proxy propio Intermediario comercial Pasarela de IA unificada
Criterio de facturación Factura del proveedor, reglas claras Factura upstream más costos propios Depende del operador; exige conciliación Factura unificada del sitio
Rendimiento por lotes Limitado por la cuenta Se puede encolar, pero sigue sujeto al upstream Puede usar un grupo compartido; hay que confirmarlo Depende de los límites y la programación de la pasarela
Propiedad de la clave Propia Propia Puede ser compartida o revendida Normalmente clave independiente
Frontera de datos Evaluación propia Responsabilidad propia Hay que revisar términos y retención Hay que revisar términos y cualificación
Factura y contrato Según la entidad Sin contrato con terceros Según la capacidad del proveedor Normalmente permite factura
Costo de operación Medio Alto De bajo a medio Bajo

2. Solicitudes por lotes: primero la prueba de carga, después el precio

El rendimiento de los embeddings depende de tres variables: número de elementos por solicitud, longitud de cada texto y concurrencia. Cada proveedor impone límites al número de elementos, al total de tokens y al tamaño del cuerpo de la solicitud. Si se superan, puede devolverse un error de parámetros o la capa intermedia puede truncar la entrada directamente.

La prueba de carga debe usar datos de producción. Se toma un conjunto de fragmentos reales, se agrupan en lotes pequeños, medianos y grandes, y se observan el tiempo por lote, la latencia p95, la proporción de respuestas 429 y los tipos de error. Un lote más grande no siempre es mejor: si falla, cuesta más reprocesarlo y el tiempo de espera es más difícil de controlar.

Flujo de fragmentación recomendado:

  1. Analizar primero la distribución de longitudes y estimar por tokens, no cortar por número de elementos.
  2. Fijar un límite por lote y dejar margen para textos largos.
  3. Empezar con poca concurrencia y aumentarla en cada ronda, registrando rendimiento y tasa de error.
  4. Detener el aumento al alcanzar el rendimiento objetivo, sin consumir todo el margen.
  5. Guardar en disco el hash de entrada, el consumo de tokens y el resultado de cada lote para facilitar la conciliación y la reanudación.

3. Reintentos y fallos parciales

Las solicitudes de embeddings son operaciones de solo lectura: reintentar no duplica escrituras, pero puede convertir un fallo en una factura mayor. Los errores 429 y los 5xx transitorios admiten retroceso exponencial con fluctuación aleatoria; ante 401, 403, 404 y errores de parámetros conviene detenerse de inmediato y corregir la clave, la dirección o el cuerpo de la solicitud.

Los fallos parciales requieren un tratamiento aparte. Si en un lote de 200 elementos tres son rechazados por exceso de longitud, no se debe reintentar el lote completo sin límite: hay que separar los textos problemáticos, corregirlos o truncarlos y enviarlos por separado, mientras el resto se guarda con normalidad. La ingesta debe usar un upsert basado en el hash del contenido para que una repetición no genere registros duplicados.

import hashlib
import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RELAY_API_KEY"],
    base_url=os.environ["RELAY_BASE_URL"],
    timeout=60.0,
    max_retries=0,
)
MODEL = os.environ["EMBEDDING_MODEL"]

def key_of(text):
    return hashlib.sha256(text.encode("utf-8")).hexdigest()

def embed_with_retry(batch, attempts=4):
    for i in range(attempts):
        try:
            resp = client.embeddings.create(model=MODEL, input=batch)
            store = {
                key_of(batch[d.index]): d.embedding
                for d in resp.data
            }
            return store, resp.usage
        except Exception as exc:
            if i == attempts - 1:
                raise
            time.sleep(min(2 ** i, 30))

texts = ["fragmento de documento uno", "fragmento de documento dos", "fragmento de documento tres"]
store, usage = embed_with_retry(texts)
print(len(store), len(next(iter(store.values()))), usage)

4. Transparencia de la facturación

Los embeddings suelen facturarse por tokens de entrada, sin tokens de salida, lo que los diferencia de los modelos conversacionales. Al conciliar hay que preguntar:

  • Cómo se calculan los tokens y si coinciden con el tokenizador del proveedor.
  • Si las solicitudes fallidas y los reintentos se facturan.
  • Si hay descuentos por lote, caché o precios escalonados.
  • Si el consumo se puede exportar por proyecto, clave y modelo.
  • Si el prepago tiene vigencia y si el saldo es reembolsable.
  • Cómo se determinan el contenido de la factura, la moneda y el tipo de cambio.

Un "multiplicador bajo" no equivale a un costo total bajo. Si el intermediario factura también los reintentos fallidos, o si sus estadísticas de uso no coinciden con el campo usage de las respuestas, el precio bajo queda compensado por pérdidas ocultas. Los precios y reglas concretos deben consultarse en los precios de los modelos y en la factura del proveedor; no conviene fiarse de promesas verbales.

5. Riesgo de las claves y frontera de datos

El punto que más se pasa por alto en un intermediario es la propiedad de la clave. Una clave compartida, un saldo revendido o un crédito de origen desconocido pueden acarrear cuatro problemas: si el upstream bloquea la cuenta, el negocio se interrumpe; si varios inquilinos comparten clave, las limitaciones de tráfico se afectan entre sí; el contenido de las solicitudes pasa por un tercero y la retención de registros no es transparente; y si los términos de servicio no permiten la reventa, una disputa carece de base.

Al elegir proveedor hay que confirmar al menos la entidad legal, los términos de servicio, la política de privacidad, la ubicación de retención de datos, la capacidad de emitir factura y un contacto para incidencias. Los textos con datos personales, contratos o secretos no deben enviarse a un intermediario que no pueda explicar adónde van. En entornos muy regulados conviene evaluar primero la conexión directa, el despliegue privado o un servicio con acuerdo de tratamiento de datos.

6. Lista de migración

Para pasar de la conexión directa a un intermediario o una pasarela, se recomienda este orden:

  1. Inventariar los modelos, dimensiones, parámetros de lote y estructura del índice actuales, y registrar la tasa de éxito y la latencia p95 de referencia.
  2. Ejecutar una muestra fija contra la conexión directa y guardar vectores, usage y tiempos.
  3. Crear una clave de prueba con presupuesto y alertas; no reutilizar la clave de producción.
  4. Cambiar solo base_url y api_key y ejecutar la solicitud mínima en el entorno de preproducción.
  5. Llamar al intermediario con la misma muestra y comparar dimensión, número de elementos, usage y similitud coseno.
  6. Enviar entre el 5 % y el 10 % de las tareas por lotes al nuevo canal, observar de 3 a 7 días y mantener la conexión directa como reversión.
  7. Tras la migración completa, conciliar durante una semana y confirmar que factura, registros ingresados y reintentos fallidos coinciden.
  8. Conservar al menos una versión del índice antiguo y limpiarlo solo cuando la recuperación sea estable.

Si el intermediario utiliza un modelo distinto, los vectores antiguos no se pueden mezclar directamente. Hay que crear un índice paralelo, recalcular todo y comparar la recuperación antes de decidir el cambio.

7. Cómo verificar si un intermediario es fiable

  • Coherencia de vectores: enviar la misma entrada por la conexión directa y por el intermediario, y comparar dimensión y similitud coseno; si se desvían, comprobar primero si se cambió el modelo o se truncó la entrada.
  • Coherencia de consumo: contrastar el campo usage de cada lote con la factura del panel, prestando atención a si los fallos y reintentos se cobran dos veces.
  • Latencia y tasa de error: probar con lotes reales en hora punta y registrar p50/p95, proporción de 429 y de 5xx.
  • Límites por lote: confirmar el máximo de elementos, de tokens totales y de tamaño del cuerpo para evitar truncamientos en producción.
  • Aislamiento de claves: verificar si la clave es independiente, si se puede rotar y si la cuota y los límites se comparten con otros clientes.
  • Contrato y soporte: revisar entidad, términos, facturación y respuesta a incidencias. Que solo haya un contacto personal y se rechace el detalle de consumo son señales de alerta.

El campo model de la respuesta no sirve por sí solo como prueba, porque puede reescribirse. La verificación combinada es más fiable que una comprobación aislada.

8. Cuándo no conviene usar un intermediario

Si los datos son sensibles y no se puede auditar la política de retención, si se necesita soporte directo del proveedor, si el volumen de llamadas es muy bajo o si el equipo no tiene personal para conciliar facturas, un intermediario puede no compensar. Tampoco permite eludir los límites del upstream ni sus términos de servicio. Si solo se vectoriza a pequeña escala de forma ocasional, la conexión directa con un script sencillo puede resultar más cómoda.

Si se necesita un punto de entrada unificado y comparar varios modelos, se puede crear una clave de prueba en ZSQH AI Gateway, validar primero la coherencia de los vectores con una muestra fija y después migrar las tareas por lotes; los modelos disponibles y la facturación figuran en los precios de los modelos.

Preguntas frecuentes

¿En qué se diferencia un intermediario de embeddings de uno de chat?

Un intermediario de chat se centra en la salida en streaming y en la latencia del primer token; uno de embeddings se centra en el rendimiento por lotes, el límite por solicitud, la reanudación tras fallos y la coherencia de los vectores. Al conciliar hay que recordar que los embeddings suelen facturar solo tokens de entrada.

¿Se pueden mezclar los vectores devueltos por el intermediario con los de la conexión directa?

Solo se recomienda mezclarlos si son el mismo modelo y la misma versión. Los espacios vectoriales de modelos distintos son diferentes y, aunque la dimensión coincida, no se pueden introducir en el mismo índice. Antes de migrar conviene comparar la similitud coseno con una muestra fija.

¿Qué hacer si falla la mitad de una solicitud por lotes?

Primero hay que identificar el tipo de fallo: los límites de tráfico y los 5xx transitorios admiten reintento con retroceso; los textos demasiado largos o los errores de parámetros deben separarse y tratarse aparte. Usar el hash del contenido como clave de idempotencia permite reprocesar solo lo que falta y evitar duplicados.

¿Cómo se calcula la facturación de un intermediario?

La mayoría factura por tokens de entrada, pero el criterio de conteo, el cobro de fallos y reintentos y los descuentos por lote varían. Hay que guiarse por la factura y el detalle de consumo, y dejar estos puntos por escrito en la tabla comparativa antes de contratar.

¿Hay que volver a vectorizar al migrar a un intermediario?

Con el mismo modelo y la misma versión, normalmente no; si se cambia de modelo, hay que reconstruir el índice. Aunque no haga falta recalcular, conviene conservar el índice antiguo y una ruta de reversión, y validar la coherencia con una muestra fija.

Lecturas relacionadas: