.NET Aspire Azure OpenAI 통합(미리 보기)

포함: 호스팅 통합 및 Client 통합

Azure OpenAI Service는 OpenAI의 강력한 언어 및 삽입 모델에 대한 액세스를 제공하고, Azure의 보안과 엔터프라이즈 약속으로 이를 활용할 수 있게 합니다. .NET Aspire Azure OpenAI 통합을 사용하면 .NET 애플리케이션에서 AzureOpenAI Service 또는 OpenAIAPI에 연결할 수 있습니다.

호스팅 통합

.NET .NET Aspire Azure OpenAI 호스팅 통합 모델은 AzureOpenAI 리소스를 AzureOpenAIResource로. 앱 호스트 프로젝트 내에서 이러한 형식 및 API를 표현하기 위해, 📦Aspire.Hosting.Azure.CognitiveServices NuGet 패키지를 설치하십시오.

dotnet add package Aspire.Hosting.Azure.CognitiveServices

<PackageReference Include="Aspire.Hosting.Azure.CognitiveServices"
                  Version="*" />

자세한 내용은 dotnet add package 또는 응용 프로그램에서 패키지 종속성을 관리하기 .NET를 참조하십시오.

Azure OpenAI 리소스 추가

앱 호스트 프로젝트에 AzureOpenAIResource 추가하려면 AddAzureOpenAI 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

앞의 코드는 앱 호스트 프로젝트에 openaiAzureOpenAI 리소스를 추가합니다. WithReference 메서드는 연결 정보를 ExampleProject 프로젝트에 전달합니다.

Azure OpenAI 배포 리소스 추가

Azure OpenAI 배포 리소스를 추가하려면 AddDeployment(IResourceBuilder<AzureOpenAIResource>, AzureOpenAIDeployment) 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddAzureOpenAI("openai");
openai.AddDeployment(
    new AzureOpenAIDeployment(
        name: "preview",
        modelName: "gpt-4.5-preview",
        modelVersion: "2025-02-27"));

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai)
       .WaitFor(openai);

// After adding all resources, run the app...

앞의 코드는 다음과 같습니다.

• openai라는 AzureOpenAI 리소스를 추가합니다.
• Azure OpenAI 배포 리소스에 모델 이름이 gpt-4.5-preview인 preview를 추가합니다. 모델 이름은 AzureOpenAI 서비스에서 사용 가능한 모델 해당해야 합니다.

Bicep 프로비저닝 생성 완료

Bicep 에 대해 처음 접하신다면, 이는 Azure 리소스를 정의하기 위한 도메인별 언어입니다. .NET .NET Aspire사용하면 Bicep을 직접 작성할 필요가 없으며 프로비전 API는 Bicep을 생성합니다. 앱을 게시할 때 생성된 Bicep은 표준 기본값으로 AzureOpenAI 리소스를 프로비전합니다.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  name: take('openai-${uniqueString(resourceGroup().id)}', 64)
  location: location
  kind: 'OpenAI'
  properties: {
    customSubDomainName: toLower(take(concat('openai', uniqueString(resourceGroup().id)), 24))
    publicNetworkAccess: 'Enabled'
    disableLocalAuth: true
  }
  sku: {
    name: 'S0'
  }
  tags: {
    'aspire-resource-name': 'openai'
  }
}

resource openai_CognitiveServicesOpenAIContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(openai.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'a001fd3d-188f-4b5d-821b-7da978bf7442'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'a001fd3d-188f-4b5d-821b-7da978bf7442')
    principalType: principalType
  }
  scope: openai
}

resource preview 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = {
  name: 'preview'
  properties: {
    model: {
      format: 'OpenAI'
      name: 'gpt-4.5-preview'
      version: '2025-02-27'
    }
  }
  sku: {
    name: 'Standard'
    capacity: 8
  }
  parent: openai
}

output connectionString string = 'Endpoint=${openai.properties.endpoint}'

