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

중요

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 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 사용자와 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다.

중요

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

다음 단계에 따라 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 리소스.
Cognitive Services 사용자 역할을 사용하는 대신 사용자 지정 역할 정의를 만들려면 역할에 다음 권한이 있는지 확인합니다.
```
{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/MaaS/*"
      ]
    }
  ]
}
```

유추를 위해 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을 다시 생성하고 >를 다시 생성합니다.

코드에서 Microsoft Entra ID 사용

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

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

pip install azure-ai-inference

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예제에서는 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"],
)

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(),
    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를 사용하여 채팅 완료를 사용하는 클라이언트를 만드는 방법을 보여 줍니다.

TokenCredential 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,
    clientOptions.
);

프로젝트에 패키지를 추가합니다.

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

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예에서는 채팅 완성을 이용하는 클라이언트를 만드는 방법을 보여 줍니다.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .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에서 다음 결정적 자격 증명 솔루션 중 하나로 전환할 것을 강력히 고려하십시오.
- TokenCredential와 같은 특정 ManagedIdentityCredential 구현. 옵션은 파생 목록을 참조하세요.
- 앱이 실행되는 Azure 환경에 최적화된 축소된 ChainedTokenCredential 구현입니다. ChainedTokenCredential기본적으로 프로덕션 및 개발과 ManagedIdentity 같은 VisualStudioCredential 허용 가능한 자격 증명 옵션의 특정 허용 목록을 만듭니다.
가능하면 코드가 실행되는 Azure 리소스에 시스템 할당 또는 사용자 할당 관리 ID를 구성합니다. 해당 특정 ID에 대한 Microsoft Entra ID 액세스를 구성합니다.

문제 해결

문제를 해결하기 전에 적절한 권한이 할당되었는지 확인합니다.

Azure Portal로 이동하여 사용 중인 Azure AI Services 리소스를 찾습니다.
왼쪽 창에서 액세스 제어(IAM) 를 선택한 다음 , 액세스 확인을 선택합니다.
서비스에 연결하는 데 사용하는 사용자 또는 ID의 이름을 입력합니다.
Cognitive Services 사용자가 나열된 역할(또는 필수 구성 요소에 설명된 대로 필요한 권한이 포함된 역할)인지 확인합니다.

중요

소유자 또는 참가자와 같은 역할은 Microsoft Entra ID를 통해 액세스를 제공하지 않습니다.
나열되지 않은 경우 계속하기 전에 이 가이드의 단계를 수행합니다.

다음 표에는 Microsoft Entra ID 문제를 해결하는 데 도움이 되는 여러 시나리오가 포함되어 있습니다.

오류/시나리오	근본 원인	솔루션
SDK를 사용하고 있습니다.	알려진 문제.	추가 문제 해결을 하기 전에 서비스에 연결하는 데 사용하는 최신 버전의 소프트웨어를 설치하는 것이 좋습니다. 사용 중인 소프트웨어의 최신 버전에서 인증 버그가 수정되었을 수 있습니다.
`401 Principal does not have access to API/Operation`	요청은 올바른 방법으로 인증을 나타내지만, 사용자 주체에는 추론 엔드포인트를 사용하는 데 필요한 권한이 없습니다.	다음을 가지고 있는지 확인하세요. 1. Azure AI 서비스 리소스에 대한 주체에게 Cognitive Services 사용자 역할을 할당했습니다. Cognitive Services OpenAI 사용자는 OpenAI 모델에 대한 액세스 권한만 부여합니다. 소유자 또는 참가자 는 액세스 권한을 제공하지 않습니다. 2. 첫 번째 호출을 하기 전에 5분 이상 기다립니다.
`401 HTTP/1.1 401 PermissionDenied`	요청은 올바른 방법으로 인증을 나타내지만, 사용자 주체에는 추론 엔드포인트를 사용하는 데 필요한 권한이 없습니다.	Azure AI 서비스 리소스에서 주체에게 Cognitive Services 사용자 역할을 할당했습니다. 역할은 관리자 또는 참가자와 같은 추론 액세스 권한을 부여하지 않습니다. 첫 번째 호출을 하기 전에 5분 이상 기다립니다.
REST API 호출을 사용하는 동안 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`가 발생합니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	헤더에 `Authentication` 범위 `https://cognitiveservices.azure.com/.default`가 있는 유효한 토큰이 포함되어 있는지 확인합니다.
당신이 `AzureOpenAI` 클래스를 사용하면 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`를 얻습니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	엔드포인트에 `https://<resource>.openai.azure.com` 사용하고 있는지 확인합니다. `OpenAI` 클래스나 Models-as-a-Service 모델을 사용할 수 없습니다. 모델이 OpenAI가 아닌 경우 Azure AI 유추 SDK를 사용합니다.
Azure AI Inference SDK를 사용하는 동안 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`가 발생합니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	엔드포인트 `https://<resource>.services.ai.azure.com/model` 에 연결되어 있고 Entra ID(`https://cognitiveservices.azure.com/.default`)에 대한 올바른 범위를 표시했는지 확인합니다.
`404 Not found`	사용 중인 SDK에 따라 엔드포인트 URL이 잘못되거나 모델 배포가 없습니다.	올바른 엔드포인트에 연결된 올바른 SDK를 사용하고 있는지 확인합니다. 1. Azure AI 유추 SDK를 사용하는 경우 엔드포인트가 `https://<resource>.services.ai.azure.com/modelmodel="<model-deployment-name>"` 페이로드에 있는지 또는 엔드포인트가 `https://<resource>.openai.azure.com/deployments/<model-deployment-name>`있는지 확인합니다. 클래스를 `AzureOpenAI` 사용하는 경우 엔드포인트 `https://<resource>.openai.azure.com`가 .인지 확인합니다.

프로젝트에서 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를 구현하고 서비스를 사용하는 모든 애플리케이션에서 호환성 또는 대체 문제를 완전히 해결한 경우 키 기반 인증을 사용하지 않도록 설정하는 것이 좋습니다. 키 기반 인증을 사용하지 않도록 설정하는 것은 Bicep/ARM을 사용하여 배포할 때만 사용할 수 있습니다.

중요

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 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 사용자와 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다.

중요

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

다음 단계에 따라 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 리소스.
Cognitive Services 사용자 역할을 사용하는 대신 사용자 지정 역할 정의를 만들려면 역할에 다음 권한이 있는지 확인합니다.
```
{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/MaaS/*"
      ]
    }
  ]
}
```

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

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예제에서는 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"],
)

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(),
    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를 사용하여 채팅 완료를 사용하는 클라이언트를 만드는 방법을 보여 줍니다.

TokenCredential 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,
    clientOptions.
);

프로젝트에 패키지를 추가합니다.

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

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예에서는 채팅 완성을 이용하는 클라이언트를 만드는 방법을 보여 줍니다.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .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에서 다음 결정적 자격 증명 솔루션 중 하나로 전환할 것을 강력히 고려하십시오.
- TokenCredential와 같은 특정 ManagedIdentityCredential 구현. 옵션은 파생 목록을 참조하세요.
- 앱이 실행되는 Azure 환경에 최적화된 축소된 ChainedTokenCredential 구현입니다. ChainedTokenCredential기본적으로 프로덕션 및 개발과 ManagedIdentity 같은 VisualStudioCredential 허용 가능한 자격 증명 옵션의 특정 허용 목록을 만듭니다.
가능하면 코드가 실행되는 Azure 리소스에 시스템 할당 또는 사용자 할당 관리 ID를 구성합니다. 해당 특정 ID에 대한 Microsoft Entra ID 액세스를 구성합니다.

문제 해결

문제를 해결하기 전에 적절한 권한이 할당되었는지 확인합니다.

Azure Portal로 이동하여 사용 중인 Azure AI Services 리소스를 찾습니다.
왼쪽 창에서 액세스 제어(IAM) 를 선택한 다음 , 액세스 확인을 선택합니다.
서비스에 연결하는 데 사용하는 사용자 또는 ID의 이름을 입력합니다.
Cognitive Services 사용자가 나열된 역할(또는 필수 구성 요소에 설명된 대로 필요한 권한이 포함된 역할)인지 확인합니다.

중요

소유자 또는 참가자와 같은 역할은 Microsoft Entra ID를 통해 액세스를 제공하지 않습니다.
나열되지 않은 경우 계속하기 전에 이 가이드의 단계를 수행합니다.

다음 표에는 Microsoft Entra ID 문제를 해결하는 데 도움이 되는 여러 시나리오가 포함되어 있습니다.

오류/시나리오	근본 원인	솔루션
SDK를 사용하고 있습니다.	알려진 문제.	추가 문제 해결을 하기 전에 서비스에 연결하는 데 사용하는 최신 버전의 소프트웨어를 설치하는 것이 좋습니다. 사용 중인 소프트웨어의 최신 버전에서 인증 버그가 수정되었을 수 있습니다.
`401 Principal does not have access to API/Operation`	요청은 올바른 방법으로 인증을 나타내지만, 사용자 주체에는 추론 엔드포인트를 사용하는 데 필요한 권한이 없습니다.	다음을 가지고 있는지 확인하세요. 1. Azure AI 서비스 리소스에 대한 주체에게 Cognitive Services 사용자 역할을 할당했습니다. Cognitive Services OpenAI 사용자는 OpenAI 모델에 대한 액세스 권한만 부여합니다. 소유자 또는 참가자 는 액세스 권한을 제공하지 않습니다. 2. 첫 번째 호출을 하기 전에 5분 이상 기다립니다.
`401 HTTP/1.1 401 PermissionDenied`	요청은 올바른 방법으로 인증을 나타내지만, 사용자 주체에는 추론 엔드포인트를 사용하는 데 필요한 권한이 없습니다.	Azure AI 서비스 리소스에서 주체에게 Cognitive Services 사용자 역할을 할당했습니다. 역할은 관리자 또는 참가자와 같은 추론 액세스 권한을 부여하지 않습니다. 첫 번째 호출을 하기 전에 5분 이상 기다립니다.
REST API 호출을 사용하는 동안 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`가 발생합니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	헤더에 `Authentication` 범위 `https://cognitiveservices.azure.com/.default`가 있는 유효한 토큰이 포함되어 있는지 확인합니다.
당신이 `AzureOpenAI` 클래스를 사용하면 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`를 얻습니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	엔드포인트에 `https://<resource>.openai.azure.com` 사용하고 있는지 확인합니다. `OpenAI` 클래스나 Models-as-a-Service 모델을 사용할 수 없습니다. 모델이 OpenAI가 아닌 경우 Azure AI 유추 SDK를 사용합니다.
Azure AI Inference SDK를 사용하는 동안 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`가 발생합니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	엔드포인트 `https://<resource>.services.ai.azure.com/model` 에 연결되어 있고 Entra ID(`https://cognitiveservices.azure.com/.default`)에 대한 올바른 범위를 표시했는지 확인합니다.
`404 Not found`	사용 중인 SDK에 따라 엔드포인트 URL이 잘못되거나 모델 배포가 없습니다.	올바른 엔드포인트에 연결된 올바른 SDK를 사용하고 있는지 확인합니다. 1. Azure AI 유추 SDK를 사용하는 경우 엔드포인트가 `https://<resource>.services.ai.azure.com/modelmodel="<model-deployment-name>"` 페이로드에 있는지 또는 엔드포인트가 `https://<resource>.openai.azure.com/deployments/<model-deployment-name>`있는지 확인합니다. 클래스를 `AzureOpenAI` 사용하는 경우 엔드포인트 `https://<resource>.openai.azure.com`가 .인지 확인합니다.

중요

이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 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 사용자와 같은 역할을 사용하면 이러한 작업을 수행할 수 있습니다.

중요

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

다음 단계에 따라 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 리소스.
Cognitive Services 사용자 역할을 사용하는 대신 사용자 지정 역할 정의를 만들려면 역할에 다음 권한이 있는지 확인합니다.
```
{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/MaaS/*"
      ]
    }
  ]
}
```

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 User 역할이 있는 지정된 보안 주체에 대한 역할 할당입니다.

다음 자산을 사용하여 해당 리소스를 만듭니다.

템플릿 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: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
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 ID 사용

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

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

pip install azure-ai-inference

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예제에서는 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"],
)

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(),
    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를 사용하여 채팅 완료를 사용하는 클라이언트를 만드는 방법을 보여 줍니다.

TokenCredential 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,
    clientOptions.
);

프로젝트에 패키지를 추가합니다.

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

그런 다음 패키지를 사용하여 모델을 활용할 수 있습니다. 다음 예에서는 채팅 완성을 이용하는 클라이언트를 만드는 방법을 보여 줍니다.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .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에서 다음 결정적 자격 증명 솔루션 중 하나로 전환할 것을 강력히 고려하십시오.
- TokenCredential와 같은 특정 ManagedIdentityCredential 구현. 옵션은 파생 목록을 참조하세요.
- 앱이 실행되는 Azure 환경에 최적화된 축소된 ChainedTokenCredential 구현입니다. ChainedTokenCredential기본적으로 프로덕션 및 개발과 ManagedIdentity 같은 VisualStudioCredential 허용 가능한 자격 증명 옵션의 특정 허용 목록을 만듭니다.
가능하면 코드가 실행되는 Azure 리소스에 시스템 할당 또는 사용자 할당 관리 ID를 구성합니다. 해당 특정 ID에 대한 Microsoft Entra ID 액세스를 구성합니다.

문제 해결

문제를 해결하기 전에 적절한 권한이 할당되었는지 확인합니다.

Azure Portal로 이동하여 사용 중인 Azure AI Services 리소스를 찾습니다.
왼쪽 창에서 액세스 제어(IAM) 를 선택한 다음 , 액세스 확인을 선택합니다.
서비스에 연결하는 데 사용하는 사용자 또는 ID의 이름을 입력합니다.
Cognitive Services 사용자가 나열된 역할(또는 필수 구성 요소에 설명된 대로 필요한 권한이 포함된 역할)인지 확인합니다.

중요

소유자 또는 참가자와 같은 역할은 Microsoft Entra ID를 통해 액세스를 제공하지 않습니다.
나열되지 않은 경우 계속하기 전에 이 가이드의 단계를 수행합니다.

다음 표에는 Microsoft Entra ID 문제를 해결하는 데 도움이 되는 여러 시나리오가 포함되어 있습니다.

오류/시나리오	근본 원인	솔루션
SDK를 사용하고 있습니다.	알려진 문제.	추가 문제 해결을 하기 전에 서비스에 연결하는 데 사용하는 최신 버전의 소프트웨어를 설치하는 것이 좋습니다. 사용 중인 소프트웨어의 최신 버전에서 인증 버그가 수정되었을 수 있습니다.
`401 Principal does not have access to API/Operation`	요청은 올바른 방법으로 인증을 나타내지만, 사용자 주체에는 추론 엔드포인트를 사용하는 데 필요한 권한이 없습니다.	다음을 가지고 있는지 확인하세요. 1. Azure AI 서비스 리소스에 대한 주체에게 Cognitive Services 사용자 역할을 할당했습니다. Cognitive Services OpenAI 사용자는 OpenAI 모델에 대한 액세스 권한만 부여합니다. 소유자 또는 참가자 는 액세스 권한을 제공하지 않습니다. 2. 첫 번째 호출을 하기 전에 5분 이상 기다립니다.
`401 HTTP/1.1 401 PermissionDenied`	요청은 올바른 방법으로 인증을 나타내지만, 사용자 주체에는 추론 엔드포인트를 사용하는 데 필요한 권한이 없습니다.	Azure AI 서비스 리소스에서 주체에게 Cognitive Services 사용자 역할을 할당했습니다. 역할은 관리자 또는 참가자와 같은 추론 액세스 권한을 부여하지 않습니다. 첫 번째 호출을 하기 전에 5분 이상 기다립니다.
REST API 호출을 사용하는 동안 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`가 발생합니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	헤더에 `Authentication` 범위 `https://cognitiveservices.azure.com/.default`가 있는 유효한 토큰이 포함되어 있는지 확인합니다.
당신이 `AzureOpenAI` 클래스를 사용하면 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`를 얻습니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	엔드포인트에 `https://<resource>.openai.azure.com` 사용하고 있는지 확인합니다. `OpenAI` 클래스나 Models-as-a-Service 모델을 사용할 수 없습니다. 모델이 OpenAI가 아닌 경우 Azure AI 유추 SDK를 사용합니다.
Azure AI Inference SDK를 사용하는 동안 `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.`가 발생합니다.	요청이 Entra ID를 사용하여 인증을 수행하지 못했습니다.	엔드포인트 `https://<resource>.services.ai.azure.com/model` 에 연결되어 있고 Entra ID(`https://cognitiveservices.azure.com/.default`)에 대한 올바른 범위를 표시했는지 확인합니다.
`404 Not found`	사용 중인 SDK에 따라 엔드포인트 URL이 잘못되거나 모델 배포가 없습니다.	올바른 엔드포인트에 연결된 올바른 SDK를 사용하고 있는지 확인합니다. 1. Azure AI 유추 SDK를 사용하는 경우 엔드포인트가 `https://<resource>.services.ai.azure.com/modelmodel="<model-deployment-name>"` 페이로드에 있는지 또는 엔드포인트가 `https://<resource>.openai.azure.com/deployments/<model-deployment-name>`있는지 확인합니다. 클래스를 `AzureOpenAI` 사용하는 경우 엔드포인트 `https://<resource>.openai.azure.com`가 .인지 확인합니다.

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

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: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
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를 사용하는 경우 자격 증명 옵션

모범 사례

문제 해결

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

다음 단계

피드백

추가 리소스