.NET Aspire Azure OpenAI tümleştirmesi (Önizleme)

Içerir: Barındırma tümleştirmesi ve Client tümleştirmesi

Azure OpenAI Servisi, OpenAI'ın güçlü dil ve yerleştirme modellerine, Azure'in güvenlik ve kurumsal vaatleriyle erişim sağlar. .NET Aspire Azure OpenAI tümleştirmesi, .NET uygulamalarınızdan AzureOpenAI Hizmetine veya OpenAIAPI'sine bağlanmanızı sağlar.

Hosting entegrasyonu

Tümleştirme modellerini barındıran .NET.NET AspireAzure OpenAI, kaynakları AzureOpenAIResourceolarak AzureOpenAI. uygulama konağı projenizde bu türlere ve API'lere erişmek için 📦Aspire.Hosting.Azure.CognitiveServices NuGet paketini yükleyin.

dotnet add package Aspire.Hosting.Azure.CognitiveServices

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

Daha fazla bilgi için bkz. dotnet add package veya .NET uygulamalarında paket bağımlılıklarını yönetme.

Azure OpenAI kaynağı ekleme

Uygulama ana bilgisayar projenize bir AzureOpenAIResource eklemek için AddAzureOpenAI yöntemini çağırın:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Yukarıdaki kod, uygulama konak projesine openai adlı bir AzureOpenAI kaynağı ekler. WithReference yöntemi, bağlantı bilgilerini ExampleProject projesine geçirir.

Azure OpenAI dağıtım kaynağı ekleme

Azure OpenAI dağıtım kaynağı eklemek için AddDeployment(IResourceBuilder<AzureOpenAIResource>, AzureOpenAIDeployment) yöntemini çağırın:

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...

Önceki kod:

• openaiadlı bir AzureOpenAI kaynağı ekler.
• preview adlı, model adı gpt-4.5-previewolan bir AzureOpenAI dağıtım kaynağı ekler. Model adı, AzureOpenAI hizmetinde kullanılabilen model karşılık gelir.

Bicep için oluşturulan yapılandırma dosyası

Eğer Bicepdiline yeniyseniz, bu, Azure kaynaklarını tanımlamak için etki alanına özgü bir dildir. .NET .NET Aspireile Bicep'i elle yazmanız gerekmez; bunun yerine, sağlama API'leri Bicep'i sizin için oluşturur. Uygulamanızı yayımladığınızda, oluşturulan Bicep varsayılan standartlarla bir AzureOpenAI kaynağı sağlar.

@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}'

Yukarıdaki Bicep, Azure Bilişsel Hizmetler kaynağını aşağıdaki varsayılan değerlerle sağlayan bir modüldür:

• location: Kaynak grubunun konumu.
• principalType: Bilişsel Hizmetler kaynağının asıl türü.
• principalId: Bilişsel Hizmetler kaynağının asıl kimliği.
• openai: Bilişsel Hizmetler hesap kaynağı.
  • kind: OpenAIolarak ayarlanan kaynak türü.
  • properties: Kaynağın özellikleri.
    • customSubDomainName: Kaynak grubu kimliğinin benzersiz dizesini temel alan kaynak için özel alt etki alanı adı.
    • publicNetworkAccess: Enabledolarak ayarlayın.
    • disableLocalAuth: trueolarak ayarlayın.
  • sku: Kaynağın SKU'su S0olarak ayarlanır.
• openai_CognitiveServicesOpenAIContributor: Yerleşik Azure Cognitive Services OpenAI Contributor rolünü temel alan Bilişsel Hizmetler kaynak yöneticisi. Daha fazla bilgi için bkz. Azure Bilişsel Hizmetler OpenAI Katkıda Bulunan.
• preview: preview adına göre dağıtım kaynağı.
  • properties: Dağıtım kaynağının özellikleri.
    • format: Dağıtım kaynağının biçimi, OpenAIolarak ayarlanır.
    • modelName: Dağıtım kaynağının model adı gpt-4.5-previewolarak ayarlanmıştır.
    • modelVersion: Dağıtım kaynağının model sürümü 2025-02-27olarak ayarlanır.
• connectionString: Bilişsel Hizmetler kaynağının uç noktasını içeren bağlantı dizesi.

Oluşturulan Bicep bir başlangıç noktasıdır ve özel gereksinimlerinizi karşılayacak şekilde özelleştirilebilir.

Sağlama altyapısını özelleştirme

Tüm .NET AspireAzure kaynaklar AzureProvisioningResource türünün alt sınıflarıdır. Bu, ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API'sini kullanarak Azure kaynaklarını yapılandırmak için akıcı bir API sağlayarak oluşturulan Bicep'in özelleştirilmesini sağlar:

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

Önceki kod:

• bir çağrıyı ConfigureInfrastructure API'sine zincirler:
  • infra parametresi, AzureResourceInfrastructure türünün bir örneğidir.
  • Sağlanabilir kaynaklar GetProvisionableResources() yöntemi çağrılarak alınır.
  • Tek bir CognitiveServicesAccount kaynağı alınır.
  • CognitiveServicesAccount.Sku özelliği, E0 adı ve CognitiveServicesSkuTier.Enterprise katmanıyla yeni bir CognitiveServicesSku örneğine atanır.
  • Bilişsel Hizmetler kaynağına ExampleKey anahtarı ve Example valuedeğeriyle bir etiket eklenir.

Mevcut bir AzureOpenAI hizmetine bağlanma

Bağlanmak istediğiniz mevcut bir AzureOpenAI hizmetiniz olabilir. AzureOpenAIResource'ın mevcut bir kaynak olduğunu belirtmek için bir çağrıyı zincirleyebilirsiniz.

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 kaynakları mevcut kaynaklar olarak ele alma hakkında daha fazla bilgi için bkz. Var olan Azure kaynaklarını kullanma.

Alternatif olarak, bir AzureOpenAI kaynağını temsil etmek yerine uygulama konağına bir bağlantı dizesi ekleyebilirsiniz. Bu, yalnızca string değeri temel alan zayıf türlenmiş bir yaklaşımdır. Mevcut bir AzureOpenAI hizmetine bağlantı eklemek için AddConnectionString yöntemini çağırın:

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...

Bağlantı dizesi, uygulama ana bilgisayarının yapılandırmasında, genellikle Kullanıcı Gizli Dizileri altında, ConnectionStrings bölümü altında yapılandırılır:

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

Daha fazla bilgi için bkz. Bağlantı dizeleriyle var olan Azure kaynaklarını ekleme.

Client entegrasyon

.NET Aspire Azure OpenAI istemci tümleştirmesini kullanmaya başlamak için 📦Aspireyükleyin.Azure. AI. nuget paketini istemci kullanan projede, yani AzureOpenAI istemcisini kullanan uygulamanın projesindeOpenAI.

dotnet add package Aspire.Azure.AI.OpenAI

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

Azure OpenAI müşteri ekle

İstemciyi kullanan projenizin Program.cs dosyasında, bağımlılık ekleme (DI) için bir OpenAIClient kaydetmek üzere herhangi bir IHostApplicationBuilder üzerinde AddAzureOpenAIClient(IHostApplicationBuilder, String, Action<AzureOpenAISettings>, Action<IAzureClientBuilder<AzureOpenAIClient,AzureOpenAIClientOptions>>) yöntemini kullanın. AzureOpenAIClient, OpenAIClientalt sınıfıdır ve DI'den herhangi bir tür istemenizi sağlar. Bu, Azure'ye özgü özelliklere bağımlı olmayan kodun genel kalmasını sağlar. AddAzureOpenAIClient yöntemi bir bağlantı adı parametresi gerektirir.

builder.AddAzureOpenAIClient(connectionName: "openai");

OpenAIClientekledikten sonra, bağımlılık enjeksiyonu kullanarak istemci örneğini alabilirsiniz.

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

Daha fazla bilgi için bkz:

• Azure.AI.OpenAI belgeleri, OpenAIClientkullanma örnekleri için.
• Bağımlılık enjeksiyonu hakkında ayrıntılı bilgi için .NET.
• Hızlı Başlangıç: AzureOpenAI Serviceile GPT-35-Turbo ve GPT-4 kullanmaya başlayın.

Kayıtlı IChatClient olan AzureOpenAI istemcisini ekle

OpenAI istemcisiyle IChatClient arabirimini kullanmak istiyorsanız aşağıdaki API'lerden birini AddAzureOpenAIClient yöntemine zincirlemeniz yeterlidir:

• AddChatClient(AspireOpenAIClientBuilder, String): AspireOpenAIClientBuildertarafından sağlanan hizmetlere tek bir IChatClient'i kaydeder.
• AddKeyedChatClient(AspireOpenAIClientBuilder, String, String): AspireOpenAIClientBuildertarafından sağlanan hizmetlere anahtarlı bir tekil IChatClient kaydeder.

Örneğin, DI kapsayıcısına bir IChatClient ekleyen aşağıdaki C# kodunu göz önünde bulundurun:

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

Benzer şekilde, aşağıdaki C# koduyla anahtarlı bir IChatClient ekleyebilirsiniz:

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

IChatClient ve karşılık gelen kitaplığı hakkında daha fazla bilgi için .NET'de Yapay Zeka (Önizleme)bölümüne bakın.

Azure OpenAI istemci ayarlarını yapılandırma

.NET Aspire Azure OpenAI kitaplığı, AzureOpenAI istemcisini yapılandırmak için bir dizi ayar sağlar. AddAzureOpenAIClient yöntemi, Action<AzureOpenAISettings>?türünde isteğe bağlı bir configureSettings parametresini kullanıma sunar. Ayarları satır içinde yapılandırmak için aşağıdaki örneği göz önünde bulundurun:

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

Yukarıdaki kod, AzureOpenAISettings.DisableTracing özelliğini trueolarak ayarlar ve AzureOpenAISettings.Endpoint özelliğini AzureOpenAI uç noktasına ayarlar.

Azure OpenAI istemci oluşturucu seçeneklerini yapılandırma

İstemci için AzureOpenAIClientOptions'ı yapılandırmak üzere AddAzureOpenAIClient yöntemini kullanabilirsiniz. Bu yöntem, Action<IAzureClientBuilder<OpenAIClient, AzureOpenAIClientOptions>>?türünde isteğe bağlı bir configureClientBuilder parametresi alır. Aşağıdaki örneği göz önünde bulundurun:

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

İstemci oluşturucu, istemci seçeneklerini yapılandırmak için akıcı bir API sağlayan IAzureClientBuilder<TClient,TOptions> türünün bir örneğidir. Yukarıdaki kod, AzureOpenAIClientOptions.UserAgentApplicationId özelliğini CLIENT_IDolarak ayarlar. Daha fazla bilgi için bkz. ConfigureOptions(ChatClientBuilder, Action<ChatOptions>).

Yapılandırmadan AzureOpenAI istemcisi ekleme

Ayrıca paket, sağlanan bağlantı dizesini temel alan bir OpenAIClient veya AzureOpenAIClient örneği kaydetmek için AddOpenAIClientFromConfiguration(IHostApplicationBuilder, String) uzantısı yöntemini sağlar. Bu yöntem şu kuralları izler:

• Endpoint özniteliği boş veya eksikse, sağlanan anahtar kullanılarak bir OpenAIClient örneği kaydedilir, örneğin Key={key};.
• IsAzure özniteliği trueise bir AzureOpenAIClient kaydedilir; aksi takdirde, bir OpenAIClient kaydedilir, örneğin, Endpoint={azure_endpoint};Key={key};IsAzure=true bir AzureOpenAIClientkaydederken Endpoint=https://localhost:18889;Key={key} bir OpenAIClientkaydeder.
• Endpoint özniteliği ".azure."içeriyorsa, bir AzureOpenAIClient kaydedilir; aksi takdirde, bir OpenAIClient kaydedilir, örneğin, Endpoint=https://{account}.azure.com;Key={key};.

Aşağıdaki örneği göz önünde bulundurun:

builder.AddOpenAIClientFromConfiguration("openai");

Aşağıdaki örnek bağlantı dizelerini ve bir OpenAIClient veya AzureOpenAIClientkaydedip kaydetmediklerini göz önünde bulundurun:

Anahtarlı AzureOpenAI istemciler ekle

Farklı bağlantı adlarına sahip birden çok OpenAIClient örneğini kaydetmek istediğiniz durumlar olabilir. Anahtarlı AzureOpenAI istemcilerini kaydetmek için AddKeyedAzureOpenAIClient yöntemini çağırın:

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

Daha sonra bağımlılık enjeksiyonu kullanarak istemci örneklerine erişebilirsiniz. Örneğin, bir hizmetten müşterileri almak için:

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

Daha fazla bilgi için .NET Anahtarlı hizmetleri inceleyin.

Yapılandırmadan anahtarlı AzureOpenAI istemcileri ekle

