使用 Microsoft Entra 識別碼設定無密鑰驗證

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

部署至 Azure AI 模型推斷的 Azure AI 服務模型支援使用 Microsoft Entra ID 的無密鑰授權。無密鑰授權可增強安全性、簡化用戶體驗、降低作業複雜度，併為新式開發提供強固的合規性支援。它讓組織採用安全且可調整的身分識別管理解決方案，是一個強有力的選擇。

本文說明如何在 Azure AI 模型推斷中設定Microsoft Entra ID 以進行推斷。

瞭解 Azure 中資源內容中的角色

Microsoft Entra ID 會使用角色型存取控制（RBAC）的概念進行授權。角色是管理雲端資源存取權的核心。角色基本上是許可權集合，可定義可在特定 Azure 資源上執行的動作。藉由將角色指派給使用者、群組、服務主體或受控識別，統稱為安全性主體，即可控制其在 Azure 環境中對特定資源的存取。

當您指派角色時，您可以指定安全性主體、角色定義和範圍。這種組合稱為角色指派。 Azure AI 模型推斷是 Azure AI 服務資源的一項功能，因此指派給該特定資源的角色會控制推斷的存取權。

您可以識別不同類型的資源存取：

系統管理存取：與資源管理相關的動作。它們通常會變更資源的狀態及其組態。在 Azure 中，這些作業是控制平面作業，而且可以使用 Azure 入口網站、Azure CLI 或基礎結構即程式代碼來執行。的範例包括建立新的模型部署、變更內容篩選組態、變更所提供的模型版本，或變更部署的SKU。
開發人員存取：與資源耗用量相關的動作。例如，叫用聊天完成 API。不過，用戶無法變更資源的狀態及其組態。

在 Azure 中，系統管理作業一律會使用 Microsoft Entra ID 來執行。認知服務參與者等角色可讓您執行這些作業。另一方面，開發人員作業可以使用存取密鑰或/和Microsoft Entra 標識符來執行。認知服務使用者等角色可讓您執行這些作業。

重要

擁有資源的系統管理存取權不一定授與開發人員存取權。仍然需要授與角色的明確存取權。這類似於資料庫伺服器的運作方式。擁有資料庫伺服器的系統管理員存取權並不表示您可以在資料庫內讀取數據。

請遵循下列步驟，在 Azure AI 服務資源中設定 Azure AI 模型推斷的開發人員存取權。

必要條件

若要完成本文，您需要：

Azure 訂用帳戶。如果您使用 GitHub 模型，您可以升級您的體驗，並在程式中建立 Azure 訂用帳戶。如果是您的情況，請閱讀從 GitHub 模型升級至 Azure AI 模型推斷。
Azure AI 服務資源。如需詳細資訊，請參閱建立 Azure AI 服務資源。
具有 Microsoft.Authorization/roleAssignments/write 和許可權的帳戶，例如系統管理員Microsoft.Authorization/roleAssignments/delete角色型訪問控制。
若要指派角色，您必須指定三個元素：
- 安全性主體：例如您的用戶帳戶。
- 角色定義： 認知服務使用者 角色。
- 範圍：Azure AI 服務資源。

設定Microsoft輸入標識碼以進行推斷

請遵循下列步驟來設定Microsoft Entra ID 以進行推斷：

移至 Azure 入口網站，並找出您正在使用的 Azure AI 服務資源。如果您使用 Azure AI Foundry 搭配專案或中樞，您可以流覽至它：：
1. 移至 Azure AI Foundry 入口網站。
2. 在登陸頁面上，選取 [ 開啟管理中心]。
3. 移至 [已連線的資源] 區段，然後選取您要設定的 Azure AI 服務資源連線。如果未列出，請選取 [全部 檢視] 以查看完整清單。
4. 在 [連線詳細數據] 區段的 [資源] 底下，選取 Azure 資源的名稱。新的頁面會開啟。
5. 您現在位於 Azure 入口網站，您可以在其中管理資源本身的所有層面。
在左側導覽列上，選取 [訪問控制][IAM]。

