Importación de una API de Azure OpenAI

2025-05-20

SE APLICA A: todos los niveles de API Management

Puede importar los puntos de conexión del modelo de IA implementados en el servicio Azure OpenAI a la instancia de API Management como UNA API REST. Use directivas de puerta de enlace de IA y otras funcionalidades de API Management para simplificar la integración, mejorar la observabilidad y mejorar el control sobre los puntos de conexión del modelo.

En este artículo se muestran dos opciones para importar una API de Azure OpenAI en una instancia de Azure API Management como UNA API REST:

Importación de una API de Azure OpenAI directamente desde Azure OpenAI Service (opción recomendada)
Descargar y agregar la especificación OpenAPI para Azure OpenAI y agregarla a API Management como una API de OpenAPI.

Obtenga más información sobre cómo administrar las API de IA en API Management:

Funcionalidades de puerta de enlace de IA en Azure API Management

Requisitos previos

Una instancia existente de API Management. Créelo si aún no lo ha hecho.
Un recurso de Azure OpenAI con un modelo implementado. Para más información sobre la implementación de modelos en el servicio Azure OpenAI, consulte la guía de implementación de recursos.

Anote el identificador (nombre) de la implementación. Lo necesitará cuando pruebe la API importada en API Management.

Nota:

Las directivas de API Management, como azure-openai-token-limit y azure-openai-emit-token-metric, son compatibles con ciertos puntos de conexión de API que están expuestos a través de modelos específicos del servicio Azure OpenAI. Para más información, consulte Modelos de servicio De Azure OpenAI compatibles.
Permisos para conceder acceso al recurso de Azure OpenAI desde la instancia de API Management.

Opción 1. Importación de la API desde Azure OpenAI Service

Puede importar una API de Azure OpenAI directamente desde el servicio Azure OpenAI a API Management.

Nota:

Actualmente, esta característica no está disponible en áreas de trabajo.

Al importar la API, API Management configura automáticamente:

Operaciones para cada uno de los puntos de conexión de la API REST de Azure OpenAI
Una identidad asignada por el sistema con los permisos necesarios para acceder al recurso de Azure OpenAI.
Un recurso backend y una directiva set-backend-service que dirigen las solicitudes de API al punto de conexión del servicio Azure OpenAI.
Autenticación en el back-end de Azure OpenAI mediante la identidad administrada asignada por el sistema de la instancia.
(opcionalmente) Directivas que le ayudarán a supervisar y administrar la API de Azure OpenAI.

Para importar una API de Azure OpenAI a API Management:

Vaya a la instancia de API Management en Azure Portal.
En el menú de la izquierda, en API, seleccioneAPI >+ Agregar API.
En Crear desde recurso Azure, seleccione Azure OpenAI Service.
En la pestaña Aspectos básicos:
1. Seleccione el recurso de Azure OpenAI que desea importar.
2. Opcionalmente, seleccione una Versión de API de Azure OpenAI. Si no selecciona una, la versión más reciente de la API de REST lista para producción se usa de manera predeterminada. Anote la versión seleccionada. Necesitará este valor para probar la API.
3. Escriba un Nombre para mostrar y una Descripción opcional para la API.
4. En la Dirección URL base, anexe una ruta de acceso que la instancia de API Management usa para acceder a los puntos de conexión de la API de Azure OpenAI. Si habilita Garantizar la compatibilidad del SDK de OpenAI (recomendado), /openai se anexa automáticamente a la dirección URL base.
  
  Por ejemplo, si el punto de conexión de su puerta de enlace de API Management es https://contoso.azure-api.net, establezca una Dirección URL base similar a https://contoso.azure-api.net/my-openai-api/openai.
5. Opcionalmente, seleccione uno o varios productos para asociarlos a la API. Seleccione Siguiente.
En la pestaña Directivas , opcionalmente, habilite directivas para ayudar a supervisar y administrar la API. También puede establecer o editar directivas más adelante.

Si está seleccionado, escriba la configuración o acepte los valores predeterminados que definen las siguientes directivas (consulte los artículos vinculados para obtener los requisitos previos y los detalles de configuración):
Seleccione Revisar + crear.
Una vez validada la configuración, seleccione Crear.

Opción 2. Adición de una especificación de OpenAPI a API Management

Como alternativa, descargue manualmente la especificación de OpenAPI para la API de REST de Azure OpenAI y agréguela a API Management como una API de OpenAPI.

Descargar la especificación de OpenAPI

Descargue la especificación de OpenAPI para la API REST de Azure OpenAI, como la versión de disponibilidad general 2024-10-21.

En un editor de texto, abra el archivo de especificación que descargó.
En el elemento servers de la especificación, sustituya el nombre del punto de conexión de Azure OpenAI Service en los valores de marcador de posición del punto de conexión url y default en la especificación. Por ejemplo, si su punto de conexión de Azure OpenAI Service es contoso.openai.azure.com, actualice el elemento servers con los siguientes valores:
- url: https://contoso.openai.azure.com/openai
- punto de conexión predeterminado: contoso.openai.azure.com
```
[...]
"servers": [
    {
      "url": "https://contoso.openai.azure.com/openai",
      "variables": {
        "endpoint": {
          "default": "contoso.openai.azure.com"
        }
      }
    }
  ],
[...]
```
Anote el valor de la API version en la especificación. Necesitará este valor para probar la API. Ejemplo: 2024-10-21.

Agregar la especificación de OpenAPI a API Management

Vaya a la instancia de API Management en Azure Portal.
En el menú izquierdo, seleccione API>+Agregar API.
En Definir una nueva API, seleccione OpenAPI. Escriba un Nombre para mostrar y un Nombre para la API.
Escriba un sufijo de dirección URL de API que termine en /openai para acceder a los puntos de conexión de la Azure OpenAI API en su instancia de API Management. Ejemplo: my-openai-api/openai.
Seleccione Crear.

La API se importa y muestra las operaciones de la especificación OpenAPI.

Configuración de la autenticación en Azure OpenAI API

Para autenticarse en la API de Azure OpenAI, proporcione una clave de API o una identidad administrada. Si ha importado la API de Azure OpenAI directamente a la instancia de API Management, la autenticación mediante la identidad administrada de la instancia de API Management se configura automáticamente.

Si ha agregado la API de Azure OpenAI desde su especificación de OpenAPI, debe configurar la autenticación. Para obtener más información sobre la configuración de la autenticación a través de las directivas de API Management, consulte Autenticar y autorizar en la API de Azure OpenAI.

Prueba de la API de Azure OpenAI

Para asegurarse de que la API de Azure OpenAI funciona según lo previsto, pruébela en la consola de prueba de API Management. Debe proporcionar un identificador de implementación de modelo (nombre) configurado en el recurso de Azure OpenAI y la versión de la API para probar la API.

Seleccione la API que creó en los pasos anteriores.
Seleccione la pestaña Prueba.
Seleccione una operación que sea compatible con el modelo que ha implementado en el recurso de Azure OpenAI. En la página se muestran los campos de los parámetros y los encabezados.
En Parámetros de plantilla, escriba los siguientes valores:
- deployment-id: el identificador de una implementación en el servicio Azure OpenAI
- api-version: una versión válida de la API de Azure OpenAI, como la versión de API que seleccionó al importar la API.
Escriba otros parámetros y encabezados según sea necesario. En función de la operación, es posible que tenga que configurar o actualizar un cuerpo de la solicitud.

Nota:

En la consola de prueba, API Management rellena automáticamente un encabezado Ocp-Apim-Subscription-Key y configura la clave de suscripción de la suscripción de acceso completo integrada. Esta clave permite el acceso a todas las API de la instancia de API Management. Opcionalmente, se puede mostrar el encabezado Ocp-Apim-Subscription-Key si se selecciona el icono de ojo situado junto a la Solicitud HTTP.
Seleccione Enviar.

Cuando la prueba se realiza correctamente, el back-end responde con un código de respuesta HTTP correcto y algunos datos. Anexado a la respuesta es datos de uso de tokens para ayudarle a supervisar y administrar el consumo de tokens de API de Azure OpenAI.

Compartir a través de