Aspire Azure AI 搜索集成

2025-10-02

包含： 托管集成 —&— Client 集成

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

托管集成

Aspire Azure AI 搜索托管集成将 Azure AI 搜索资源建模为 AzureSearchResource 类型。若要访问此类型和 API 以在 AppHost 项目中表达它们，请安装。📦AspireHosting.Azure.搜索 NuGet 包：

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

dotnet add package Aspire.Hosting.Azure.Search

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

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

添加 Azure AI 搜索资源

若要向 AppHost 项目添加一个 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 AppHost 项目的 AI 搜索资源添加到该资源 search 。 WithReference 方法将连接信息传递给 ExampleProject 项目。

重要

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

连接到现有的 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...

重要

调用RunAsExisting或PublishAsExistingAsExisting处理订阅中Azure已存在的资源的方法时，必须将某些配置值添加到 AppHost，以确保Aspire找到它们。必要的配置值包括 SubscriptionId、 AllowResourceGroupCreation、 ResourceGroup 和 Location。如果您不设置它们，仪表板中就会出现“缺少配置”错误 Aspire。有关如何设置它们的详细信息，请参阅 “配置”。

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

注释

或者，可以向 AppHost 添加连接字符串，而不是表示 Azure AI 搜索资源。此方法属于弱类型，不适用于角色分配或基础结构自定义。有关详细信息，请参阅添加包含连接字符串的现有 Azure 资源。

预配生成的 Bicep

如果你不熟悉 Bicep，则它是用于定义 Azure 资源的特定于域的语言。使用 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 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 AspireAzure 资源都是 AzureProvisioningResource 类型的子类。这类型通过提供用于配置 Azure 资源的流畅 API 来允许自定义生成的 Bicep - ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API。例如，可以配置搜索服务分区、副本等：

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 搜索托管集成目前未执行任何运行状况检查。将来的版本可能会更改此限制。与往常一样，如果有任何建议或反馈，请随时提出问题。

Client 集成

若要开始进行 AspireAzure AI 搜索文档客户端集成，请在使用客户端的项目（也就是使用 📦 AI 搜索文档客户端的应用程序的项目）中安装 Aspire NuGet 包。

.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 必须与在 AppHost 项目中添加 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使用 .NET 的 SearchIndexClient的 AI 搜索客户端库。
.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 中的键控服务。

配置

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

使用配置提供程序

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。

使用命名配置

Aspire Azure AI 搜索库支持命名配置，这样就可以使用不同的设置来配置同一资源类型的多个实例。命名配置使用连接名称作为主配置部分下的密钥。

{
  "Aspire": {
    "Azure": {
      "Search": {
        "Documents": {
          "search1": {
            "Endpoint": "https://mysearch1.search.windows.net/",
            "DisableTracing": false
          },
          "search2": {
            "Endpoint": "https://mysearch2.search.windows.net/",
            "DisableTracing": true
          }
        }
      }
    }
  }
}

在此示例中，当调用search1时，可以使用search2和AddAzureSearchClient作为连接名称。

builder.AddAzureSearchClient("search1");
builder.AddAzureSearchClient("search2");

命名配置优先于顶级配置。如果同时提供这两种设置，则命名配置中的设置将替代顶级设置。

使用内联委托

你还可以传递 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 集成运行状况检查

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

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

可观测性和遥测

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

日志记录

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

Azure
Azure.Core
Azure.Identity

跟踪

Aspire Azure AI 搜索文档集成在与搜索服务交互时使用 OpenTelemetry 发出跟踪活动。

另请参阅

反馈

此页面是否有帮助？