在不使用金鑰的情況下使用 Azure OpenAI (部分機器翻譯)

發行項
11/14/2024

對大部分 Azure 服務的應用程式要求都必須使用金鑰或無密碼連線進行驗證。開發人員必須盡可能避免在不安全的地方公開金鑰。能夠取得金鑰存取權的任何人都可以進行服務驗證。無金鑰驗證可透過帳戶金鑰提供改良的管理和安全性優勢，因為沒有要儲存的金鑰 (或連接字串)。

使用下列步驟啟用無金鑰連線：

設定您的驗證。
視需要設定環境變數。
使用 Azure 身分識別連結庫認證類型來建立 Azure OpenAI 客戶端物件。

驗證

若要使用 Azure 用戶端連結庫，必須驗證Microsoft Entra ID。

驗證會根據應用程式執行所在的環境而有所不同：

本機開發
Azure

Azure OpenAI 無密鑰建置組塊

使用下列連結來探索 Azure OpenAI 無密鑰建置組塊 AI 範本。此範本會使用您的使用者帳戶 RBAC 角色許可權來佈建 Azure OpenAI 帳戶，以進行無密鑰（Microsoft Entra）驗證，以存取 OpenAI API SDK。

注意

本文使用一或多個 AI 應用程式範本作為本文範例和指引的基礎。 AI 應用程式範本提供您妥善維護且易於部署的參考實作，以協助確保 AI 應用程式的高品質起點。

探索 .NET 端對端 Azure OpenAI 無密鑰驗證建置組塊 AI 樣本。

驗證本機開發

選取在本機開發期間進行驗證的工具。

針對 Azure 裝載的環境進行驗證

瞭解如何管理部署至 Azure 之應用程式的 DefaultAzureCredential 。

設定授權的角色

尋找 Azure OpenAI 使用方式的角色。視您想要如何設定該角色而定，您需要名稱或識別碼。

角色名稱角色 ID

針對 Azure CLI 或 Azure PowerShell，您可以使用角色名稱。針對 Bicep，您需要角色識別碼。

角色名稱	角色 ID
針對 Azure CLI 或 Azure PowerShell，您可以使用角色名稱。	針對 Bicep，您需要角色識別碼。

使用下表來選取角色和標識碼。

使用案例	角色名稱	角色 ID
助理	`Cognitive Services OpenAI Contributor`	`a001fd3d-188f-4b5d-821b-7da978bf7442`
聊天完成	`Cognitive Services OpenAI User`	`5e0bd9bd-7b93-4f28-af87-19fc36ad61bd`

選取要使用的識別類型。
- 個人身分識別：這是系結至您登入 Azure 的個人身分識別。
- 受控識別：這是由管理並建立的身分識別，以供在 Azure 上使用。針對受控識別，建立使用者指派的受控識別。當您建立受控識別時，您需要 Client ID，也稱為 app ID。
若要尋找您的個人身分識別，請使用下列其中一個命令。使用識別碼作為 <identity-id> 下一個步驟中的。
若要進行本機開發，若要取得您自己的身分識別識別碼，請使用下列命令。使用此命令之前，您必須使用登入 az login 。
```
az ad signed-in-user show \
    --query id -o tsv
```
若要進行本機開發，若要取得您自己的身分識別識別碼，請使用下列命令。使用此命令之前，您必須使用登入 Connect-AzAccount 。
```
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
```
使用與 Azure 開發人員 CLI 一起部署的 Bicep 時，執行部署的人員或服務的身分識別會設定為 principalId 參數。

下列 main.parameters.json 變數會設定為執行進程的身分識別。
```
"principalId": {
    "value": "${AZURE_PRINCIPAL_ID}"
  },
```
若要在 Azure 中使用，請在 Bicep 部署程式中指定使用者指派的受控識別。建立使用者指派的受控識別，與執行進程的身分識別分開。
```
resource userAssignedManagedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
  name: managedIdentityName
  location: location
}
```
使用在此處找到的步驟：在 Azure 入口網站中尋找使用者物件識別碼。

將角色型存取控制 (RBAC) 角色指派給資源群組的身分識別。

若要透過 RBAC 將身分識別許可權授與資源，請使用 Azure CLI 命令 az role assignment create 來指派角色。

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

若要透過 RBAC 將應用程式許可權授與 Azure OpenAI 資源，請使用 Azure PowerShell Cmdlet New-AzRoleAssignment 指派角色。

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

使用下列 Azure OpenAI Bicep 範本來建立資源，並設定的 identityId驗證。 Bicep 需要角色識別碼。此 Bicep 片段中顯示的 name 不是 Azure 角色；而是特定於 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'
    }
}

從呼叫 main.bicep 下列泛型 Bicep 以建立任何角色。

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

如果適用，請將 <identity-id>、<subscription-id> 和 <resource-group-name> 取代為您的實際值。

設定環境變數

若要連線到 Azure OpenAI，您的程式代碼必須知道您的資源端點，而且 可能需要 其他環境變數。

為您的 Azure OpenAI 端點建立環境變數。
- AZURE_OPENAI_ENDPOINT：此 URL 是您 Azure OpenAI 資源的存取點。

根據應用程式執行的位置建立環境變數：

Location	身分識別	描述
本機	個人版	針對具有個人身分識別的本機運行時間，請使用工具登入以建立您的認證。
Azure 雲端	使用者指派的受控識別	建立 `AZURE_CLIENT_ID` 環境變數，其中包含使用者指派受控識別的用戶端標識符，以驗證身分。

安裝 Azure 身分識別用戶端程式庫

使用下列連結來安裝 Azure 身分識別客戶端連結庫。

安裝 .NET Azure Identity 用戶端連結庫：

dotnet add package Azure.Identity

安裝 Go Azure 身分識別用戶端連結庫：

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

使用下列 POM 檔案安裝 Java Azure 身分識別用戶端連結庫：

<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 Azure 身分識別用戶端連結庫：

npm install --save @azure/identity

安裝 Python Azure 身分識別用戶端連結庫：

pip install azure-identity

使用 DefaultAzureCredential

Azure 身分識別連結庫 DefaultAzureCredential 可讓客戶在本機開發環境和 Azure 雲端中執行相同的程式代碼。

如需 .NET 的 DefaultAzureCredential 詳細資訊，請參閱適用於 .NET 的 Azure 身分識別用戶端程式庫。

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

如需 Go 的詳細資訊 DefaultAzureCredential ，請參閱適用於 Go 的 Azure 身分識別客戶端連結庫。

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 的 DefaultAzureCredential 詳細資訊，請參閱適用於 Java 的 Azure 身分識別用戶端程式庫。

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

如需 JavaScript 的 DefaultAzureCredential 詳細資訊，請參閱適用於 JavaScript 的 Azure 身分識別用戶端程式庫。

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

如需 Python 的 DefaultAzureCredential 詳細資訊，請參閱適用於 Python 的 Azure 身分識別用戶端程式庫。

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
)

資源

無密碼連線開發人員指南

共用方式為