Couchbase コネクタの使用 (プレビュー)

警告

セマンティックカーネルベクターストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

概要

Couchbase Vector Store コネクタを使用すると、Couchbase のデータにアクセスして管理できます。コネクタには次の特性があります。

特色エリア	サポート
コレクションのマップ	Couchbase コレクション + インデックス
サポートされているキープロパティの種類	`string`
サポートされているデータプロパティ型	`System.Text.Json`でサポートされているすべての型 (組み込みまたはカスタムコンバーターを使用)
サポートされているベクタープロパティ型	`ReadOnlyMemory<float>` `Embedding<float>` `float[]`
サポートされている距離関数	コサイン類似度 DotProductSimilarity EuclideanDistance
サポートされているフィルター句	`AnyTagEqualTo` `EqualTo`
レコード内の複数のベクターをサポートします	はい
IsIndexed はサポートされていますか?	はい
IsFullTextIndexed がサポートされていますか?	はい
StoragePropertyName がサポートされていますか?	いいえ。代わりに `JsonSerializerOptions` と `JsonPropertyNameAttribute` を使用してください。詳細については、こちらを参照してください。
HybridSearch はサポートされていますか?	はい

はじめに

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

名前付きコレクションへの直接参照を構築できます。

クエリコレクションの使用 (ハイパースケールまたは複合インデックス)

Hyperscale インデックスを使用した高パフォーマンスベクター検索の場合:

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

検索コレクションの使用 (シーチベクターインデックス)

フルテキスト検索を組み合わせたハイブリッド検索シナリオの場合:

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 には、ベクター検索用の 3 種類のインデックスが用意されています。

ハイパースケールベクターインデックス

純粋ベクター検索に最適 - コンテンツ検出、推奨事項、セマンティック検索
メモリ占有領域が少ない高パフォーマンス - 数十億のベクトルにスケーリングするように設計されています
同時操作用に最適化 - 同時検索と挿入をサポート
次の場合に使用します。 主に、複雑なスカラーフィルター処理を使用せずにベクターのみのクエリを実行します
次の用途に最適です。 大規模なセマンティック検索、レコメンデーションシステム、コンテンツ検出
必要： Couchbase Server 8.0 以降または Capella

複合ベクターインデックス

フィルター処理されたベクター検索に最適 - ベクター検索とスカラー値のフィルター処理を組み合わせたもの
効率的な事前フィルター処理 - スカラー属性によってベクター比較スコープが縮小される
次の場合に使用します。 クエリでは、ベクターの類似性と、データの大部分を排除するスカラーフィルターが組み合わせられます
次の用途に最適です。 コンプライアンスベースのフィルター処理、ユーザー固有の検索、時間制限付きクエリ
必要： Couchbase Server 8.0 以降または Capella

ベクターインデックスの検索

フルテキスト検索とベクターの類似性を組み合わせたハイブリッド検索に最適
従来のキーワードマッチングと共にセマンティック検索を許可する
ベクターとテキストに加えて地理空間検索をサポート
次の場合に使用します。 同じクエリで従来のキーワード検索とベクター類似性検索を組み合わせる必要がある
次の用途に最適です。 Eコマース製品の検索、旅行に関する推奨事項、複数の検索条件を持つコンテンツの検出
必要： Couchbase Server 7.6 以降または Capella

適切なインデックスの種類の選択:

純粋なベクター検索と大規模なデータセットの Hyperscale Index から始める (数十億にスケーリング)
スカラーフィルターによって検索領域が大幅に削減される場合は 、複合インデックス を選択します (数千万から数十億のベクターに適しています)
テキストとベクターを組み合わせたハイブリッド検索に検索 ベクトルインデックス を使用する

ベクターインデックス型の詳細な比較

データマッピング

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 に格納する方法の例を次に示します。また、ストレージの名前付けをさらにカスタマイズするために、JsonPropertyNameAttribute プロパティでのDescriptionの使用にも注意してください。

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
  ]
}

サポートされていません

サポートされていません。

サポートされていません

サポートされていません。

Last updated on 2025-11-13

次の方法で共有

Couchbase コネクタの使用 (プレビュー)

概要

はじめに

クエリ コレクションの使用 (ハイパースケールまたは複合インデックス)

検索コレクションの使用 (シーチ ベクター インデックス)

インデックスの種類の比較

データ マッピング

サポートされていません

サポートされていません

その他のリソース

クエリコレクションの使用 (ハイパースケールまたは複合インデックス)

検索コレクションの使用 (シーチベクターインデックス)

データマッピング