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

개요

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

시작

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

dotnet add package CouchbaseConnector.SemanticKernel --prerelease

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

using Microsoft.SemanticKernel;
using Couchbase.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddCouchbaseVectorStore(
        connectionString: "couchbases://your-cluster-address",
        username: "username",
        password: "password",
        bucketName: "bucket-name",
        scopeName: "scope-name");

using Couchbase.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name");

인덱스 형식 구성

벡터 저장소는 기본적으로 하이퍼스케일 인덱스를 사용합니다. 다음을 전달 CouchbaseVectorStoreOptions하여 다른 인덱스 형식을 지정할 수 있습니다.

using Couchbase.SemanticKernel;

var builder = WebApplication.CreateBuilder(args);

// Option 1: Use Hyperscale index 
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name",
    options: new CouchbaseVectorStoreOptions 
    { 
        IndexType = CouchbaseIndexType.Hyperscale
    });

// Option 2: Use Composite index
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name",
    options: new CouchbaseVectorStoreOptions 
    { 
        IndexType = CouchbaseIndexType.Composite
    });

// Option 3: Use Search vector index
builder.Services.AddCouchbaseVectorStore(
    connectionString: "couchbases://your-cluster-address",
    username: "username",
    password: "password",
    bucketName: "bucket-name",
    scopeName: "scope-name",
    options: new CouchbaseVectorStoreOptions 
    { 
        IndexType = CouchbaseIndexType.Search
    });

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

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Couchbase;
using Couchbase.KeyValue;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<ICluster>(sp =>
{
    var clusterOptions = new ClusterOptions
    {
        ConnectionString = "couchbases://your-cluster-address",
        UserName = "username",
        Password = "password"
    };

    return Cluster.ConnectAsync(clusterOptions).GetAwaiter().GetResult();
});

kernelBuilder.Services.AddSingleton<IScope>(sp =>
{
    var cluster = sp.GetRequiredService<ICluster>();
    var bucket = cluster.BucketAsync("bucket-name").GetAwaiter().GetResult();
    return bucket.Scope("scope-name");
});

// Add Couchbase Vector Store
kernelBuilder.Services.AddCouchbaseVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Couchbase.KeyValue;
using Couchbase;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ICluster>(sp =>
{
    var clusterOptions = new ClusterOptions
    {
        ConnectionString = "couchbases://your-cluster-address",
        UserName = "username",
        Password = "password"
    };

    return Cluster.ConnectAsync(clusterOptions).GetAwaiter().GetResult();
});

builder.Services.AddSingleton<IScope>(sp =>
{
    var cluster = sp.GetRequiredService<ICluster>();
    var bucket = cluster.BucketAsync("bucket-name").GetAwaiter().GetResult();
    return bucket.Scope("scope-name");
});

// Add Couchbase Vector Store
builder.Services.AddCouchbaseVectorStore();

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

using Couchbase;
using Couchbase.KeyValue;
using Couchbase.SemanticKernel;

var clusterOptions = new ClusterOptions
{
    ConnectionString = "couchbases://your-cluster-address",
    UserName = "username",
    Password = "password"
};

var cluster = await Cluster.ConnectAsync(clusterOptions);
var bucket = await cluster.BucketAsync("bucket-name");
var scope = bucket.Scope("scope-name");

var vectorStore = new CouchbaseVectorStore(scope);

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

쿼리 컬렉션 사용(하이퍼스케일 또는 복합 인덱스)

하이퍼스케일 인덱스를 사용하여 고성능 벡터 검색의 경우:

using Couchbase.SemanticKernel;
using Couchbase;
using Couchbase.KeyValue;

var cluster = await Cluster.ConnectAsync(clusterOptions);
var bucket = await cluster.BucketAsync("bucket-name");
var scope = bucket.Scope("scope-name");

// Using Hyperscale index (default)
var collection = new CouchbaseQueryCollection<string, Hotel>(
    scope,
    "skhotels",
    indexType: CouchbaseIndexType.Hyperscale);

// Or using Composite index
var collectionComposite = new CouchbaseQueryCollection<string, Hotel>(
    scope,
    "skhotels",
    indexType: CouchbaseIndexType.Composite);

검색 컬렉션 사용(Seach Vector Index)

전체 텍스트 검색을 결합하는 하이브리드 검색 시나리오의 경우:

