Usar o OpenAI do Azure sem chaves

As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autenticadas com chaves ou conexões sem senha. Os desenvolvedores devem ser diligentes para nunca expor as chaves em um local não seguro. Qualquer pessoa que obtenha acesso à chave será capaz de se autenticar no serviço. A autenticação sem chave oferece vantagens de segurança e gerenciamento aprimorados com relação à chave de conta porque não há nenhuma chave (nem cadeia de conexão) para armazenar.

As conexões sem chave estão habilitadas com as seguintes etapas:

• Configure sua autenticação.
• Defina as variáveis de ambiente, conforme necessário.
• Use um tipo de credencial de biblioteca de identidade do Azure para criar um objeto de cliente OpenAI do Azure.

Autenticação

A autenticação na ID do Microsoft Entra é necessária para usar as bibliotecas de cliente do Azure.

A autenticação difere com base no ambiente em que o aplicativo está sendo executado:

• Desenvolvimento local
• Azure

Bloco de construção sem chave do OpenAI do Azure

Use o link a seguir para explorar o modelo de IA do Building Block Keyless do OpenAI do Azure. Este modelo provisiona uma conta OpenAI do Azure com sua permissão de função RBAC de conta de usuário para autenticação sem chave (Microsoft Entra) para acessar os SDKs da API OpenAI.

Observação

Este artigo usa um ou mais modelos de aplicativo de IA como base para os exemplos e as diretrizes no artigo. Os modelos de aplicativo de IA fornecem implementações de referência regulares e fáceis de implantar que ajudam a garantir um ponto de partida de alta qualidade para os aplicativos de IA.

.NET

Explore o modelo de IA de Bloco de Construção de Autenticação Sem Chave do OpenAI do Azure do .NET de ponta a ponta.

Go

Explore o modelo de IA do Building Block de Autenticação Sem Chave do Azure OpenAI de Ponta a Ponta.

Java

Explore o modelo de IA de Bloco de Construção de Autenticação Sem Chave do Azure OpenAI de Ponta a Ponta do Java.

JavaScript

Explore o modelo de IA de Bloco de Construção de Autenticação Sem Chave do Azure OpenAI de Ponta a Ponta do JavaScript.

Python

Explore o modelo de IA de Bloco de Construção de Autenticação Sem Chave do Azure OpenAI de ponta a ponta do Python.

Autenticar para o desenvolvimento local

.NET

Selecione uma ferramenta para autenticação durante o desenvolvimento local.

Go

Selecione uma ferramenta para autenticação durante o desenvolvimento local.

Java

Selecione uma ferramenta para autenticação durante o desenvolvimento local.

JavaScript

Selecione uma ferramenta para autenticação durante o desenvolvimento local.

Python

Selecione uma ferramenta para autenticação durante o desenvolvimento local.

Autenticar para ambientes hospedados no Azure

.NET

Saiba mais sobre como gerenciar o DefaultAzureCredential para aplicativos implantados no Azure.

Go

Saiba mais sobre como gerenciar o DefaultAzureCredential para aplicativos implantados no Azure.

Java

Saiba mais sobre como gerenciar o DefaultAzureCredential para aplicativos implantados no Azure.

JavaScript

Saiba mais sobre como gerenciar o DefaultAzureCredential para aplicativos implantados no Azure.

Python

Saiba mais sobre como gerenciar o DefaultAzureCredential para aplicativos implantados no Azure.

Configurar funções para autorização

1. Localize a função para o uso do Azure OpenAI. Dependendo de como você pretende definir essa função, você precisa do nome ou da ID.

   Nome da função	ID de Função
   Para a CLI do Azure ou o Azure PowerShell, você pode usar o nome da função.	Para o Bicep, você precisa da ID da função.

2. Use a tabela a seguir para selecionar uma função e um ID.

   Caso de uso	Nome da função	ID de Função
   Assistentes	Cognitive Services OpenAI Contributor	a001fd3d-188f-4b5d-821b-7da978bf7442
   Preenchimentos de chat	Cognitive Services OpenAI User	5e0bd9bd-7b93-4f28-af87-19fc36ad61bd

3. Selecione um tipo identidade para utilizar.

   • Identidade pessoal: essa é sua identidade pessoal vinculada à sua entrada no Azure.
   • Identidade gerenciada: essa é uma identidade gerenciada e criada para uso no Azure. Para identidade gerenciada, crie uma identidade gerenciada atribuída pelo usuário. Ao criar a identidade gerenciada, você precisa do Client ID, também conhecido como app ID.

