интеграция .NET AspireAzureOpenAI (предварительная версия)

включает в себя: интеграцию хостинга и Client интеграцию

Azure OpenAI сервис предоставляет доступ к мощным языковым и моделям внедрения от OpenAIс обеспечением безопасности и корпоративным уровнем от Azure. Интеграция .NET AspireAzureOpenAI позволяет подключаться к службе AzureOpenAI или API OpenAIиз приложений .NET.

Хостинг-интеграция

.NET .NET Aspire Azure OpenAI хостинг моделей интеграции AzureOpenAI ресурсов как AzureOpenAIResource. Чтобы получить доступ к этим типам и API для выражения их в проекте хоста приложения , установите пакет NuGet 📦Aspire.Hosting.Azure.CognitiveServices:

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

Дополнительные сведения см. в статье dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Добавьте ресурс AzureOpenAI

Чтобы добавить 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...

Приведенный выше код добавляет ресурс AzureOpenAI с именем openai в проект узла приложения. Метод WithReference передает сведения о подключении в проект ExampleProject.

Добавление ресурса развертывания AzureOpenAI

Чтобы добавить ресурс развертывания AzureOpenAI, вызовите метод 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...

Предыдущий код:

• Добавляет ресурс AzureOpenAI с именем openai.
• Добавляет ресурс развертывания AzureOpenAI с названием preview и именем модели gpt-4.5-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 — это модуль, который подготавливает ресурс Cognitive Services с идентификатором Azure со следующими параметрами по умолчанию.

• location: расположение группы ресурсов.
• principalType: основной тип ресурса когнитивных сервисов.
• principalId: основной идентификатор ресурса Cognitive Services.
• openai: ресурс учетной записи службы Cognitive Services.
  • kind: тип ресурса, установленный на OpenAI.
  • properties: свойства ресурса.
    • customSubDomainName: настраиваемое имя поддомена ресурса на основе уникальной строки идентификатора группы ресурсов.
    • publicNetworkAccess: задано значение Enabled.
    • disableLocalAuth: задано значение true.
  • sku: номер SKU ресурса, установите значение S0.
• openai_CognitiveServicesOpenAIContributor: владелец ресурса Cognitive Services, основанный на встроенной роли Azure Cognitive Services OpenAI Contributor. Дополнительные сведения см. в разделе 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. Это позволяет настроить созданный Bicep, предоставляя гибкий API для конфигурации ресурсов Azure с помощью API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>).

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");
    });

Предыдущий код:

• Связывает вызов с API ConfigureInfrastructure:
  • Параметр infra является экземпляром типа AzureResourceInfrastructure.
  • Ресурсы, доступные для предоставления, извлекаются через вызов метода GetProvisionableResources().
  • Извлекается один CognitiveServicesAccount ресурс.
  • Свойство CognitiveServicesAccount.Sku назначается новому экземпляру CognitiveServicesSku с именем E0 и уровнем CognitiveServicesSkuTier.Enterprise.
  • В ресурс 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...

Дополнительные сведения об обработке AzureOpenAI ресурсов в качестве существующих ресурсов см. в разделе Использование существующих 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 AspireAzureOpenAI, установите 📦Aspire.Azure.AI.OpenAI пакет NuGet в проекте, который использует клиента, то есть проект приложения, которое использует клиента AzureOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

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

Добавить клиента AzureOpenAI

В файле Program.cs проекта, используюющего клиент, используйте метод AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) для любой IHostApplicationBuilder, чтобы зарегистрировать OpenAIClient для внедрения зависимостей (DI). AzureOpenAIClient — это подкласс OpenAIClient, позволяющий запрашивать любой тип из DI. Это гарантирует, что код не зависит от специфических особенностей Azureи остается универсальным. Для метода AddAzureOpenAIClient требуется параметр имени подключения.

builder.AddAzureOpenAIClient(connectionName: "openai");

После добавления OpenAIClientвы можете получить экземпляр клиента с помощью инъекции зависимостей.

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

Дополнительные сведения можно найти здесь

• Azure.ИИ.OpenAI см. документацию по использованию OpenAIClient.
• Подробнее о внедрении зависимостей в .NET.
• Быстрый старт: Начало работы с GPT-35-Turbo и GPT-4 с сервисом AzureOpenAI.

Добавьте клиента AzureOpenAI с зарегистрированным IChatClient

Если вы хотите использовать интерфейс IChatClient с клиентом OpenAI, просто прицепите любой из следующих API к методу AddAzureOpenAIClient:

• AddChatClient(AspireOpenAIClientBuilder, String): регистрирует синглтон IChatClient в службах, предоставляемых AspireOpenAIClientBuilder.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): регистрирует ключ одноэлементный IChatClient в службах, предоставляемых AspireOpenAIClientBuilder.

Например, рассмотрим следующий код C#, который добавляет IChatClient в контейнер DI:

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

Аналогичным образом можно добавить ключевой элемент IChatClient с использованием следующего кода на C#:

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