using Couchbase.SemanticKernel;
using Couchbase;
using Couchbase.KeyValue;

var cluster = await Cluster.ConnectAsync(clusterOptions);
var bucket = await cluster.BucketAsync("bucket-name");
var scope = bucket.Scope("scope-name");

var collection = new CouchbaseSearchCollection<string, Hotel>(
    scope,
    "skhotels");

인덱스 형식 비교

Couchbase는 벡터 검색을 위한 세 가지 유형의 인덱스를 제공합니다.

하이퍼스케일 벡터 인덱스

• 순수 벡터 검색에 가장 적합 - 콘텐츠 검색, 권장 사항, 의미 체계 검색
• 메모리 공간이 적은 고성능 - 수십억 개의 벡터로 확장하도록 설계
• 동시 작업에 최적화됨 - 동시 검색 및 삽입 지원
• 사용 시기: 주로 복잡한 스칼라 필터링 없이 벡터 전용 쿼리를 수행합니다.
• 적합한 대상: 대규모 의미 체계 검색, 권장 사항 시스템, 콘텐츠 검색
• 필요: Couchbase Server 8.0 이상 또는 Capella

복합 벡터 인덱스

• 필터링된 벡터 검색에 가장 적합 - 스칼라 값 필터링과 벡터 검색 결합
• 효율적인 사전 필터링 - 스칼라 특성은 벡터 비교 범위를 줄입니다.
• 사용 시기: 쿼리는 많은 양의 데이터를 제거하는 스칼라 필터와 벡터 유사성을 결합합니다.
• 적합한 대상: 규정 준수 기반 필터링, 사용자별 검색, 시간 제한 쿼리
• 필요: Couchbase Server 8.0 이상 또는 Capella

벡터 인덱스 검색

• 전체 텍스트 검색과 벡터 유사성을 결합한 하이브리드 검색에 가장 적합합니다.
• 기존 키워드 일치와 함께 의미 체계 검색 허용
• 벡터 및 텍스트 외에 지리 공간적 검색 지원
• 사용 시기: 동일한 쿼리에서 기존 키워드 검색을 벡터 유사성 검색과 결합해야 합니다.
• 적합한 대상: 전자 상거래 제품 검색, 여행 권장 사항, 여러 검색 조건이 있는 콘텐츠 검색
• 필요: Couchbase Server 7.6 이상 또는 Capella

올바른 인덱스 형식 선택:

• 전용 벡터 검색 및 대량의 데이터 세트(수십억까지 확장 가능)에 대한 하이퍼스케일 인덱스로 시작하십시오.
• 스칼라 필터가 검색 공간을 크게 줄일 때 복합 인덱 스 선택(수천만~수십억 개의 벡터에 적합)
• 텍스트와 벡터를 결합하는 하이브리드 검색에 Search 벡터 인덱 스 사용

벡터 인덱스 형식의 자세한 비교

데이터 매핑

Couchbase 커넥터는 System.Text.Json.JsonSerializer를 사용하여 매핑을 수행합니다. 데이터 모델의 속성은 JSON 개체로 직렬화되고 Couchbase에 문서 값으로 저장됩니다.

JsonPropertyNameAttribute 데이터 모델 속성 이름과 다른 스토리지 이름이 필요한 경우 이 사용이 지원됩니다. 사용자 지정 속성 명명 정책과 함께 사용자 지정 JsonSerializerOptions 인스턴스를 사용할 수도 있습니다.

using Couchbase.SemanticKernel;
using Couchbase.KeyValue;
using System.Text.Json;

var jsonSerializerOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper
};

var options = new CouchbaseQueryCollectionOptions
{
    JsonSerializerOptions = jsonSerializerOptions
};

var collection = new CouchbaseQueryCollection<string, Hotel>(scope, "skhotelsjson", options);

뱀 대/소문자 위쪽의 명명 정책을 선택했기 때문에 이 데이터 형식이 Couchbase에 저장되는 방법의 예는 다음과 같습니다. 또한 Description 속성에서 JsonPropertyNameAttribute을(를) 사용하여 스토리지 이름을 추가로 사용자 지정하십시오.

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

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

    [VectorStoreData(IsIndexed = true)]
    public string HotelName { get; set; }

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

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

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

지원되지 않음

지원되지 않습니다.

지원되지 않음

지원되지 않습니다.