위의 Bicep은 다음 기본값으로 Azure Cognitive Services 리소스를 프로비전하는 모듈입니다.

• location: 리소스 그룹의 위치입니다.
• principalType: Cognitive Services 리소스의 주요 유형입니다.
• principalId: Cognitive Services 리소스의 주체 ID입니다.
• openai: Cognitive Services 계정 리소스입니다.
  • kind: 리소스의 종류는 OpenAI로 설정됩니다.
  • properties: 리소스의 속성입니다.
    • customSubDomainName: 리소스 그룹 ID의 고유 문자열에 따라 리소스에 대한 사용자 지정 하위 도메인 이름입니다.
    • publicNetworkAccess: Enabled로 설정.
    • disableLocalAuth: true로 설정.
  • sku: S0로 설정된 리소스의 SKU입니다.
• openai_CognitiveServicesOpenAIContributor: 내장된 Azure Cognitive Services OpenAI Contributor 역할에 기반한 Cognitive Services 리소스 소유자입니다. 자세한 내용은 Azure Cognitive Services OpenAI 기여자참조하세요.
• preview: preview 이름을 기반으로 하는 배포 리소스입니다.
  • properties: 배포 리소스의 속성입니다.
    • format: 배포 리소스의 형식은 OpenAI로 설정됩니다.
    • modelName: 배포 리소스의 모델 이름은 gpt-4.5-preview로 설정됩니다.
    • modelVersion: 2025-02-27설정되는 배포 리소스의 모델 버전입니다.
• connectionString: Cognitive Services 리소스의 엔드포인트를 포함하는 연결 문자열입니다.

생성된 Bicep은 시작 지점이며 특정 요구 사항을 충족하도록 사용자 지정할 수 있습니다.

프로비저닝 인프라 사용자 지정

모든 .NET AspireAzure 리소스는 AzureProvisioningResource 형식의 하위 클래스입니다. 이렇게 하면 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API를 사용하여 Azure 리소스를 구성하는 흐름 API를 제공하여 생성된 Bicep을 사용자 지정할 수 있습니다.

builder.AddAzureOpenAI("openai")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();
        var account = resources.OfType<CognitiveServicesAccount>().Single();

        account.Sku = new CognitiveServicesSku
        {
            Tier = CognitiveServicesSkuTier.Enterprise,
            Name = "E0"
        };
        account.Tags.Add("ExampleKey", "Example value");
    });

앞의 코드는 다음과 같습니다.

• ConfigureInfrastructure API에 대한 호출을 연결합니다.
  • infra 매개 변수는 AzureResourceInfrastructure 형식의 인스턴스입니다.
  • 프로비전 가능한 리소스는 GetProvisionableResources() 메서드를 호출하여 검색됩니다.
  • 단일 CognitiveServicesAccount 리소스가 검색됩니다.
  • CognitiveServicesAccount.Sku 속성은 E0 이름 및 CognitiveServicesSkuTier.Enterprise 계층을 사용하여 CognitiveServicesSku 새 인스턴스에 할당됩니다.
  • Cognitive Services 리소스에 ExampleKey 키와 Example value값을 가진 태그가 추가됩니다.

기존 AzureOpenAI 서비스에 연결

연결하려는 기존 AzureOpenAI 서비스가 있을 수 있습니다. AzureOpenAIResource이(가) 기존 리소스임을 주석으로 표시하기 위한 호출을 체인할 수 있습니다.

var builder = DistributedApplication.CreateBuilder(args);

var existingOpenAIName = builder.AddParameter("existingOpenAIName");
var existingOpenAIResourceGroup = builder.AddParameter("existingOpenAIResourceGroup");