Anahtarlı AzureOpenAI istemcileri için de, anahtarsız istemciler için olduğu gibi aynı işlevsellik ve kurallar geçerlidir. Sağlanan bağlantı dizesini temel alan bir OpenAIClient veya AzureOpenAIClient örneği kaydetmek için AddKeyedOpenAIClientFromConfiguration(IHostApplicationBuilder, String) uzantısı yöntemini kullanabilirsiniz.

Aşağıdaki örneği göz önünde bulundurun:

builder.AddKeyedOpenAIClientFromConfiguration("openai");

Bu yöntem, yapılandırmadan AzureOpenAI istemcisi eklemeayrıntılarıyla aynı kuralları izler.

Konfigürasyon

.NET Aspire Azure OpenAI kitaplığı, projenizin gereksinimlerine ve kurallarına göre AzureOpenAI bağlantısını yapılandırmak için birden çok seçenek sağlar. Ya bir Endpoint ya da ConnectionString sağlanması gerekir.

Bağlantı dizesi kullanma

ConnectionStrings yapılandırma bölümünden bir bağlantı dizesi kullanırken, builder.AddAzureOpenAIClientçağırırken bağlantı dizesinin adını sağlayabilirsiniz:

builder.AddAzureOpenAIClient("openai");

Bağlantı dizesi ConnectionStrings yapılandırma bölümünden alınır ve desteklenen iki biçim vardır:

Hesap uç noktası

Önerilen yaklaşım, bağlantı kurmak için özelliğiyle çalışan bir AzureOpenAISettings.Credentialkullanmaktır. Hiçbir kimlik bilgisi yapılandırılmamışsa, DefaultAzureCredential kullanılır.

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

Daha fazla bilgi için , AzureOpenAI'yi anahtarlar olmadan kullanma'e bakın.

Bağlantı dizesi

Alternatif olarak, özel bir bağlantı dizesi kullanılabilir:

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

Azure OpenAI olmayan hizmete bağlanmak için Endpoint özelliğini bırakın ve yalnızca Key özelliğini API anahtarınıayarlayacak şekilde ayarlayın.

Yapılandırma sağlayıcılarını kullanma

.NET Aspire Azure OpenAI entegrasyonu Microsoft.Extensions.Configurationdestekler. AzureOpenAISettings anahtarını kullanarak yapılandırmadan Aspire:Azure:AI:OpenAI yükler. Bazı seçenekleri yapılandıran örnek appsettings.json:

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

tüm AzureOpenAI istemci tümleştirmesi JSON şeması için bkz. Aspire.Azure. AI.OpenAI/ConfigurationSchema.json.

Yerleşik temsilcileri kullan.

Satır içi seçeneklerin bazılarını veya tümünü ayarlamak için Action<AzureOpenAISettings> configureSettings temsilcisini geçirebilirsiniz, örneğin koddan izlemeyi devre dışı bırakmak için:

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

AddAzureOpenAIClient yönteminin isteğe bağlı Action<IAzureClientBuilder<OpenAIClient, OpenAIClientOptions>> configureClientBuilder parametresini kullanarak OpenAIClientOptions'u da ayarlayabilirsiniz. Örneğin, bu istemcinin istemci kimliğini ayarlamak için:

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

Gözlemlenebilirlik ve telemetri

tümleştirmeleri, bazengözlemlenebilirliğin sütunları olarak bilinen Günlük, İzleme ve Ölçüm yapılandırmalarını otomatik olarak ayarlar. Tümleştirme gözlemlenebilirliği ve telemetri hakkında daha fazla bilgi için bkz. tümleştirmelere genel bakış. Yedekleme hizmetine bağlı olarak, bazı tümleştirmeler bu özelliklerden yalnızca bazılarını destekleyemeyebilir. Örneğin, bazı tümleştirmeler izlemeyi ve günlüğe kaydetmeyi destekler, ancak ölçümleri desteklemez. Telemetri özellikleri, Yapılandırma bölümünde sunulan teknikler kullanılarak da devre dışı bırakılabilir.

Kayıt işlemi

.NET Aspire Azure OpenAI tümleştirmesi, aşağıdaki günlük kategorilerini kullanır:

• Azure
• Azure.Core
• Azure.Identity

İzleme

.NET Aspire Azure OpenAI tümleştirmesi, OpenAIClientile gerçekleştirilen işlemler için OpenTelemetry kullanarak izleme etkinliklerini üretir.

Ayrıca bkz.

• Azure OpenAI
• .NET .NET Aspire tümleştirmelerine genel bakış
• .NET Aspire Azure tümleştirmelerine genel bakış
• .NET Aspire GitHub depo