La API de Rerank no está en la cadena de generación, pero determina directamente si los primeros resultados de búsqueda son correctos. Envía «una consulta + un lote de documentos candidatos» al modelo de reordenamiento y recibe un orden por relevancia. Como la llamada ocurre mientras el usuario espera, lo que realmente debe resolver un equipo en China no es «si se puede conectar», sino si la red es estable, si la factura puede reembolsarse, si la latencia es controlable y si hay una ruta de degradación cuando algo falla.
Este artículo compara tres caminos —conexión directa, intermediario y gateway unificado— y ofrece una lista de verificación antes de pasar a producción. Los modelos, las rutas de interfaz y los precios concretos se rigen por la documentación de cada proveedor y por los precios de modelos del sitio.
Nota: Cohere, Jina AI y otros nombres son marcas de sus respectivos titulares; este artículo no implica afiliación con esas empresas. No se fijan precios unitarios aquí; antes de comprar, consulta la cotización vigente y el contrato del proveedor.
1. Por qué la API de Rerank es un problema de integración aparte
Rerank se diferencia de las API de chat en tres puntos. Primero, es una solicitud breve y síncrona: una llamada puede tardar decenas o cientos de milisegundos, pero el usuario está esperando ese resultado. Segundo, no forma parte del estándar Chat Completions de OpenAI: los campos y las rutas los define cada proveedor, por ejemplo Cohere usa /v2/rerank y Jina usa /v1/rerank, así que no basta con cambiar la Base URL al migrar. Tercero, la unidad de facturación puede ser solicitudes, documentos, tokens o search units, y la estructura de la factura es más compleja que «tokens de entrada y salida».
Por eso, una solución de acceso desde China debe cumplir cuatro cosas a la vez: conectividad de red sostenible, pagos y facturas que pasen por el proceso corporativo, latencia dentro del presupuesto de búsqueda y un plan para límites de velocidad y fallos. Mirar solo si «devuelve resultados» no es suficiente.
2. Cómo elegir entre conexión directa, intermediario y gateway unificado
Los caminos habituales se agrupan en cuatro categorías. La conexión directa a un proveedor internacional conviene a equipos con red internacional y capacidad de pago en moneda extranjera; la conexión directa a un proveedor local simplifica red y factura, pero exige adaptar modelos y protocolos; el intermediario comercial empaqueta red y pago; el gateway unificado prioriza la consolidación de varios proveedores, la gestión de claves y una factura común.
| Camino | Red | Pago y factura | Control de latencia | Límites y conmutación | Recomendado para |
|---|---|---|---|---|---|
| Conexión directa a proveedor internacional | Depende de enlaces internacionales; varía en horas pico | Suele requerir tarjeta en moneda extranjera; el proceso de factura es más largo | Se puede elegir región, pero el RTT transfronterizo es alto | El equipo gestiona los 429 y los reintentos | Empresas con entidad y operación en el exterior |
| Conexión directa a proveedor local | Normalmente estable desde China | Liquidación en yuanes y factura sencilla | Región seleccionable y enlace corto | Sujeto a la cuota del proveedor | Servicios dirigidos principalmente al mercado local |
| Intermediario comercial | El proveedor optimiza la ruta | Recarga en yuanes; hay que confirmar la factura | Depende del enrutamiento del intermediario | El intermediario responde, pero hay que aclarar los límites | Equipos pequeños que quieren lanzar rápido |
| Gateway unificado | Varias rutas del lado del gateway | Factura unificada, compra más simple | Depende de la región de despliegue del gateway | Permite configurar varios proveedores y degradación | Varios modelos y proyectos en paralelo |
Al elegir, no compares solo el precio unitario. Incluye en la evaluación «quién diagnostica cuando hay una falla», «qué entidad emite la factura» y «si se puede obtener el tiempo y el detalle de cobro de cada llamada»; muchas veces importa más que el descuento. Si vas a probar una integración unificada, puedes revisar primero la página de registro para ver las interfaces y los modelos disponibles y luego decidir si la llevas a producción.
3. Red y latencia: calcula primero el presupuesto de búsqueda
El reordenamiento suele situarse «después de la recuperación y antes de la generación». Un presupuesto razonable sería: recuperación de 20–80 ms, reordenamiento con P95 por debajo de 300 ms y generación de 1–3 segundos. En escenarios de búsqueda con resultados mientras se escribe, puede ser necesario hacer el reordenamiento asíncrono o aplicarlo solo a la segunda página.
La latencia depende de tres variables: cantidad de documentos candidatos, longitud de cada documento y tokens totales de la consulta y los documentos. La documentación de Jina da como referencia unos 150 ms para 100 documentos de aproximadamente 256 tokens con una consulta de 64 tokens; pero un documento de 4096 tokens puede elevar el tiempo a varios segundos. La documentación de Cohere recomienda no superar los 1000 documentos por solicitud y trunca cada documento a 4096 tokens de forma predeterminada. Estas cifras cambian con el modelo y la carga, pero la regla es consistente: primero reduce candidatos, luego trunca y solo al final considera un modelo más rápido.
En ingeniería, prioriza cuatro acciones: fija un top_n pequeño para devolver solo lo necesario; fragmenta o trunca los documentos largos antes; llama desde la región más cercana al negocio; y reutiliza conexiones para evitar un nuevo handshake en cada solicitud. Mide P95 y P99, no solo el promedio.
4. Pago, factura y contrato
Los problemas habituales de la conexión directa internacional son el método de pago y el criterio de reembolso. La tarjeta en moneda extranjera, el tipo de cambio, la factura de una entidad extranjera y las reglas de reembolso del saldo prepago afectan el proceso financiero. Los proveedores locales y la mayoría de los gateways permiten liquidar en yuanes, pero también hay que confirmar el tipo de factura, el momento de emisión, si la recarga es facturable y si el reembolso vuelve por la misma vía.
Conviene confirmar por escrito cinco puntos antes del contrato o el pedido: cuál es la unidad de facturación, si las solicitudes fallidas se cobran, si hay consumo mínimo, cómo se notifican los ajustes de precio y cuál es la política de retención de datos y registros. En el caso del reordenamiento, la solicitud incluye fragmentos de documentos de negocio que pueden contener información de clientes o material interno; no des por hecho que las condiciones de tratamiento de datos son «iguales que en la interfaz de chat».
5. Límites de velocidad, tiempos de espera y conmutación
El reordenamiento suele limitarse simultáneamente por RPM y TPM. Como el costo crece con «documentos × longitud», un lote grande puede activar la cuota en un momento de alta demanda. El cliente debe definir tiempos de espera claros, por ejemplo entre 800 ms y 1.5 segundos; ante un fallo, reintenta como máximo una vez y agrega fluctuación aleatoria para evitar una tormenta de reintentos.
Más importante aún es la ruta de degradación. Si el reordenamiento falla, el sistema debe poder volver al orden original de la etapa de recuperación o cambiar a otro proveedor, en lugar de hacer fallar toda la búsqueda. Este es un ejemplo de llamada con tiempo de espera; ajusta los nombres de campo según la documentación del proveedor:
curl -sS --max-time 1.5 https://<tu-endpoint>/v1/rerank \
-H "Authorization: Bearer $RERANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<según la documentación del proveedor>",
"query": "¿Qué documentos se necesitan para registrar una empresa en Rusia?",
"documents": ["Fragmento uno", "Fragmento dos", "Fragmento tres"],
"top_n": 5,
"return_documents": false
}'
Ten en cuenta que las rutas y los campos no son uniformes entre proveedores; hay que revisar uno por uno return_documents, el rango de puntuaciones y si se admiten documentos estructurados. No supongas que basta con cambiar la Base URL de la interfaz de chat para llamar al reordenamiento.
6. Lista de verificación antes de lanzar
- Revisa el protocolo: confirma la ruta de solicitud, los campos obligatorios, el rango de puntuaciones y el número máximo de documentos.
- Compara fuera de línea con consultas reales y 50–100 candidatos, y registra los cambios en la calidad del orden.
- Haz una prueba de carga en la región objetivo y registra P50, P95, P99 y la tasa de errores.
- Provoca un 429 de forma deliberada y verifica que la estrategia de retroceso funcione.
- Simula tiempos de espera agotados y errores 5xx, y confirma que se pueda volver al orden original o a un proveedor de respaldo.
- Concilia con una carga de trabajo fija y compara el registro de llamadas con la factura real.
- Confirma la entidad del contrato, el tipo de factura, las reglas de reembolso y las condiciones de datos.
- Lanza con poco tráfico gradualmente y observa a la vez la tasa de clics en búsqueda y la latencia de la interfaz.
El objetivo de esta lista no es «probar una vez», sino dejar registros reproducibles. La calidad y la latencia del reordenamiento dependen mucho del corpus del negocio; las pruebas de referencia de otros solo sirven como orientación.
7. Preguntas frecuentes
¿Cuál es la diferencia entre la API de Rerank y la API de embeddings?
Embeddings convierte texto en vectores y se usa para recuperación amplia; Rerank puntúa directamente pares «consulta-documento» y se usa para el ordenamiento fino. Normalmente se encadenan y no son intercambiables.
¿Un modelo de Rerank local puede sustituir directamente a uno internacional?
Las interfaces y las distribuciones de puntuación pueden ser distintas. Tras el cambio, recalibra los umbrales y compara el orden con el mismo conjunto de consultas; no basta con comprobar que la interfaz devuelva 200.
¿La conexión directa a una API internacional requiere una línea dedicada?
No necesariamente. Primero mide la pérdida de paquetes, el P95 y la tasa de tiempos agotados en el horario objetivo. Si el negocio es sensible a la latencia, evalúa después una línea dedicada, un gateway regional o un intermediario; no empieces con la solución más pesada.
¿Cuánto ralentiza el reordenamiento a la búsqueda?
Depende de la cantidad de candidatos y de la longitud de los documentos. Si aplicas el método anterior y mantienes decenas de candidatos con truncamiento por documento, el incremento suele quedar en cientos de milisegundos; los documentos largos y los lotes grandes lo aumentan de forma notable.
¿Un gateway unificado siempre admite Rerank?
No necesariamente. Rerank no forma parte del estándar de chat de OpenAI; la compatibilidad depende de la lista de interfaces del gateway. Al elegir, confirma primero la compatibilidad de protocolo y luego habla de precio y cuota; puedes entrar por la página de registro y revisar las capacidades actuales.
