你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Microsoft Entra ID 配置无密钥身份验证

重要

本文中标记了“（预览版）”的项目目前为公共预览版。 此预览版未提供服务级别协议，不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

部署到 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 ID 来执行。 认知服务用户等角色允许你执行这些操作。

重要

对资源拥有管理访问权限不一定授予开发人员访问权限。 仍需要授予角色的显式访问权限。 这类似于数据库服务器的工作原理。 拥有数据库服务器的管理员访问权限并不意味着你可以读取数据库中的数据。

按照以下步骤在 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 Entra ID

按照以下步骤为推理配置 Microsoft Entra ID：

1. 转到 Azure 门户，找到正在使用的 Azure AI 服务资源。 如果对项目或中心使用 Azure AI Foundry，可以通过以下方式导航到它：

   1. 转到 Azure AI Foundry 门户。

   2. 在登陆页面上，选择“打开管理中心”。

   3. 转到“连接的资源”部分，然后选择要配置的 Azure AI 服务资源的连接。 如果未列出，请选择“查看所有”以查看完整列表。

   4. 在“连接详细信息”部分的“资源”下，选择 Azure 资源的名称。 将打开一个新页面。

   5. 现在，可在 Azure 门户中管理资源本身的所有方面。

2. 在左侧导航栏中，选择“访问控制(标识和访问管理)”。

   提示

   使用“查看我的访问”选项来验证哪些角色已分配给你。

3. 选择“角色分配”，然后选择“添加”>“添加角色分配”。

4. 在“作业函数角色”上，键入“认知服务用户”。 将筛选出角色列表。

5. 选择角色，然后选择“下一步”。

6. 在“成员”上，选择要向其授予访问权限的用户或组。 我们建议尽可能使用安全组，因为它们更易于管理和维护。

7. 选择“下一步”并完成向导。

8. 所选用户现在可以使用 Microsoft Entra ID 进行推理。

   提示

   请记住，Azure 角色分配可能需要最多五分钟的时间进行传播。 使用安全组时，添加或删除安全组中的用户会立即传播。

请注意，对于已经有密钥的用户来说，仍然可以通过密钥进行访问。 若要撤销密钥，请在 Azure 门户中的左侧导航中选择“资源管理”>“密钥和终结点”>“重新生成密钥1”和“重新生成密钥2”。

在代码中使用 Microsoft Entra ID

一旦在资源中配置了 Microsoft Entra ID，在使用推理终结点时，需要更新代码以启用它。 以下示例演示如何使用聊天补全模型：

Python

使用包管理器（例如 pip）安装包 azure-ai-inference：

pip install azure-ai-inference>=1.0.0b5

警告

Azure AI 服务资源需要 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",
)

JavaScript

使用 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,
);

C#

请使用以下命令安装 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.
);

Java

将包添加到项目：

<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 参考文档以开始使用。

REST

使用参考部分探索 API 设计以及可用的参数可用，并在标头 Authorization 中指示身份验证令牌。 例如，聊天补全的参考部分详细介绍了如何使用路由 /chat/completions 根据聊天格式的指令生成预测。 请注意，URL 的根目录包含路径 /models：

Request

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 ID

即使资源已配置 Microsoft Entra ID，项目仍可能使用密钥来使用资源的预测。 使用 Azure AI Foundry 操场时，会使用与项目所建立的连接相关联的凭据。

若要更改此行为，必须更新项目中的连接以使用 Microsoft Entra ID。 执行以下步骤：

1. 转到 Azure AI Foundry 门户。

2. 通过连接导航到正在使用 Azure AI 服务资源的项目或中心。

3. 选择“管理中心”。

4. 转到“连接的资源”部分，然后选择要配置的 Azure AI 服务资源的连接。 如果未列出，请选择“查看所有”以查看完整列表。

5. 在“连接详细信息”部分，选择“访问详细信息”旁边的编辑图标。

6. 在“身份验证”下，将值更改为 Microsoft Entra ID。

7. 选择“更新”。

8. 连接现已配置为使用 Microsoft Entra ID。

在资源中禁用基于密钥的身份验证

在实现了 Microsoft Entra ID 并且解决了所有使用该服务的应用程序中的兼容性或回退问题时，建议禁用基于密钥的身份验证。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。 此预览版未提供服务级别协议，不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

部署到 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 ID 来执行。 认知服务用户等角色允许你执行这些操作。

重要

