Configuración de AI Gateway en los recursos de Foundry

En este artículo se muestra cómo habilitar AI Gateway para un recurso de Microsoft Foundry mediante el portal de Foundry. AI Gateway usa Azure API Management en segundo plano para proporcionar límites, cuotas y gobernanza de tokens para las implementaciones de modelos.

Requisitos previos

• Azure suscripción (crear una gratuita).

• Permisos para crear o reutilizar una instancia de Azure API Management (APIM):

  • Para crear una instancia de APIM: colaborador o propietario en el grupo de recursos de destino (o suscripción).
  • Para administrar una instancia de APIM existente: colaborador del servicio API Management (o propietario) en la instancia de APIM. Para obtener más información, vea Cómo usar el control de acceso basado en rol en Azure API Management.

• Acceso al portal de Foundry (consola de administración) para el recurso foundry de destino.

  • Por ejemplo: Propietario de la cuenta de Foundry o Propietario de Foundry en el recurso Foundry. Para obtener más información, consulte control de acceso basado en roles para Microsoft Foundry.

    Importante

    Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

• Decisión sobre si desea crear una instancia de APIM dedicada o reutilizar una existente.

Requisitos para usar una instancia de API Management existente

Al seleccionar Usar APIM existente, solo se muestran las instancias de API Management que cumplan todos los requisitos siguientes:

• La instancia de API Management debe estar en el mismo inquilino de Microsoft Entra y la misma suscripción que el recurso de Foundry.
• Tiene al menos el rol de Contribuyente del servicio de gestión de API (o de Propietario) en la instancia de gestión de API.
• La instancia de API Management está en una suscripción a la que puede acceder desde el portal de Foundry.
• La instancia de API Management debe crearse en uno de los niveles v2.

Si ninguna de las instancias de API Management aparece en la lista, compruebe que la instancia cumple los requisitos anteriores y que tiene los permisos necesarios.

Nota

Si el recurso foundry tiene deshabilitado el acceso a la red pública, asegúrese de que la instancia de API Management también sea accesible de forma privada para integrarse con el recurso de Foundry privado. En este caso, use una instancia de Standard v2 o Premium v2 con un punto de conexión privado o una instancia premium v2 que se inserte en una red virtual. Para obtener más información, consulte las opciones de red de Azure API Management.

Creación de una puerta de enlace de AI

Siga estos pasos en el portal de Foundry para habilitar AI Gateway para un recurso.

1. Inicie sesión en Microsoft Foundry. Asegúrese de que el interruptor New Foundry esté activado. Estos pasos hacen referencia a Foundry (new).

   

2. Seleccione Operar>Consola de Administración.

3. Abra la pestaña Pasarela de IA.

4. Seleccione Agregar puerta de enlace de IA.

   

5. Seleccione el recurso Foundry que desea conectar con la puerta de enlace.

6. Seleccione Crear nuevo o Usar APIM existente.

   • Crear nuevo: crea una instancia de SKU básica v2. Basic v2 está diseñado para desarrollo y pruebas con compatibilidad con SLA.
   • Usar existente: seleccione una instancia que cumpla los requisitos de gobernanza y redes de su organización.

   Sugerencia

   Para cargas de trabajo de producción o requisitos de rendimiento superiores, considere la posibilidad de usar una instancia de APIM existente con un nivel Estándar v2 o Premium v2. Para obtener más información, consulte Azure API Management planes de tarifa.

   Nota

   AI Gateway incluye un nivel gratuito para Azure API Management. Para más información sobre los costos y la elegibilidad de nivel gratuito, consulte Precios de API Management.

   

7. Asigne un nombre a la puerta de enlace y seleccione Agregar para crear o asociar la instancia de APIM.

8. Compruebe que la puerta de enlace de IA aparece en la lista con el estado Habilitado. Si el estado muestra Aprovisionamiento, espere unos minutos y actualice la página.

9. Los nuevos proyectos creados en el recurso Foundry tienen la puerta de enlace de IA habilitada de forma predeterminada. Los proyectos existentes deben habilitarse manualmente.

10. Para habilitar un proyecto existente, seleccione el nombre de la puerta de enlace de AI para ver los proyectos asociados.

11. En la lista de proyectos, busque el proyecto que desea habilitar. La columna Estado de la puerta de enlace muestra el estado actual.

