Para los equipos de China continental, la dificultad de integrar una API de embeddings normalmente no está en el SDK. Lo que consume tiempo es la estabilidad del enlace, cómo pagar, cómo emitir facturas y qué hacer cuando la vectorización por lotes de cientos de miles de textos falla a mitad de camino. Las solicitudes de embeddings son cortas, de alta concurrencia y de gran volumen total, así que la lógica de selección no es la misma que la de una API de chat.

Este artículo compara tres rutas habituales —conexión directa con el proveedor, proxy propio y gateway de IA local— y ofrece un diseño de fiabilidad para tareas por lotes, los límites de la conmutación por error y una lista de verificación antes de producción. Los modelos, dimensiones y precios concretos se rigen por precios de modelos.

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 afiliación con esos proveedores. El tráfico transfronterizo, la salida de datos y la liquidación de pagos deben cumplir la legislación local y los términos de servicio de cada plataforma; consulta a tus responsables legales y de cumplimiento antes de implementar.

1. Las tres rutas, en claro

La conexión directa con el proveedor llama directamente a la interfaz del fabricante del modelo. El enlace es el más corto y la documentación y las funciones se sincronizan rápido; encaja en equipos que ya tienen red transfronteriza, canales de pago internacionales y un proceso de reembolso. El costo es que la calidad de la red, la factura en dólares, el tipo de cambio y las facturas corren por cuenta propia.

El proxy propio consiste en desplegar un proxy inverso o un gateway en un servidor conforme a la normativa, para centralizar autenticación, registros, reintentos y límites de velocidad. Da mucho control, pero el servidor, los certificados, las actualizaciones y las guardias son responsabilidad del equipo; si se monta solo para simplificar, el costo de operación suele superar lo previsto.

El gateway de IA local ofrece un punto de entrada compatible con OpenAI, liquidación en moneda local y, habitualmente, consola, estadísticas de uso y facturas. La integración es sencilla y facilita unificar varios modelos; hay que confirmar la entidad del servicio, las cláusulas de datos, las reglas de cuota y la respuesta ante incidentes.

Dimensión Conexión directa Proxy propio Gateway de IA local
Red y acceso Depende del enlace transfronterizo; hay que optimizarlo Ruta elegible, pero con operación propia Entrada local, normalmente lista para usar
Pago y factura Liquidación en dólares; circuito de reembolso más largo Depende de la cuenta y del servidor Liquidación en moneda local y factura
Rendimiento por lotes Limitado por la cuota de la cuenta Se pueden usar colas, pero el límite del proveedor persiste Depende de la cuota y la programación del gateway
Límite de datos Evaluar por cuenta propia la salida y las cláusulas La ubicación de los datos es responsabilidad propia Revisar las cláusulas y la habilitación del proveedor
Costo de operación Medio, sobre todo red y cuenta Alto: servidores, certificados, monitoreo Bajo, con gestión centralizada en consola
Cobertura de modelos Principalmente un fabricante Ampliable por cuenta propia Normalmente varios modelos

Ninguna ruta sirve para todos los equipos. Si usas un solo modelo y la red y el pago funcionan bien, la conexión directa es lo más simple; si necesitas una salida fija y auditoría, elige el proxy propio; si no tienes personal de operación y necesitas varios modelos con factura unificada, evalúa el gateway local.

2. Pruebas de red: los embeddings miran el rendimiento, no solo la latencia

La API de chat se preocupa por la latencia del primer token; la de embeddings, por el rendimiento por lotes y la estabilidad. Una solicitud puede incluir de decenas a cientos de textos y el cuerpo de la respuesta son cientos o miles de números en coma flotante; los problemas de enlace aparecen como tiempos de espera, truncamientos y errores 5xx.

No basta con enviar un «hola» en la prueba. Usa fragmentos de documentos con la longitud real y arma solicitudes con el tamaño de lote de producción; observa al menos cuatro métricas: tiempo por lote, latencia P50/P95, tasa de error y comportamiento en la hora pico. Confirma también los límites de tamaño del cuerpo de solicitud del proxy o gateway, la reutilización de conexiones y los tiempos de espera; cuando una capa intermedia trunca una solicitud grande, el mensaje de error no suele ser claro.

