Cómo crear una API de LLM para socios sin exponer claves de proveedor sin procesar

Un socio API para el acceso a LLM no debe ser un envoltorio delgado para las claves del proveedor. Si los socios, revendedores o aplicaciones de clientes necesitan acceso delegado a los modelos de lenguaje, la plataforma necesita su propio plano de control, puerta de enlace, capa de políticas, canal de medición y runbooks operativos. De lo contrario, la facturación a nivel de proveedor, los límites a nivel de proveedor y las credenciales compartidas se convierten en los únicos controles entre la integración de un socio y un incidente muy costoso.

El objetivo es sencillo: permitir que terceros consuman capacidades de LLM a través de su plataforma mientras usted mantiene privadas las credenciales de los proveedores, aplica derechos específicos de los socios, mide el uso facturable y brinda a los socios suficiente transparencia para crear clientes confiables.

Arquitectura de referencia

Un socio práctico API tiene dos partes principales: un plano de control y una puerta de enlace de solicitudes.

El plano de control gestiona organizaciones asociadas, aplicaciones, entornos, API claves delegadas, derechos de modelo, niveles de límite de tarifas, límites de gasto, condiciones de facturación, puntos finales de webhook y registros de auditoría. Es donde las reglas comerciales y operativas se convierten en políticas legibles por máquina.

La puerta de enlace de solicitudes recibe tráfico de socios, autentica la clave delegada, evalúa la política, aplica cuota, enruta al proveedor del modelo seleccionado, registra el uso y devuelve metadatos de respuesta visibles para los socios. En un LLM empresarial API maduro, esta puerta de enlace también es donde el enrutamiento del modelo, los reintentos, la conmutación por error, los controles de contenido y la observabilidad se aplican de manera consistente.

El límite importante es este: los socios reciben solo las claves emitidas por la plataforma. Nunca reciben credenciales de proveedor sin procesar. Las claves del proveedor ascendente permanecen en el almacén secreto de su plataforma y solo las utilizan la puerta de enlace o los trabajadores de backend.

Patrón de datos sobre el que construir

Los siguientes son hechos respaldados por la plataforma pública y la documentación de la nube, no suposiciones sobre ninguna implementación en particular:

• Algunos proveedores de LLM admiten claves de alcance de proyecto, cuentas de servicio, acceso al modelo a nivel de proyecto y límites de tarifas a nivel de proyecto.
• La guía en la nube para API SaaS multiinquilino normalmente separa la administración de políticas, la decisión de políticas y la aplicación de políticas para reducir el acceso accidental entre inquilinos.
• API las puertas de enlace y los planos de control SaaS pueden aplicar limitaciones y controles de cuota específicos del inquilino, incluidos niveles de tasa, ráfaga y cuota.
• La facturación de SaaS basada en el uso depende de recopilar la actividad del inquilino, agregarla y conciliarla con los registros de facturación.
• Las claves de idempotencia son un patrón documentado para reintentar de forma segura API solicitudes de cambio de estado sin crear efectos secundarios duplicados.
• Los encabezados de respuesta de límite de velocidad estandarizados pueden ayudar a los clientes a comprender los límites, la asignación restante, restablecer el tiempo y reintentar el comportamiento.

La recomendación es combinar estos patrones en una capa de acceso LLM orientada a los socios de su propiedad, en lugar de pedir a cada socio que se integre directamente con cada proveedor de modelo ascendente.

Paso 1: Definir el inquilino y el modelo de identidad

No identifique el tráfico de socios con una sola cadena de clave API. Un socio útil API necesita identificadores separados porque la facturación, la revisión de abusos, la depuración de cuotas y las investigaciones de soporte a menudo plantean preguntas diferentes.

Como mínimo, cree identificadores para:

• Organización asociada: la empresa externa contratada.
• Aplicación de socio: una integración, producto, complemento o aplicación de revendedor específica.
• Entorno: producción, puesta en escena, sandbox o desarrollo.
• Cliente final: el cliente, el espacio de trabajo, la cuenta o el inquilino del socio, cuando esté permitido contractualmente y esté técnicamente disponible.
• API clave: la credencial delegada utilizada para autenticar solicitudes.
• ID de solicitud: un identificador único para rastrear una solicitud a través de su puerta de enlace, llamadas de proveedores, eventos de uso y registros de soporte.

Esta estructura evita el modo de error común en el que una integración comprometida o ruidosa solo puede describirse como "tráfico del socio X". También le permite suspender una aplicación o entorno sin deshabilitar todo el negocio del socio.

Paso 2: Emitir claves de socios delegadas

Las claves de socio deben ser objetos de plataforma de primera clase, no tokens estáticos en una hoja de cálculo. Cada clave debe tener metadatos y enlaces de políticas:

• ID de organización asociada
• ID de aplicación
• Medio ambiente
• API superficies permitidas, como chat, incrustaciones, generación de imágenes o por lotes
• Alias de modelo permitidos
• Restricciones de región o residencia de datos cuando corresponda
• Nivel de límite de velocidad
• Regla de límite de gasto o saldo prepago
• Hora de creación, hora de último uso, propietario y estado de rotación

Cuando sea posible, almacene solo material de claves hash, exponga todos los secretos solo una vez en el momento de la creación y admita la rotación sin tiempo de inactividad. Un modelo de rotación práctico permite dos claves activas durante un breve período de transición, con registros de auditoría que muestran qué clave se utilizó para cada solicitud.

Paso 3: Separar los derechos de la ruta

El derecho de un socio a utilizar un modelo no debe estar implícito en el código de enrutamiento que admita actualmente. Mantenga las comprobaciones de derechos explícitas y separadas de la selección del proveedor.

Por ejemplo, una solicitud para model: premium-reasoning primero debe aprobar una decisión de política:

• ¿Este socio puede utilizar el alias del modelo?
• ¿La aplicación asociada puede utilizarla en este entorno?
• ¿La solicitud está dentro de la región permitida o del límite de datos?
• ¿El contrato está activo y al día?
• ¿El socio se encuentra dentro de los umbrales de gasto, cuota y abuso?

Solo después de esa decisión el enrutamiento debe elegir el proveedor ascendente, el proyecto del proveedor, la implementación o la ruta alternativa. Esto es importante porque los cambios de enrutamiento del modelo son operativamente frecuentes. Los cambios en los derechos deben ser deliberados y auditables.

Paso 4: Publicar un socio estable API Superficie

Los socios necesitan un comportamiento estable incluso cuando cambian sus proveedores ascendentes. Utilice sus propios alias de modelo y descripciones de capacidades en lugar de exponer cada nombre de modelo de proveedor directamente.

Un pequeño ejemplo:

POST /v1/chat/completions
Authorization: Bearer partner_key_...
Idempotency-Key: job_01J7...
X-Partner-Customer-Id: customer_123

{
  "model": "standard-chat",
  "messages": [
    {"role": "user", "content": "Summarize this support thread."}
  ],
  "metadata": {
    "ticket_id": "T-44821",
    "workflow": "support_summary"
  }
}

El socio solicita standard-chat. Su puerta de enlace asigna ese alias al proveedor y modelo aprobados actuales, sujeto a derechos, disponibilidad, precio, latencia, región y reglas de calidad.

Sin embargo, evite ocultar todas las diferencias entre proveedores. Si dos alias de modelo tienen diferentes ventanas de contexto, soporte de salida estructurada, comportamiento de llamada de herramientas, perfiles de latencia o disponibilidad regional, documente esas diferencias claramente. La abstracción debería simplificar la integración, no crear un comportamiento sorpresa.

Paso 5: hacer cumplir las cuotas antes de que el proveedor llame

Los límites de los proveedores son barreras de seguridad útiles, pero su aplicación a nivel de socio pertenece a su plataforma. Un proyecto de proveedor upstream puede servir a muchos socios, o un socio puede tener varias aplicaciones con diferentes contratos. Confiar únicamente en los límites de tarifas a nivel de proveedor no puede expresar esas distinciones claramente.

Aplicar comprobaciones de cuota antes de realizar llamadas ascendentes:

• Solicitudes por minuto por clave de socio
• Tokens por minuto por organización asociada
• Solicitudes simultáneas por aplicación
• Cuota de unidades facturables diaria o mensual
• Saldo prepago o umbral de crédito
• Límites por cliente final cuando sea necesario

Para solicitudes sincrónicas, rechace claramente cuando la solicitud no pueda aceptarse. Para cargas de trabajo asíncronas y por lotes, considere la admisión a la cola por separado de la cuota de ejecución. Se puede aceptar una carga por lotes, pero los trabajos individuales aún se deben medir y detener cuando se alcancen los límites de los socios.