4. Para encontrar sua identidade pessoal, use um dos seguintes comandos. Use o ID como o <identity-id> na próxima etapa.

   CLI do Azure

   Para desenvolvimento local, para obter sua própria ID de identidade, use o comando a seguir. Você precisa entrar com az login antes de usar este comando.

   az ad signed-in-user show \
       --query id -o tsv
   

   PowerShell do Azure

   Para desenvolvimento local, para obter sua própria ID de identidade, use o comando a seguir. Você precisa entrar com Connect-AzAccount antes de usar este comando.

   (Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
   

   Bicep

   Ao usar o Bicep implantado com a CLI do Desenvolvedor do Azure, a identidade da pessoa ou do serviço que executa a implantação é definida como o parâmetro principalId.

   A variável a seguir main.parameters.json é definida como a identidade que executa o processo.

   "principalId": {
       "value": "${AZURE_PRINCIPAL_ID}"
     },
   

   Para uso no Azure, especifique uma identidade gerenciada atribuída pelo usuário como parte do processo de implantação do Bicep. Crie uma identidade gerenciada atribuída pelo usuário separada da identidade que executa o processo.

   resource userAssignedManagedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
     name: managedIdentityName
     location: location
   }
   

   Portal do Azure

   Use as etapas encontradas aqui: encontre a ID de objeto do usuário no portal do Azure.

5. Atribua a função de controle de acesso baseado em função (RBAC) à identidade para o grupo de recursos.

   CLI do Azure

   Para conceder suas permissões de identidade ao recurso por meio do RBAC, atribua uma função usando o comando da CLI do Azure az role assignment create.

   az role assignment create \
       --role "Cognitive Services OpenAI User" \
       --assignee "<identity-id>" \
       --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
   

   PowerShell do Azure

   Para conceder permissões de aplicativo ao recurso OpenAI do Azure por meio do RBAC, atribua uma função usando o cmdlet New-AzRoleAssignment do Azure PowerShell.

   New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "Cognitive Services OpenAI User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
   

   Bicep

   Use o seguinte modelo do OpenAI Bicep do Azure para criar o recurso e definir a autenticação para o identityId. O Bicep requer a ID da função. O name mostrado nesse snippet do Bicep não é a função do Azure; é específico para a implantação do Bicep.

   // main.bicep
   param environment string = 'production'
   
   // USER ROLES
   module openAiRoleUser 'core/security/role.bicep' = {
       scope: openAiResourceGroup
       name: 'openai-role-user'
       params: {
           principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity 
           principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
           roleDefinitionId: '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd'
       }
   }
   

   O Bicep genérico a seguir é chamado do main.bicep para criar qualquer função.

   // core/security/role.bicep
   metadata description = 'Creates a role assignment for an identity.'
   param principalId string // passed in from main.bicep identityId
   
   @allowed([
       'Device'
       'ForeignGroup'
       'Group'
       'ServicePrincipal'
       'User'
   ])
   param principalType string = 'ServicePrincipal'
   param roleDefinitionId string
   
   resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
       name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
       properties: {
           principalId: principalId
           principalType: principalType
           roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
       }
   }
   

   Portal do Azure

   Use as etapas encontradas em abrir a página Adicionar atribuição de função no portal do Azure.

   Quando aplicável, substitua <identity-id>, <subscription-id> e <resource-group-name> por seus valores reais.

Configurar variáveis de ambiente

Para se conectar ao OpenAI do Azure, seu código precisa conhecer o ponto de extremidade do recurso e pode precisar de outras variáveis de ambiente.

1. Crie uma variável de ambiente para o ponto de extremidade OpenAI do Azure.

   • AZURE_OPENAI_ENDPOINT: essa URL é o ponto de acesso para o recurso OpenAI do Azure.

2. Crie variáveis de ambiente com base no local em que seu aplicativo é executado:

   Location	Identidade	Descrição
   Local	Pessoal	Para tempos de execução locais com sua identidade pessoal, faça login para criar sua credencial com uma ferramenta.
   Nuvem do Azure	Identidade gerenciada atribuída pelo usuário	Crie uma variável de ambiente AZURE_CLIENT_ID contendo o ID do cliente da identidade gerenciada atribuída pelo usuário para autenticar como.

Instalar a biblioteca de clientes da Identidade do Azure

Use o link a seguir para instalar a biblioteca de clientes do Azure Identity.

.NET

Instale a Biblioteca de clientes .NET da Identidade do Azure:

dotnet add package Azure.Identity

Go

Instale a Biblioteca de clientes GO da Identidade do Azure:

go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity

Java

Instale a biblioteca do cliente Java de identidade do Azure com o seguinte arquivo POM:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript

Instale a Biblioteca de cliente JavaScript de identidade do Azure:

npm install --save @azure/identity

Python

Instale a Biblioteca de clientes Python da Identidade do Azure:

pip install azure-identity

Use DefaultAzureCredential

A biblioteca de Identidades do Azure DefaultAzureCredential permite que o cliente execute o mesmo código no ambiente de desenvolvimento local e na Nuvem do Azure.

.NET

Para obter mais informações sobre DefaultAzureCredential para .NET, consulte a visão geral DefaultAzureCredential.

Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:

• Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usará o valor dessa variável de ambiente, se presente.

  using Azure;
  using Azure.AI.OpenAI;
  using Azure.Identity;
  using System;
  using static System.Environment;
  
  string endpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
  
  OpenAIClient client = new(new Uri(endpoint), new DefaultAzureCredential());
  

• Defina a propriedade ManagedIdentityClientId no DefaultAzureCredentialOptions:

  using Azure;
  using Azure.AI.OpenAI;
  using Azure.Identity;
  using System;
  using static System.Environment;
  
  string endpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
  
  var credential = new DefaultAzureCredential(
      new DefaultAzureCredentialOptions
      {
          ManagedIdentityClientId = "<user_assigned_client_id>"
      });
  
  OpenAIClient client = new(new Uri(endpoint), credential);
  

Go

Para obter mais informações sobre DefaultAzureCredential para Go, consulte a visão geral DefaultAzureCredential.

import (
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

func main() {
	dac, err := azidentity.NewDefaultAzureCredential(nil)

	if err != nil {
		log.Fatalf("ERROR: %s", err)
	}

	client, err := azopenai.NewClient(os.Getenv("AZURE_OPENAI_ENDPOINT"), dac, nil)

	if err != nil {
		log.Fatalf("ERROR: %s", err)
	}

	_ = client
}

Java

Para obter mais informações sobre DefaultAzureCredential para Java, consulte a visão geral DefaultAzureCredential.

Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:

• Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usará o valor dessa variável de ambiente, se presente.

  import com.azure.identity.DefaultAzureCredentialBuilder;
  import com.azure.ai.openai.OpenAIClient;
  import com.azure.ai.openai.OpenAIClientBuilder;
  
  String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
  
  DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
  OpenAIClient client = new OpenAIClientBuilder()
      .credential(credential)
      .endpoint(endpoint)
      .buildClient();
  

• Atribua uma identidade gerenciada específica atribuída pelo usuário com DefaultAzureCredential usando o DefaultAzureCredentialBuilder para configurá-la com uma ID do cliente:

  import com.azure.identity.DefaultAzureCredentialBuilder;
  import com.azure.ai.openai.OpenAIClient;
  import com.azure.ai.openai.OpenAIClientBuilder;
  
  String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
  String userAssignedClientId = "<your managed identity client ID>";
  
  TokenCredential dacWithUserAssignedManagedIdentity
       = new DefaultAzureCredentialBuilder().managedIdentityClientId(userAssignedClientId).build();
  OpenAIClient client = new OpenAIClientBuilder()
      .credential(dacWithUserAssignedManagedIdentity)
      .endpoint(endpoint)
      .buildClient();
  

JavaScript

Para obter mais informações sobre DefaultAzureCredential para JavaScript, consulte a visão geral DefaultAzureCredential.

Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:

• Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usará o valor dessa variável de ambiente, se presente.

  import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
  import { AzureOpenAI } from "openai";
  
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  
  const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
  const deployment = "<your Azure OpenAI deployment name>";
  const apiVersion = "2024-05-01-preview";
  const options = { azureADTokenProvider, deployment, apiVersion, endpoint }
  
  const client = new AzureOpenAI(options);
  

• Atribua uma identidade gerenciada específica atribuída pelo usuário com DefaultAzureCredential usando o parâmetro managedIdentityClientId para configurá-la com uma ID do cliente:

  import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
  import { AzureOpenAI } from "openai";
  
  const managedIdentityClientId = "<your managed identity client ID>";
  
  const credential = new DefaultAzureCredential({
        managedIdentityClientId: managedIdentityClientId,
      });
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  
  const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
  const deployment = "<your Azure OpenAI deployment name>";
  const apiVersion = "2024-05-01-preview";
  const options = { azureADTokenProvider, deployment, apiVersion, endpoint }
  
  const client = new AzureOpenAI(options);
  

Python

Para obter mais informações sobre DefaultAzureCredential para Python, consulte a visão geral DefaultAzureCredential.

Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:

• Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usará o valor dessa variável de ambiente, se presente.

  import openai
  from azure.identity import DefaultAzureCredential, get_bearer_token_provider
  
  token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")
  
  openai_client = openai.AzureOpenAI(
      api_version=os.getenv("AZURE_OPENAI_VERSION"),
      azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
      azure_ad_token_provider=token_provider
  )
  

• Atribua uma identidade gerenciada específica atribuída pelo usuário com DefaultAzureCredential usando o parâmetro managed_identity_client_id para configurá-la com uma ID do cliente:

  import openai
  from azure.identity import DefaultAzureCredential, get_bearer_token_provider
  
  user_assigned_client_id = "<your managed identity client ID>"
  
  credential = DefaultAzureCredential(
   managed_identity_client_id=user_assigned_client_id
  )
  
  token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")
  
  openai_client = openai.AzureOpenAI(
      api_version=os.getenv("AZURE_OPENAI_VERSION"),
      azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
      azure_ad_token_provider=token_provider
  )
  
  

Recursos

• Guia do desenvolvedor de conexões sem senha