Aspire Azure AI 推理集成（预览版）

包括：Client 集成 - 托管集成

Aspire Azure AI 推理集成提供了在云中部署和管理机器学习模型的无缝方法。 此集成使你能够利用Azure的AI服务的强大功能，同时保持Aspire的灵活性和易用性。

托管集成

Azure尽管 AI 推理库当前不提供直接托管集成，但仍可将其集成到 AppHost 项目中。 只需添加连接字符串即可建立对现有 Azure AI Foundry 资源的引用。

连接到现有的 Azure AI Foundry 服务

如果已有 Azure AI Foundry 服务，可以通过向 AppHost 添加连接字符串轻松连接到它。 此方法使用简单的基于字符串的配置。 若要建立连接，请使用 AddConnectionString 以下方法：

var builder = DistributedApplication.CreateBuilder(args);

var aiFoundry = builder.AddConnectionString("ai-foundry");

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

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

连接字符串在 AppHost 的配置中配置，通常位于“用户机密”部分下 ConnectionStrings ：

{
  "ConnectionStrings": {
    "ai-foundry": "Endpoint=https://{endpoint}/;DeploymentId={deploymentName}"
  }
}

有关详细信息，请参阅 添加包含连接字符串的现有 Azure 资源。

Client 集成

若要开始使用 AspireAzure AI 推理客户端集成，请在使用这个客户端的项目中安装 📦Aspire.Azure.AI.Inference NuGet 包，即该使用 Azure AI 推理客户端的应用程序项目。

dotnet add package Aspire.Azure.AI.Inference

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

有关详细信息，请参阅 dotnet 添加包 或 管理 .NET 应用程序中的包依赖性。

Azure添加 AI 推理客户端

在你客户端使用的项目的 Program.cs 文件中，在任何 AddAzureChatCompletionsClient 上使用 IHostApplicationBuilder 方法为依赖注入（DI）注册一个 ChatCompletionsClient。

builder.AddAzureChatCompletionsClient(connectionName: "ai-foundry");

添加 ChatCompletionsClient后，可以使用依赖项注入检索客户端实例：

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

有关详细信息，请参见:

• 什么是 Azure AI 模型推理？ 有关 Azure AI 模型推理的详细信息。
• 请参阅 .NET中的依赖项注入以获取有关依赖项注入的详细信息。
• AI Foundry SDK: C#Azure。

添加已注册的 AI 推理客户端 AzureIChatClient

如果有兴趣将 IChatClient 接口与 Azure AI 推理客户端配合使用，只需将以下任一 API AddAzureChatCompletionsClient 链接到该方法：

• AddChatClient：在服务中注册单例 IChatClient。
• AddKeyedChatClient：在服务中注册具有键的单例IChatClient。

例如，请考虑将 IChatClient 添加到 DI 容器的以下 C# 代码：

builder.AddAzureChatCompletionsClient(connectionName: "ai-foundry")
       .AddChatClient("deploymentName");

同样，可以使用以下 C# 代码添加带键值的项 IChatClient：

builder.AddAzureChatCompletionsClient(connectionName: "ai-foundry")
       .AddKeyedChatClient("serviceKey", "deploymentName");

添加 IChatClient后，可以使用依赖项注入检索客户端实例：

public class ExampleService(IChatClient chatClient)
{
    public async Task<string> GetResponseAsync(string userMessage)
    {
        var response = await chatClient.CompleteAsync(userMessage);
        return response.Message.Text ?? string.Empty;
    }
}

有关 IChatClient 及其相应库的详细信息，请参阅 人工智能 .NET（预览版）。

添加键式 Azure AI 推理客户端

在某些情况下，可能需要使用不同的连接名称注册多个 ChatCompletionsClient 实例。 若要注册键式 Azure AI 推理客户端，请调用 AddKeyedAzureChatCompletionsClient 方法。

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

然后，可以使用依赖项注入检索客户端实例。 例如，若要从服务检索客户：

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

