Como configurar Azure OpenAI em modelos de Microsoft foundry com autenticação de Microsoft Entra ID (clássico)

Aplica-se somente a:Portal Foundry (clássico). Este artigo não está disponível para o novo portal do Foundry. Saiba mais sobre o novo portal.

Microsoft Entra ID permite que você chame seu recurso Azure OpenAI sem armazenar uma chave de API em seu aplicativo. Em vez de uma chave, seu código solicita um token de acesso de curta duração para uma identidade que você concede uma função no recurso. Este artigo mostra como autenticar duas maneiras: como você mesmo durante o desenvolvimento local e como uma identidade gerenciada quando seu aplicativo é executado em Azure.

Entra ID autenticação em comparação com identidades gerenciadas

Esses dois termos geralmente são usados de forma intercambiável, mas descrevem coisas diferentes.

Microsoft Entra ID é a plataforma de identidade. Cada chamada baseada em token para Azure OpenAI passa por ela, independentemente de qual identidade você usa.

Uma identidade gerenciada é um tipo de identidade do Entra. Azure o cria, atribui-o a um recurso Azure, como uma máquina virtual ou aplicativo Web, e gira suas credenciais para você. Não há segredo para você armazenar ou girar.

A identidade com a qual você se autentica depende de onde seu código é executado:

Use uma identidade gerenciada atribuída pelo sistema quando um único recurso precisar de acesso. Use uma identidade gerenciada atribuída pelo usuário quando vários recursos precisarem do mesmo acesso ou quando você quiser conceder a função antes de criar o recurso que a usa.

Você não precisa escrever código diferente para cada um deles. A DefaultAzureCredential classe na biblioteca Azure Identity tenta uma cadeia de credenciais em ordem e usa a primeira que encontra. No seu laptop, ele pega sua az login sessão. Em um host Azure, ele pega a identidade gerenciada. É por isso que o mesmo exemplo funciona em ambos os lugares e é por isso que este artigo aborda ambos.

Pré-requisitos

• Uma assinatura Azure – Criar uma gratuitamente

• Um recurso Azure OpenAI com um nome de subdomínio personalizado. Você precisa de um subdomínio personalizado para autenticação Microsoft Entra ID.

• Um modelo implantado em seu recurso.

• CLI do Azure – guia Instalação

• Python 3.8 ou posterior, com os seguintes pacotes instalados:

  pip install openai azure-identity
  

Atribuir uma função

As atribuições de função controlam quem pode chamar seu recurso. Atribua a si mesmo a função de Colaborador openai dos Serviços Cognitivos openai ou usuário do Serviços Cognitivos no recurso Azure OpenAI. Qualquer função permite que você faça chamadas de API de inferência com sua própria identidade em vez de uma chave.

Atribua a mesma função à identidade gerenciada do aplicativo mais tarde, quando você implantar no Azure.

Autenticar em seu computador de desenvolvimento

No computador local, DefaultAzureCredential usa a sessão CLI do Azure. Entre primeiro. Talvez seja necessário entrar novamente se a sessão ficar ociosa por muito tempo.

az login

Se você pertencer a mais de um locatário, entre no locatário que contém seu recurso Azure OpenAI:

az login --tenant YOUR-TENANT-ID

Agora chame seu modelo. Esse exemplo solicita um token e envia uma solicitação de conclusão de chat.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

response = client.chat.completions.create(
    model="gpt-4o",  # Use your deployment name, which might differ from the model name.
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},
        {"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},
        {"role": "user", "content": "Do other Azure services support this too?"}
    ]
)

print(response.choices[0].message.content)

Por que o exemplo passa um token para api_key

O api_key parâmetro parece fora de lugar em um exemplo sem chave e é o ponto mais comum de confusão nesse fluxo de trabalho. Aqui está o que está acontecendo.

O api_key parâmetro aceita uma cadeia de caracteres ou uma chamada. Quando você passa o token_provider callable, o cliente o invoca antes de cada solicitação para obter um token de acesso Microsoft Entra atual e envia esse token como um token de portador no Authorization cabeçalho. Nenhuma chave de API é criada, armazenada ou transmitida. O parâmetro mantém o nome api_key para compatibilidade com a biblioteca de clientes OpenAI, que usa um parâmetro para ambos os estilos de autenticação.

