다음을 통해 공유

.NET Aspire Azure AI Search 문서 통합

  • 아티클

이 문서에서는 .NET AspireAzure AI Search Documents 클라이언트를 사용하는 방법을 알아봅니다. Aspire.Azure.Search.Documents 라이브러리는 SearchIndexClient Search에 연결하기 위해 DI(종속성 주입) 컨테이너에 Azure 등록하는 데 사용됩니다. 해당 상태 검사 및 로깅을 활성화합니다.

SearchIndexClient사용에 대한 자세한 내용은 의 Azure사용 방법에 대해 알아보세요. C# .NET 애플리케이션의 문서를 검색하세요.

시작

.NET Aspire Azure AI Search 문서 통합을 시작하려면 Azure NuGet 패키지를 설치하는 것을 포함합니다.

dotnet add package Aspire.Azure.Search.Documents

자세한 내용은 dotnet add package 또는 manage package dependencies in .NET applications.

예제 사용

클라이언트 사용 프로젝트의 Program.cs 파일에서 확장 메서드를 호출하여, 종속성 주입 컨테이너를 통해 사용할 SearchIndexClient을 등록합니다. AddAzureSearchClient 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddAzureSearchClient("searchConnectionName");

그런 다음 종속성 주입을 사용하여 SearchIndexClient 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 클라이언트를 검색하려면 다음을 수행합니다.

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

다음과 같이 SearchClient 메서드를 호출하여 쿼리에 사용할 수 있는 SearchIndexClient.GetSearchClient 검색할 수도 있습니다.

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사용 방법에 대한 예제를 보려면 SearchIndexClient를 참조하세요.

앱 호스트 사용

Azure에 IDistributedApplicationBuilder AI 호스팅 지원을 추가하려면, 📦 프로젝트에서 AspireAzure호스팅검색 NuGet 패키지를 설치하세요.

dotnet add package Aspire.Hosting.Azure.Search

Program.cs AppHost 파일에서 Azure Search 서비스를 추가하고, 다음 방법을 사용하여 연결을 활용합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(search);

AddAzureSearch 메서드는 ConnectionStrings:search 구성 키 아래의 AppHost 구성(예: "사용자 비밀")에서 연결 정보를 읽습니다. WithReference 메서드는 해당 연결 정보를 search 프로젝트의 MyService 연결 문자열에 전달합니다. Program.cs의 MyService 파일에서는 다음 방법으로 연결을 사용할 수 있습니다.

builder.AddAzureSearch("search");

구성

.NET Aspire Azure Azure Search 라이브러리는 프로젝트의 요구 사항 및 규칙에 따라 Azure Search Service를 구성하는 여러 옵션을 제공합니다. Endpoint 또는 ConnectionString 중 하나를 반드시 제공해야 합니다.

연결 문자열 사용

키 및 엔드포인트 탭에서 Endpoint={endpoint};Key={key};형식으로 연결을 구성할 수 있습니다. builder.AddAzureSearch()호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddAzureSearch("searchConnectionName");

그런 다음 ConnectionStrings 구성 섹션에서 연결 문자열을 검색합니다. 두 가지 연결 형식이 지원됩니다.

계정 엔드포인트

권장되는 방법은 Endpoint 속성과 함께 작동하는 AzureSearchSettings.Credential을 사용하여 연결을 설정하는 것입니다. 자격 증명이 구성되지 않은 경우 DefaultAzureCredential 사용됩니다.

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

연결 문자열

또는 사용자 지정 연결 문자열을 사용할 수 있습니다.

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

구성 공급자 사용

.NET Aspire Azure AI Search 라이브러리는 Microsoft.Extensions.Configuration지원합니다. 구성에서 AzureSearchSettings 및 SearchClientOptions을 Aspire:Azure:Search:Documents 키를 사용하여 로드합니다. 몇 가지 옵션을 구성하는 예제 appsettings.json:

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

인라인 대리자 사용

Action<AzureSearchSettings> configureSettings 대리자를 전달하여 코드에서 추적을 사용하지 않도록 설정하는 등 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다.

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

SearchClientOptions 메서드의 선택적 Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder 매개 변수를 사용하여 AddAzureSearch 설정할 수도 있습니다. 예를 들어 이 클라이언트에 대한 클라이언트 ID를 설정하려면 다음을 수행합니다.

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

Client 통합 시스템 상태 점검

기본적으로 .NET.NET Aspire클라이언트 통합에는 모든 서비스에 대해 상태 검사 사용하도록 설정될 있습니다. 마찬가지로, 많은 .NET.NET Aspire호스팅 통합도 상태 검사 엔드포인트를 활성화합니다. 자세한 내용은 다음을 참조하세요.

.NET Aspire Azure AI Search 문서 통합은 GetServiceStatisticsAsync에서 SearchIndexClient 메서드를 호출하여 서비스가 사용 가능한지 확인하는 단일 상태 점검을 수행합니다.

관찰 가능성 및 원격 분석

통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이는 때때로 관찰성의 핵심 요소라고도 합니다 . 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire Azure AI Search 문서 통합은 다음 로그 범주를 사용합니다.

  • Azure
  • Azure.Core
  • Azure.Identity

참조