Las tareas largas deben poder reanudarse desde un punto de control. Numera la entrada con un hash de contenido, guarda en disco cada lote exitoso y, en caso de fallo, vuelve a ejecutar solo la parte faltante en lugar de reconstruir todo.

3. Pagos, contrato y facturas

El punto que suele atascar a los equipos locales es la entidad de pago. Si la recarga se hace con tarjeta personal, mediante un tercero o con comprobantes que no coinciden, finanzas a menudo no puede contabilizarla. Antes de elegir una ruta, aclara: con quién se firma el contrato, en qué moneda se liquida, qué tipo de factura se emite, si el prepago caduca y cuáles son las reglas de reembolso.

Con facturación por uso, confirma también el criterio de la factura: si se cobra por tokens de entrada o por número de solicitudes, si las solicitudes fallidas se contabilizan, si los reintentos se cobran dos veces y si el uso puede desglosarse por proyecto o por clave. Incluye estos puntos en la tabla comparativa de compra y prueba con el mismo conjunto de datos para calcular el costo real. Los importes concretos se rigen por precios de modelos y por el contrato.

4. Diseño de fiabilidad para tareas por lotes

La vectorización suele ser un procesamiento sin conexión, y el peor escenario es fallar al 80% sin poder reanudar. Se recomienda diseñarla en este orden:

  1. Genera un hash de contenido por cada texto y úsalo como clave de idempotencia; los envíos repetidos solo sobrescriben, no duplican.
  2. Estima los lotes por tokens, respetando a la vez tres límites: cantidad de elementos por solicitud, longitud de cada elemento y tokens totales.
  3. Aumenta la concurrencia de forma gradual y observa la proporción de errores 429; no la abras al máximo desde el inicio.
  4. Aplica retroceso exponencial con jitter aleatorio para 429 y 5xx, con un número máximo de reintentos.
  5. Al terminar cada lote, registra la cantidad de éxitos, el consumo de tokens y el tiempo; guarda aparte las muestras fallidas.
  6. Antes de escribir en la base, valida la dimensión, los vectores vacíos y los valores NaN; aísla los datos anómalos en lugar de escribirlos en silencio.
  7. Al finalizar la ejecución completa, compara una muestra y confirma que la cantidad, la dimensión y las estadísticas del índice coinciden.

El proceso no es complejo, pero evita el problema de «parecía haber terminado y en realidad faltaba un lote».

5. Límites de velocidad, reintentos y conmutación por error

Las interfaces de embeddings suelen aplicar límites por dos dimensiones: número de solicitudes y tokens. Al alcanzar el límite devuelven 429; cuando el gateway está sobrecargado pueden aparecer 5xx o tiempos de espera. La estrategia de reintentos debe distinguir el tipo de error: los 429 y los 5xx transitorios admiten retroceso y reintento; los 401, 403 y los errores de parámetros no se solucionan reintentando y primero hay que corregir la configuración.

import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url=os.environ["ZSQH_BASE_URL"],
    timeout=60.0,
    max_retries=0,
)

def embed_batch(texts, model, attempts=4):
    for i in range(attempts):
        try:
            resp = client.embeddings.create(model=model, input=texts)
            vectors = [item.embedding for item in resp.data]
            dims = {len(v) for v in vectors}
            if len(dims) != 1 or len(vectors) != len(texts):
                raise ValueError("Dimensión o cantidad inconsistente")
            return vectors, resp.usage
        except Exception as exc:
            if i == attempts - 1:
                raise
            wait = min(2 ** i, 30) + 0.5 * (i + 1)
            print(type(exc).__name__, "retry in", wait)
            time.sleep(wait)

