.NET Aspire Azure AI 搜索集成

2025-04-23

包含： - Client 集成

.NET Aspire Azure AI 搜索文档集成使您能够从您的 Azure 应用程序连接到 Azure（以前称为 .NET 认知搜索）服务。 Azure AI 搜索是一个企业级的信息检索系统，适用于将异构内容引入搜索索引，并通过查询和应用呈现给用户。它配备了一整套先进的搜索技术，专为各种规模的高性能应用程序而打造。

托管集成

.NET Aspire Azure AI 搜索托管集成将 Azure AI 搜索资源建模为 AzureSearchResource 类型。若要在应用主机项目中访问和使用此类型及 API，请安装 📦AspireHosting.Azure.Search NuGet 包。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Azure.Search

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

有关详细信息，请参阅 dotnet add package 或 .NET。

添加 Azure 人工智能搜索资源

若要将 AzureSearchResource 添加到应用主机项目，请调用提供名称的 AddAzureSearch 方法：

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.AddAzureSearch("search");

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

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

前面的代码将名为 Azure 的 search AI 搜索资源添加到应用主机项目中。 WithReference 方法将连接信息传递给 ExampleProject 项目。

重要

调用 AddAzureSearch时，它会隐式调用 AddAzureProvisioning(IDistributedApplicationBuilder)，这增加了在应用启动期间动态生成 Azure 资源的支持。应用程序必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置

由预配生成的 Bicep

如果你不熟悉 Bicep，则它是用于定义 Azure 资源的特定于域的语言。使用 .NET.NET Aspire时，无需手动编写 Bicep;相反，预配 API 会为你生成 Bicep。发布应用时，生成的 Bicep 文件将会与清单文件一同输出。添加 Azure AI 搜索资源时，会生成 Bicep，以便使用适当的默认值预配搜索服务。

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

resource search 'Microsoft.Search/searchServices@2023-11-01' = {
  name: take('search-${uniqueString(resourceGroup().id)}', 60)
  ___location: ___location
  properties: {
    hostingMode: 'default'
    disableLocalAuth: true
    partitionCount: 1
    replicaCount: 1
  }
  sku: {
    name: 'basic'
  }
  tags: {
    'aspire-resource-name': 'search'
  }
}

output connectionString string = 'Endpoint=https://${search.name}.search.windows.net'

output name string = search.name

前面的 Bicep 模块是用于配置 Azure AI 搜索服务资源的。此外，在单独的模块中为 Azure 资源创建角色分配：

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

param search_outputs_name string

param principalType string

param principalId string

resource search 'Microsoft.Search/searchServices@2023-11-01' existing = {
  name: search_outputs_name
}

resource search_SearchIndexDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7')
    principalType: principalType
  }
  scope: search
}

resource search_SearchServiceContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0')
    principalType: principalType
  }
  scope: search
}

生成的 Bicep 作为起点，受 C# 中资源配置基础设施更改的影响。直接对 Bicep 文件的自定义项所做的更改将被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。此类型提供了一种流畅的 API，可以通过 Azure API 来配置 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源，从而实现对生成的 Bicep 的自定义。例如，可以配置搜索服务分区、副本等：

builder.AddAzureSearch("search")
    .ConfigureInfrastructure(infra =>
    {
        var searchService = infra.GetProvisionableResources()
                                 .OfType<SearchService>()
                                 .Single();

        searchService.PartitionCount = 6;
        searchService.ReplicaCount = 3;
        searchService.SearchSkuName = SearchServiceSkuName.Standard3;
        searchService.Tags.Add("ExampleKey", "Example value");
    });

前面的代码：

将一个调用链接至 ConfigureInfrastructure API：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 检索单个 SearchService 资源。
  - SearchService.PartitionCount 设置为 6。
  - SearchService.ReplicaCount 设置为 3。
  - SearchService.SearchSkuName 设置为 SearchServiceSkuName.Standard3。
  - 在认知服务资源上添加了一个标记，键为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义 Azure AI 搜索资源。有关详细信息，请参阅 Azure.Provisioning 自定义。

连接到现有的 Azure AI 搜索服务

你可能有一个现有的 Azure AI 搜索服务，想要连接到它。可以链式调用以标注 AzureSearchResource 是现有资源。

var builder = DistributedApplication.CreateBuilder(args);

var existingSearchName = builder.AddParameter("existingSearchName");
var existingSearchResourceGroup = builder.AddParameter("existingSearchResourceGroup");

var search = builder.AddAzureSearch("search")
                    .AsExisting(existingSearchName, existingSearchResourceGroup);

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

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

有关将 Azure AI 搜索资源视为现有资源的详细信息，请参阅 “使用现有 Azure 资源”。

作为另一种选择，你可以向应用主机添加连接字符串，而非表示Azure AI 搜索服务。这是一种仅依赖于 string 值的弱类型化方法。若要将连接添加到现有 Azure AI 搜索服务，请调用 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureSearch("search")
    : builder.AddConnectionString("search");

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

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

注释

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

连接字符串在应用主机的配置（通常位于用户机密）的 ConnectionStrings 部分下进行配置：

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

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

托管环境集成运行状况检查

Azure AI 搜索托管集成目前未实现任何健康检查。将来的版本可能会更改此限制。与往常一样，如果有任何建议或反馈，请随时提出问题。

Client 集成

若要开始使用 .NET AspireAzure AI 搜索文档客户端集成，请在客户端使用的项目中安装 📦Aspire。Azure。Search.Documents NuGet 包，也就是该应用程序使用 Azure AI 搜索文档客户端的项目。

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Azure.Search.Documents

<PackageReference Include="Aspire.Azure.Search.Documents"
                  Version="*" />

添加 Azure AI 搜索索引客户端

在您的客户端消费项目中的 Program.cs 文件中，对任何 AddAzureSearchClient 调用 IHostApplicationBuilder 扩展方法，以注册 SearchIndexClient，以便通过依赖注入容器进行使用。该方法采用连接名称参数。

builder.AddAzureSearchClient(connectionName: "search");

小提示

connectionName 参数必须与在应用主机项目中添加 Azure AI 搜索资源时使用的名称匹配。有关详细信息，请参阅添加 Azure AI 搜索资源。

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

public class ExampleService(SearchIndexClient indexClient)
{
    // Use indexClient
}

您还可以通过调用 SearchClient 方法来检索一个可用于查询的 GetSearchClient(String)。

public class ExampleService(SearchIndexClient indexClient)
{
    public async Task<long> GetDocumentCountAsync(
        string indexName,
        CancellationToken cancellationToken)
    {
        var searchClient = indexClient.GetSearchClient(indexName);

        var documentCountResponse = await searchClient.GetDocumentCountAsync(
            cancellationToken);

        return documentCountResponse.Value;
    }
}

有关详细信息，请参阅：

Azure AI 搜索客户端库用于.NET示例，使用SearchIndexClient。
依赖项注入 .NET 有关依赖项注入的详细信息。

添加键控 Azure AI 搜索索引客户端

在某些情况下，可能需要使用不同的连接名称注册多个 SearchIndexClient 实例。若要注册密钥 Azure AI 搜索客户端，请调用 AddKeyedAzureSearchClient 方法：

builder.AddKeyedAzureSearchClient(name: "images");
builder.AddKeyedAzureSearchClient(name: "documents");

重要

使用键控服务时，您应确保您的 Azure AI 搜索资源已配置两个命名连接，一个用于 images，一个用于 documents。

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

public class ExampleService(
    [KeyedService("images")] SearchIndexClient imagesClient,
    [KeyedService("documents")] SearchIndexClient documentsClient)
{
    // Use clients...
}

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

配置

.NET Aspire Azure AI 搜索文档库提供了多个选项，用于根据项目的要求和约定配置 Azure AI 搜索连接。必须提供 Endpoint 或 ConnectionString。

使用连接字符串

可以使用格式从Endpoint={endpoint};Key={key};”选项卡构造连接。调用 builder.AddAzureSearchClient()时，可以提供连接字符串的名称：

builder.AddAzureSearchClient("searchConnectionName");

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

帐户终结点

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

{
  "ConnectionStrings": {
    "search": "https://{search_service}.search.windows.net/"
  }
}

连接字符串

或者，可以使用具有密钥的连接字符串;不建议采用以下方法：

{
  "ConnectionStrings": {
    "search": "Endpoint=https://{search_service}.search.windows.net/;Key={account_key};"
  }
}

使用配置提供程序

.NET Aspire Azure AI 搜索库支持 Microsoft.Extensions.Configuration。它通过 AzureSearchSettings 键从配置中加载 SearchClientOptions 和 Aspire:Azure:Search:Documents。配置某些选项的示例 appsettings.json：

{
  "Aspire": {
    "Azure": {
      "Search": {
        "Documents": {
          "DisableTracing": false
        }
      }
    }
  }
}

有关完整的 Azure AI 搜索文档客户端集成架构JSON，请参阅 Aspire.Azure.Search.Documents/ConfigurationSchema.json。

使用内联委托

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

builder.AddAzureSearchClient(
    "searchConnectionName",
    static settings => settings.DisableTracing = true);

还可以使用 SearchClientOptions 方法的可选 Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder 参数来设置 AddAzureSearchClient。例如，若要设置此客户端的客户端 ID：

builder.AddAzureSearchClient(
    "searchConnectionName",
    configureClientBuilder: builder => builder.ConfigureOptions(
        static options => options.Diagnostics.ApplicationId = "CLIENT_ID"));

Client 整合健康检查

默认情况下， .NET.NET Aspire客户端集成为所有服务启用了运行状况检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

在 C# 中的应用健康检查
ASP.NET Core中的运行状况检查

.NET Aspire Azure AI 搜索文档整合实现了一项独立的健康检查，该检查通过调用 GetServiceStatisticsAsync 上的 SearchIndexClient 方法来验证服务的可用性。

可观测性和遥测

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

伐木

.NET Aspire Azure AI 搜索文档集成使用以下日志类别：

Azure
Azure.Core
Azure.Identity

追踪

.NET Aspire Azure AI 搜索文档集成在与搜索服务交互时，通过 OpenTelemetry 发出跟踪活动。

通过