Microsoft Entra ID를 사용하여 키 없는 인증 구성

Important

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

Azure AI Services에서 Azure AI 모델 유추에 배포된 모델은 Microsoft Entra ID를 사용하여 키가 없는 권한 부여를 지원합니다. 키가 없는 권한 부여는 보안을 강화하고, 사용자 환경을 간소화하며, 운영 복잡성을 줄이며, 최신 개발을 위한 강력한 규정 준수 지원을 제공합니다. 이는 안전하고 확장 가능한 ID 관리 솔루션을 채택하는 조직에 강력한 선택입니다.

이 문서에서는 Azure AI 모델 유추에서 유추를 위해 Microsoft Entra ID를 구성하는 방법을 설명합니다.

Azure의 리소스 컨텍스트에서 역할 이해

Microsoft Entra ID는 권한 부여를 위해 RBAC(역할 기반 액세스 제어)의 개념을 사용합니다. 역할은 클라우드 리소스에 대한 액세스를 관리하는 데 핵심적인 역할을 합니다. 역할은 기본적으로 특정 Azure 리소스에서 수행할 수 있는 작업을 정의하는 권한 컬렉션입니다. 사용자, 그룹, 서비스 주체 또는 관리 ID(보안 주체라고도 함)에 역할을 할당하면 Azure 환경 내에서 특정 리소스에 대한 액세스를 제어할 수 있습니다.

역할을 할당할 때 보안 주체, 역할 정의 및 범위를 지정합니다. 이 조합을 역할 할당이라고 합니다. Azure AI 모델 유추는 Azure AI Services 리소스의 기능이므로 특정 리소스에 할당된 역할은 유추에 대한 액세스를 제어합니다.

리소스에 대한 두 가지 유형의 액세스를 식별합니다.

관리 액세스: 리소스 관리와 관련된 작업입니다. 일반적으로 리소스의 상태와 해당 구성을 변경합니다. Azure에서 이러한 작업은 컨트롤 플레인 작업이며 Azure Portal, Azure CLI 또는 코드로 인프라를 사용하여 실행할 수 있습니다. 예를 들어 새 모델 배포 만들기, 콘텐츠 필터링 구성 변경, 제공된 모델 버전 변경 또는 배포의 SKU 변경 등이 있습니다.
개발자 액세스: 리소스 사용과 관련된 작업입니다. 예를 들어 채팅 완료 API를 호출합니다. 그러나 사용자는 리소스의 상태와 해당 구성을 변경할 수 없습니다.

Azure에서 관리 작업은 항상 Microsoft Entra ID를 사용하여 수행됩니다. Cognitive Services 기여자 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다. 반면에 액세스 키 또는/및 Microsoft Entra ID를 사용하여 개발자 작업을 수행할 수 있습니다. Cognitive Services 사용자와 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다.

Important

리소스에 대한 관리 액세스 권한이 반드시 개발자에게 액세스 권한을 부여하는 것은 아닙니다. 역할을 부여하여 명시적 액세스는 여전히 필요합니다. 데이터베이스 서버의 작동 방식과 유사합니다. 관리자가 데이터베이스 서버에 액세스할 수 있다고 해서 데이터베이스 내의 데이터를 읽을 수 있는 것은 아닙니다.

다음 단계에 따라 Azure AI Services 리소스에서 Azure AI 모델 유추에 대한 개발자 액세스를 구성합니다.

필수 조건

이 문서를 완료하려면 다음이 필요합니다.

Azure 구독 GitHub 모델을 사용하는 경우 환경을 업그레이드하고 프로세스에서 Azure 구독을 만들 수 있습니다. 사용자의 경우 GitHub 모델에서 Azure AI 모델 유추로 업그레이드를 읽습니다.
Azure AI 서비스 리소스입니다. 자세한 내용은 Azure AI Services 리소스 만들기를 참조 하세요.
관리자 역할 기반 액세스 제어와 같은 권한이 있는 Microsoft.Authorization/roleAssignments/write계정입니다Microsoft.Authorization/roleAssignments/delete.
역할을 할당하려면 다음 세 가지 요소를 지정해야 합니다.
- 보안 주체: 예: 사용자 계정.
- 역할 정의: Cognitive Services 사용자 역할.
- 범위: Azure AI Services 리소스.

