Compartilhar via

Configurar a autenticação sem chave com o Microsoft Entra ID

  • Artigo

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Os modelos implantados na inferência de modelo da IA do Azure nos Serviços de IA do Azure dão suporte à autorização sem chave usando o Microsoft Entra ID. A autorização sem chave melhora a segurança, simplifica a experiência do usuário, reduz a complexidade operacional e fornece suporte de conformidade robusto para desenvolvimento moderno. Isso a torna uma ótima escolha para as organizações que adotam soluções de gerenciamento de identidade seguras e escaláveis.

Este artigo explica como configurar o Microsoft Entra ID para inferência na inferência de modelo da IA do Azure.

Entender as funções no contexto do recurso no Azure

O Microsoft Entra ID usa a ideia do RBAC (Controle de Acesso Baseado em Função) para autorização. As funções são centrais para gerenciar o acesso aos recursos de nuvem. Uma função é essencialmente uma coleção de permissões que definem quais ações podem ser executadas em recursos específicos do Azure. Ao atribuir funções a usuários, grupos, entidades de serviço ou identidades gerenciadas, conhecidas coletivamente como entidades de segurança, você controla o acesso deles dentro do seu ambiente do Azure a recursos específicos.

Ao atribuir uma função, especifique a entidade de segurança, a definição de função e o escopo. Essa combinação é conhecida como uma atribuição de função. A inferência de modelo da IA do Azure é uma funcionalidade dos recursos dos Serviços de IA do Azure e, portanto, as funções atribuídas a esse recurso específico controlam o acesso à inferência.

Você identifica dois tipos diferentes de acesso aos recursos:

  • Acesso de administração: as ações relacionadas com a administração do recurso. Geralmente alteram o estado do recurso e sua configuração. No Azure, essas operações são operações de plano de controle e podem ser executadas usando o portal do Azure, a CLI do Azure ou com a infraestrutura como código. Exemplos incluem a criação de uma nova implantação de modelo, a alteração das configurações de filtragem de conteúdo, a alteração da versão do modelo servido ou a alteração da SKU de uma implantação.

  • Acesso de desenvolvedor: as ações relacionadas com o consumo do recurso. Por exemplo, invocar a API de conclusões de chat. No entanto, o usuário não pode alterar o estado do recurso e sua configuração.

No Azure, as operações de administração são sempre executadas usando o Microsoft Entra ID. As funções como Colaborador dos Serviços Cognitivos permitem que você execute essas operações. Por outro lado, as operações de desenvolvedor podem ser executadas usando as chaves de acesso ou/e o Microsoft Entra ID. As funções como Usuário dos Serviços Cognitivos permitem que você execute essas operações.

Importante

Ter acesso de administração a um recurso não necessariamente concede acesso de desenvolvedor a ele. O acesso explícito por meio da concessão de funções ainda é necessário. É análogo ao funcionamento dos servidores de banco de dados. Ter acesso de administrador ao servidor de banco de dados não significa que você possa ler os dados dentro de um banco de dados.

Siga estas etapas para configurar o acesso de desenvolvedor à inferência de modelo da IA do Azure no recurso dos Serviços de IA do Azure.

Pré-requisitos

Para concluir este artigo, você precisa do seguinte:

  • Uma assinatura do Azure. Se você estiver usando modelos do GitHub, poderá atualizar sua experiência e criar uma assinatura do Azure no processo. Leia Atualizar de modelos do GitHub para a inferência do modelo de IA do Azure se for o seu caso.

  • Um recurso dos serviços de IA do Azure. Para obter mais informações, confira Criar um recurso dos Serviços de IA do Azure.

  • Uma conta com permissões de Microsoft.Authorization/roleAssignments/write e Microsoft.Authorization/roleAssignments/delete, como o controle de acesso baseado na função de Administrador.

  • Para atribuir uma função, você deve especificar três elementos:

    • Entidade de segurança: por exemplo, sua conta de usuário.
    • Definição de função: a função de Usuário dos Serviços Cognitivos.
    • Escopo: o recurso dos Serviços de IA do Azure.

Configurar o Microsoft Entra ID para inferência

Siga estas etapas para configurar o Microsoft Entra ID para inferência:

  1. Acesse o portal do Azure e localize o recurso dos Serviços de IA do Azure que você está usando. Se você estiver usando a Fábrica de IA do Azure com projetos ou hubs, navegue até ela:

    1. Acesse o portal do IA do Azure Foundry.

    2. Na página de aterrissagem, selecione Abrir o centro de gerenciamento.

    3. Vá para a seção Recursos conectados e selecione a conexão com o recurso dos Serviços de IA do Azure que você quer configurar. Se ele não estiver listado, selecione Exibir tudo para ver a lista completa.

    4. Na seção Detalhes da conexão, em Recurso, selecione o nome do recurso do Azure. Uma nova página será aberta.

    5. Agora você está no portal do Azure onde pode gerenciar todos os aspectos do próprio recurso.

  2. Na barra de navegação à esquerda, selecione Controle de acesso (IAM).

    Dica

    Use a opção Exibir meu acesso para verificar quais funções já estão atribuídas a você.

  3. Selecione Atribuições de função e, em seguida, selecione Adicionar>Adicionar atribuição de função.

  4. Em Funções de função de trabalho, digite Usuário dos Serviços Cognitivos. A lista de funções é filtrada.

  5. Escolha a função e selecione Avançar.

  6. Em Membros, selecione o usuário ou grupo ao qual você quer conceder acesso. É recomendável usar grupos de segurança sempre que possível, pois eles são mais fáceis de gerenciar e manter.

  7. Selecione Avançar e conclua o assistente.

  8. O usuário selecionado agora pode usar o Microsoft Entra ID para inferência.

    Dica

    Lembre-se de que as atribuições de função do Azure podem levar até cinco minutos para se propagar. Ao trabalhar com grupos de segurança, adicionar ou remover usuários do grupo de segurança é propagado imediatamente.

Observe que o acesso baseado em chave ainda é possível para os usuários que já têm chaves disponíveis para eles. Se você quiser revogar as chaves, no portal do Azure, na navegação à esquerda, selecione Gerenciamento do Recurso>Chaves e Pontos de Extremidade>Regenerar Chave1 e Regenerar Chave2.

Use o Microsoft Entra ID em seu código

Depois de configurar o Microsoft Entra ID em seu recurso, você precisará atualizar seu código para usá-lo ao consumir o ponto de extremidade de inferência. O exemplo a seguir mostra como usar um modelo de conclusão de chat:

Instale o pacote azure-ai-inference usando seu gerenciador de pacotes, como o pip:

pip install azure-ai-inference>=1.0.0b5

Aviso

O recurso dos Serviços de IA do Azure requer a versão azure-ai-inference>=1.0.0b5 para Python.

Em seguida, você poderá usar o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente para consumir as conclusões de chat com o 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",
)

Opções de credencial ao usar o Microsoft Entra ID

DefaultAzureCredential é uma sequência opinativa e ordenada de mecanismos para autenticação no Microsoft Entra ID. Cada mecanismo de autenticação é uma classe derivada da classe TokenCredential e é conhecida como uma credencial. No runtime, DefaultAzureCredential tenta autenticar usando a primeira credencial. Se essa credencial não conseguir adquirir um token de acesso, a próxima credencial na sequência será tentada e assim por diante, até que um token de acesso seja obtido com êxito. Dessa forma, seu aplicativo pode usar credenciais diferentes em ambientes diferentes sem escrever código específico do ambiente.

Quando o código anterior é executado na sua estação de trabalho de desenvolvimento local, ele procura uma entidade de serviço de aplicativo nas variáveis de ambiente ou procura um conjunto de credenciais de desenvolvedor nas ferramentas de desenvolvedor instaladas localmente, como o Visual Studio. Qualquer abordagem pode ser usada para autenticar o aplicativo nos recursos do Azure durante o desenvolvimento local.

Quando implantado no Azure, esse mesmo código também pode autenticar seu aplicativo em outros recursos do Azure. DefaultAzureCredential pode recuperar configurações de ambiente e configurações de identidade gerenciada para autenticar-se em outros serviços automaticamente.

Práticas recomendadas

  • Use as credenciais determinísticas em ambientes de produção: considere seriamente migrar de DefaultAzureCredential para uma das seguintes soluções determinísticas em ambientes de produção:

    • Uma implementação TokenCredential específica, como ManagedIdentityCredential. Consulte a Lista derivada para obter opções.
    • Uma implementação ChainedTokenCredential simplificada e otimizada para o ambiente do Azure no qual seu aplicativo é executado. ChainedTokenCredential essencialmente cria uma lista de permissões específica de opções de credencial aceitáveis, como ManagedIdentity para produção e VisualStudioCredential para desenvolvimento.

  • Configure as identidades gerenciadas atribuídas pelo sistema ou atribuídas pelo usuário para os recursos do Azure onde seu código está em execução, se possível. Configure o Microsoft Entra ID para essas identidades específicas.

Use o Microsoft Entra ID em seu projeto

Mesmo quando seu recurso tem o Microsoft Entra ID configurado, seus projetos ainda podem estar usando chaves para consumir as previsões do recurso. Ao usar o playground da Fábrica de IA do Azure, as credenciais associadas à conexão do seu projeto são usadas.

Para alterar esse comportamento, você precisa atualizar as conexões de seus projetos para usar o Microsoft Entra ID. Siga estas etapas:

  1. Acesse o portal do IA do Azure Foundry.

  2. Navegue até os projetos ou hubs que estão usando o recurso dos Serviços de IA do Azure por meio de uma conexão.

  3. Selecione Centro de gerenciamento.

  4. Vá para a seção Recursos conectados e selecione a conexão com o recurso dos Serviços de IA do Azure que você quer configurar. Se não estiver listado, selecione Exibir tudo para ver a lista completa.

  5. Na seção Detalhes da conexão, ao lado de Detalhes do acesso, selecione o ícone de edição.

  6. Em Autenticação, altere o valor para Microsoft Entra ID.

  7. Selecione Atualizar.

  8. Sua conexão está configurada para funcionar com o Microsoft Entra ID agora.

Desabilitar a autenticação baseada em chave no recurso

É aconselhável desabilitar a autenticação baseada em chave quando você implementou o Microsoft Entra ID e resolveu completamente os problemas de compatibilidade ou fallback em todos os aplicativos que consomem o serviço.

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Os modelos implantados na inferência de modelo da IA do Azure nos Serviços de IA do Azure dão suporte à autorização sem chave usando o Microsoft Entra ID. A autorização sem chave melhora a segurança, simplifica a experiência do usuário, reduz a complexidade operacional e fornece suporte de conformidade robusto para desenvolvimento moderno. Isso a torna uma ótima escolha para as organizações que adotam soluções de gerenciamento de identidade seguras e escaláveis.

Este artigo explica como configurar o Microsoft Entra ID para inferência na inferência de modelo da IA do Azure.

Entender as funções no contexto do recurso no Azure

O Microsoft Entra ID usa a ideia do RBAC (Controle de Acesso Baseado em Função) para autorização. As funções são centrais para gerenciar o acesso aos recursos de nuvem. Uma função é essencialmente uma coleção de permissões que definem quais ações podem ser executadas em recursos específicos do Azure. Ao atribuir funções a usuários, grupos, entidades de serviço ou identidades gerenciadas, conhecidas coletivamente como entidades de segurança, você controla o acesso deles dentro do seu ambiente do Azure a recursos específicos.

Ao atribuir uma função, especifique a entidade de segurança, a definição de função e o escopo. Essa combinação é conhecida como uma atribuição de função. A inferência de modelo da IA do Azure é uma funcionalidade dos recursos dos Serviços de IA do Azure e, portanto, as funções atribuídas a esse recurso específico controlam o acesso à inferência.

Você identifica dois tipos diferentes de acesso aos recursos:

  • Acesso de administração: as ações relacionadas com a administração do recurso. Geralmente alteram o estado do recurso e sua configuração. No Azure, essas operações são operações de plano de controle e podem ser executadas usando o portal do Azure, a CLI do Azure ou com a infraestrutura como código. Exemplos incluem a criação de uma nova implantação de modelo, a alteração das configurações de filtragem de conteúdo, a alteração da versão do modelo servido ou a alteração da SKU de uma implantação.

  • Acesso de desenvolvedor: as ações relacionadas com o consumo do recurso. Por exemplo, invocar a API de conclusões de chat. No entanto, o usuário não pode alterar o estado do recurso e sua configuração.

No Azure, as operações de administração são sempre executadas usando o Microsoft Entra ID. As funções como Colaborador dos Serviços Cognitivos permitem que você execute essas operações. Por outro lado, as operações de desenvolvedor podem ser executadas usando as chaves de acesso ou/e o Microsoft Entra ID. As funções como Usuário dos Serviços Cognitivos permitem que você execute essas operações.

Importante

Ter acesso de administração a um recurso não necessariamente concede acesso de desenvolvedor a ele. O acesso explícito por meio da concessão de funções ainda é necessário. É análogo ao funcionamento dos servidores de banco de dados. Ter acesso de administrador ao servidor de banco de dados não significa que você possa ler os dados dentro de um banco de dados.

Siga estas etapas para configurar o acesso de desenvolvedor à inferência de modelo da IA do Azure no recurso dos Serviços de IA do Azure.

Pré-requisitos

Para concluir este artigo, você precisa do seguinte:

  • Uma assinatura do Azure. Se você estiver usando modelos do GitHub, poderá atualizar sua experiência e criar uma assinatura do Azure no processo. Leia Atualizar de modelos do GitHub para a inferência do modelo de IA do Azure se for o seu caso.

  • Um recurso dos serviços de IA do Azure. Para obter mais informações, confira Criar um recurso dos Serviços de IA do Azure.

  • Uma conta com permissões de Microsoft.Authorization/roleAssignments/write e Microsoft.Authorization/roleAssignments/delete, como o controle de acesso baseado na função de Administrador.

  • Para atribuir uma função, você deve especificar três elementos:

    • Entidade de segurança: por exemplo, sua conta de usuário.
    • Definição de função: a função de Usuário dos Serviços Cognitivos.
    • Escopo: o recurso dos Serviços de IA do Azure.

  • Instale a CLI do Azure.

  • Identifique as seguintes informações:

    • Sua ID da assinatura do Azure.

    • O nome do recurso dos Serviços de IA do Azure.

    • O grupo de recursos em que o recurso dos Serviços de IA do Azure é implantado.

Configurar o Microsoft Entra ID para inferência

Siga estas etapas para configurar o Microsoft Entra ID para inferência no recurso dos Serviços de IA do Azure:

  1. Faça logon em sua assinatura do Azure:

    az login

  2. Se você tiver mais de uma assinatura, selecione a assinatura na qual o recurso está localizado:

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

  3. Defina as variáveis de ambiente a seguir com o nome do recurso dos Serviços de IA do Azure que você planeja usar e grupo de recursos.

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

  4. Obtenha o nome completo do seu recurso:

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

  5. Obtenha a ID do objeto da entidade de segurança à qual você quer atribuir permissões. O exemplo a seguir mostra como obter a ID do objeto associada a:

    Sua própria conta conectada:

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

    Um grupo de segurança:

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

    Uma entidade de serviço:

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

  6. Atribua a função de Usuário dos Serviços Cognitivos à entidade de serviço (com escopo para o recurso). Ao atribuir uma função, você está concedendo acesso principal de serviço a este recurso.

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

  7. O usuário selecionado agora pode usar o Microsoft Entra ID para inferência.

    Dica

    Lembre-se de que as atribuições de função do Azure podem levar até cinco minutos para se propagar. Adicionar ou remover usuários de um grupo de segurança se propaga imediatamente.

Use o Microsoft Entra ID em seu código

Depois de configurar o Microsoft Entra ID em seu recurso, você precisará atualizar seu código para usá-lo ao consumir o ponto de extremidade de inferência. O exemplo a seguir mostra como usar um modelo de conclusão de chat:

Instale o pacote azure-ai-inference usando seu gerenciador de pacotes, como o pip:

pip install azure-ai-inference>=1.0.0b5

Aviso

O recurso dos Serviços de IA do Azure requer a versão azure-ai-inference>=1.0.0b5 para Python.

Em seguida, você poderá usar o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente para consumir as conclusões de chat com o 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",
)

Opções de credencial ao usar o Microsoft Entra ID

DefaultAzureCredential é uma sequência opinativa e ordenada de mecanismos para autenticação no Microsoft Entra ID. Cada mecanismo de autenticação é uma classe derivada da classe TokenCredential e é conhecida como uma credencial. No runtime, DefaultAzureCredential tenta autenticar usando a primeira credencial. Se essa credencial não conseguir adquirir um token de acesso, a próxima credencial na sequência será tentada e assim por diante, até que um token de acesso seja obtido com êxito. Dessa forma, seu aplicativo pode usar credenciais diferentes em ambientes diferentes sem escrever código específico do ambiente.

Quando o código anterior é executado na sua estação de trabalho de desenvolvimento local, ele procura uma entidade de serviço de aplicativo nas variáveis de ambiente ou procura um conjunto de credenciais de desenvolvedor nas ferramentas de desenvolvedor instaladas localmente, como o Visual Studio. Qualquer abordagem pode ser usada para autenticar o aplicativo nos recursos do Azure durante o desenvolvimento local.

Quando implantado no Azure, esse mesmo código também pode autenticar seu aplicativo em outros recursos do Azure. DefaultAzureCredential pode recuperar configurações de ambiente e configurações de identidade gerenciada para autenticar-se em outros serviços automaticamente.

Práticas recomendadas

  • Use as credenciais determinísticas em ambientes de produção: considere seriamente migrar de DefaultAzureCredential para uma das seguintes soluções determinísticas em ambientes de produção:

    • Uma implementação TokenCredential específica, como ManagedIdentityCredential. Consulte a Lista derivada para obter opções.
    • Uma implementação ChainedTokenCredential simplificada e otimizada para o ambiente do Azure no qual seu aplicativo é executado. ChainedTokenCredential essencialmente cria uma lista de permissões específica de opções de credencial aceitáveis, como ManagedIdentity para produção e VisualStudioCredential para desenvolvimento.

  • Configure as identidades gerenciadas atribuídas pelo sistema ou atribuídas pelo usuário para os recursos do Azure onde seu código está em execução, se possível. Configure o Microsoft Entra ID para essas identidades específicas.

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Os modelos implantados na inferência de modelo da IA do Azure nos Serviços de IA do Azure dão suporte à autorização sem chave usando o Microsoft Entra ID. A autorização sem chave melhora a segurança, simplifica a experiência do usuário, reduz a complexidade operacional e fornece suporte de conformidade robusto para desenvolvimento moderno. Isso a torna uma ótima escolha para as organizações que adotam soluções de gerenciamento de identidade seguras e escaláveis.

Este artigo explica como configurar o Microsoft Entra ID para inferência na inferência de modelo da IA do Azure.

Entender as funções no contexto do recurso no Azure

O Microsoft Entra ID usa a ideia do RBAC (Controle de Acesso Baseado em Função) para autorização. As funções são centrais para gerenciar o acesso aos recursos de nuvem. Uma função é essencialmente uma coleção de permissões que definem quais ações podem ser executadas em recursos específicos do Azure. Ao atribuir funções a usuários, grupos, entidades de serviço ou identidades gerenciadas, conhecidas coletivamente como entidades de segurança, você controla o acesso deles dentro do seu ambiente do Azure a recursos específicos.

Ao atribuir uma função, especifique a entidade de segurança, a definição de função e o escopo. Essa combinação é conhecida como uma atribuição de função. A inferência de modelo da IA do Azure é uma funcionalidade dos recursos dos Serviços de IA do Azure e, portanto, as funções atribuídas a esse recurso específico controlam o acesso à inferência.

Você identifica dois tipos diferentes de acesso aos recursos:

  • Acesso de administração: as ações relacionadas com a administração do recurso. Geralmente alteram o estado do recurso e sua configuração. No Azure, essas operações são operações de plano de controle e podem ser executadas usando o portal do Azure, a CLI do Azure ou com a infraestrutura como código. Exemplos incluem a criação de uma nova implantação de modelo, a alteração das configurações de filtragem de conteúdo, a alteração da versão do modelo servido ou a alteração da SKU de uma implantação.

  • Acesso de desenvolvedor: as ações relacionadas com o consumo do recurso. Por exemplo, invocar a API de conclusões de chat. No entanto, o usuário não pode alterar o estado do recurso e sua configuração.

No Azure, as operações de administração são sempre executadas usando o Microsoft Entra ID. As funções como Colaborador dos Serviços Cognitivos permitem que você execute essas operações. Por outro lado, as operações de desenvolvedor podem ser executadas usando as chaves de acesso ou/e o Microsoft Entra ID. As funções como Usuário dos Serviços Cognitivos permitem que você execute essas operações.

Importante

Ter acesso de administração a um recurso não necessariamente concede acesso de desenvolvedor a ele. O acesso explícito por meio da concessão de funções ainda é necessário. É análogo ao funcionamento dos servidores de banco de dados. Ter acesso de administrador ao servidor de banco de dados não significa que você possa ler os dados dentro de um banco de dados.

Siga estas etapas para configurar o acesso de desenvolvedor à inferência de modelo da IA do Azure no recurso dos Serviços de IA do Azure.

Pré-requisitos

Para concluir este artigo, você precisa do seguinte:

  • Uma assinatura do Azure. Se você estiver usando modelos do GitHub, poderá atualizar sua experiência e criar uma assinatura do Azure no processo. Leia Atualizar de modelos do GitHub para a inferência do modelo de IA do Azure se for o seu caso.

  • Um recurso dos serviços de IA do Azure. Para obter mais informações, confira Criar um recurso dos Serviços de IA do Azure.

  • Uma conta com permissões de Microsoft.Authorization/roleAssignments/write e Microsoft.Authorization/roleAssignments/delete, como o controle de acesso baseado na função de Administrador.

  • Para atribuir uma função, você deve especificar três elementos:

    • Entidade de segurança: por exemplo, sua conta de usuário.
    • Definição de função: a função de Usuário dos Serviços Cognitivos.
    • Escopo: o recurso dos Serviços de IA do Azure.

  • Instale a CLI do Azure.

  • Identifique as seguintes informações:

    • Sua ID da assinatura do Azure.

Sobre este tutorial

O exemplo neste artigo baseia-se em exemplos de código contidos no repositório Azure-Samples/azureai-model-inference-bicep. Para executar os comandos localmente sem precisar copiar ou colar o conteúdo do arquivo, use os seguintes comandos para clonar o repositório e ir para a pasta do idioma de codificação:

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

Os arquivos desse exemplo estão em:

cd azureai-model-inference-bicep/infra

Entenda os recursos

O tutorial ajuda você a criar:

  • Um recurso dos Serviços de IA do Azure com acesso de chave desabilitado. Para simplificar, esse modelo não implanta modelos.
  • Uma atribuição de função para uma determinada entidade de segurança com a função de Usuário dos Serviços Cognitivos.

Você está usando os seguintes ativos para criar esses recursos:

  1. Use o modelo modules/ai-services-template.bicep para descrever o recurso dos Serviços de IA do Azure:

    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

    Dica

    Observe que esse modelo pode usar o parâmetro allowKeys que, quando false desabilitará o uso de chaves no recurso. Essa configuração é opcional.

  2. Use o modelo modules/role-assignment-template.bicep para descrever uma atribuição de função no 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

Criar os recursos

No console, siga estas etapas:

  1. Defina a implantação 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. Faça logon no Azure:

    az login

  3. Verifique se você está na assinatura certa:

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

  4. Execute a implantação:

    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. O modelo gera o ponto de extremidade de inferência do modelo de IA do Azure que você pode usar para consumir qualquer uma das implantações de modelo que você criou.

Use o Microsoft Entra ID em seu código

Depois de configurar o Microsoft Entra ID em seu recurso, você precisará atualizar seu código para usá-lo ao consumir o ponto de extremidade de inferência. O exemplo a seguir mostra como usar um modelo de conclusão de chat:

Instale o pacote azure-ai-inference usando seu gerenciador de pacotes, como o pip:

pip install azure-ai-inference>=1.0.0b5

Aviso

O recurso dos Serviços de IA do Azure requer a versão azure-ai-inference>=1.0.0b5 para Python.

Em seguida, você poderá usar o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente para consumir as conclusões de chat com o 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",
)

Opções de credencial ao usar o Microsoft Entra ID

DefaultAzureCredential é uma sequência opinativa e ordenada de mecanismos para autenticação no Microsoft Entra ID. Cada mecanismo de autenticação é uma classe derivada da classe TokenCredential e é conhecida como uma credencial. No runtime, DefaultAzureCredential tenta autenticar usando a primeira credencial. Se essa credencial não conseguir adquirir um token de acesso, a próxima credencial na sequência será tentada e assim por diante, até que um token de acesso seja obtido com êxito. Dessa forma, seu aplicativo pode usar credenciais diferentes em ambientes diferentes sem escrever código específico do ambiente.

Quando o código anterior é executado na sua estação de trabalho de desenvolvimento local, ele procura uma entidade de serviço de aplicativo nas variáveis de ambiente ou procura um conjunto de credenciais de desenvolvedor nas ferramentas de desenvolvedor instaladas localmente, como o Visual Studio. Qualquer abordagem pode ser usada para autenticar o aplicativo nos recursos do Azure durante o desenvolvimento local.

Quando implantado no Azure, esse mesmo código também pode autenticar seu aplicativo em outros recursos do Azure. DefaultAzureCredential pode recuperar configurações de ambiente e configurações de identidade gerenciada para autenticar-se em outros serviços automaticamente.

Práticas recomendadas

  • Use as credenciais determinísticas em ambientes de produção: considere seriamente migrar de DefaultAzureCredential para uma das seguintes soluções determinísticas em ambientes de produção:

    • Uma implementação TokenCredential específica, como ManagedIdentityCredential. Consulte a Lista derivada para obter opções.
    • Uma implementação ChainedTokenCredential simplificada e otimizada para o ambiente do Azure no qual seu aplicativo é executado. ChainedTokenCredential essencialmente cria uma lista de permissões específica de opções de credencial aceitáveis, como ManagedIdentity para produção e VisualStudioCredential para desenvolvimento.

  • Configure as identidades gerenciadas atribuídas pelo sistema ou atribuídas pelo usuário para os recursos do Azure onde seu código está em execução, se possível. Configure o Microsoft Entra ID para essas identidades específicas.

Desabilitar a autenticação baseada em chave no recurso

É aconselhável desabilitar a autenticação baseada em chave quando você implementou o Microsoft Entra ID e resolveu completamente os problemas de compatibilidade ou fallback em todos os aplicativos que consomem o serviço. Você pode obtê-lo alterando a propriedade 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

Próximas etapas