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

경고

의미 체계 커널 벡터 저장소 기능은 미리 보기 상태이며 릴리스 전에 제한된 상황에서도 호환성이 손상되는 변경이 필요한 개선 사항이 계속 발생할 수 있습니다.

개요

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

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

시작

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

dotnet add package CouchbaseConnector.SemanticKernel --prerelease

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

using Microsoft.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 Microsoft.Extensions.DependencyInjection;

// 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");

매개 변수를 사용하지 않는 확장 메서드도 제공됩니다. 이를 위해서는 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 Microsoft.SemanticKernel;
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;
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 collection = new CouchbaseFtsVectorStoreRecordCollection<Hotel>(
    scope,
    "hotelCollection");

데이터 매핑

Couchbase 커넥터는 데이터 매핑에 System.Text.Json.JsonSerializer 사용합니다. 데이터 모델의 속성은 JSON 개체로 직렬화되고 Couchbase 스토리지에 매핑됩니다.

JsonPropertyName 특성을 사용하여 Couchbase 스토리지의 다른 이름에 속성을 매핑합니다. 또는 고급 사용자 지정을 위해 JsonSerializerOptions 구성할 수 있습니다.

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

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

var options = new CouchbaseFtsVectorStoreRecordCollectionOptions<Hotel>
{
    JsonSerializerOptions = jsonSerializerOptions
};

var collection = new CouchbaseFtsVectorStoreRecordCollection<Hotel>(scope, "hotels", options);

위의 사용자 지정 JsonSerializerOptions가 CamelCase을 사용하여, 다음 데이터 모델이 아래 json에 매핑됩니다.

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

public class Hotel
{
    [JsonPropertyName("hotelId")]
    [VectorStoreRecordKey]
    public string HotelId { get; set; }

    [JsonPropertyName("hotelName")]
    [VectorStoreRecordData]
    public string HotelName { get; set; }

    [JsonPropertyName("description")]
    [VectorStoreRecordData]
    public string Description { get; set; }

    [JsonPropertyName("descriptionEmbedding")]
    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.DotProductSimilarity)]
    public ReadOnlyMemory<float> DescriptionEmbedding { get; set; }
}

{
  "hotelId": "h1",
  "hotelName": "Hotel Happy",
  "description": "A place where everyone can be happy",
  "descriptionEmbedding": [0.9, 0.1, 0.1, 0.1]
}

지원되지 않음

지원되지 않습니다.

지원되지 않음

지원되지 않습니다.