유추를 위해 Microsoft Entra ID 구성

다음 단계에 따라 유추를 위해 Microsoft Entra ID를 구성합니다.

Azure Portal로 이동하여 사용 중인 Azure AI Services 리소스를 찾습니다. 프로젝트 또는 허브에서 Azure AI Foundry를 사용하는 경우 다음을 통해 탐색할 수 있습니다.
1. Azure AI Foundry 포털로 이동합니다.
2. 방문 페이지에서 관리 센터 열기를 선택합니다.
3. 연결된 리소스 섹션으로 이동하여 구성하려는 Azure AI Services 리소스에 대한 연결을 선택합니다. 나열되지 않은 경우 모두 보기를 선택하여 전체 목록을 확인합니다.
4. 연결 세부 정보 섹션의 리소스 아래에서 Azure 리소스의 이름을 선택합니다. 새 페이지가 열립니다.
5. 이제 리소스 자체의 모든 측면을 관리할 수 있는 Azure Portal에 있습니다.
왼쪽 탐색 모음에서 액세스 제어(IAM)를 선택합니다.

팁

내 액세스 보기 옵션을 사용하여 이미 할당된 역할을 확인합니다.
역할 할당을 선택한 다음, 역할 할당 추가를>선택합니다.
작업 함수 역할에 Cognitive Services 사용자를 입력합니다. 역할 목록이 필터링됩니다.
역할을 선택하고 다음을 선택합니다.
구성원에서 액세스 권한을 부여할 사용자 또는 그룹을 선택합니다. 관리 및 유지 관리가 더 쉽기 때문에 가능한 한 보안 그룹을 사용하는 것이 좋습니다.
다음을 선택하고 마법사를 완료합니다.
선택한 사용자는 이제 유추에 Microsoft Entra ID를 사용할 수 있습니다.

팁

Azure 역할 할당을 전파하는 데 최대 5분이 소요될 수 있습니다. 보안 그룹을 사용하는 경우 보안 그룹에서 사용자를 추가하거나 제거하면 즉시 전파됩니다.

이미 사용할 수 있는 키가 있는 사용자는 키 기반 액세스가 여전히 가능합니다. 키를 해지하려면 Azure Portal의 왼쪽 탐색 영역에서 리소스 관리>키 및 엔드포인트>를 선택하여 Key1을 다시 생성하고 Key2를 다시 생성합니다.

코드에서 Microsoft Entra ID 사용

리소스에서 Microsoft Entra ID를 구성한 후에는 유추 엔드포인트를 사용할 때 사용할 코드를 업데이트해야 합니다. 다음 예제에서는 채팅 완료 모델을 사용하는 방법을 보여 줍니다.

pip와 같은 패키지 관리 시스템을 사용하여 azure-ai-inference 패키지를 설치합니다.

pip install azure-ai-inference>=1.0.0b5

Warning

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 사용하여 채팅 형식의 지침에 따라 예측을 생성하는 방법을 자세히 설명합니다. 경로 /models 는 URL의 루트에 포함됩니다.

요청

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은 환경 설정 및 관리 ID 구성을 검색하여 다른 서비스에 자동으로 인증할 수 있습니다.

모범 사례

프로덕션 환경에서 결정적 자격 증명 사용: 프로덕션 환경에서 다음 결정적 솔루션 중 하나로 이동하는 DefaultAzureCredential 것이 좋습니다.
- ManagedIdentityCredential와 같은 특정 TokenCredential 구현. 옵션은 파생 목록을 참조하세요.
- 앱이 실행되는 Azure 환경에 최적화된 축소된 ChainedTokenCredential 구현입니다. ChainedTokenCredential기본적으로 프로덕션 및 개발과 VisualStudioCredential 같은 ManagedIdentity 허용 가능한 자격 증명 옵션의 특정 허용 목록을 만듭니다.
가능하면 코드가 실행되는 Azure 리소스에 시스템 할당 또는 사용자 할당 관리 ID를 구성합니다. 해당 특정 ID에 대한 Microsoft Entra ID 액세스를 구성합니다.