vectors, usage = embed_batch(
    ["Primer fragmento de texto", "Segundo fragmento de texto"],
    os.environ["EMBEDDING_MODEL"],
)
print(len(vectors), len(vectors[0]), usage)

Hay un límite de la conmutación por error que se pasa por alto con facilidad: los vectores de modelos de embeddings distintos no pueden mezclarse. Aunque la dimensión coincida, el espacio vectorial no es el mismo; si se escriben vectores de dos modelos en el mismo índice, la recuperación empeora de forma evidente. Por eso, al cambiar de proveedor, confirma primero si se trata del mismo modelo y la misma versión; si de verdad hay que cambiar de modelo, crea un índice nuevo, recalcula todo y compara los resultados antes de hacer la transición, en lugar de cambiar el nombre del modelo de forma improvisada durante una falla.

6. Lista de verificación antes de producción

  • Dimensión: coincide con la configuración del índice y la cantidad de elementos devueltos coincide con la entrada.
  • Línea base: con un conjunto fijo de textos de prueba, compara la similitud del coseno con la de la conexión directa; normalmente debe ser muy cercana.
  • Uso: el campo usage de la respuesta coincide con la factura del panel; en solicitudes por lotes, verifica lote por lote.
  • Límites: el máximo de concurrencia, la proporción de 429 y la tasa de éxito tras los reintentos son aceptables.
  • Tiempos de espera: el lote más grande termina dentro del plazo en la hora pico.
  • Datos: si la entrada contiene datos personales y si las políticas de retención, registro y eliminación del proveedor están claras.
  • Salida: si la clave puede rotarse, si el saldo es reembolsable y si se conservan el índice anterior y la ruta de reversión.

Si algún punto no está claro, conviene probar primero con poco tráfico y no migrar directamente el índice de producción.

7. Elegir según las restricciones

Revisa primero si la red y el pago pueden mantenerse estables a largo plazo; después, si necesitas una salida fija y auditoría; por último, la cobertura de modelos y la capacidad de facturación. Si necesitas un punto de entrada unificado, liquidación en moneda local y comparación de varios modelos, puedes crear una clave de prueba en ZSQH AI Gateway, validar con un lote pequeño y aumentar el volumen de forma gradual; los modelos disponibles y la facturación aparecen en precios de modelos.

Preguntas frecuentes

¿En qué se diferencia el acceso a la API de embeddings del acceso a una API de chat?

La API de chat se centra en la latencia del primer token y la estabilidad del streaming; la de embeddings trabaja por lotes, con respuestas cortas y gran volumen total, y se centra en el rendimiento, el límite por solicitud y la reanudación tras fallos. Al elegir, incluye en el plan las pruebas de carga por lotes y la reanudación desde puntos de control.

¿Es estable la conexión directa a la API de embeddings desde China?

Depende de la salida local, la franja horaria y la cuota de la cuenta; no hay una respuesta general. Observa durante un período con lotes y concurrencia reales, registra la tasa de error y la latencia P95 y compara con la opción del gateway. No saques conclusiones a partir de una sola solicitud exitosa.

¿Qué hacer si se interrumpe la vectorización por lotes?

Usa el hash de contenido como clave de idempotencia, guarda cada lote en disco y completa solo lo que falta. Antes de reanudar, verifica la cantidad y la dimensión de lo ya escrito para evitar duplicados o tomar un lote incompleto como resultado final.

Si cambio de gateway, ¿sirven los vectores antiguos?

Si sigues usando el mismo modelo y la misma versión, normalmente sí; si cambias de modelo, debes reconstruir el índice. Antes de migrar, compara la similitud del coseno entre vectores nuevos y antiguos con una muestra fija, y conserva el índice anterior como ruta de reversión.

¿Se pueden desglosar facturas y uso por proyecto?

Depende del proveedor. Antes de contratar, confirma si el uso puede exportarse por proyecto, clave o modelo, si el criterio de facturación incluye solicitudes fallidas y reintentos, y si el contenido de la factura cumple los requisitos de compra.

Lecturas relacionadas: