La clave de una API de embeddings no suele ser distinta de la de un modelo de chat: es una credencial de identidad, y lo que realmente determina qué puedes llamar son los permisos de la cuenta y el parámetro de modelo incluido en la solicitud. Sin embargo, las tareas de vectorización suelen ejecutarse en segundo plano y procesar lotes grandes de documentos. Si una clave se filtra o se configura mal, el costo y el tiempo de diagnóstico pueden ser considerables.

Este artículo explica, en orden: dónde registrarse, qué completar al crear una clave, cómo separar permisos, dónde guardar las variables de entorno, cómo investigar un error 401, cómo elegir entre una clave del proveedor y una de gateway, y cómo rotar claves y responder ante una filtración.

Nota: OpenAI y las demás marcas mencionadas son marcas de sus respectivos titulares. Este artículo solo tiene fines técnicos y no implica afiliación con esos proveedores; las interfaces, los permisos y los precios se rigen por la documentación de cada plataforma y por las páginas de este sitio.

1. Primero, ¿los embeddings necesitan una clave aparte?

La mayoría de las plataformas compatibles con OpenAI usan el mismo sistema de autenticación: una misma clave puede llamar tanto a /v1/chat/completions como a /v1/embeddings. La disponibilidad depende del saldo de la cuenta, de los permisos de modelo y de las políticas de la plataforma, no del tipo de clave.

Algunas plataformas facturan o autorizan el servicio de vectores por separado. Antes de crear una clave, confirma tres cosas en la consola:

  • Si el plan actual o el saldo cubre el modelo de embeddings.
  • Si la clave tiene una lista de modelos permitidos o restricciones por proyecto.
  • Si los embeddings y el chat comparten la misma cuota.

Si la consola no ofrece permisos detallados, aísla por uso con la regla «una clave por propósito», de modo que al menos puedas limitar el gasto y desactivar cada clave por separado.

2. Registro y acceso a la consola

Tomemos como ejemplo ZSQH AI Gateway:

  1. Abre https://ai.zhongshangqihang.com, regístrate con tu correo y completa la verificación.
  2. Inicia sesión, entra a la consola y busca la página «API Keys».
  3. Revisa el saldo en la página «Wallet» o «Recarga»; para las pruebas basta con una recarga pequeña.
  4. Abre «Registros de uso» y confirma que puedes ver el modelo, los tokens y el costo de cada llamada.

También puedes registrarte directamente desde el enlace de registro. Si solo quieres validar la interfaz sin recargar todavía, crea primero una clave de prueba con una cuota baja y ajústala cuando la integración funcione.

3. Qué completar al crear la clave

Al pulsar «Nueva clave» verás normalmente estos campos:

  1. Nombre: indica el propósito y el entorno, por ejemplo rag-prod-backend o embedding-batch-dev. Evita nombres como «prueba1».
  2. Límite de cuota: empieza con un valor bajo y auméntalo cuando conozcas el consumo real de los lotes.
  3. Fecha de caducidad: para scripts temporales, fija 7 o 30 días; las claves de producción también deben tener un ciclo de rotación definido.
  4. Alcance de modelo o proyecto: si la plataforma lo permite, marca solo los modelos de embeddings y los proyectos necesarios.
  5. Guardar y copiar: la clave completa suele mostrarse una sola vez; si no la guardas, tendrás que eliminarla y crearla de nuevo.

Por lo general, las claves empiezan por sk-, pero el prefijo no sirve para verificar su autenticidad. Al copiar, asegúrate de no incluir espacios ni saltos de línea al principio o al final; es una de las causas más frecuentes del error 401.

4. Cómo diseñar permisos y cuotas

Las tareas de vectorización se caracterizan por leer mucho, escribir poco, ejecutarse por lotes y reintentarse con facilidad. El objetivo del diseño de permisos no es defenderse de ataques externos, sino evitar que una sola clave afecte a todos los entornos.

Escenario Nombre de la clave Cuota Ubicación Rotación
Desarrollo local emb-dev-nombre Mínima .env local 30 días
Entorno de prueba emb-staging Baja Secretos de CI/CD 60 días
Lote de producción emb-prod-batch Según presupuesto Gestor de secretos 90 días
Consultas de producción emb-prod-query Según presupuesto Gestor de secretos 90 días

Algunos principios:

  • Separar desarrollo y producción: una filtración de la clave de prueba no afecta la factura de producción.
  • Separar lotes y consultas: los lotes se reintentan con facilidad; un límite independiente facilita localizar consumos anómalos.
  • Mínimo privilegio: si solo necesitas embeddings, no habilites modelos de chat; si puedes limitar el proyecto, no otorgues permisos a nivel de cuenta.
  • No incluir claves en el frontend: las claves en navegadores, apps y miniprogramas siempre pueden extraerse; las solicitudes de vectorización deben pasar por tu propio backend.
  • No compartir claves personales: si un colega se va o se pierde un dispositivo, una clave compartida no se puede desactivar de forma individual.

5. Guardar la clave en variables de entorno

No escribas la clave directamente en el código. En un proyecto de Python puedes leerla así:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Primer fragmento de texto", "Segundo fragmento de texto"],
)
print(len(resp.data[0].embedding))

Si usas un archivo .env en local, añádelo a .gitignore y versiona solo .env.example. En producción, prioriza los secretos de contenedor, el gestor de claves del proveedor de nube o un servicio como Vault; no escribas la clave en el Dockerfile, en las capas de la imagen, en el paquete del frontend ni en los registros de CI.