提示

使用 [ 檢視我的存取權] 選項來確認哪些角色已指派給您。
選取 [角色指派]，然後選取 [新增>角色指派]。
在 [作業函式角色] 上，輸入認知服務使用者。 角色清單已篩選掉。
選取角色，然後選取 [ 下一步]。
在 [成員] 上，選取您想要授與存取權的使用者或群組。建議您盡可能使用安全組，因為它們更容易管理和維護。
選取 [ 下一步 ] 並完成精靈。
選取的用戶現在可以使用Microsoft Entra ID 進行推斷。

提示

請記住，Azure 角色指派最多可能需要五分鐘的時間傳播。使用安全組時，從安全組新增或移除使用者會立即傳播。

請注意，對於已經有金鑰可供使用的使用者，仍然可以使用金鑰型存取。如果您要撤銷金鑰，請在 Azure 入口網站的左側導覽中，選取 [資源管理>金鑰] 和 [端點>重新產生金鑰1] 和 [重新產生密鑰2]。

在您的程式代碼中使用Microsoft Entra識別符

在資源中設定Microsoft Entra ID 之後，您必須更新程序代碼，以在取用推斷端點時使用它。下列範例示範如何使用聊天完成模型：

使用套件管理員安裝套件 azure-ai-inference，例如 pip：

pip install azure-ai-inference>=1.0.0b5

警告

Azure AI Services 資源需要適用於 Python 的版本 azure-ai-inference>=1.0.0b5 。

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 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",
)

從 npm 安裝套件 @azure-rest/ai-inference：

npm install @azure-rest/ai-inference

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 Entra ID 取用聊天完成：

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    "mistral-large-2407",
    clientOptions,
);

使用下列命令來安裝 Azure AI 推斷程式庫：

dotnet add package Azure.AI.Inference --prerelease

安裝 Azure.Identity 套件：

dotnet add package Azure.Identity

匯入下列命名空間：

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 Entra ID 取用聊天完成：

var credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    "mistral-large-2407",
    clientOptions.
);

將套件新增至您的專案：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

然後，您可以使用套件來取用模型。下列範例會示範如何建立用戶端以取用聊天完成：

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .model("mistral-large-2407")
    .buildClient();

探索我們的範例，並閱讀 API 參考文件以開始使用。

使用參考區段來探索 API 設計，以及哪些參數可供使用，並指出標頭 Authorization中的驗證令牌。例如，聊天完成的參考區段會詳細說明如何使用路由/chat/completions，根據聊天格式的指示產生預測。請注意，URL 的根目錄包含路徑 /models ：

要求

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

權杖必須發行範圍 https://cognitiveservices.azure.com/.default。

為了進行測試，取得用戶帳戶有效令牌最簡單的方式是使用 Azure CLI。在主控台中，執行下列 Azure CLI 命令：

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

使用 Microsoft Entra ID 時認證的選項

DefaultAzureCredential 是一種有意見、已排序的機制序列，用於驗證至Microsoft Entra ID。每個驗證機制都是衍生自類別的 TokenCredential 類別，稱為認證。在執行階段中，DefaultAzureCredential 會嘗試使用第一個認證進行驗證。如果該認證無法取得存取權杖，則會嘗試序列中的下一個認證，以此類推，直到成功取得存取權杖為止。因此，您的應用程式可以在相異環境中使用不同的認證，而不需要撰寫環境特定程式碼。

當上述程式碼在本機開發工作站上執行時，它會在環境變數中尋找應用程式服務主體，或在本機安裝的開發工具 (例如 Visual Studio) 中尋找一組開發人員認證。在本機開發期間，您可以使用任一方法向 Azure 資源驗證應用程式。