有关详细信息，请参阅 .NET中的键控服务。

配置

Aspire Azure AI 推理库提供了多个选项，用于根据项目的要求和约定配置 Azure AI Foundry 服务。

使用连接字符串

可以从Keys、Deployment ID和Endpoint选项卡中按照格式构建连接。

Endpoint={endpoint};Key={key};DeploymentId={deploymentId}`

调用 builder.AddAzureChatCompletionsClient()时，可以提供连接字符串的名称：

builder.AddAzureChatCompletionsClient(
    connectionName: "connection-string-name");

从 ConnectionStrings 配置部分检索连接字符串。 支持两种连接格式：

Azure AI Foundry 接口

建议的方法是使用 Endpoint，它与 ChatCompletionsClientSettings.Credential 属性配合使用以建立连接。 如果未配置凭据，则使用 DefaultAzureCredential。

{
  "ConnectionStrings": {
    "connection-string-name": "Endpoint=https://{endpoint}/;DeploymentId={deploymentName}"
  }
}

连接字符串

或者，可以使用自定义连接字符串。

{
  "ConnectionStrings": {
    "connection-string-name": "Endpoint=https://{endpoint}/;Key={account_key};DeploymentId={deploymentName}"
  }
}

使用配置提供器

Aspire Azure AI 推理库支持 Microsoft.Extensions.Configuration。 它通过 ChatCompletionsClientSettings 键从配置中加载 AzureAIInferenceClientOptions 和 Aspire:Azure:AI:Inference。 例如，考虑一个配置某些选项的 appsettings.json：

{
  "Aspire": {
    "Azure": {
      "AI": {
        "Inference": {
          "DisableTracing": false,
          "EnableSensitiveTelemetryData": false,
          "ClientOptions": {
            "UserAgentApplicationId": "myapp"
          }
        }
      }
    }
  }
}

使用内联委托功能

还可以传递 Action<ChatCompletionsClientSettings> configureSettings 委托来设置一些或所有内联选项，例如，禁用代码中的跟踪：

builder.AddAzureChatCompletionsClient(
    connectionName: "connection-string-name",
    static settings => settings.DisableTracing = true);

可观测性和遥测

Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性支柱。 有关集成可观测性和遥测的详细信息，请参阅 Aspire 集成概述。 根据支持服务，某些集成可能仅支持其中一些功能。 例如，某些集成支持日志记录和跟踪，但不支持指标。 还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木业

Aspire Azure AI 推理集成使用以下日志类别：

• Azure.Core
• Azure.Identity

追踪

Aspire Azure AI 推理集成将使用OpenTelemetry发出以下跟踪活动：

• Experimental.Microsoft.Extensions.AI — Microsoft.Extensions.AI 用于记录 AI 操作

在遥测中配置敏感数据

默认情况下，遥测包括令牌计数等元数据，但不包括原始输入和输出（如消息内容）。 若要在遥测中包括潜在的敏感信息，请设置 EnableSensitiveTelemetryData 配置选项：

builder.AddAzureChatCompletionsClient(
    connectionName: "ai-foundry",
    configureSettings: settings =>
    {
        settings.EnableSensitiveTelemetryData = true;
    })
    .AddChatClient("deploymentName");

或通过配置：

{
  "Aspire": {
    "Azure": {
      "AI": {
        "Inference": {
          "EnableSensitiveTelemetryData": true
        }
      }
    }
  }
}

或者，可以通过设置环境变量来启用敏感数据捕获：

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

使用基础库遥测

如果需要直接从基础 Azure AI 推理库访问遥测数据，可以手动将相应的活动源和计量添加到 OpenTelemetry 配置：

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing.AddSource("Azure.AI.Inference.*"))
    .WithMetrics(metrics => metrics.AddMeter("Azure.AI.Inference.*"));

但是，你需要通过在应用启动期间将Azure环境变量AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE设置为或调用"true"来启用 AI 推理库中的AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true)实验性遥测支持。

另请参阅