Partilhar via

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

  • Artigo

Importante

Os itens marcados (visualização) neste artigo estão atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

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

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

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

O Microsoft Entra ID usa a ideia de RBAC (Controle de Acesso Baseado em Função) para autorização. As funções são fundamentais para gerenciar o acesso aos seus 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 delas em seu ambiente do Azure a recursos específicos.

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

Você identifica dois tipos diferentes de acesso aos recursos:

  • Acesso à administração: as ações relacionadas com a administração do recurso. Eles geralmente mudam 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 disso incluem a criação de implantações de um novo modelo, a alteração de configurações de filtragem de conteúdo, a alteração da versão do modelo atendido ou a alteração da SKU de uma implantação.

  • Acesso do desenvolvedor: As ações que estão relacionadas com o consumo dos recursos. Por exemplo, invocar a API de conclusão 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. Funções como Colaborador de Serviços Cognitivos permitem que você execute essas operações. Por outro lado, as operações do desenvolvedor podem ser executadas usando chaves de acesso e/ou Microsoft Entra ID. Funções como Usuário de Serviços Cognitivos permitem que você execute essas operações.

Importante

Ter acesso de administração a um recurso não necessariamente concede ao desenvolvedor acesso a ele. O acesso explícito através 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ê pode ler os dados dentro de um banco de dados.

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

Pré-requisitos

Para concluir este artigo, precisa de:

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

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

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

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

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

Configurar o ID do Microsoft Entra para inferência

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

  1. Vá para o portal do Azure e localize o recurso dos Serviços de IA do Azure que você está usando. Se você estiver usando o Azure AI Foundry com projetos ou hubs, poderá navegar até ele da seguinte forma:

    1. Vá para o portal do Azure AI Foundry.

    2. Na página de destino, selecione Abrir 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ê deseja configurar. Se não estiver listado, selecione Ver tudo para ver a lista completa.

    4. Na seção Detalhes da conexão, em Recurso, selecione o nome do recurso do Azure. Abre-se uma nova página.

    5. Agora você está no portal do Azure, onde pode gerenciar todos os aspetos do recurso em si.

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

    Gorjeta

    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>adição de atribuição de função.

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

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

  6. Em Membros, selecione o usuário ou grupo ao qual você deseja conceder acesso. Recomendamos o uso de grupos de segurança sempre que possível, pois 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.

    Gorjeta

    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 se propaga imediatamente.

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

Use o Microsoft Entra ID no seu código

Depois de configurar o Microsoft Entra ID em seu recurso, você precisa 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 pip:

pip install azure-ai-inference>=1.0.0b5

Aviso

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

Em seguida, você pode usar o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente para consumir finalizações de bate-papo 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 TokenCredential classe e é conhecido como uma credencial. No tempo de execução, 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 em sua estação de trabalho de desenvolvimento local, ele procura nas variáveis de ambiente uma entidade de serviço de aplicativo ou em ferramentas de desenvolvedor instaladas localmente, como o Visual Studio, para um conjunto de credenciais de desenvolvedor. Qualquer uma das abordagens 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 em outros serviços automaticamente.

Melhores práticas

  • Use credenciais determinísticas em ambientes de produção: considere fortemente a mudança de DefaultAzureCredential uma das seguintes soluções determinísticas em ambientes de produção:

    • Uma implementação específica TokenCredential , como ManagedIdentityCredential. Consulte a lista Derivados para obter opções.
    • Uma implementação reduzida ChainedTokenCredential 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 credenciais aceitáveis, como ManagedIdentity para produção e VisualStudioCredential desenvolvimento.

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

Usar 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 previsões do recurso. Ao usar o playground do Azure AI Foundry, as credenciais associadas à conexão que seu projeto tem são usadas.

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

  1. Vá para o portal do Azure AI Foundry.

  2. Navegue até os projetos ou hubs que estão usando o recurso 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ê deseja configurar. Se não estiver listado, selecione Ver tudo para ver a lista completa.

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

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

  7. Selecione Atualizar.

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

Desativar a autenticação baseada em chave no recurso

A desativação da autenticação baseada em chave é aconselhável quando você implementou o Microsoft Entra ID e resolveu totalmente as preocupações de compatibilidade ou fallback em todos os aplicativos que consomem o serviço.

Importante

Os itens marcados (visualização) neste artigo estão atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

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

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

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

O Microsoft Entra ID usa a ideia de RBAC (Controle de Acesso Baseado em Função) para autorização. As funções são fundamentais para gerenciar o acesso aos seus 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 delas em seu ambiente do Azure a recursos específicos.

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

Você identifica dois tipos diferentes de acesso aos recursos:

  • Acesso à administração: as ações relacionadas com a administração do recurso. Eles geralmente mudam 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 disso incluem a criação de implantações de um novo modelo, a alteração de configurações de filtragem de conteúdo, a alteração da versão do modelo atendido ou a alteração da SKU de uma implantação.

  • Acesso do desenvolvedor: As ações que estão relacionadas com o consumo dos recursos. Por exemplo, invocar a API de conclusão 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. Funções como Colaborador de Serviços Cognitivos permitem que você execute essas operações. Por outro lado, as operações do desenvolvedor podem ser executadas usando chaves de acesso e/ou Microsoft Entra ID. Funções como Usuário de Serviços Cognitivos permitem que você execute essas operações.

Importante

Ter acesso de administração a um recurso não necessariamente concede ao desenvolvedor acesso a ele. O acesso explícito através 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ê pode ler os dados dentro de um banco de dados.

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

Pré-requisitos