var openai = builder.AddAzureOpenAI("openai")
                    .AsExisting(existingOpenAIName, existingOpenAIResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

Azure OpenAI 리소스를 기존 리소스로 처리하는 방법에 대한 자세한 내용은 기존 Azure 리소스 사용을 참조하세요.

또는 AzureOpenAI 리소스를 나타내는 대신 앱 호스트에 연결 문자열을 추가할 수 있습니다. 이는 string 값만을 기반으로 하는 약한 형식의 접근 방식입니다. 기존 AzureOpenAI 서비스에 대한 연결을 추가하려면 AddConnectionString 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureOpenAI("openai")
    : builder.AddConnectionString("openai");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(openai);

// After adding all resources, run the app...

연결 문자열은 앱 호스트의 구성에서 구성되며, 일반적으로 사용자 비밀 아래의 ConnectionStrings 섹션에서 구성됩니다.

{
  "ConnectionStrings": {
    "openai": "https://{account_name}.openai.azure.com/"
  }
}

자세한 내용은 연결 문자열이 있는 Azure 리소스 추가를 참조하세요.

Client 통합

.NET Aspire Azure OpenAI 클라이언트 통합을 시작하려면 📦Aspire.Azure.AI.를 설치합니다. 클라이언트를 사용하는 프로젝트에서OpenAI NuGet 패키지를 설치하는데, 이는 AzureOpenAI 클라이언트를 사용하는 애플리케이션의 프로젝트를 의미합니다.

dotnet add package Aspire.Azure.AI.OpenAI

<PackageReference Include="Aspire.Azure.AI.OpenAI"
                  Version="*" />

Azure OpenAI 클라이언트 추가

클라이언트 사용 프로젝트의 Program.cs 파일에서 모든 IHostApplicationBuilder에 대해 AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) 메서드를 사용하여 DI(종속성 주입)를 위한 OpenAIClient를 등록합니다. AzureOpenAIClient OpenAIClient하위 클래스이므로 DI에서 두 형식 중 하나를 요청할 수 있습니다. 이로 인해 Azure에 특정된 기능에 의존하지 않는 코드는 보편적 상태로 남게 됩니다. AddAzureOpenAIClient 메서드에는 연결 이름 매개 변수가 필요합니다.

builder.AddAzureOpenAIClient(connectionName: "openai");

OpenAIClient추가한 후 종속성 주입을 사용하여 클라이언트 인스턴스를 검색할 수 있습니다.

public class ExampleService(OpenAIClient client)
{
    // Use client...
}

자세한 내용은 다음을 참조하세요.

• Azure.AI.OpenAI 설명서에서 OpenAIClient사용하는 예제는에 있습니다.
• 종속성 주입은 입니다. 종속성 주입에 대한 자세한 내용은 .NET를 참조하십시오.
• 빠른 시작: AzureOpenAI Service를 활용하여 GPT-35-Turbo와 GPT-4를 사용하기 시작합니다.

등록된 IChatClient 사용하여 AzureOpenAI 클라이언트 추가

OpenAI 클라이언트와 함께 IChatClient 인터페이스를 사용하려는 경우 다음 API 중 하나를 AddAzureOpenAIClient 메서드에 연결하기만 하면 됩니다.

• AddChatClient(AspireOpenAIClientBuilder, String): AspireOpenAIClientBuilder가 제공하는 서비스에 싱글톤 IChatClient을 등록합니다.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): AspireOpenAIClientBuilder제공하는 서비스에 키 지정된 싱글톤 IChatClient 등록합니다.

예를 들어 DI 컨테이너에 IChatClient 추가하는 다음 C# 코드를 고려합니다.

builder.AddAzureOpenAIClient(connectionName: "openai")
       .AddChatClient("deploymentName");

마찬가지로 다음 C# 코드를 사용하여 키 입력 IChatClient 추가할 수 있습니다.

builder.AddAzureOpenAIClient(connectionName: "openai")
       .AddKeyedChatClient("serviceKey", "deploymentName");

IChatClient 해당 라이브러리와 관련된 자세한 내용은 .NET(미리 보기)인공 지능을 참조하세요.

Azure OpenAI 클라이언트 설정 구성