部署至 Azure 時，同一組程式碼也可向其他 Azure 資源驗證您的應用程式。 DefaultAzureCredential 可擷取環境設定與受控識別設定，以便自動向其他服務進行驗證。

最佳作法

在生產環境中使用具決定性認證：強烈建議您從 DefaultAzureCredential 移至下列生產環境具決定性的解決方案之一：
- 特定的 TokenCredential 實作，例如 ManagedIdentityCredential。如需選項，請參閱衍生清單。
- 針對您執行應用程式的 Azure 環境最佳化的簡化 ChainedTokenCredential 實作。 ChainedTokenCredential 基本上會建立可接受認證選項的特定允許清單，例如 ManagedIdentity 用於生產環境及 VisualStudioCredential 開發。
將系統指派或使用者指派的受控識別設定為可能執行程序代碼的 Azure 資源。設定Microsoft Entra ID 存取這些特定身分識別。

在您的專案中使用Microsoft Entra識別符

即使您的資源已設定Microsoft Entra ID，您的專案仍可能使用索引鍵來取用資源的預測。使用 Azure AI Foundry 遊樂場時，會使用與專案連線相關聯的認證。

若要變更此行為，您必須更新專案中的連線，以使用Microsoft Entra 識別碼。執行下列步驟:

移至 Azure AI Foundry 入口網站。
流覽至透過連線使用 Azure AI Services 資源的專案或中樞。
選取 [管理中心]。
移至 [已連線的資源] 區段，然後選取您要設定的 Azure AI 服務資源連線。如果未列出，請選取 [ 全部檢視] 以查看完整清單。
在 [連線詳細數據] 區段的 [存取詳細數據] 旁，選取編輯圖示。
在 [驗證] 下，將值變更為 Microsoft Entra ID。
選取更新。
您的連線已設定為立即使用 Microsoft Entra 識別碼。

停用資源中的金鑰型驗證

當您實作 Microsoft Entra 識別符，並在取用服務的所有應用程式中完全解決相容性或後援考慮時，建議停用密鑰型驗證。

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

部署至 Azure AI 模型推斷的 Azure AI 服務模型支援使用 Microsoft Entra ID 的無密鑰授權。無密鑰授權可增強安全性、簡化用戶體驗、降低作業複雜度，併為新式開發提供強固的合規性支援。它讓組織採用安全且可調整的身分識別管理解決方案，是一個強有力的選擇。

本文說明如何在 Azure AI 模型推斷中設定Microsoft Entra ID 以進行推斷。

瞭解 Azure 中資源內容中的角色

Microsoft Entra ID 會使用角色型存取控制（RBAC）的概念進行授權。角色是管理雲端資源存取權的核心。角色基本上是許可權集合，可定義可在特定 Azure 資源上執行的動作。藉由將角色指派給使用者、群組、服務主體或受控識別，統稱為安全性主體，即可控制其在 Azure 環境中對特定資源的存取。

當您指派角色時，您可以指定安全性主體、角色定義和範圍。這種組合稱為角色指派。 Azure AI 模型推斷是 Azure AI 服務資源的一項功能，因此指派給該特定資源的角色會控制推斷的存取權。

您可以識別不同類型的資源存取：

系統管理存取：與資源管理相關的動作。它們通常會變更資源的狀態及其組態。在 Azure 中，這些作業是控制平面作業，而且可以使用 Azure 入口網站、Azure CLI 或基礎結構即程式代碼來執行。的範例包括建立新的模型部署、變更內容篩選組態、變更所提供的模型版本，或變更部署的SKU。
開發人員存取：與資源耗用量相關的動作。例如，叫用聊天完成 API。不過，用戶無法變更資源的狀態及其組態。

在 Azure 中，系統管理作業一律會使用 Microsoft Entra ID 來執行。認知服務參與者等角色可讓您執行這些作業。另一方面，開發人員作業可以使用存取密鑰或/和Microsoft Entra 標識符來執行。認知服務使用者等角色可讓您執行這些作業。