12. Seleccione Agregar proyecto a puerta de enlace. La columna Estado de la puerta de enlace se actualiza a Habilitado.

    

Verifique que la puerta de enlace funcione

Confirme que el tráfico se enruta a través de AI Gateway:

1. En el portal de Azure, abra la instancia de API Management conectada al recurso Foundry.

2. Seleccione Métricas de supervisión>. En la lista desplegable Métrica , seleccione Solicitudes. Realice una llamada de prueba a una implementación de modelo en el proyecto habilitado y compruebe que el recuento de solicitudes aumenta.

3. Para comprobar los registros detallados, seleccione Registros de supervisión>y ejecute una consulta en la tabla GatewayLogs . Busque entradas con un código de respuesta 200 y un nombre de API que coincida con su AI Gateway.

4. Si ha configurado límites de token, compruebe que se aplican mediante la prueba de una solicitud que supere el límite. La instancia de API Management devuelve una 429 Too Many Requests respuesta cuando se supera el límite.

Arquitectura de puerta de enlace de AI

AI Gateway se sitúa entre los clientes y los componentes de Foundry, incluidos los modelos y las herramientas. Todas las solicitudes fluyen a través de la instancia de APIM una vez asociada. Los límites se aplican en el nivel de proyecto, por lo que cada proyecto puede tener su propia configuración de TPM y cuota.

AI Gateway habilita:

• Contención de tokens de múltiples equipos (evitar que un proyecto monopolice la capacidad).
• Control de costos limitando el uso agregado.
• Límites de cumplimiento para cargas de trabajo reguladas (aplicar límites de uso predecibles).
• Registro de agentes personalizados para la gobernanza.

Uso de AI Gateway con varios proyectos

Habilita AI Gateway en el nivel del recurso de Foundry, y todos los proyectos de ese recurso comparten la misma puerta de enlace y su instancia subyacente de API Management. No asignas una puerta de enlace distinta para cada proyecto. En su lugar, agregue proyectos individuales a la puerta de enlace y asigne a cada uno sus propios límites y cuotas de token:

• Los nuevos proyectos creados en el recurso tienen la puerta de enlace de IA habilitada de forma predeterminada.
• Los proyectos existentes se deben agregar manualmente. Seleccione el nombre de la puerta de enlace de AI, busque el proyecto y seleccione Agregar proyecto a puerta de enlace.
• Establezca los límites de tokens por proyecto para que cada proyecto tenga un límite máximo de capacidad independiente en la puerta de enlace compartida.

Si necesita que los proyectos se enruten a través de puertas de enlace completamente independientes (por ejemplo, instancias de API Management independientes para un aislamiento estricto o requisitos de red diferentes), coloque esos proyectos en recursos de Foundry independientes y habilite una instancia de AI Gateway en cada recurso. Una instancia de API Management solo se puede asociar a una instancia de AI Gateway.

Escenarios de gobernanza

Una vez que haya configurado AI Gateway para el recurso y el proyecto, puede hacer lo siguiente:

• Configure los límites de token para los modelos.
• Agregue agentes personalizados al plano de control.
• Administrar las herramientas de agente MCP y A2A.

Solución de problemas

Nota

La interfaz de usuario del portal de Foundry se actualiza con frecuencia. Las capturas de pantalla y la numeración de pasos de este artículo pueden diferir ligeramente de lo que ve. Si un paso no coincide, busque la opción equivalente en la interfaz de usuario actual.

Problema	Causa	Resolución
La puerta de enlace de IA no aparece después de la creación.	El aprovisionamiento todavía está en curso.	Espere unos minutos y actualice la página. Las instancias básicas v2 normalmente tardan en aprovisionarse de 5 a 10 minutos.
Project muestra Gateway status como Disabled.	Los proyectos existentes no están habilitados automáticamente para AI Gateway.	Seleccione AI Gateway, busque el proyecto y seleccione Agregar proyecto a puerta de enlace.
Las solicitudes omiten la puerta de enlace.	El proyecto no se ha habilitado antes de realizar solicitudes o la puerta de enlace no está totalmente aprovisionada.	Compruebe que el estado de la puerta de enlace muestra Habilitado para el recurso y el proyecto.
Error de permiso al crear la puerta de enlace.	Falta el rol RBAC necesario.	Compruebe que tiene Colaborador o Propietario en el grupo de recursos (para crear) o Colaborador del Servicio de API Management en una instancia ya existente.
La instancia de API Management existente no aparece en la lista al seleccionar Usar APIM existente.	La instancia de API Management no cumple los requisitos de idoneidad o el usuario no tiene permisos suficientes.	Compruebe que la instancia de API Management está en el mismo tenant, utiliza una SKU compatible, no está ya asociada con otra pasarela de IA y que tiene el rol de Colaborador del servicio API Management (o Propietario) en la instancia.
Los límites de token no se aplican a las solicitudes.	Los límites no están configurados o el proyecto no usa la puerta de enlace.	Compruebe que el proyecto está habilitado para AI Gateway y, a continuación, configure los límites de token en la consola de administración.
500 errores en llamadas a modelos tras la configuración de la pasarela.	Es posible que los puntos de conexión de APIM creados automáticamente no estén completamente aprovisionados o que el despliegue del modelo no se asigne correctamente a través de la puerta de enlace.	Espere varios minutos para que se complete el aprovisionamiento. Compruebe primero que se puede acceder a la implementación del modelo sin la pasarela. Compruebe losregistros> de APIM para obtener información detallada sobre los errores. Si el problema persiste, intente quitar y volver a agregar el proyecto a la puerta de enlace.
Los proyectos no aparecen en la pestaña Puerta de enlace de AI una vez que se han asociado.	La lista de proyectos puede tardar tiempo en actualizarse o el proyecto se creó antes de habilitar la puerta de enlace.	Actualice la página o desplácese hacia fuera y vuelva a la pestaña Puerta de enlace de AI. Si los proyectos aún no aparecen, compruebe que el estado de la puerta de enlace muestra Habilitado en el nivel de recurso. Para los proyectos existentes, debe agregarlos manualmente a la puerta de enlace seleccionando Agregar proyecto a puerta de enlace.

Para obtener una solución de problemas específica de las herramientas, consulte Gobernanza de herramientas con AI Gateway.

Desactivar o eliminar una puerta de enlace de IA

La deshabilitación y eliminación de una instancia de AI Gateway son diferentes operaciones:

• Deshabilitar detiene el enrutamiento del tráfico de un solo proyecto a través de la puerta de enlace. La puerta de enlace y su instancia de API Management siguen ejecutándose y permanecen disponibles para otros proyectos.
• Delete quita la puerta de enlace del recurso Foundry y, al eliminar también la instancia subyacente de API Management, quita completamente la puerta de enlace y detiene sus cargos.

Deshabilitación de AI Gateway para un proyecto

1. Seleccione Operate>Admin console, y a continuación abra la pestaña AI Gateway.
2. Seleccione el nombre de la puerta de enlace de AI para ver sus proyectos asociados.
3. Localice el proyecto y, a continuación, seleccione Quitar el proyecto de la puerta de enlace. La columna Estado de la puerta de enlace se actualiza a Deshabilitado.

Al deshabilitar un proyecto, la puerta de enlace se mantiene, por lo que otros proyectos siguen dirigiendo el tráfico a través de ella.

Eliminar una puerta de enlace de IA

Para eliminar completamente una instancia de AI Gateway, la quita del recurso Foundry y, a continuación, elimina la instancia subyacente de API Management. Deshabilitar un proyecto por sí mismo no elimina la puerta de enlace ni detiene los cargos asociados a API Management.

1. En la pestaña AI Gateway, desactive la puerta de enlace para todos los proyectos asociados a ella, tal como se describe en la sección anterior.
2. Seleccione ai Gateway y, a continuación, seleccione la opción para eliminarla del recurso Foundry.
3. En el portal Azure, abra el grupo de recursos que contiene la instancia de API Management.
4. Elimine la instancia de API Management que tiene el mismo nombre que ai Gateway, a menos que otra carga de trabajo la siga usando. La eliminación de la instancia detiene los cargos asociados y completa la eliminación.

Limpieza de recursos

Si creó una instancia dedicada de API Management para AI Gateway y ya no la necesita, elimine ai Gateway y la instancia de API Management. Antes de eliminar la instancia, confirme que ninguna otra carga de trabajo depende de ella.

Contenido relacionado

• Capacidades de AI Gateway en Azure API Management
• Información general sobre Azure API Management
• Limitar el uso de tokens en la API de modelos de lenguaje extensos
• Cómo usar el control de acceso basado en rol en Azure API Management
• control de acceso basado en roles para Microsoft Foundry