Ten en cuenta además que, después de cambiar una variable de entorno, debes reiniciar el proceso. Muchos casos de «401 en producción y todo bien en local» se deben a que el servicio sigue leyendo la variable antigua o a que la plataforma de despliegue no la inyectó en el entorno de ejecución.

6. Orden para diagnosticar un error 401

Cuando recibas 401 Unauthorized, revisa en este orden; normalmente bastan unos minutos para localizar el problema:

  1. Comprueba que la cabecera sea Authorization: Bearer sk-..., con un solo espacio entre Bearer y la clave.
  2. Vuelve a copiar la clave y confirma que no tiene espacios, saltos de línea, comillas ni caracteres invisibles.
  3. Confirma que la clave no fue eliminada, desactivada o caducada.
  4. Confirma que la clave pertenece a la plataforma correspondiente a la Base URL; no envíes una clave de la plataforma A a la plataforma B.
  5. Verifica que el proceso realmente leyó la variable de entorno y que no recibió una cadena vacía.
  6. Revisa si el proxy inverso, el gateway o el SDK reescribieron la cabecera Authorization.
  7. Si solo fallan algunas solicitudes, comprueba si alguien expuso la clave en el frontend y el sistema de control de riesgos la desactivó.

Un detalle adicional: 401 es un problema de identidad; 403 suele indicar permisos o restricciones regionales, y 429, límites de frecuencia o de cuota. No atribuyas todos los fallos a la clave.

7. Clave del proveedor o clave de gateway

Ambas rutas funcionan; la diferencia está sobre todo en la compra, la red y el mantenimiento:

  • Conexión directa con el proveedor: la cuenta, la facturación y los modelos los gestiona el fabricante. Es adecuada para equipos con capacidad de pago internacional y con recursos para resolver la red y el cumplimiento por su cuenta. La desventaja es que los modelos quedan repartidos entre varias plataformas y las claves y la conciliación también deben gestionarse por separado.
  • Acceso mediante gateway: una Base URL y una clave para varios modelos; el acceso local y la liquidación en moneda local simplifican la operación, y los registros y límites quedan centralizados. El costo es una capa adicional de dependencia: conviene confirmar la política de datos, la disponibilidad y la gestión de incidentes del proveedor.

No elijas solo por precio. Confirma al menos si los datos se conservan, si se admiten facturas, cómo se notifican las fallas, si hay avisos previos cuando un modelo se retira y si se pueden exportar los registros de uso. Los modelos y precios concretos se rigen por lo que muestre la página de precios de modelos; los precios cambian, así que no presupuestes con cifras de artículos antiguos.

8. Rotación y respuesta ante filtraciones

Conviene convertir la rotación en una acción periódica y no esperar a que ocurra un incidente:

  1. Crea en la plataforma original una clave nueva con los mismos permisos.
  2. Actualiza el valor en las variables de entorno o en el gestor de secretos.
  3. Reinicia o vuelve a desplegar el servicio y haz una llamada de embeddings para confirmar que funciona.
  4. Observa los registros de uso durante 24 a 48 horas para descartar consumos anómalos.
  5. Elimina la clave anterior y registra la fecha de rotación.

Si sospechas una filtración, invierte el orden: primero desactiva la clave anterior, luego revisa los registros de uso y el historial del repositorio, y solo después crea la clave nueva. Borrar la cadena del código no es suficiente; la clave puede haber quedado en registros de CI, capas de imágenes o cachés de terceros.

Preguntas frecuentes

¿Los embeddings siempre necesitan una clave aparte?

No necesariamente. La mayoría de las plataformas compatibles con OpenAI permiten que una misma clave llame a embeddings y a chat. Crear una clave separada depende de si necesitas cuotas independientes, auditoría separada o la posibilidad de desactivarla sin afectar otros usos.

¿Se puede ver la clave completa después de crearla?

Normalmente no. La clave completa se muestra una sola vez al crearla; después solo se conserva el prefijo o una versión enmascarada. Si no la guardaste, elimínala y crea otra; no intentes recuperarla de los registros.

¿Una clave puede llamar a varios modelos de embeddings?

Por lo general, sí. El modelo se especifica en el campo model de la solicitud. Los modelos disponibles y sus dimensiones se rigen por la documentación de la plataforma y por precios de modelos.

¿Por qué curl funciona en local pero en producción devuelve 401?

Revisa primero tres cosas: si las variables de entorno se inyectaron en producción, si el proxy inverso conserva la cabecera Authorization y si producción usa otra clave que fue eliminada o caducó. Después comprueba si la Base URL apunta a la plataforma equivocada.

¿Basta con borrar la clave después de una filtración?

No. Desactiva primero la clave, revisa los registros de uso para confirmar si hubo llamadas anómalas, inspecciona el repositorio, los registros de CI y el historial de imágenes, y por último rota todas las claves que puedan estar afectadas. Si la clave tenía saldo de recarga, evalúa también si debes ajustar la cuota.

Próximos pasos

Si aún no tienes cuenta, puedes empezar desde la página de registro, crear una clave con cuota baja y probar /v1/embeddings con un solo texto. Cuando funcione, consulta precios de modelos para elegir el modelo definitivo. Para el flujo de vectorización en sí, continúa con la guía de integración que aparece abajo.

Lecturas relacionadas: