Compartir a través de

Configuración de la autenticación sin clave con Microsoft Entra ID

  • Artículo

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Los modelos implementados en la inferencia de modelos de Azure AI Services admiten la autorización sin clave mediante Microsoft Entra ID. La autorización sin clave mejora la seguridad, simplifica la experiencia del usuario, reduce la complejidad operativa y proporciona una sólida compatibilidad de cumplimiento para el desarrollo moderno. Lo convierte en una opción segura para las organizaciones que adoptan soluciones de administración de identidades seguras y escalables.

En este artículo se explica cómo configurar Microsoft Entra ID para la inferencia en la inferencia de modelos de Azure AI.

Descripción de los roles en el contexto del recurso en Azure

Microsoft Entra ID usa la idea de Control de acceso basado en rol (RBAC) para la autorización. Los roles son fundamentales para administrar el acceso a los recursos en la nube. Un rol es básicamente una colección de permisos que definen qué acciones se pueden realizar en recursos específicos de Azure. Al asignar roles a usuarios, grupos, entidades de servicio o identidades administradas (conocidas colectivamente como entidades de seguridad), se controla su acceso dentro del entorno de Azure a recursos específicos.

Al asignar un rol, se especifica la entidad de seguridad, la definición de roles y el ámbito. Esta combinación se conoce como asignación de roles. La inferencia del modelo de Azure AI es una funcionalidad de los recursos de Azure AI Services y, por tanto, los roles asignados a ese recurso concreto controlan el acceso para la inferencia.

Puede identificar dos tipos diferentes de acceso a los recursos:

  • Acceso de administración: las acciones relacionadas con la administración del recurso. Normalmente cambian el estado del recurso y su configuración. En Azure, esas operaciones son operaciones del plano de control y se pueden ejecutar mediante Azure Portal, la CLI de Azure o con la infraestructura como código. Algunos ejemplos de incluyen la creación de implementaciones de modelos, el cambio de las configuraciones de filtrado de contenido, el cambio de la versión del modelo servido o el cambio de SKU de una implementación.

  • Acceso para desarrolladores: las acciones relacionadas con el consumo de los recursos. Por ejemplo, invocar la API de finalizaciones de chat. Sin embargo, el usuario no puede cambiar el estado del recurso y su configuración.

En Azure, las operaciones de administración siempre se realizan mediante Microsoft Entra ID. Los roles como colaborador de Cognitive Services le permiten realizar esas operaciones. Por otro lado, las operaciones de desarrollador se pueden realizar mediante claves de acceso y/o Microsoft Entra ID. Los roles como el usuario de Cognitive Services le permiten realizar esas operaciones.

Importante

Tener acceso de administración a un recurso no concede necesariamente acceso para desarrolladores. El acceso explícito mediante la concesión de roles sigue siendo necesario. Es análogo a cómo funcionan los servidores de bases de datos. Tener acceso de administrador al servidor de bases de datos no significa que pueda leer los datos dentro de una base de datos.

Siga estos pasos para configurar el acceso de desarrollador a la inferencia del modelo de Azure AI en el recurso de Servicios de Azure AI.

Requisitos previos

Para completar este artículo, necesitará lo siguiente:

  • Suscripción a Azure. Si usa Modelos de GitHub, puede actualizar la experiencia y crear una suscripción de Azure en el proceso. Lea Actualización de modelos de GitHub a la inferencia del modelo de Azure AI si es su caso.

  • Recurso de Servicios de Azure AI. Para más información, vea Creación de un recurso de Servicios de Azure AI.

  • Una cuenta con permisos Microsoft.Authorization/roleAssignments/write y Microsoft.Authorization/roleAssignments/delete, como el control de acceso basado en roles de administrador.

  • Para asignar un rol, debe especificar tres elementos:

    • Entidad de seguridad: por ejemplo, su cuenta de usuario.
    • Definición de roles: el rol de usuario de Cognitive Services.
    • Ámbito: el recurso de Servicios de Azure AI.

Configuración de Microsoft Entra ID para la inferencia

Siga estos pasos para configurar Microsoft Entra ID para la inferencia:

  1. Vaya a Azure Portal y busque el recurso de Servicios de Azure AI que usa. Si usa Fundición de IA de Azure con proyectos o centros de conectividad, puede ir a él mediante:

    1. Visite el portal de Azure AI Foundry.

    2. En la página de aterrizaje, seleccione Abrir centro de administración.

    3. Vaya a la sección Recursos conectados y seleccione la conexión al recurso de Servicios de Azure AI que desea configurar. Si no aparece, seleccione Ver todo para ver la lista completa.

    4. En la sección Detalles de conexión, en Recurso, seleccione el nombre del recurso de Azure. Se abre una página nueva.

    5. Ahora está en Azure Portal, donde puede administrar todos los aspectos del propio recurso.

  2. En el panel de navegación izquierdo, seleccione Control de acceso (IAM).

    Sugerencia

    Use la opción Ver mi acceso para comprobar qué roles ya están asignados.

  3. Seleccione Asignaciones de roles y, a continuación, seleccione Agregar>Agregar asignación de roles.

  4. En Roles de función de trabajo, escriba Usuario de Cognitive Services. La lista de roles se filtra.

  5. Seleccione el rol y seleccione Guardar.

  6. En Miembros, seleccione el usuario o grupo al que desea conceder acceso. Se recomienda usar grupos de seguridad siempre que sea posible, ya que son más fáciles de administrar y mantener.

  7. Seleccione Siguiente y finalice el asistente.

  8. El usuario seleccionado ahora puede usar Microsoft Entra ID para la inferencia.

    Sugerencia

    Tenga en cuenta que las asignaciones de roles de Azure pueden tardar hasta cinco minutos en propagarse. Al trabajar con grupos de seguridad, agregar o quitar usuarios del grupo de seguridad se propaga inmediatamente.

Tenga en cuenta que el acceso basado en claves sigue siendo posible para los usuarios que ya tienen claves disponibles para ellos. Si quiere revocar las claves, en Azure Portal, en el panel de navegación izquierdo, seleccione Administración de recursos>Claves y puntos de conexión>Regenerar clave1 y Regenerar clave2.

Uso de Microsoft Entra ID en el código

Una vez configurado Microsoft Entra ID en el recurso, debe actualizar el código para usarlo al consumir el punto de conexión de inferencia. En el ejemplo siguiente se muestra cómo usar un modelo de finalizaciones de chat:

Instale el paquete azure-ai-inference mediante el administrador de paquetes, como pip:

pip install azure-ai-inference>=1.0.0b5

Advertencia

El recurso de Servicios de Azure AI necesita la versión azure-ai-inference>=1.0.0b5 para Python.

A continuación, puede usar el paquete para consumir el modelo. En el ejemplo siguiente se muestra cómo crear un cliente para consumir finalizaciones de chat con Entra ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
    model="mistral-large-2407",
)

Opciones de credenciales al usar Microsoft Entra ID

DefaultAzureCredential es una secuencia ordenada de mecanismos para autenticarse en Microsoft Entra ID. Cada mecanismo de autenticación es una clase derivada de la clase TokenCredential y se conoce como credencial. En tiempo de ejecución, DefaultAzureCredential intenta autenticarse con la primera credencial. Si esa credencial no puede adquirir un token de acceso, se intenta utilizar la siguiente credencial de la secuencia, y así sucesivamente hasta que se obtenga correctamente un token de acceso. De esta manera, la aplicación puede usar diferentes credenciales en distintos entornos sin implementar código específico del entorno.

Cuando el código anterior se ejecuta en la estación de trabajo de desarrollo local, busca en las variables de entorno una entidad de servicio de aplicación o en las herramientas de desarrollo instaladas localmente, como Visual Studio, un conjunto de credenciales de desarrollador. Se puede usar cualquier enfoque para autenticar la aplicación en los recursos de Azure durante el desarrollo local.

Cuando se implementa en Azure, este mismo código también puede autenticar su aplicación en otros recursos de Azure. DefaultAzureCredential puede recuperar la configuración del entorno y las configuraciones de identidad administrada para autenticarse en otros servicios automáticamente.

procedimientos recomendados

  • Usar credenciales deterministas en entornos de producción: considere la posibilidad de pasar de DefaultAzureCredential a una de las siguientes soluciones deterministas en entornos de producción:

    • Una implementación de TokenCredential específica, como ManagedIdentityCredential. Consulte la lista de Derived para ver las opciones.
    • Una implementación de ChainedTokenCredential reducida optimizada para el entorno Azure en el que se ejecuta la aplicación. ChainedTokenCredential básicamente crea una lista de permitidos específica de opciones de credenciales aceptables, como ManagedIdentity para producción y VisualStudioCredential para desarrollo.

  • Configure identidades administradas asignadas por el sistema o asignadas por el usuario en los recursos de Azure donde el código se ejecuta si es posible. Configure el acceso de Microsoft Entra ID a esas identidades específicas.

Uso de Microsoft Entra ID en el proyecto

Incluso cuando el recurso tiene configurado Microsoft Entra ID, es posible que los proyectos sigan usando claves para consumir predicciones del recurso. Al usar el área de juegos de Fundición de IA de Azure, se usan las credenciales asociadas a la conexión que tiene el proyecto.

Para cambiar este comportamiento, debe actualizar las conexiones de los proyectos para usar Microsoft Entra ID. Siga estos pasos:

  1. Visite el portal de Azure AI Foundry.

  2. Vaya a los proyectos o centros que usan el recurso Servicios de Azure AI a través de una conexión.

  3. Seleccione Centro de administración.

  4. Vaya a la sección Recursos conectados y seleccione la conexión al recurso de Servicios de Azure AI que desea configurar. Si no aparece, seleccione Ver todo para ver la lista completa.

  5. En la sección Detalles de conexión, junto a Detalles de acceso, seleccione el icono de edición.

  6. En Autenticación, cambie el valor a Microsoft Entra ID.

  7. Selecciona Actualización.

  8. La conexión está configurada para que funcione con Microsoft Entra ID ahora.

Deshabilitación de la autenticación basada en claves en el recurso

Deshabilitar la autenticación basada en claves es aconsejable cuando implementó Microsoft Entra ID y solucionó completamente los problemas de compatibilidad o reserva en todas las aplicaciones que consumen el servicio.

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Los modelos implementados en la inferencia de modelos de Azure AI Services admiten la autorización sin clave mediante Microsoft Entra ID. La autorización sin clave mejora la seguridad, simplifica la experiencia del usuario, reduce la complejidad operativa y proporciona una sólida compatibilidad de cumplimiento para el desarrollo moderno. Lo convierte en una opción segura para las organizaciones que adoptan soluciones de administración de identidades seguras y escalables.

En este artículo se explica cómo configurar Microsoft Entra ID para la inferencia en la inferencia de modelos de Azure AI.

Descripción de los roles en el contexto del recurso en Azure

Microsoft Entra ID usa la idea de Control de acceso basado en rol (RBAC) para la autorización. Los roles son fundamentales para administrar el acceso a los recursos en la nube. Un rol es básicamente una colección de permisos que definen qué acciones se pueden realizar en recursos específicos de Azure. Al asignar roles a usuarios, grupos, entidades de servicio o identidades administradas (conocidas colectivamente como entidades de seguridad), se controla su acceso dentro del entorno de Azure a recursos específicos.

Al asignar un rol, se especifica la entidad de seguridad, la definición de roles y el ámbito. Esta combinación se conoce como asignación de roles. La inferencia del modelo de Azure AI es una funcionalidad de los recursos de Servicios de Azure AI y, por tanto, los roles asignados a ese recurso concreto controlan el acceso para la inferencia.

Puede identificar dos tipos diferentes de acceso a los recursos:

  • Acceso de administración: las acciones relacionadas con la administración del recurso. Normalmente cambian el estado del recurso y su configuración. En Azure, esas operaciones son operaciones del plano de control y se pueden ejecutar mediante Azure Portal, la CLI de Azure o con la infraestructura como código. Algunos ejemplos de incluyen la creación de implementaciones de modelos, el cambio de las configuraciones de filtrado de contenido, el cambio de la versión del modelo servido o el cambio de SKU de una implementación.

  • Acceso para desarrolladores: las acciones relacionadas con el consumo de los recursos. Por ejemplo, invocar la API de finalizaciones de chat. Sin embargo, el usuario no puede cambiar el estado del recurso y su configuración.

En Azure, las operaciones de administración siempre se realizan mediante Microsoft Entra ID. Los roles como colaborador de Cognitive Services le permiten realizar esas operaciones. Por otro lado, las operaciones de desarrollador se pueden realizar mediante claves de acceso y/o Microsoft Entra ID. Los roles como el usuario de Cognitive Services le permiten realizar esas operaciones.

Importante

Tener acceso de administración a un recurso no concede necesariamente acceso para desarrolladores. El acceso explícito mediante la concesión de roles sigue siendo necesario. Es análogo a cómo funcionan los servidores de bases de datos. Tener acceso de administrador al servidor de bases de datos no significa que pueda leer los datos dentro de una base de datos.

Siga estos pasos para configurar el acceso de desarrollador a la inferencia del modelo de Azure AI en el recurso de Servicios de Azure AI.

Requisitos previos

Para completar este artículo, necesitará lo siguiente:

  • Suscripción a Azure. Si usa Modelos de GitHub, puede actualizar la experiencia y crear una suscripción de Azure en el proceso. Lea Actualización de modelos de GitHub a la inferencia del modelo de Azure AI si es su caso.

  • Recurso de Servicios de Azure AI. Para más información, vea Creación de un recurso de Servicios de Azure AI.

  • Una cuenta con permisos Microsoft.Authorization/roleAssignments/write y Microsoft.Authorization/roleAssignments/delete, como el control de acceso basado en roles de administrador.

  • Para asignar un rol, debe especificar tres elementos:

    • Entidad de seguridad: por ejemplo, su cuenta de usuario.
    • Definición de roles: el rol de usuario de Cognitive Services.
    • Ámbito: el recurso de Servicios de Azure AI.

  • Instale la CLI de Azure.

  • Identifique la siguiente información:

    • Su identificador de suscripción de Azure.

    • Nombre del recurso de Servicios de Azure AI.

    • El grupo de recursos donde se implementa el recurso de Servicios de Azure AI.

Configuración de Microsoft Entra ID para la inferencia

Siga estos pasos para configurar el identificador de Entra de Microsoft para la inferencia en el recurso de Servicios de Azure AI:

  1. Inicie sesión en su suscripción de Azure:

    az login

  2. Si tiene más de una suscripción, seleccione la suscripción donde se encuentra el recurso:

    az account set --subscription "<subscription-id>"

  3. Establezca las siguientes variables de entorno con el nombre del recurso de Servicios de Azure AI que planea usar y el grupo de recursos.

    ACCOUNT_NAME="<ai-services-resource-name>"
RESOURCE_GROUP="<resource-group>"

  4. Obtenga el nombre completo del recurso:

    RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")

  5. Obtenga el identificador de objeto de la entidad de seguridad a la que desea asignar permisos. En el ejemplo siguiente se muestra cómo obtener el identificador de objeto asociado a:

    Su propia cuenta de inicio de sesión:

    OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)

    Un grupo de seguridad:

    OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)

    Una entidad de servicio:

    OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)

  6. Asigne el rol usuario de Cognitive Services a la entidad de servicio (con ámbito al recurso). Mediante la asignación de un rol, concede acceso a la entidad de servicio a este recurso.

    az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID

  7. El usuario seleccionado ahora puede usar Microsoft Entra ID para la inferencia.

    Sugerencia

    Tenga en cuenta que las asignaciones de roles de Azure pueden tardar hasta cinco minutos en propagarse. Agregar o quitar usuarios de un grupo de seguridad se propaga inmediatamente.

Uso de Microsoft Entra ID en el código

Una vez configurado Microsoft Entra ID en el recurso, debe actualizar el código para usarlo al consumir el punto de conexión de inferencia. En el ejemplo siguiente se muestra cómo usar un modelo de finalizaciones de chat:

Instale el paquete azure-ai-inference mediante el administrador de paquetes, como pip:

pip install azure-ai-inference>=1.0.0b5

Advertencia

El recurso de Servicios de Azure AI necesita la versión azure-ai-inference>=1.0.0b5 para Python.

A continuación, puede usar el paquete para consumir el modelo. En el ejemplo siguiente se muestra cómo crear un cliente para consumir finalizaciones de chat con Entra ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
    model="mistral-large-2407",
)

Opciones de credenciales al usar Microsoft Entra ID

DefaultAzureCredential es una secuencia ordenada de mecanismos para autenticarse en Microsoft Entra ID. Cada mecanismo de autenticación es una clase derivada de la clase TokenCredential y se conoce como credencial. En tiempo de ejecución, DefaultAzureCredential intenta autenticarse con la primera credencial. Si esa credencial no puede adquirir un token de acceso, se intenta utilizar la siguiente credencial de la secuencia, y así sucesivamente hasta que se obtenga correctamente un token de acceso. De esta manera, la aplicación puede usar diferentes credenciales en distintos entornos sin implementar código específico del entorno.

Cuando el código anterior se ejecuta en la estación de trabajo de desarrollo local, busca en las variables de entorno una entidad de servicio de aplicación o en las herramientas de desarrollo instaladas localmente, como Visual Studio, un conjunto de credenciales de desarrollador. Se puede usar cualquier enfoque para autenticar la aplicación en los recursos de Azure durante el desarrollo local.

Cuando se implementa en Azure, este mismo código también puede autenticar su aplicación en otros recursos de Azure. DefaultAzureCredential puede recuperar la configuración del entorno y las configuraciones de identidad administrada para autenticarse en otros servicios automáticamente.

procedimientos recomendados

  • Usar credenciales deterministas en entornos de producción: considere la posibilidad de pasar de DefaultAzureCredential a una de las siguientes soluciones deterministas en entornos de producción:

    • Una implementación de TokenCredential específica, como ManagedIdentityCredential. Consulte la lista de Derived para ver las opciones.
    • Una implementación de ChainedTokenCredential reducida optimizada para el entorno Azure en el que se ejecuta la aplicación. ChainedTokenCredential básicamente crea una lista de permitidos específica de opciones de credenciales aceptables, como ManagedIdentity para producción y VisualStudioCredential para desarrollo.

  • Configure identidades administradas asignadas por el sistema o asignadas por el usuario en los recursos de Azure donde el código se ejecuta si es posible. Configure el acceso de Microsoft Entra ID a esas identidades específicas.

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Los modelos implementados en la inferencia de modelos de Servicios de Azure AI admiten la autorización sin clave mediante Microsoft Entra ID. La autorización sin clave mejora la seguridad, simplifica la experiencia del usuario, reduce la complejidad operativa y proporciona una sólida compatibilidad de cumplimiento para el desarrollo moderno. Lo convierte en una opción segura para las organizaciones que adoptan soluciones de administración de identidades seguras y escalables.

En este artículo se explica cómo configurar Microsoft Entra ID para la inferencia en la inferencia de modelos de Azure AI.

Descripción de los roles en el contexto del recurso en Azure

Microsoft Entra ID usa la idea de Control de acceso basado en rol (RBAC) para la autorización. Los roles son fundamentales para administrar el acceso a los recursos en la nube. Un rol es básicamente una colección de permisos que definen qué acciones se pueden realizar en recursos específicos de Azure. Al asignar roles a usuarios, grupos, entidades de servicio o identidades administradas (conocidas colectivamente como entidades de seguridad), se controla su acceso dentro del entorno de Azure a recursos específicos.

Al asignar un rol, se especifica la entidad de seguridad, la definición de roles y el ámbito. Esta combinación se conoce como asignación de roles. La inferencia del modelo de Azure AI es una funcionalidad de los recursos de Servicios de Azure AI y, por tanto, los roles asignados a ese recurso concreto controlan el acceso para la inferencia.

Puede identificar dos tipos diferentes de acceso a los recursos:

  • Acceso de administración: las acciones relacionadas con la administración del recurso. Normalmente cambian el estado del recurso y su configuración. En Azure, esas operaciones son operaciones del plano de control y se pueden ejecutar mediante Azure Portal, la CLI de Azure o con la infraestructura como código. Algunos ejemplos de incluyen la creación de implementaciones de modelos, el cambio de las configuraciones de filtrado de contenido, el cambio de la versión del modelo servido o el cambio de SKU de una implementación.

  • Acceso para desarrolladores: las acciones relacionadas con el consumo de los recursos. Por ejemplo, invocar la API de finalizaciones de chat. Sin embargo, el usuario no puede cambiar el estado del recurso y su configuración.