重要

擁有資源的系統管理存取權不一定授與開發人員存取權。仍然需要授與角色的明確存取權。這類似於資料庫伺服器的運作方式。擁有資料庫伺服器的系統管理員存取權並不表示您可以在資料庫內讀取數據。

請遵循下列步驟，在 Azure AI 服務資源中設定 Azure AI 模型推斷的開發人員存取權。

必要條件

若要完成本文，您需要：

Azure 訂用帳戶。如果您使用 GitHub 模型，您可以升級您的體驗，並在程式中建立 Azure 訂用帳戶。如果是您的情況，請閱讀從 GitHub 模型升級至 Azure AI 模型推斷。
Azure AI 服務資源。如需詳細資訊，請參閱建立 Azure AI 服務資源。
具有 Microsoft.Authorization/roleAssignments/write 和許可權的帳戶，例如系統管理員Microsoft.Authorization/roleAssignments/delete角色型訪問控制。
若要指派角色，您必須指定三個元素：
- 安全性主體：例如您的用戶帳戶。
- 角色定義： 認知服務使用者 角色。
- 範圍：Azure AI 服務資源。

安裝 Azure CLI。
識別下列資訊：
- 您的 Azure 訂用帳戶識別碼。
- 您的 Azure AI 服務資源名稱。
- 部署 Azure AI 服務資源的資源群組。

設定Microsoft輸入標識碼以進行推斷

請遵循下列步驟，在 Azure AI Services 資源中設定Microsoft Entra ID 以進行推斷：

登入您的 Azure 訂用帳戶：
```
az login
```
如果您有多個訂用帳戶，請選取資源所在的訂用帳戶：
```
az account set --subscription "<subscription-id>"
```
使用您計劃使用的 Azure AI 服務資源名稱和資源群組，設定下列環境變數。
```
ACCOUNT_NAME="<ai-services-resource-name>"
RESOURCE_GROUP="<resource-group>"
```

取得資源的完整名稱：

RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")

取得您要指派許可權之安全性主體的物件標識碼。下列範例示範如何取得與相關聯的物件識別碼：

您自己的登入帳戶：

OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)

安全組：

OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)

服務主體：

OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)

將 認知服務使用者 角色指派給服務主體（範圍設定為資源）。藉由指派角色，您會將服務主體存取權授與此資源。
```
az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
```
選取的用戶現在可以使用Microsoft Entra ID 進行推斷。

提示

請記住，Azure 角色指派最多可能需要五分鐘的時間傳播。從安全組新增或移除使用者會立即傳播。

在您的程式代碼中使用Microsoft Entra識別符

一旦在您的資源中設定Microsoft Entra ID 之後，您必須更新程序代碼，以在取用推斷端點時使用它。下列範例示範如何使用聊天完成模型：

使用套件管理員安裝套件 azure-ai-inference，例如 pip：

pip install azure-ai-inference>=1.0.0b5

警告

Azure AI Services 資源需要適用於 Python 的版本 azure-ai-inference>=1.0.0b5 。

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 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",
)

從 npm 安裝套件 @azure-rest/ai-inference：

npm install @azure-rest/ai-inference

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 Entra ID 取用聊天完成：

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    "mistral-large-2407",
    clientOptions,
);

使用下列命令來安裝 Azure AI 推斷程式庫：

dotnet add package Azure.AI.Inference --prerelease

安裝 Azure.Identity 套件：

dotnet add package Azure.Identity

匯入下列命名空間：

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 Entra ID 取用聊天完成：

var credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    "mistral-large-2407",
    clientOptions.
);

將套件新增至您的專案：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

然後，您可以使用套件來取用模型。下列範例會示範如何建立用戶端以取用聊天完成：

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .model("mistral-large-2407")
    .buildClient();

探索我們的範例，並閱讀 API 參考文件以開始使用。

