Elasticsearch 커넥터 사용(미리 보기)

경고

시맨틱 커널 벡터 저장소 기능은 프리뷰 상태이며, 릴리스 전에 제한된 상황에서 돌이킬 수 없는 변경이 필요한 개선 사항이 발생할 수도 있습니다.

개요

Elasticsearch Vector Store 커넥터를 사용하여 Elasticsearch의 데이터에 액세스하고 관리할 수 있습니다. 커넥터의 특징은 다음과 같습니다.

기능 영역	지원
컬렉션이 다음으로 매핑됩니다.	Elasticsearch 인덱스
지원되는 키 속성 형식	문자열
지원되는 데이터 속성 형식	System.Text.Json에서 지원되는 모든 형식(기본 제공 또는 사용자 지정 변환기 사용)
지원되는 벡터 속성 형식	읽기 전용 메모리<float> IEnumerable<float>
지원되는 인덱스 형식	HNSW(32, 8 또는 4비트) FLAT(32, 8 또는 4비트)
지원되는 거리 함수	코사인 유사도 DotProductSimilarity EuclideanDistance MaxInnerProduct
지원되는 필터 문장	AnyTagEqualTo EqualTo
레코드에서 여러 벡터를 지원합니다.	예
IsFilterable이 지원되는가요?	예
IsFullTextSearchable이 지원되나요?	예
StoragePropertyName이 지원되는가요?	아니요, 대신 JsonSerializerOptions과 JsonPropertyNameAttribute을 사용하세요. 자세한 내용은 여기를 참조하세요.

시작

로컬 개발 또는 테스트를 위해 Elasticsearch를 로컬로 실행하려면 다음 명령을 사용하여 스크립트를 실행합니다.

curl -fsSL https://elastic.co/start-local | sh

Elasticsearch Vector Store 커넥터 NuGet 패키지를 프로젝트에 추가합니다.

dotnet add package Elastic.SemanticKernel.Connectors.Elasticsearch --prerelease

의미 체계 커널에서 제공하는 확장 메서드를 사용하여 KernelBuilder 사용 가능한 종속성 주입 컨테이너 또는 IServiceCollection 종속성 주입 컨테이너에 벡터 저장소를 추가할 수 있습니다.

using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddElasticsearchVectorStore(new ElasticsearchClientSettings(new Uri("http://localhost:9200")));

using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddElasticsearchVectorStore(new ElasticsearchClientSettings(new Uri("http://localhost:9200")));

매개 변수를 사용하지 않는 확장 메서드도 제공됩니다. 이를 위해서는 Elastic.Clients.Elasticsearch.ElasticsearchClient 클래스의 인스턴스를 종속성 주입 컨테이너에 별도로 등록해야 합니다.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<ElasticsearchClient>(sp =>
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))));
kernelBuilder.AddElasticsearchVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ElasticsearchClient>(sp =>
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))));
builder.Services.AddElasticsearchVectorStore();

Elasticsearch Vector Store 인스턴스를 직접 생성할 수 있습니다.

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;

var vectorStore = new ElasticsearchVectorStore(
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))));

명명된 컬렉션에 대한 직접 참조를 생성할 수 있습니다.

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;

var collection = new ElasticsearchVectorStoreRecordCollection<Hotel>(
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))),
    "skhotels");

데이터 매핑

Elasticsearch 커넥터는 System.Text.Json.JsonSerializer 사용하여 매핑을 수행합니다. Elasticsearch는 별도의 키/ID 및 값으로 문서를 저장하므로 매퍼는 키를 제외한 모든 속성을 JSON 개체에 직렬화하고 값으로 사용합니다.

데이터 모델 속성 이름과 다른 스토리지 이름이 필요한 경우 JsonPropertyNameAttribute 사용이 지원됩니다. 사용자 지정 속성 명명 정책과 함께 사용자 지정 JsonSerializerOptions 인스턴스를 사용할 수도 있습니다. 이를 사용하도록 설정하려면 사용자 지정 원본 직렬 변환기를 구성해야 합니다.

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;
using Elastic.Clients.Elasticsearch.Serialization;
using Elastic.Transport;

var nodePool = new SingleNodePool(new Uri("http://localhost:9200"));
var settings = new ElasticsearchClientSettings(
    nodePool,
    sourceSerializer: (defaultSerializer, settings) =>
        new DefaultSourceSerializer(settings, options => 
            options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper));
var client = new ElasticsearchClient(settings);

var collection = new ElasticsearchVectorStoreRecordCollection<Hotel>(
    client,
    "skhotelsjson");

또는 동일한 결과를 달성하거나 동적 조건에 따라 속성 명명을 추가로 사용자 지정하도록 DefaultFieldNameInferrer 람다 함수를 구성할 수 있습니다.

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;

var settings = new ElasticsearchClientSettings(new Uri("http://localhost:9200"));
settings.DefaultFieldNameInferrer(name => JsonNamingPolicy.SnakeCaseUpper.ConvertName(name));
var client = new ElasticsearchClient(settings);

var collection = new ElasticsearchVectorStoreRecordCollection<Hotel>(
    client,
    "skhotelsjson");

스네이크 케이스 대문자 명명 정책이 선택되었으므로, Elasticsearch에서 이 데이터 형식을 설정하는 방법의 예는 다음과 같습니다. 또한 스토리지 이름을 추가로 사용자 지정하기 위해 Description 속성에서 JsonPropertyNameAttribute를 사용합니다.

using System.Text.Json.Serialization;
using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public string HotelId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string HotelName { get; set; }

    [JsonPropertyName("HOTEL_DESCRIPTION")]
    [VectorStoreRecordData(IsFullTextSearchable = true)]
    public string Description { get; set; }

    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
  "_index" : "skhotelsjson",
  "_id" : "h1",
  "_source" : {
    "HOTEL_NAME" : "Hotel Happy",
    "HOTEL_DESCRIPTION" : "A place where everyone can be happy.",
    "DESCRIPTION_EMBEDDING" : [
      0.9,
      0.1,
      0.1,
      0.1
    ]
  }
}

지원되지 않음

지원되지 않습니다.

지원되지 않음

지원되지 않습니다.