Paso 6: Devolver señales de límite de velocidad predecibles

429 Too Many Requests respuestas opacas crean tickets de soporte evitables. Devuelve señales de cuota visibles para los socios en respuestas exitosas y limitadas.

Una respuesta útil puede incluir:

RateLimit-Limit: 600;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 17
Retry-After: 17
X-Request-Id: req_01J8...

Recomendaciones:

• Documente si se aplican límites por clave, aplicación, organización, modelo o punto final.
• Tiempo de restablecimiento de retorno en el que los clientes pueden actuar.
• Utilice Retry-After para respuestas limitadas.
• Mantenga los cuerpos de error estables y legibles por máquina.
• No exponga los elementos internos del proveedor a menos que los socios los necesiten para depurar el comportamiento.

Esto hace que sea más fácil crear clientes asociados y reduce las tormentas de reintentos durante los picos de tráfico.

Paso 7: Utilice la idempotencia para el trabajo facturable

Cualquier punto final que cree trabajo estatal o facturable debe admitir claves de idempotencia. Esto es especialmente importante para trabajos de generación asíncrona, envíos por lotes, compras de crédito, reintentos activados por webhooks y tareas de larga duración.

La regla de implementación es simple: cuando un socio repite la misma solicitud con la misma clave de idempotencia dentro de la ventana de retención, devuelve el resultado original en lugar de crear trabajo duplicado.

Haga explícitos los casos extremos:

• Durante cuánto tiempo se conservan los registros de idempotencia
• A qué punto final y clave de socio se aplica la clave de idempotencia
• ¿Qué sucede si se reutiliza la misma clave con diferentes parámetros de solicitud?
• Si las solicitudes fallidas se almacenan en caché
• Cómo se aplica la idempotencia a los trabajos por lotes parcialmente completados

Para trabajos de LLM facturables, almacene suficientes datos de huellas dactilares de solicitud para detectar discrepancias en los parámetros sin retener contenido de carga útil confidencial innecesario.

Paso 8: Emitir eventos de uso inmutables

No trate las facturas de los proveedores como la fuente veraz para la facturación de los socios. Las facturas de proveedores generalmente no conocen los contratos de sus socios, las reglas de margen, los niveles de revendedor, las identificaciones de los clientes finales ni el flujo de trabajo de disputas. En su lugar, emita un evento de uso inmutable cuando cada solicitud alcance un estado terminal.

Un evento de uso debe incluir:

• ID de organización asociada
• ID de aplicación y entorno
• API ID de clave, no la clave sin formato
• ID de cliente final, si se proporciona y se permite
• ID de solicitud e ID de correlación de proveedor
• Alias de modelo y modelo de proveedor ascendente
• Tokens de entrada, tokens de salida, tokens almacenados en caché u otras unidades facturables
• Base de costos del proveedor cuando esté disponible
• Unidad de facturación del socio, margen de beneficio, reducción de crédito o tasa de contrato
• Estado, clase de error, latencia y recuento de reintentos
• Marca de tiempo y versión del esquema

Estos eventos alimentan los paneles de control de los socios, las exportaciones de facturación, la detección de anomalías, los contadores de cuotas y la conciliación. Mantenga la transmisión de eventos solo para agregar. Las correcciones deben ser eventos de ajuste, no ediciones silenciosas.

Paso 9: conciliar diariamente

La medición solo es útil si concilia. Cree un proceso diario que compare sus eventos de uso con el uso de proveedores ascendentes, facturas de proveedores, saldos de crédito y registros de facturación de socios.

El proceso de conciliación debe identificar:

• Solicitudes aceptadas por su puerta de enlace pero faltan eventos de uso del terminal
• Uso del proveedor que no se puede asignar a una solicitud de socio
• Diferencias en el recuento de tokens entre los informes de proveedores y los registros de puerta de enlace
• Reintentos que se facturaron incorrectamente
• Créditos, reembolsos y correcciones de facturación manuales
• Socios que se acercan al gasto comprometido, agotamiento del prepago o crecimiento inusual

Aquí también es donde finanzas, soporte e ingeniería necesitan las mismas identificaciones. Si el panel, la partida de la factura, el evento de registro y el registro del proveedor no se pueden vincular, las disputas se convierten en investigaciones manuales.