Дополнительные сведения о IChatClient и соответствующей библиотеке см. в разделе Искусственный интеллект в .NET (предварительная версия).

Настройка параметров клиента AzureOpenAI

Библиотека .NET AspireAzureOpenAI предоставляет набор параметров для настройки клиента AzureOpenAI. Метод AddAzureOpenAIClient предоставляет необязательный параметр configureSettings типа Action<AzureOpenAISettings>?. Чтобы настроить параметры напрямую, рассмотрим следующий пример:

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.

Настройка параметров построителя клиентов AzureOpenAI

Чтобы настроить AzureOpenAIClientOptions для клиента, можно использовать метод AddAzureOpenAIClient. Этот метод принимает необязательный параметр configureClientBuilder типа Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?. Рассмотрим следующий пример:

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

Построитель клиентов — это экземпляр типа IAzureClientBuilder<TClient,TOptions>, который предоставляет простой API для настройки параметров клиента. Предыдущий код задает для свойства AzureOpenAIClientOptions.UserAgentApplicationId значение CLIENT_ID. Дополнительные сведения см. в разделе ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Добавление клиента AzureOpenAI из конфигурации

Кроме того, пакет предоставляет метод расширения AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) для регистрации экземпляра OpenAIClient или AzureOpenAIClient в зависимости от указанной строки подключения. Этот метод следует этим правилам:

• Если атрибут Endpoint пуст или отсутствует, OpenAIClient экземпляр регистрируется с помощью предоставленного ключа, например Key={key};.
• Если атрибут IsAzuretrue, регистрируется AzureOpenAIClient; в противном случае регистрируется OpenAIClient, например, Endpoint={azure_endpoint};Key={key};IsAzure=true регистрирует AzureOpenAIClient, а 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 с разными именами соединений. Чтобы зарегистрировать клиентов с идентификаторами AzureиOpenAI, вызовите метод AddKeyedAzureOpenAIClient:

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

Затем можно получить экземпляры клиента с помощью внедрения зависимостей. Например, чтобы получить клиентов из сервиса:

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

Для получения дополнительной информации см. раздел «Ключевые услуги» в .NET.

Добавление ключей AzureOpenAI клиентов из конфигурации

Та же функциональность и правила применимы к клиентам с ключами AzureOpenAI, как и к клиентам без ключей. Метод расширения AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) можно использовать для регистрации экземпляра OpenAIClient или AzureOpenAIClient на основании предоставленной строки подключения.

Рассмотрим следующий пример:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Этот метод следует тем же правилам, что и в Добавить AzureOpenAI клиент из конфигурации.

Конфигурация

Библиотека .NET AspireAzureOpenAI предоставляет несколько вариантов настройки подключения AzureOpenAI на основе требований и соглашений проекта. Необходимо предоставить Endpoint или ConnectionString.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове builder.AddAzureOpenAIClient:

builder.AddAzureOpenAIClient("openai");

Строка подключения извлекается из раздела конфигурации ConnectionStrings и существует два поддерживаемых формата:

Конечная точка учетной записи

Рекомендуемый подход — использовать конечную точку, которая работает со свойством AzureOpenAISettings.Credential, чтобы установить подключение. Если учетные данные не настроены, используется DefaultAzureCredential.

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

Дополнительные сведения см. в разделе Использование AzureOpenAI без ключей.

Строка подключения

Кроме того, можно использовать настраиваемую строку подключения:

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

Чтобы подключиться к службе, отличной отAzureOpenAI, удалите свойство Endpoint и задайте только свойство Key, чтобы задать ключ API .

Использование поставщиков конфигураций

Интеграция .NET AspireAzureOpenAI поддерживает Microsoft.Extensions.Configuration. Он загружает AzureOpenAISettings из конфигурации, используя ключ Aspire:Azure:AI:OpenAI. Пример appsettings.json, который настраивает некоторые параметры:

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

Полный AzureOpenAI схеме интеграции с клиентом JSON см. в Aspire.Azure. Искусственный интеллект.OpenAI/ConfigurationSchema.json.

Использование встроенных делегатов

Чтобы настроить некоторые или все параметры непосредственно в коде, можно передать делегат Action<AzureOpenAISettings> configureSettings, например, чтобы отключить трассировку из кода.

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

Вы также можете настроить OpenAIClientOptions с помощью необязательного параметра Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder метода AddAzureOpenAIClient. Например, чтобы задать идентификатор клиента для этого клиента:

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

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации логирования, трассировки и метрик, которые иногда называют пилонами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireAzureOpenAI использует следующие категории журналов:

• Azure
• Azure.Core
• Azure.Identity

Отслеживание

Интеграция .NET AspireAzureOpenAI осуществляет трассировку операций с использованием OpenTelemetry для операций, выполняемых с OpenAIClient.

См. также

• Azure OpenAI
• Обзор интеграции
• Обзор интеграции
• .NET Aspire GitHub репозиторий