Para concluir este artigo, precisa de:

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

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

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

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

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

  • Instale a CLI do Azure.

  • Identifique as seguintes informações:

    • O seu ID de subscrição do Azure.

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

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

Configurar o ID do Microsoft Entra para inferência

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

  1. Inicie sessão na sua subscrição do Azure:

    az login

  2. Se tiver mais do que uma subscrição, selecione a subscrição onde o recurso está localizado:

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

  3. Defina as seguintes variáveis de ambiente com o nome do recurso dos Serviços de IA do Azure que você planeja usar e o 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 o ID do objeto da entidade de segurança à qual você deseja atribuir permissões. O exemplo a seguir mostra como obter a ID do objeto associada:

    A sua própria conta com sessão iniciada:

    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 Usuário dos Serviços Cognitivos à entidade de serviço (com escopo para o recurso). Ao atribuir uma função, você está concedendo acesso da entidade de serviço a esse 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.

    Gorjeta

    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 no seu código

Depois que o Microsoft Entra ID estiver configurado 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 pip:

pip install azure-ai-inference>=1.0.0b5

Aviso

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

Em seguida, você pode usar o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente para consumir finalizações de bate-papo 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 TokenCredential classe e é conhecido como uma credencial. No tempo de execução, 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 em sua estação de trabalho de desenvolvimento local, ele procura nas variáveis de ambiente uma entidade de serviço de aplicativo ou em ferramentas de desenvolvedor instaladas localmente, como o Visual Studio, para um conjunto de credenciais de desenvolvedor. Qualquer uma das abordagens 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 em outros serviços automaticamente.

Melhores práticas

  • Use credenciais determinísticas em ambientes de produção: considere fortemente a mudança de DefaultAzureCredential uma das seguintes soluções determinísticas em ambientes de produção:

    • Uma implementação específica TokenCredential , como ManagedIdentityCredential. Consulte a lista Derivados para obter opções.
    • Uma implementação reduzida ChainedTokenCredential 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 credenciais aceitáveis, como ManagedIdentity para produção e VisualStudioCredential desenvolvimento.

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

Importante

Os itens marcados (visualização) neste artigo estão atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

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

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

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

O Microsoft Entra ID usa a ideia de RBAC (Controle de Acesso Baseado em Função) para autorização. As funções são fundamentais para gerenciar o acesso aos seus 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 delas em seu ambiente do Azure a recursos específicos.

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

Você identifica dois tipos diferentes de acesso aos recursos:

  • Acesso à administração: as ações relacionadas com a administração do recurso. Eles geralmente mudam 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 disso incluem a criação de implantações de um novo modelo, a alteração de configurações de filtragem de conteúdo, a alteração da versão do modelo atendido ou a alteração da SKU de uma implantação.

  • Acesso do desenvolvedor: As ações que estão relacionadas com o consumo dos recursos. Por exemplo, invocar a API de conclusão 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. Funções como Colaborador de Serviços Cognitivos permitem que você execute essas operações. Por outro lado, as operações do desenvolvedor podem ser executadas usando chaves de acesso e/ou Microsoft Entra ID. Funções como Usuário de Serviços Cognitivos permitem que você execute essas operações.

Importante

Ter acesso de administração a um recurso não necessariamente concede ao desenvolvedor acesso a ele. O acesso explícito através 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ê pode ler os dados dentro de um banco de dados.

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

Pré-requisitos

Para concluir este artigo, precisa de:

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

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

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

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

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

  • Instale a CLI do Azure.

  • Identifique as seguintes informações:

    • O seu ID de subscrição do Azure.

Acerca deste tutorial

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

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

Os arquivos para este exemplo estão em:

cd azureai-model-inference-bicep/infra

Compreender os recursos

O tutorial ajuda você a criar:

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

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

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

    módulos/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

    Gorjeta

    Observe que este modelo pode tomar o parâmetro allowKeys que, quando false irá desativar o uso de chaves no recurso. Esta configuração é opcional.

  2. Use o modelo modules/role-assignment-template.bicep para descrever uma atribuição de função no Azure:

    módulos/função-atribuição-modelo.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

Na consola, siga estes passos:

  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. Certifique-se de que tem a subscrição 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 no seu código

Depois de configurar o Microsoft Entra ID em seu recurso, você precisa 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 pip:

pip install azure-ai-inference>=1.0.0b5

Aviso

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

Em seguida, você pode usar o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente para consumir finalizações de bate-papo 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 TokenCredential classe e é conhecido como uma credencial. No tempo de execução, 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 em sua estação de trabalho de desenvolvimento local, ele procura nas variáveis de ambiente uma entidade de serviço de aplicativo ou em ferramentas de desenvolvedor instaladas localmente, como o Visual Studio, para um conjunto de credenciais de desenvolvedor. Qualquer uma das abordagens 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 em outros serviços automaticamente.

Melhores práticas

  • Use credenciais determinísticas em ambientes de produção: considere fortemente a mudança de DefaultAzureCredential uma das seguintes soluções determinísticas em ambientes de produção:

    • Uma implementação específica TokenCredential , como ManagedIdentityCredential. Consulte a lista Derivados para obter opções.
    • Uma implementação reduzida ChainedTokenCredential 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 credenciais aceitáveis, como ManagedIdentity para produção e VisualStudioCredential desenvolvimento.

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

Desativar a autenticação baseada em chave no recurso

A desativação da autenticação baseada em chave é aconselhável quando você implementou o Microsoft Entra ID e resolveu totalmente as preocupações de compatibilidade ou fallback em todos os aplicativos que consomem o serviço. Você pode alcançá-lo alterando a propriedade disableLocalAuth:

módulos/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óximos passos