A get_bearer_token_provider função manipula o cache de token e a atualização para você, portanto, você não precisa acompanhar a expiração do token por conta própria.

Verificar seu acesso

Para confirmar se a atribuição de função funciona antes de executar qualquer código, solicite um token e chame a API diretamente. Esse método também fornece a maneira mais clara de ver o Authorization cabeçalho que a biblioteca de clientes define para você.

TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken --output tsv)

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Autenticar de um aplicativo hospedado Azure usando uma identidade gerenciada

Quando o código for executado em uma máquina virtual Azure, aplicativo Web, aplicativo de funções, aplicativo de contêiner ou conjunto de dimensionamento de máquinas virtuais, use uma identidade gerenciada em vez de sua conta de desenvolvedor. Seu aplicativo nunca armazena uma credencial e Azure gira a identidade para você.

Habilitar e atribuir a identidade

1. Habilite uma identidade gerenciada no recurso Azure que hospeda seu aplicativo. Para uma máquina virtual, consulte o início rápido da ferramenta preferida: Azure portal, Azure PowerShell, CLI do Azure, modelo de Azure Resource Manager ou bibliotecas de cliente Azure Resource Manager.

2. Atribua a identidade gerenciada à função de Usuário OpenAI dos Serviços Cognitivos em seu recurso Azure OpenAI, da mesma forma que você fez para sua própria conta em Atribuir uma função.

Usar uma identidade gerenciada atribuída pelo sistema

Se o host tiver apenas uma identidade gerenciada atribuída pelo sistema, o exemplo de Autenticação do computador de desenvolvimento funcionará sem alterações. DefaultAzureCredentiallocaliza a identidade gerenciada automaticamente quando ela é executada em Azure.

Usar uma identidade gerenciada atribuída pelo usuário

Um host pode ter várias identidades atribuídas a ele, portanto, você precisa dizer qual delas usar. Passe a ID do cliente da identidade gerenciada atribuída pelo usuário:

from openai import OpenAI
from azure.identity import ManagedIdentityCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    ManagedIdentityCredential(client_id="YOUR-USER-ASSIGNED-CLIENT-ID"),
    "https://ai.azure.com/.default",
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

Para continuar usando DefaultAzureCredential para que o mesmo código ainda seja executado localmente, defina a AZURE_CLIENT_ID variável de ambiente no host Azure para a ID do cliente da identidade gerenciada atribuída pelo usuário. DefaultAzureCredential lê essa variável e seleciona a identidade correspondente.

Para obter mais informações, consulte Identidades gerenciadas para recursos do Azure.

Chamar a API do painel de controle

Os exemplos anteriores chamam o plano de dados, que é onde você executa a inferência. As operações de gerenciamento, como listar os modelos disponíveis em uma região, usam o plano de controle. O plano de controle é uma API diferente com um público-alvo de token diferente: https://management.azure.com/.default em vez de https://ai.azure.com/.default. Um token emitido para um público não funciona com o outro.

import requests
import json
from azure.identity import DefaultAzureCredential

region = "eastus"
token_credential = DefaultAzureCredential()
subscriptionId = "{YOUR-SUBSCRIPTION-ID}" 

token = token_credential.get_token('https://management.azure.com/.default')
headers = {'Authorization': 'Bearer ' + token.token}

url = f"https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{region}/models?api-version=2023-05-01"

response = requests.get(url, headers=headers)

data = json.loads(response.text)

print(json.dumps(data, indent=4))

As chamadas do plano de controle precisam de uma função que conceda permissões de gerenciamento, como Colaborador dos Serviços Cognitivos. As funções de inferência em Atribuir uma função não concedem acesso ao plano de controle.

Solucionar erros de autenticação

Conteúdo relacionado

• Controle de acesso baseado em função para o Azure OpenAI
• Nomes de subdomínio personalizados para Serviços de IA do Azure
• Identidades gerenciadas para os recursos do Azure
• DefaultAzureCredential na biblioteca Azure Identity para Python