使用參考區段來探索 API 設計，以及哪些參數可供使用，並指出標頭 Authorization中的驗證令牌。例如，聊天完成的參考區段會詳細說明如何使用路由/chat/completions，根據聊天格式的指示產生預測。請注意，URL 的根目錄包含路徑 /models ：

要求

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

權杖必須發行範圍 https://cognitiveservices.azure.com/.default。

為了進行測試，取得用戶帳戶有效令牌最簡單的方式是使用 Azure CLI。在主控台中，執行下列 Azure CLI 命令：

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

使用 Microsoft Entra ID 時認證的選項

DefaultAzureCredential 是一種有意見、已排序的機制序列，用於驗證至Microsoft Entra ID。每個驗證機制都是衍生自類別的 TokenCredential 類別，稱為認證。在執行階段中，DefaultAzureCredential 會嘗試使用第一個認證進行驗證。如果該認證無法取得存取權杖，則會嘗試序列中的下一個認證，以此類推，直到成功取得存取權杖為止。因此，您的應用程式可以在相異環境中使用不同的認證，而不需要撰寫環境特定程式碼。

當上述程式碼在本機開發工作站上執行時，它會在環境變數中尋找應用程式服務主體，或在本機安裝的開發工具 (例如 Visual Studio) 中尋找一組開發人員認證。在本機開發期間，您可以使用任一方法向 Azure 資源驗證應用程式。

部署至 Azure 時，同一組程式碼也可向其他 Azure 資源驗證您的應用程式。 DefaultAzureCredential 可擷取環境設定與受控識別設定，以便自動向其他服務進行驗證。

最佳作法

在生產環境中使用具決定性認證：強烈建議您從 DefaultAzureCredential 移至下列生產環境具決定性的解決方案之一：
- 特定的 TokenCredential 實作，例如 ManagedIdentityCredential。如需選項，請參閱衍生清單。
- 針對您執行應用程式的 Azure 環境最佳化的簡化 ChainedTokenCredential 實作。 ChainedTokenCredential 基本上會建立可接受認證選項的特定允許清單，例如 ManagedIdentity 用於生產環境及 VisualStudioCredential 開發。
將系統指派或使用者指派的受控識別設定為可能執行程序代碼的 Azure 資源。設定Microsoft Entra ID 存取這些特定身分識別。

重要

本文中標示為 (預覽) 的項目目前處於公開預覽狀態。此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

部署至 Azure AI 模型推斷的 Azure AI 服務模型支援使用 Microsoft Entra ID 的無密鑰授權。無密鑰授權可增強安全性、簡化用戶體驗、降低作業複雜度，併為新式開發提供強固的合規性支援。它讓組織採用安全且可調整的身分識別管理解決方案，是一個強有力的選擇。

本文說明如何在 Azure AI 模型推斷中設定Microsoft Entra ID 以進行推斷。

瞭解 Azure 中資源內容中的角色

Microsoft Entra ID 會使用角色型存取控制（RBAC）的概念進行授權。角色是管理雲端資源存取權的核心。角色基本上是許可權集合，可定義可在特定 Azure 資源上執行的動作。藉由將角色指派給使用者、群組、服務主體或受控識別，統稱為安全性主體，即可控制其在 Azure 環境中對特定資源的存取。

當您指派角色時，您可以指定安全性主體、角色定義和範圍。這種組合稱為角色指派。 Azure AI 模型推斷是 Azure AI 服務資源的一項功能，因此指派給該特定資源的角色會控制推斷的存取權。

您可以識別不同類型的資源存取：

系統管理存取：與資源管理相關的動作。它們通常會變更資源的狀態及其組態。在 Azure 中，這些作業是控制平面作業，而且可以使用 Azure 入口網站、Azure CLI 或基礎結構即程式代碼來執行。的範例包括建立新的模型部署、變更內容篩選組態、變更所提供的模型版本，或變更部署的SKU。
開發人員存取：與資源耗用量相關的動作。例如，叫用聊天完成 API。不過，用戶無法變更資源的狀態及其組態。