Paso 10: crear runbooks operativos

Un socio API es una superficie de producto externa, por lo que el comportamiento operativo debe planificarse antes de que ocurran incidentes. Como mínimo, escriba runbooks para estas situaciones:

• Clave de socio comprometida: revoque o suspenda una clave, notifique al socio, conserve los registros de auditoría y proporcione una ruta de rotación.
• Uso fuera de control: aplica límites de emergencia, pausa una aplicación o requiere aprobación para su uso posterior.
• Interrupción del proveedor: conmuta por error a un proveedor aprobado o devuelve un error estable con instrucciones de reintento.
• Agotamiento de la cuota: muestra si el socio necesita esperar, actualizar, comprar créditos o reducir el tráfico.
• Repetición de webhook: verifica firmas, utiliza idempotencia y realiza un seguimiento de los intentos de entrega de eventos.
• Corrección de facturación: crea eventos de ajuste y conserva los registros de uso originales.

Los runbooks deben definir quién puede realizar cada acción. Suspender una clave es diferente a inhabilitar una organización asociada. Aumentar una cuota es diferente a cambiar un contrato. Los controles de emergencia necesitan pistas de auditoría.

Compensaciones

Una puerta de enlace del socio API añade latencia y responsabilidad operativa. Ese es el costo de controlar las credenciales, las cuotas, el enrutamiento, la facturación y la visibilidad a nivel de contrato de socio.

Las cuotas estrictas protegen los márgenes y reducen el abuso, pero pueden generar errores innecesarios si el comportamiento de ráfaga y la guía de reintentos no están bien diseñados. Un sistema de cuotas útil tiene límites estrictos y un comportamiento de ráfaga documentado.

La medición detallada mejora la transparencia de la facturación y los resultados de soporte, pero aumenta las obligaciones de retención, privacidad y conciliación. Recopile los identificadores necesarios para las operaciones y la facturación, pero evite almacenar contenido de avisos y respuestas sin procesar en los registros de facturación a menos que exista una base contractual y de cumplimiento clara.

La abstracción de modelos simplifica las integraciones de socios, pero una abstracción excesiva puede ocultar diferencias materiales. Los socios no necesitan conocer todos los detalles de la implementación del proveedor, pero sí necesitan saber cuándo un alias de modelo cambia los límites de contexto, los formatos de salida, las expectativas de latencia o la disponibilidad regional.

Lista de verificación de implementación

• Emitir claves de socio propiedad de la plataforma en lugar de compartir las credenciales del proveedor.
• Asignar cada clave a registros de socios, aplicaciones, entornos, derechos, cuotas y facturación.
• Mantenga las comprobaciones de autorización y derechos separadas de la lógica de enrutamiento.
• Utilice alias de modelos estables con capacidades y límites documentados.
• Aplicar comprobaciones de cuota antes de las llamadas del proveedor ascendente.
• Encabezados con límite de tasa de retorno y errores legibles por máquina.
• Requerir claves de idempotencia para los puntos finales que crean trabajo estatal o facturable.
• Emitir eventos de uso inmutables al finalizar la solicitud.
• Conciliar el uso con los registros de proveedores y las facturas de los socios.
• Mantener runbooks para detectar compromisos clave, uso descontrolado, interrupción del proveedor, agotamiento de cuotas, repetición de webhooks y corrección de facturación.

Conclusión procesable

El socio más seguro API para el acceso a LLM no es un proxy que reenvía solicitudes con credenciales ocultas. Es un sistema de acceso delegado con su propio modelo de identidad, capa de políticas, cumplimiento de cuotas, medidor de uso, proceso de conciliación y transparencia de cara a los socios.

Comience con los límites de control: claves de socios, derechos explícitos, comprobaciones de cuotas previas a la llamada, puntos finales de cambio de estado idempotentes y eventos de uso inmutables. Luego agregue madurez operativa: paneles de control, conciliación, semántica de límite de velocidad y runbooks de incidentes. Esta arquitectura permite a los socios aprovechar las capacidades de LLM sin recibir claves de proveedor sin procesar, al tiempo que brinda a la plataforma suficiente control para gestionar costos, abuso, confiabilidad y disputas de facturación.

Lecturas relacionadas

• diseño de claves API gobernadas para equipos e integraciones de socios