프로젝트에서 Microsoft Entra ID 사용

리소스에 Microsoft Entra ID가 구성된 경우에도 프로젝트에서 키를 사용하여 리소스의 예측을 사용할 수 있습니다. Azure AI Foundry 플레이그라운드를 사용하는 경우 프로젝트의 연결과 연결된 자격 증명이 사용됩니다.

이 동작을 변경하려면 Microsoft Entra ID를 사용하도록 프로젝트의 연결을 업데이트해야 합니다. 다음 단계를 수행합니다.

Azure AI Foundry 포털로 이동합니다.
연결을 통해 Azure AI Services 리소스를 사용하는 프로젝트 또는 허브로 이동합니다.
관리 센터를 선택합니다.
연결된 리소스 섹션으로 이동하여 구성하려는 Azure AI Services 리소스에 대한 연결을 선택합니다. 나열되지 않은 경우 모두 보기를 선택하여 전체 목록을 확인합니다.
연결 세부 정보 섹션의 액세스 세부 정보 옆에 있는 편집 아이콘을 선택합니다.
인증에서 값을 Microsoft Entra ID로 변경합니다.
업데이트를 선택합니다.
연결이 이제 Microsoft Entra ID와 작동하도록 구성됩니다.

리소스에서 키 기반 인증 사용 안 함

Microsoft Entra ID를 구현하고 서비스를 사용하는 모든 애플리케이션에서 호환성 또는 대체 문제를 완전히 해결한 경우 키 기반 인증을 사용하지 않도록 설정하는 것이 좋습니다.

Important

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

Azure AI Services에서 Azure AI 모델 유추에 배포된 모델은 Microsoft Entra ID를 사용하여 키가 없는 권한 부여를 지원합니다. 키가 없는 권한 부여는 보안을 강화하고, 사용자 환경을 간소화하며, 운영 복잡성을 줄이며, 최신 개발을 위한 강력한 규정 준수 지원을 제공합니다. 이는 안전하고 확장 가능한 ID 관리 솔루션을 채택하는 조직에 강력한 선택입니다.

이 문서에서는 Azure AI 모델 유추에서 유추를 위해 Microsoft Entra ID를 구성하는 방법을 설명합니다.

Azure의 리소스 컨텍스트에서 역할 이해

Microsoft Entra ID는 권한 부여를 위해 RBAC(역할 기반 액세스 제어)의 개념을 사용합니다. 역할은 클라우드 리소스에 대한 액세스를 관리하는 데 핵심적인 역할을 합니다. 역할은 기본적으로 특정 Azure 리소스에서 수행할 수 있는 작업을 정의하는 권한 컬렉션입니다. 사용자, 그룹, 서비스 주체 또는 관리 ID(보안 주체라고도 함)에 역할을 할당하면 Azure 환경 내에서 특정 리소스에 대한 액세스를 제어할 수 있습니다.

역할을 할당할 때 보안 주체, 역할 정의 및 범위를 지정합니다. 이 조합을 역할 할당이라고 합니다. Azure AI 모델 유추는 Azure AI Services 리소스의 기능이므로 특정 리소스에 할당된 역할은 유추에 대한 액세스를 제어합니다.

리소스에 대한 두 가지 유형의 액세스를 식별합니다.

관리 액세스: 리소스 관리와 관련된 작업입니다. 일반적으로 리소스의 상태와 해당 구성을 변경합니다. Azure에서 이러한 작업은 컨트롤 플레인 작업이며 Azure Portal, Azure CLI 또는 코드로 인프라를 사용하여 실행할 수 있습니다. 예를 들어 새 모델 배포 만들기, 콘텐츠 필터링 구성 변경, 제공된 모델 버전 변경 또는 배포의 SKU 변경 등이 있습니다.
개발자 액세스: 리소스 사용과 관련된 작업입니다. 예를 들어 채팅 완료 API를 호출합니다. 그러나 사용자는 리소스의 상태와 해당 구성을 변경할 수 없습니다.