在 Azure 中，系統管理作業一律會使用 Microsoft Entra ID 來執行。認知服務參與者等角色可讓您執行這些作業。另一方面，開發人員作業可以使用存取密鑰或/和Microsoft Entra 標識符來執行。認知服務使用者等角色可讓您執行這些作業。

重要

擁有資源的系統管理存取權不一定授與開發人員存取權。仍然需要授與角色的明確存取權。這類似於資料庫伺服器的運作方式。擁有資料庫伺服器的系統管理員存取權並不表示您可以在資料庫內讀取數據。

請遵循下列步驟，在 Azure AI 服務資源中設定 Azure AI 模型推斷的開發人員存取權。

必要條件

若要完成本文，您需要：

Azure 訂用帳戶。如果您使用 GitHub 模型，您可以升級您的體驗，並在程式中建立 Azure 訂用帳戶。如果是您的情況，請閱讀從 GitHub 模型升級至 Azure AI 模型推斷。
Azure AI 服務資源。如需詳細資訊，請參閱建立 Azure AI 服務資源。
具有 Microsoft.Authorization/roleAssignments/write 和許可權的帳戶，例如系統管理員Microsoft.Authorization/roleAssignments/delete角色型訪問控制。
若要指派角色，您必須指定三個元素：
- 安全性主體：例如您的用戶帳戶。
- 角色定義： 認知服務使用者 角色。
- 範圍：Azure AI 服務資源。

安裝 Azure CLI。
識別下列資訊：
- 您的 Azure 訂用帳戶識別碼。

關於本教學課程

本文中的範例是以 Azure-Samples/azureai-model-inference-bicep 存放庫中所包含的程式代碼範例為基礎。若要在本機執行命令，而不需要複製或貼上檔案內容，請使用下列命令來複製存放庫，並移至您程式代碼撰寫語言的資料夾：

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

此範例的檔案位於：

cd azureai-model-inference-bicep/infra

了解資源

本教學課程可協助您建立：

已停用金鑰存取的 Azure AI Services 資源。為了簡單起見，此範本不會部署模型。
具有認知服務使用者角色之指定安全性主體的角色指派。

您正使用下列資產來建立這些資源：

使用範本 modules/ai-services-template.bicep 來描述您的 Azure AI Services 資源：

modules/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

提示

請注意，此範本可以採用參數 allowKeys ，何時 false 會停用資源中的密鑰使用。此組態為選用。

使用範本 modules/role-assignment-template.bicep 來描述 Azure 中的角色指派：

modules/role-assignment-template.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

建立資源

在您的控制台中，遵循下列步驟：

定義主要部署：

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

登入 Azure：
```
az login
```

請確定您位於正確的訂用帳戶中：

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

執行部署：

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

此範本會輸出 Azure AI 模型推斷端點，讓您可用來取用您所建立的任何模型部署。

在您的程式代碼中使用Microsoft Entra識別符

在資源中設定Microsoft Entra ID 之後，您必須更新程序代碼，以在取用推斷端點時使用它。下列範例示範如何使用聊天完成模型：

使用套件管理員安裝套件 azure-ai-inference，例如 pip：

pip install azure-ai-inference>=1.0.0b5

警告

Azure AI Services 資源需要適用於 Python 的版本 azure-ai-inference>=1.0.0b5 。

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 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",
)

從 npm 安裝套件 @azure-rest/ai-inference：

npm install @azure-rest/ai-inference

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 Entra ID 取用聊天完成：

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    "mistral-large-2407",
    clientOptions,
);

使用下列命令來安裝 Azure AI 推斷程式庫：

dotnet add package Azure.AI.Inference --prerelease

安裝 Azure.Identity 套件：

dotnet add package Azure.Identity

匯入下列命名空間：

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

