Usar o OpenAI do Azure sem chaves

Artigo
11/14/2024

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.

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.

Autenticar para o desenvolvimento local

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

Autenticar para ambientes hospedados no Azure

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

Configurar funções para autorização

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.

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.

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`

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.
Para encontrar sua identidade pessoal, use um dos seguintes comandos. Use o ID como o <identity-id> na próxima etapa.
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
```
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]
```
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
}
```
Use as etapas encontradas aqui: encontre a ID de objeto do usuário no portal do Azure.

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

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>"

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>"

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)
    }
}

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 Azure OpenAI, seu código precisa conhecer o ponto de extremidade do recurso e pode precisar de outras variáveis de ambiente.

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.

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.

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

dotnet add package Azure.Identity

Instale a Biblioteca de clientes GO da Identidade do Azure:

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

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>

Instale a Biblioteca de cliente JavaScript de identidade do Azure:

npm install --save @azure/identity

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.

Para obter mais informações sobre a DefaultAzureCredential para .NET, confira a biblioteca de clientes da Identidade do Azure para .NET.

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());

Para mais informações sobre DefaultAzureCredential para Go, consulte Biblioteca de clientes da Identidade do Azure para Go.

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
}

Para obter mais informações sobre a DefaultAzureCredential para Java, confira biblioteca de clientes da Identidade do Azure para Java.

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();

Para obter mais informações sobre a DefaultAzureCredential para JavaScript, confira a biblioteca de clientes da Identidade do Azure para JavaScript.

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);

Para obter mais informações sobre a DefaultAzureCredential para Python, confira a biblioteca de clientes da Identidade do Azure para Python.

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
)

Recursos

Guia do desenvolvedor de conexões sem senha

Compartilhar via