Conceptos básicos
Cómo se relacionan los public models, deployments, adapters y virtual keys.
En esta página
AI Gateway conecta los nombres de modelo que utiliza tu aplicación con los proveedores que atienden las solicitudes. Estos son los tres conceptos iniciales:
| Concepto | Propósito | Ejemplo |
|---|---|---|
| Public Model | El nombre que envía tu aplicación en model. | general |
| Deployment | Una conexión configurada a un modelo upstream, con credenciales y límites. | general conectado a gpt-5.5 de OpenAI |
| Virtual Key | Una credencial de aplicación con acceso a modelos, rate limits y presupuesto. | Una key que solo puede utilizar general |
Public models y deployment pools
Los deployments con el mismo publicModel forman un deployment pool. No necesitas crear otra
entidad para agruparlos. Añade un deployment con publicModel: "general" para darle al router
otro candidato que pueda atender ese nombre.
Así puedes cambiar los modelos upstream o añadir proveedores sin modificar el cliente. El router selecciona un deployment elegible según la Routing, sus capacidades, sus límites y su estado. Las Fallbacks permiten probar otro public model cuando el pool original no puede atender la solicitud.
Comprueba las capacidades al combinar proveedores
Compartir un nombre público no hace que los proveedores sean intercambiables para cualquier solicitud. Cada deployment debe admitir la operación solicitada. La Política de parámetros determina cómo se gestionan los campos no admitidos.
Endpoints, adapters y transports
Un Public Endpoint define la API que utiliza el cliente, como /v1/chat/completions o
/v1/messages. Un Adapter traduce entre la representación interna de AI Gateway y el formato
del proveedor. Un Transport es el protocolo que ese adapter utiliza para comunicarse con el proveedor.
Por ejemplo, el cliente puede utilizar Chat Completions mientras el adapter de OpenAI envía la
solicitud upstream mediante Responses. El endpoint del cliente y el transport upstream son
decisiones independientes. El transport se infiere por operación; utiliza transportOverrides
solo cuando sea necesario.
Recorrido de una solicitud
Application + virtual key + public model
→ Public endpoint
→ Canonical request
→ Eligible deployment selected from the pool
→ Adapter and upstream transport
→ Provider
→ Canonical response
→ Response in the client's API formatCanonical es la representación que comparten los adapters y los hooks de las extensiones. Permite que el routing, el control de acceso y la lógica común funcionen sin depender del protocolo de cada proveedor.
Consulta Arquitectura para conocer el orden de ejecución, los reintentos, el caching y las cuotas. El Glosario define todo el vocabulario del código y los esquemas de la API.
Próximos pasos
- Inicio rápido: crea una configuración local funcional.
- Tu primer deployment: valida y conecta un proveedor a un gateway existente.
- Virtual keys: limita el acceso de cada aplicación.