Azure에서 관리 작업은 항상 Microsoft Entra ID를 사용하여 수행됩니다. Cognitive Services 기여자 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다. 반면에 액세스 키 또는/및 Microsoft Entra ID를 사용하여 개발자 작업을 수행할 수 있습니다. Cognitive Services 사용자와 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다.

Important

리소스에 대한 관리 액세스 권한이 반드시 개발자에게 액세스 권한을 부여하는 것은 아닙니다. 역할을 부여하여 명시적 액세스는 여전히 필요합니다. 데이터베이스 서버의 작동 방식과 유사합니다. 관리자가 데이터베이스 서버에 액세스할 수 있다고 해서 데이터베이스 내의 데이터를 읽을 수 있는 것은 아닙니다.

다음 단계에 따라 Azure AI Services 리소스에서 Azure AI 모델 유추에 대한 개발자 액세스를 구성합니다.

필수 조건

이 문서를 완료하려면 다음이 필요합니다.

Azure 구독 GitHub 모델을 사용하는 경우 환경을 업그레이드하고 프로세스에서 Azure 구독을 만들 수 있습니다. 사용자의 경우 GitHub 모델에서 Azure AI 모델 유추로 업그레이드를 읽습니다.
Azure AI 서비스 리소스입니다. 자세한 내용은 Azure AI Services 리소스 만들기를 참조 하세요.
관리자 역할 기반 액세스 제어와 같은 권한이 있는 Microsoft.Authorization/roleAssignments/write계정입니다Microsoft.Authorization/roleAssignments/delete.
역할을 할당하려면 다음 세 가지 요소를 지정해야 합니다.
- 보안 주체: 예: 사용자 계정.
- 역할 정의: Cognitive Services 사용자 역할.
- 범위: Azure AI Services 리소스.

Azure CLI를 설치합니다.
다음 정보를 식별합니다.
- Azure 구독 ID.
- Azure AI Services 리소스 이름입니다.
- Azure AI Services 리소스가 배포되는 리소스 그룹입니다.

유추를 위해 Microsoft Entra ID 구성

다음 단계에 따라 Azure AI Services 리소스에서 유추할 Microsoft Entra ID를 구성합니다.