En Azure, las operaciones de administración siempre se realizan mediante Microsoft Entra ID. Los roles como colaborador de Cognitive Services le permiten realizar esas operaciones. Por otro lado, las operaciones de desarrollador se pueden realizar mediante claves de acceso y/o Microsoft Entra ID. Los roles como el usuario de Cognitive Services le permiten realizar esas operaciones.

Importante

Tener acceso de administración a un recurso no concede necesariamente acceso para desarrolladores. El acceso explícito mediante la concesión de roles sigue siendo necesario. Es análogo a cómo funcionan los servidores de bases de datos. Tener acceso de administrador al servidor de bases de datos no significa que pueda leer los datos dentro de una base de datos.

Siga estos pasos para configurar el acceso de desarrollador a la inferencia del modelo de Azure AI en el recurso de Servicios de Azure AI.

Requisitos previos

Para completar este artículo, necesitará lo siguiente:

  • Suscripción a Azure. Si usa Modelos de GitHub, puede actualizar la experiencia y crear una suscripción de Azure en el proceso. Lea Actualización de modelos de GitHub a la inferencia del modelo de Azure AI si es su caso.

  • Recurso de Servicios de Azure AI. Para más información, vea Creación de un recurso de Servicios de Azure AI.

  • Una cuenta con permisos Microsoft.Authorization/roleAssignments/write y Microsoft.Authorization/roleAssignments/delete, como el control de acceso basado en roles de administrador.

  • Para asignar un rol, debe especificar tres elementos:

    • Entidad de seguridad: por ejemplo, su cuenta de usuario.
    • Definición de roles: el rol de usuario de Cognitive Services.
    • Ámbito: el recurso de Servicios de Azure AI.

  • Instale la CLI de Azure.

  • Identifique la siguiente información:

    • Su identificador de suscripción de Azure.

Acerca de este tutorial

El ejemplo de este artículo se basa en los ejemplos de código incluidos en el repositorio Azure-Samples/azureai-model-inference-bicep. Para ejecutar los comandos localmente sin tener que copiar o pegar contenido de archivo, use los siguientes comandos para clonar el repositorio y vaya a la carpeta del lenguaje de codificación:

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

Los archivos de este ejemplo están en:

cd azureai-model-inference-bicep/infra

Descripción de los recursos

El tutorial le ayuda a crear:

  • Un recurso de Servicios de Azure AI con acceso a claves deshabilitado. Por motivos de simplicidad, esta plantilla no implementa modelos.
  • Asignación de roles para una entidad de seguridad determinada con el rol Usuario de Cognitive Services.

Está usando los siguientes recursos para crear esos recursos:

  1. Use la plantilla modules/ai-services-template.bicep para describir el recurso de Servicios de Azure AI:

    modules/ai-services-template.bicep

    @description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = account.properties.endpoints['Azure AI Model Inference API']
output id string = account.id

    Sugerencia

    Tenga en cuenta que esta plantilla puede tomar el parámetro allowKeys que, cuando false deshabilite el uso de claves en el recurso. Esta configuración es opcional.

  2. Use la plantilla modules/role-assignment-template.bicep para describir una asignación de roles en Azure:

    modules/role-assignment-template.bicep

    @description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionID string

@description('Specifies the principal ID assigned to the role.')
param principalId string

@description('Specifies the resource ID of the resource to assign the role to.')
param scopeResourceId string = resourceGroup().id

var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
    principalId: principalId
  }
}

output name string = roleAssignment.name
output resourceId string = roleAssignment.id

Creación de los recursos

En la consola, siga estos pasos:

  1. Defina la implementación principal:

    deploy-entra-id.bicep

    @description('Location to create the resources in')
param location string = resourceGroup().location

@description('Name of the resource group to create the resources in')
param resourceGroupName string = resourceGroup().name

@description('Name of the AI Services account to create')
param accountName string = 'azurei-models-dev'

@description('ID of the developers to assign the user role to')
param securityPrincipalId string

module aiServicesAccount 'modules/ai-services-template.bicep' = {
  name: 'aiServicesAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    accountName: accountName
    location: location
    allowKeys: false
  }
}

module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
  name: 'roleAssignmentDeveloperAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
    principalId: securityPrincipalId
  }
}

output endpoint string = aiServicesAccount.outputs.endpointUri

  2. Inicio de sesión en Azure:

    az login

  3. Asegúrese de que está en la suscripción correcta:

    az account set --subscription "<subscription-id>"

  4. Ejecute la implementación:

    RESOURCE_GROUP="<resource-group-name>"
SECURITY_PRINCIPAL_ID="<your-security-principal-id>"

az deployment group create \
  --resource-group $RESOURCE_GROUP \
  --securityPrincipalId $SECURITY_PRINCIPAL_ID
  --template-file deploy-entra-id.bicep

  5. La plantilla genera el punto de conexión de inferencia del modelo de Azure AI que puede usar para consumir cualquiera de las implementaciones de modelo que ha creado.

Uso de Microsoft Entra ID en el código

Una vez configurado Microsoft Entra ID en el recurso, debe actualizar el código para usarlo al consumir el punto de conexión de inferencia. En el ejemplo siguiente se muestra cómo usar un modelo de finalizaciones de chat:

Instale el paquete azure-ai-inference mediante el administrador de paquetes, como pip:

pip install azure-ai-inference>=1.0.0b5

Advertencia

El recurso de Servicios de Azure AI necesita la versión azure-ai-inference>=1.0.0b5 para Python.

A continuación, puede usar el paquete para consumir el modelo. En el ejemplo siguiente se muestra cómo crear un cliente para consumir finalizaciones de chat con Entra ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
    model="mistral-large-2407",
)

Opciones de credenciales al usar Microsoft Entra ID

DefaultAzureCredential es una secuencia ordenada de mecanismos para autenticarse en Microsoft Entra ID. Cada mecanismo de autenticación es una clase derivada de la clase TokenCredential y se conoce como credencial. En tiempo de ejecución, DefaultAzureCredential intenta autenticarse con la primera credencial. Si esa credencial no puede adquirir un token de acceso, se intenta utilizar la siguiente credencial de la secuencia, y así sucesivamente hasta que se obtenga correctamente un token de acceso. De esta manera, la aplicación puede usar diferentes credenciales en distintos entornos sin implementar código específico del entorno.

Cuando el código anterior se ejecuta en la estación de trabajo de desarrollo local, busca en las variables de entorno una entidad de servicio de aplicación o en las herramientas de desarrollo instaladas localmente, como Visual Studio, un conjunto de credenciales de desarrollador. Se puede usar cualquier enfoque para autenticar la aplicación en los recursos de Azure durante el desarrollo local.

Cuando se implementa en Azure, este mismo código también puede autenticar su aplicación en otros recursos de Azure. DefaultAzureCredential puede recuperar la configuración del entorno y las configuraciones de identidad administrada para autenticarse en otros servicios automáticamente.

procedimientos recomendados

  • Usar credenciales deterministas en entornos de producción: considere la posibilidad de pasar de DefaultAzureCredential a una de las siguientes soluciones deterministas en entornos de producción:

    • Una implementación de TokenCredential específica, como ManagedIdentityCredential. Consulte la lista de Derived para ver las opciones.
    • Una implementación de ChainedTokenCredential reducida optimizada para el entorno Azure en el que se ejecuta la aplicación. ChainedTokenCredential básicamente crea una lista de permitidos específica de opciones de credenciales aceptables, como ManagedIdentity para producción y VisualStudioCredential para desarrollo.

  • Configure identidades administradas asignadas por el sistema o asignadas por el usuario en los recursos de Azure donde el código se ejecuta si es posible. Configure el acceso de Microsoft Entra ID a esas identidades específicas.

Deshabilitación de la autenticación basada en claves en el recurso

Deshabilitar la autenticación basada en claves es aconsejable cuando implementó Microsoft Entra ID y solucionó completamente los problemas de compatibilidad o reserva en todas las aplicaciones que consumen el servicio. Para lograrlo, cambie la propiedad disableLocalAuth:

modules/ai-services-template.bicep

@description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = account.properties.endpoints['Azure AI Model Inference API']
output id string = account.id

Pasos siguientes