.NET Aspire Azure OpenAI 라이브러리는 AzureOpenAI 클라이언트를 구성하는 설정 집합을 제공합니다. AddAzureOpenAIClient 메서드는 Action<AzureOpenAISettings>?형식의 선택적 configureSettings 매개 변수를 노출합니다. 설정을 인라인으로 구성하려면 다음 예제를 고려하세요.

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureSettings: settings =>
    {
        settings.DisableTracing = true;

        var uriString = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
            ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

        settings.Endpoint = new Uri(uriString);
    });

앞의 코드는 AzureOpenAISettings.DisableTracing 속성을 true설정하고 AzureOpenAISettings.Endpoint 속성을 AzureOpenAI 엔드포인트로 설정합니다.

Azure OpenAI 클라이언트 작성기 옵션 구성

클라이언트에 대한 AzureOpenAIClientOptions 구성하려면 AddAzureOpenAIClient 메서드를 사용할 수 있습니다. 이 메서드는 Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?형식의 선택적 configureClientBuilder 매개 변수를 사용합니다. 다음 예제를 고려하세요.

builder.AddAzureOpenAIClient(
    connectionName: "openai",
    configureClientBuilder: clientBuilder =>
    {
        clientBuilder.ConfigureOptions(options =>
        {
            options.UserAgentApplicationId = "CLIENT_ID";
        });
    });

클라이언트 작성기는 클라이언트 옵션을 구성하는 흐름 API를 제공하는 IAzureClientBuilder<TClient,TOptions> 형식의 인스턴스입니다. 앞의 코드는 AzureOpenAIClientOptions.UserAgentApplicationId 속성을 CLIENT_ID설정합니다. 자세한 내용은 ConfigureOptions(ChatClientBuilder, Action<ChatOptions>)를 참조하세요.

구성에서 AzureOpenAI 클라이언트 추가

또한 패키지는 제공된 연결 문자열에 따라 OpenAIClient 또는 AzureOpenAIClient 인스턴스를 등록하는 AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) 확장 메서드를 제공합니다. 이 메서드는 다음 규칙을 따릅니다.