对资源拥有管理访问权限不一定授予开发人员访问权限。 仍需要授予角色的显式访问权限。 这类似于数据库服务器的工作原理。 拥有数据库服务器的管理员访问权限并不意味着你可以读取数据库中的数据。

按照以下步骤在 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 订阅 ID。

  • 你的 Azure AI 服务资源名称。

  • 在其中部署 Azure AI 服务资源的资源组。

为推理配置 Microsoft Entra ID

按照以下步骤在 Azure AI Services 资源中为推理配置 Microsoft Entra ID：

1. 登录到 Azure 订阅：

   az login
   

2. 如果订阅超过一个，请选择资源所在的订阅：

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

3. 使用计划使用的 Azure AI 服务资源的名称和资源组设置以下环境变量。

   ACCOUNT_NAME="<ai-services-resource-name>"
   RESOURCE_GROUP="<resource-group>"
   

4. 获取资源的全名：

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

5. 获取要向其分配权限的安全主体的对象 ID。 以下示例演示如何获取与以下对象关联的对象 ID：

   登录自己的帐户：

   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)
   

6. 向服务主体分配“认知服务用户角色”（范围限定为资源）。 通过分配角色，将向服务主体授予对此资源的访问权限。

   az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
   

7. 所选用户现在可以使用 Microsoft Entra ID 进行推理。

   提示

   请记住，Azure 角色分配可能需要最多五分钟的时间进行传播。 添加或删除安全组中的用户会立即传播。

在代码中使用 Microsoft Entra ID

一旦在资源中配置了 Microsoft Entra ID，在使用推理终结点时，需要更新代码以启用它。 以下示例演示如何使用聊天补全模型：

Python

使用包管理器（例如 pip）安装包 azure-ai-inference：

pip install azure-ai-inference>=1.0.0b5

警告

Azure AI 服务资源需要 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",
)

JavaScript

使用 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,
);

C#

请使用以下命令安装 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.
);

Java

将包添加到项目：

<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 参考文档以开始使用。

REST

使用参考部分探索 API 设计以及可用的参数可用，并在标头 Authorization 中指示身份验证令牌。 例如，聊天补全的参考部分详细介绍了如何使用路由 /chat/completions 根据聊天格式的指令生成预测。 请注意，URL 的根目录包含路径 /models：

Request

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 模型推理中的模型支持使用 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 ID 来执行。 认知服务用户等角色允许你执行这些操作。

重要

对资源拥有管理访问权限不一定授予开发人员访问权限。 仍需要授予角色的显式访问权限。 这类似于数据库服务器的工作原理。 拥有数据库服务器的管理员访问权限并不意味着你可以读取数据库中的数据。

按照以下步骤在 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 订阅 ID。

关于本教程

本文中的示例基于 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 服务资源。 为简单起见，此模板不会部署模型。
• 为给定安全主体分配的角色是“认知服务用户”。

会使用以下资产创建这些资源：

1. 使用模板 modules/ai-services-template.bicep 描述 Azure AI 服务资源：

   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 时，将在资源中禁用密钥的使用。 此配置是可选的。

2. 使用模板 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
   

创建资源

在控制台中，执行以下步骤：

1. 定义主部署：

   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
   

2. 登录到 Azure：

   az login
   

3. 确保你位于正确的订阅中：

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

4. 运行部署：

   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
   

5. 该模板会输出 Azure AI 模型推理终结点，可用于使用你创建的任何模型部署。

在代码中使用 Microsoft Entra ID

一旦在资源中配置了 Microsoft Entra ID，在使用推理终结点时，需要更新代码以启用它。 以下示例演示如何使用聊天补全模型：

Python

使用包管理器（例如 pip）安装包 azure-ai-inference：

pip install azure-ai-inference>=1.0.0b5

警告

Azure AI 服务资源需要 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",
)

JavaScript

使用 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,
);

C#

请使用以下命令安装 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.
);

Java

将包添加到项目：

<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 参考文档以开始使用。

REST

使用参考部分探索 API 设计以及可用的参数可用，并在标头 Authorization 中指示身份验证令牌。 例如，聊天补全的参考部分详细介绍了如何使用路由 /chat/completions 根据聊天格式的指令生成预测。 请注意，URL 的根目录包含路径 /models：

Request

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 ID 并且解决了所有使用该服务的应用程序中的兼容性或回退问题时，建议禁用基于密钥的身份验证。 可以通过更改属性 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 AI 服务中的 Azure AI 模型推理服务开发应用程序