La clave de una API de Rerank parece igual que una clave de chat, pero el riesgo real es mayor: cada solicitud incluye la consulta del usuario y el texto completo de un lote de documentos candidatos, y se factura según el volumen de llamadas. Si la clave se filtra, otras personas pueden consumir tu saldo y hacer que en tu factura aparezcan numerosas solicitudes desconocidas.
Este artículo explica dos rutas para obtenerla: la plataforma del proveedor y un gateway de IA. También cubre la configuración de permisos y límites al crear la clave, la forma de declarar variables de entorno, el diagnóstico de errores 401 y el proceso de rotación. El alcance de modelos y los precios se rigen por los precios de modelos del sitio.
Nota: Cohere, Jina AI, Alibaba Cloud, SiliconFlow y Volcano Engine son nombres que pertenecen a sus respectivos titulares; aquí solo se usan para explicaciones técnicas. ZSQH AI Gateway no tiene relación de afiliación con esos proveedores. Las interfaces y los modelos se rigen por la información publicada en el sitio.
1. Diferencias entre una clave de Rerank y una clave de chat
Una clave de chat llama a modelos generativos: la entrada son mensajes y la salida es texto. Una clave de Rerank llama a modelos de reordenamiento: la entrada es una consulta más un conjunto de documentos candidatos, y la salida son puntuaciones de relevancia y un orden para cada documento.
Las diferencias se concentran en tres puntos:
- Datos más sensibles: los documentos candidatos suelen provenir de bases de conocimiento internas y pueden contener contratos, políticas o información de clientes.
- Facturación distinta: normalmente se cobra por los tokens de la consulta y de los documentos; los documentos largos y los lotes grandes multiplican el consumo.
- Permisos más acotados: muchas plataformas permiten limitar el alcance de modelos de una clave y habilitar solo los modelos de rerank, lo que reduce el riesgo de uso indebido.
Por eso, no conviene mezclar una clave de rerank con una clave de chat ni entregar la misma clave a varios proyectos a la vez. La granularidad adecuada es «entorno + proyecto».
2. Ruta A: obtener la clave en la plataforma del proveedor
Cohere, Jina AI, Alibaba Cloud Model Studio, SiliconFlow, Volcano Engine y otras plataformas ofrecen servicios de reordenamiento. Los accesos y los campos cambian, pero el proceso es similar:
- Elige la plataforma: confirma primero los idiomas admitidos, la longitud máxima de documento, si acepta chino y si los datos salen del país.
- Crea una cuenta: las plataformas locales suelen pedir teléfono o verificación empresarial; las internacionales, correo y un método de pago.
- Activa el servicio: localiza Rerank o el servicio de reordenamiento en la consola y confirma que el modelo objetivo esté habilitado.
- Crea la clave: entra en la página de API Keys, genera una nueva y nómbrala por «proyecto-entorno», por ejemplo
rag-prod. - Configura restricciones: establece un límite de gasto si es posible, una fecha de expiración y, si la plataforma lo permite, marca solo los modelos de rerank.
- Prueba de inmediato: copia la clave y ejecuta una solicitud mínima para confirmar que la autenticación, el nombre del modelo y la estructura de respuesta son correctos.
Los encabezados de autenticación no son idénticos en todas las plataformas. Cohere y Jina suelen usar Authorization: Bearer <key>, mientras que algunas plataformas locales emplean su propio esquema de firma. No escribas el encabezado de memoria: cópialo de la documentación vigente.
3. Ruta B: obtener la clave a través de ZSQH AI Gateway
Si el equipo no tiene un método de pago internacional o quiere unificar la factura de varios modelos, puede usar el gateway:
- Abre ZSQH AI Gateway y completa el registro.
- Entra en la página «API Keys» de la consola y crea una clave nueva.
- Asigna un nombre, elige el proyecto o grupo y define el límite de gasto y la fecha de expiración.
- Recarga en la billetera y confirma que el saldo alcance para la prueba.
- Copia la clave y guárdala en un gestor de contraseñas; no la dejes en un historial de chat.
El gateway expone la capacidad de reordenamiento como POST /v1/rerank y también acepta la ruta /rerank. La Base URL es https://ai.zhongshangqihang.com/v1. Ten en cuenta que Rerank no forma parte de la especificación Chat Completions de OpenAI: es un endpoint independiente y no se puede usar directamente con los métodos del SDK de chat.
| Dimensión | Plataforma del proveedor | ZSQH AI Gateway |
|---|---|---|
| Registro y pago | Las plataformas internacionales suelen pedir tarjeta en moneda extranjera; las locales, verificación de identidad | Registro y recarga locales; el método se rige por la página de liquidación |
| Red | Los endpoints internacionales pueden ser inestables | Conexión directa local, menos tiempo dedicado a diagnosticar la red |
| Alcance de modelos | Solo los modelos de ese proveedor | Entrada única para modelos de varios proveedores, según la lista de modelos |
| Facturación | Conciliación separada por proveedor | Factura combinada de varios modelos, más fácil de reembolsar |
| Ruta de datos | La solicitud llega directo al proveedor | Se reenvía a través del gateway; hay que revisar los términos de tratamiento de datos |
| Recomendado para | Equipos con un solo proveedor que necesitan soporte del fabricante | Equipos con varios modelos, operación local y administración centralizada |
Las dos rutas pueden coexistir. Una práctica habitual es mantener la cuenta del proveedor como respaldo en producción y usar el gateway para los equipos locales y los entornos de prueba. Antes de elegir, confirma la entidad del contrato, el tipo de factura y las condiciones de datos.
4. Cuatro ajustes de seguridad al crear la clave
Obtener la clave es solo el comienzo. La configuración del momento de creación determina el alcance del daño si algo sale mal después.
Primero, separa por entorno. Usa una clave para desarrollo, otra para pruebas y otra para producción, con el proyecto y la fecha en el nombre. Así puedes identificar el origen al revisar la factura y, si hay una filtración, solo necesitas desactivar una.
Segundo, define un límite de gasto. Asigna un límite diario o mensual a cada clave y, como mínimo, un umbral de alerta. El consumo de Rerank depende directamente de la cantidad y la longitud de los documentos; un script en bucle puede generar muchas solicitudes en poco tiempo.
Tercero, establece una fecha de expiración. Para las claves de prueba conviene una expiración corta; las de producción se rotan según la política del equipo. En claves temporales para externalizados o socios, la expiración automática es más confiable que la recuperación manual.
Cuarto, aplica el mínimo privilegio. Si la plataforma admite alcance de modelos, listas de IP o agrupación por proyecto, habilita solo los modelos de rerank y las direcciones de origen necesarias. No concedas acceso a todos los modelos por comodidad.
5. Variables de entorno y lectura desde el código
La clave solo debe existir en variables de entorno del servidor o en un servicio de gestión de secretos. No la escribas en el repositorio ni la incluyas en el frontend. La configuración mínima es:
RERANK_API_KEY=sk-tu-clave
RERANK_BASE_URL=https://ai.zhongshangqihang.com/v1
Agrega .env a .gitignore e inyecta las variables desde el panel del entorno de despliegue. Así se leen en Python:
import os
import requests
api_key = os.environ["RERANK_API_KEY"]
base_url = os.environ.get("RERANK_BASE_URL", "https://ai.zhongshangqihang.com/v1")
resp = requests.post(
f"{base_url}/rerank",
headers={"Authorization": f"Bearer {api_key}"},
json={
"model": "nombre-de-tu-modelo-de-rerank",
"query": "¿Cuánto dura el período de prueba?",
"documents": ["El período de prueba es de 14 días.", "Se acepta transferencia empresarial."],
"top_n": 2,
},
timeout=20,
)
resp.raise_for_status()
print(resp.json()["results"])
El nombre del modelo se rige por la página de precios de modelos. Si el equipo usa un gestor de secretos, guarda la clave cifrada e inyéctala en tiempo de ejecución; no la imprimas en los registros. Para diagnosticar problemas puedes registrar el ID de solicitud y el código de estado, pero nunca el encabezado Authorization completo.
6. Diagnóstico de 401: distingue autenticación de permisos
Un 401 indica que la identidad no fue reconocida; un 403 indica que la identidad sí se reconoció pero no tiene permiso. Muchos gateways unifican ambos casos en una misma estructura de error, así que revisa el cuerpo de la respuesta y el código de error, no solo el estado HTTP.
| Síntoma | Causa habitual | Acción |
|---|---|---|
| 401 Unauthorized | Clave mal escrita, con espacios al inicio o al final, o truncada al copiar | Vuelve a copiarla y confirma que no haya saltos de línea |
| 401 invalid token | Clave eliminada, expirada o de otro proyecto | Verifica su estado en la consola y crea una nueva |
| 401 con una clave correcta | Encabezado mal escrito o Base URL apuntando a otro servicio | Revisa Authorization y la ruta según la documentación |
| 403 Forbidden | La clave no tiene permiso para el modelo o la cuenta está bloqueada | Revisa el alcance de modelos y el estado de la cuenta |
| 404 Not Found | Nombre de modelo o ruta del endpoint incorrectos | Confirma /v1/rerank y la lista de modelos |
| 429 Too Many Requests | Concurrencia alta o límite de cuota alcanzado | Reintenta con retroceso exponencial y revisa cuota y velocidad |
Conviene fijar un orden de diagnóstico: primero la URL y los encabezados, luego el estado de la clave, después el nombre del modelo y al final el saldo y los límites de velocidad. Convertir estos cuatro pasos en una lista de verificación es más rápido que probar al azar cada vez.
7. Rotación y respuesta ante filtraciones
La rotación de claves no debe esperar a que ocurra un incidente. Se recomienda rotar de forma periódica y hacerlo de inmediato cuando alguien deja el equipo, se confirma una confirmación accidental en el repositorio o aparece una clave completa en los registros.
- Crea una clave nueva en la consola y pon la fecha de rotación en el nombre.
- Escribe primero la clave nueva en el entorno de pruebas y ejecuta una solicitud mínima.
- Actualiza las variables de producción y reinicia el servicio; observa la tasa de errores y el volumen de llamadas.
- Cuando la clave anterior ya no reciba tráfico, desactívala o elimínala.
- Revisa los registros de llamadas recientes para descartar orígenes desconocidos o picos anómalos.
- Anota la fecha de rotación y agenda la siguiente en el calendario del equipo.
Si sospechas que la clave se filtró, desactiva primero la clave anterior y luego revisa la factura y los registros; no borres los registros de inmediato. Conservar la evidencia ayuda a determinar el alcance del incidente. Al terminar la rotación, revisa el historial del repositorio, las variables de CI y los historiales de chat para confirmar que no queden otras copias.
8. Preguntas frecuentes
¿Una clave de API de Rerank puede llamar a modelos de chat?
Depende de si la plataforma lo permite. Aunque sea técnicamente posible, no es recomendable. Una clave de reordenamiento debería usarse solo en el endpoint de rerank, para evitar que una misma clave acumule la facturación de generación y de recuperación.
¿Se puede poner la clave en el frontend o en una miniaplicación?
No. El código del frontend y las solicitudes de red son visibles para los usuarios, así que la clave quedaría pública. Lo correcto es que el frontend llame a tu propio backend y que este guarde la clave y reenvíe la solicitud.
¿Cuál es la diferencia entre 401 y 403?
El 401 es un fallo de autenticación: normalmente la clave no es válida, expiró o el encabezado está mal. El 403 es falta de permisos: la clave puede ser válida, pero no tiene autorización para ese modelo o proyecto. Revisa primero los campos code y message del cuerpo del error.
¿Una sola clave puede compartirse entre varios proyectos?
Técnicamente suele ser posible; operativamente no es aconsejable. Una clave compartida impide separar la facturación y amplía el impacto de una filtración. Como mínimo, separa por entorno y por proyecto.
¿Cada cuánto conviene rotar la clave?
Según la política de seguridad del equipo. Una práctica común es rotar de forma periódica y hacerlo de inmediato ante cambios de personal, sospechas de filtración o confirmaciones accidentales en el repositorio. No hay un estándar único de frecuencia; lo importante es que el proceso sea ejecutable.