• Endpoint 특성이 비어 있거나 누락된 경우 제공된 키(예: Key={key};)를 사용하여 OpenAIClient 인스턴스가 등록됩니다.
• IsAzure 특성이 true경우 AzureOpenAIClient 등록됩니다. 그렇지 않으면 OpenAIClient 등록됩니다(예: Endpoint={azure_endpoint};Key={key};IsAzure=trueAzureOpenAIClient등록하는 반면 Endpoint=https://localhost:18889;Key={key}OpenAIClient등록합니다.
• Endpoint 특성에 ".azure."포함된 경우 AzureOpenAIClient 등록됩니다. 그렇지 않으면 OpenAIClient 등록됩니다(예: Endpoint=https://{account}.azure.com;Key={key};).

다음 예제를 고려하세요.

builder.AddOpenAIClientFromConfiguration("openai");

다음 연결 문자열 예제와 OpenAIClient 등록할지 또는 AzureOpenAIClient등록하는지를 고려합니다.

키 AzureOpenAI 클라이언트 추가

여러 OpenAIClient 인스턴스를 서로 다른 연결 이름으로 등록하려는 경우가 있을 수 있습니다. 키 AzureOpenAI 클라이언트를 등록하려면 AddKeyedAzureOpenAIClient 메서드를 호출합니다.

builder.AddKeyedAzureOpenAIClient(name: "chat");
builder.AddKeyedAzureOpenAIClient(name: "code");

그런 다음 종속성 주입을 사용하여 클라이언트 인스턴스를 검색할 수 있습니다. 예를 들어 서비스에서 클라이언트를 검색하려면 다음을 수행합니다.

public class ExampleService(
    [KeyedService("chat")] OpenAIClient chatClient,
    [KeyedService("code")] OpenAIClient codeClient)
{
    // Use clients...
}

자세한 내용은 Keyed 서비스에 대한 정보를 .NET에서 참조하세요.

구성에서 키 지정된 AzureOpenAI 클라이언트 추가

키가 지정되지 않은 클라이언트와 동일한 기능 및 규칙이 키 AzureOpenAI 클라이언트에 존재합니다. AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) 확장 메서드를 사용하여 제공된 연결 문자열에 따라 OpenAIClient 또는 AzureOpenAIClient 인스턴스를 등록할 수 있습니다.

다음 예제를 고려하세요.

builder.AddKeyedOpenAIClientFromConfiguration("openai");

이 메서드는 구성 Add AzureOpenAI 클라이언트에 설명된 것과 동일한 규칙을 따릅니다.

구성

.NET Aspire Azure OpenAI 라이브러리는 프로젝트의 요구 사항 및 규칙에 따라 AzureOpenAI 연결을 구성하는 여러 옵션을 제공합니다. Endpoint 또는 ConnectionString 중 하나를 제공해야 합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 builder.AddAzureOpenAIClient호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddAzureOpenAIClient("openai");

연결 문자열은 ConnectionStrings 구성 섹션에서 검색되며 지원되는 두 가지 형식이 있습니다.

계정 엔드포인트

권장되는 방법은 속성과 함께 작동하는 AzureOpenAISettings.Credential사용하여 연결을 설정하는 것입니다. 자격 증명이 구성되지 않은 경우 DefaultAzureCredential 사용됩니다.

{
  "ConnectionStrings": {
    "openai": "https://{account_name}.openai.azure.com/"
  }
}

자세한 내용은 키 없이 사용을 참조하세요.

연결 문자열

또는 사용자 지정 연결 문자열을 사용할 수 있습니다.

{
  "ConnectionStrings": {
    "openai": "Endpoint=https://{account_name}.openai.azure.com/;Key={account_key};"
  }
}

비AzureOpenAI 서비스에 연결하려면 Endpoint 속성을 삭제하고 키 속성만 설정하여 API 키설정합니다.

구성 공급자 사용

.NET Aspire Azure OpenAI 통합은 Microsoft.Extensions.Configuration지원합니다. 구성에서 AzureOpenAISettings 키를 사용해 Aspire:Azure:AI:OpenAI을 로드합니다. 몇 가지 옵션을 구성하는 예제 appsettings.json:

{
  "Aspire": {
    "Azure": {
      "AI": {
        "OpenAI": {
          "DisableTracing": false
        }
      }
    }
  }
}

전체 AzureOpenAI 클라이언트 통합 JSON 스키마는 Aspire참조하세요.Azure. AI.OpenAI/ConfigurationSchema.json.

인라인 대리자를 사용하세요

Action<AzureOpenAISettings> configureSettings 대리자를 전달하여 코드에서 추적을 사용하지 않도록 설정하는 등 일부 또는 모든 옵션을 인라인으로 설정할 수 있습니다.

builder.AddAzureOpenAIClient(
    "openai",
    static settings => settings.DisableTracing = true);

AddAzureOpenAIClient 메서드의 선택적 Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder 매개 변수를 사용하여 OpenAIClientOptions를 설정할 수도 있습니다. 예를 들어 이 클라이언트에 대한 클라이언트 ID를 설정하려면 다음을 수행합니다.

builder.AddAzureOpenAIClient(
    "openai",
    configureClientBuilder: builder => builder.ConfigureOptions(
        options => options.Diagnostics.ApplicationId = "CLIENT_ID"));

관찰 가능성 및 원격 분석

.NET .NET Aspire 통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이는 때때로 관찰성의 기둥이라고도 합니다. 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire Azure OpenAI 통합은 다음 로그 범주를 사용합니다.

• Azure
• Azure.Core
• Azure.Identity

추적

.NET Aspire Azure OpenAI 통합은 OpenAIClient로 수행된 작업에 대해 OpenTelemetry을 사용하여 추적 활동을 내보낸다.

참고 자료

• Azure OpenAI
• .NET .NET Aspire 통합 개요
• .NET Aspire Azure 통합 개요
• .NET Aspire GitHub repo