Azure 구독에 로그인합니다.
```
az login
```
둘 이상의 구독이 있는 경우 리소스가 있는 구독을 선택합니다.
```
az account set --subscription "<subscription-id>"
```
사용하려는 Azure AI Services 리소스 및 리소스 그룹의 이름으로 다음 환경 변수를 설정합니다.
```
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")

권한을 할당하려는 보안 주체의 개체 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)

Cognitive Services 사용자 역할을 서비스 주체(리소스로 범위 지정)에 할당합니다. 역할을 할당함으로써 서비스 주체에게 이 리소스에 대한 액세스 권한을 부여하게 됩니다.
```
az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
```
선택한 사용자는 이제 유추에 Microsoft Entra ID를 사용할 수 있습니다.

팁

Azure 역할 할당을 전파하는 데 최대 5분이 소요될 수 있습니다. 보안 그룹에서 사용자를 추가하거나 제거하면 즉시 전파됩니다.

코드에서 Microsoft Entra ID 사용

리소스에서 Microsoft Entra ID가 구성되면 유추 엔드포인트를 사용할 때 사용하도록 코드를 업데이트해야 합니다. 다음 예제에서는 채팅 완료 모델을 사용하는 방법을 보여 줍니다.

pip와 같은 패키지 관리 시스템을 사용하여 azure-ai-inference 패키지를 설치합니다.

pip install azure-ai-inference>=1.0.0b5

Warning

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 사용하여 채팅 형식의 지침에 따라 예측을 생성하는 방법을 자세히 설명합니다. 경로 /models 는 URL의 루트에 포함됩니다.

요청

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은 환경 설정 및 관리 ID 구성을 검색하여 다른 서비스에 자동으로 인증할 수 있습니다.

모범 사례

프로덕션 환경에서 결정적 자격 증명 사용: 프로덕션 환경에서 다음 결정적 솔루션 중 하나로 이동하는 DefaultAzureCredential 것이 좋습니다.
- ManagedIdentityCredential와 같은 특정 TokenCredential 구현. 옵션은 파생 목록을 참조하세요.
- 앱이 실행되는 Azure 환경에 최적화된 축소된 ChainedTokenCredential 구현입니다. ChainedTokenCredential기본적으로 프로덕션 및 개발과 VisualStudioCredential 같은 ManagedIdentity 허용 가능한 자격 증명 옵션의 특정 허용 목록을 만듭니다.
가능하면 코드가 실행되는 Azure 리소스에 시스템 할당 또는 사용자 할당 관리 ID를 구성합니다. 해당 특정 ID에 대한 Microsoft Entra ID 액세스를 구성합니다.

Important

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

Azure AI Services에서 Azure AI 모델 유추에 배포된 모델은 Microsoft Entra ID를 사용하여 키가 없는 권한 부여를 지원합니다. 키가 없는 권한 부여는 보안을 강화하고, 사용자 환경을 간소화하며, 운영 복잡성을 줄이며, 최신 개발을 위한 강력한 규정 준수 지원을 제공합니다. 이는 안전하고 확장 가능한 ID 관리 솔루션을 채택하는 조직에 강력한 선택입니다.

이 문서에서는 Azure AI 모델 유추에서 유추를 위해 Microsoft Entra ID를 구성하는 방법을 설명합니다.

Azure의 리소스 컨텍스트에서 역할 이해

Microsoft Entra ID는 권한 부여를 위해 RBAC(역할 기반 액세스 제어)의 개념을 사용합니다. 역할은 클라우드 리소스에 대한 액세스를 관리하는 데 핵심적인 역할을 합니다. 역할은 기본적으로 특정 Azure 리소스에서 수행할 수 있는 작업을 정의하는 권한 컬렉션입니다. 사용자, 그룹, 서비스 주체 또는 관리 ID(보안 주체라고도 함)에 역할을 할당하면 Azure 환경 내에서 특정 리소스에 대한 액세스를 제어할 수 있습니다.

역할을 할당할 때 보안 주체, 역할 정의 및 범위를 지정합니다. 이 조합을 역할 할당이라고 합니다. Azure AI 모델 유추는 Azure AI Services 리소스의 기능이므로 특정 리소스에 할당된 역할은 유추에 대한 액세스를 제어합니다.

리소스에 대한 두 가지 유형의 액세스를 식별합니다.

관리 액세스: 리소스 관리와 관련된 작업입니다. 일반적으로 리소스의 상태와 해당 구성을 변경합니다. Azure에서 이러한 작업은 컨트롤 플레인 작업이며 Azure Portal, Azure CLI 또는 코드로 인프라를 사용하여 실행할 수 있습니다. 예를 들어 새 모델 배포 만들기, 콘텐츠 필터링 구성 변경, 제공된 모델 버전 변경 또는 배포의 SKU 변경 등이 있습니다.
개발자 액세스: 리소스 사용과 관련된 작업입니다. 예를 들어 채팅 완료 API를 호출합니다. 그러나 사용자는 리소스의 상태와 해당 구성을 변경할 수 없습니다.

Azure에서 관리 작업은 항상 Microsoft Entra ID를 사용하여 수행됩니다. Cognitive Services 기여자 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다. 반면에 액세스 키 또는/및 Microsoft Entra ID를 사용하여 개발자 작업을 수행할 수 있습니다. Cognitive Services 사용자와 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다.

Important

리소스에 대한 관리 액세스 권한이 반드시 개발자에게 액세스 권한을 부여하는 것은 아닙니다. 역할을 부여하여 명시적 액세스는 여전히 필요합니다. 데이터베이스 서버의 작동 방식과 유사합니다. 관리자가 데이터베이스 서버에 액세스할 수 있다고 해서 데이터베이스 내의 데이터를 읽을 수 있는 것은 아닙니다.

다음 단계에 따라 Azure AI Services 리소스에서 Azure AI 모델 유추에 대한 개발자 액세스를 구성합니다.

필수 조건

이 문서를 완료하려면 다음이 필요합니다.

Azure 구독 GitHub 모델을 사용하는 경우 환경을 업그레이드하고 프로세스에서 Azure 구독을 만들 수 있습니다. 사용자의 경우 GitHub 모델에서 Azure AI 모델 유추로 업그레이드를 읽습니다.
Azure AI 서비스 리소스입니다. 자세한 내용은 Azure AI Services 리소스 만들기를 참조 하세요.
관리자 역할 기반 액세스 제어와 같은 권한이 있는 Microsoft.Authorization/roleAssignments/write계정입니다Microsoft.Authorization/roleAssignments/delete.
역할을 할당하려면 다음 세 가지 요소를 지정해야 합니다.
- 보안 주체: 예: 사용자 계정.
- 역할 정의: Cognitive Services 사용자 역할.
- 범위: Azure AI Services 리소스.

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 Services 리소스입니다. 간단히 하기 위해 이 템플릿은 모델을 배포하지 않습니다.
Cognitive 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

팁

이 템플릿은 리소스에서 키 사용을 사용하지 않도록 설정할 때 false 매개 변수 allowKeys 를 사용할 수 있습니다. 이 구성은 선택 사항입니다.

템플릿 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 ID 사용

리소스에서 Microsoft Entra ID를 구성한 후에는 유추 엔드포인트를 사용할 때 사용할 코드를 업데이트해야 합니다. 다음 예제에서는 채팅 완료 모델을 사용하는 방법을 보여 줍니다.

pip와 같은 패키지 관리 시스템을 사용하여 azure-ai-inference 패키지를 설치합니다.

pip install azure-ai-inference>=1.0.0b5

Warning

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 사용하여 채팅 형식의 지침에 따라 예측을 생성하는 방법을 자세히 설명합니다. 경로 /models 는 URL의 루트에 포함됩니다.

요청

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은 환경 설정 및 관리 ID 구성을 검색하여 다른 서비스에 자동으로 인증할 수 있습니다.

모범 사례

프로덕션 환경에서 결정적 자격 증명 사용: 프로덕션 환경에서 다음 결정적 솔루션 중 하나로 이동하는 DefaultAzureCredential 것이 좋습니다.
- ManagedIdentityCredential와 같은 특정 TokenCredential 구현. 옵션은 파생 목록을 참조하세요.
- 앱이 실행되는 Azure 환경에 최적화된 축소된 ChainedTokenCredential 구현입니다. ChainedTokenCredential기본적으로 프로덕션 및 개발과 VisualStudioCredential 같은 ManagedIdentity 허용 가능한 자격 증명 옵션의 특정 허용 목록을 만듭니다.
가능하면 코드가 실행되는 Azure 리소스에 시스템 할당 또는 사용자 할당 관리 ID를 구성합니다. 해당 특정 ID에 대한 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의 리소스 컨텍스트에서 역할 이해

필수 조건

유추를 위해 Microsoft Entra ID 구성

코드에서 Microsoft Entra ID 사용

Microsoft Entra ID를 사용하는 경우 자격 증명 옵션

모범 사례

프로젝트에서 Microsoft Entra ID 사용

리소스에서 키 기반 인증 사용 안 함

Azure의 리소스 컨텍스트에서 역할 이해

필수 조건

유추를 위해 Microsoft Entra ID 구성

코드에서 Microsoft Entra ID 사용

Microsoft Entra ID를 사용하는 경우 자격 증명 옵션

모범 사례

Azure의 리소스 컨텍스트에서 역할 이해

필수 조건

이 자습서 정보

리소스 이해

리소스 만들기

코드에서 Microsoft Entra ID 사용

Microsoft Entra ID를 사용하는 경우 자격 증명 옵션

모범 사례

리소스에서 키 기반 인증 사용 안 함

다음 단계

피드백

추가 리소스