然後，您可以使用套件來取用模型。下列範例示範如何建立用戶端，以使用 Entra ID 取用聊天完成：

var credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    "mistral-large-2407",
    clientOptions.
);

將套件新增至您的專案：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

然後，您可以使用套件來取用模型。下列範例會示範如何建立用戶端以取用聊天完成：

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .model("mistral-large-2407")
    .buildClient();

探索我們的範例，並閱讀 API 參考文件以開始使用。

使用參考區段來探索 API 設計，以及哪些參數可供使用，並指出標頭 Authorization中的驗證令牌。例如，聊天完成的參考區段會詳細說明如何使用路由/chat/completions，根據聊天格式的指示產生預測。請注意，URL 的根目錄包含路徑 /models ：

要求

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

權杖必須發行範圍 https://cognitiveservices.azure.com/.default。

為了進行測試，取得用戶帳戶有效令牌最簡單的方式是使用 Azure CLI。在主控台中，執行下列 Azure CLI 命令：

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

使用 Microsoft Entra ID 時認證的選項

DefaultAzureCredential 是一種有意見、已排序的機制序列，用於驗證至Microsoft Entra ID。每個驗證機制都是衍生自類別的 TokenCredential 類別，稱為認證。在執行階段中，DefaultAzureCredential 會嘗試使用第一個認證進行驗證。如果該認證無法取得存取權杖，則會嘗試序列中的下一個認證，以此類推，直到成功取得存取權杖為止。因此，您的應用程式可以在相異環境中使用不同的認證，而不需要撰寫環境特定程式碼。

當上述程式碼在本機開發工作站上執行時，它會在環境變數中尋找應用程式服務主體，或在本機安裝的開發工具 (例如 Visual Studio) 中尋找一組開發人員認證。在本機開發期間，您可以使用任一方法向 Azure 資源驗證應用程式。

部署至 Azure 時，同一組程式碼也可向其他 Azure 資源驗證您的應用程式。 DefaultAzureCredential 可擷取環境設定與受控識別設定，以便自動向其他服務進行驗證。

最佳作法

在生產環境中使用具決定性認證：強烈建議您從 DefaultAzureCredential 移至下列生產環境具決定性的解決方案之一：
- 特定的 TokenCredential 實作，例如 ManagedIdentityCredential。如需選項，請參閱衍生清單。
- 針對您執行應用程式的 Azure 環境最佳化的簡化 ChainedTokenCredential 實作。 ChainedTokenCredential 基本上會建立可接受認證選項的特定允許清單，例如 ManagedIdentity 用於生產環境及 VisualStudioCredential 開發。
將系統指派或使用者指派的受控識別設定為可能執行程序代碼的 Azure 資源。設定Microsoft Entra ID 存取這些特定身分識別。

停用資源中的金鑰型驗證

當您實作 Microsoft Entra 識別符，並在取用服務的所有應用程式中完全解決相容性或後援考慮時，建議停用密鑰型驗證。您可以藉由變更屬性 disableLocalAuth來達成此目的：

modules/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

共用方式為

瞭解 Azure 中資源內容中的角色

必要條件

設定Microsoft輸入標識碼以進行推斷

在您的程式代碼中使用Microsoft Entra識別符

使用 Microsoft Entra ID 時認證的選項

最佳作法

在您的專案中使用Microsoft Entra識別符

停用資源中的金鑰型驗證

瞭解 Azure 中資源內容中的角色

必要條件

設定Microsoft輸入標識碼以進行推斷

在您的程式代碼中使用Microsoft Entra識別符

使用 Microsoft Entra ID 時認證的選項

最佳作法

瞭解 Azure 中資源內容中的角色

必要條件

關於本教學課程

了解資源

建立資源

在您的程式代碼中使用Microsoft Entra識別符

使用 Microsoft Entra ID 時認證的選項

最佳作法

停用資源中的金鑰型驗證

下一步

意見反應

其他資源