使用 Couchbase 连接器（预览版）

警告

语义内核向量存储功能目前处于预览状态，在发布前的某些有限情况下，可能需要进行重大变更以实现改进。

概述

Couchbase Vector Store 连接器可用于访问和管理 Couchbase 中的数据。连接器具有以下特征。

功能区域	支持
集合映射到	Couchbase 集合与索引
支持的键属性类型	`string`
支持的数据属性类型	支持 `System.Text.Json` 的所有类型（无论是内置的还是使用自定义转换器的）
支持的向量属性类型	`ReadOnlyMemory<float>` `Embedding<float>` `float[]`
支持的距离函数	余弦相似度 DotProductSimilarity EuclideanDistance
支持的筛选器子句	`AnyTagEqualTo` `EqualTo`
支持记录中的多个向量	是的
是否支持 IsIndexed？	是的
是否支持FullTextIndexed？	是的
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);

可以构造对命名集合的直接引用。

使用查询集合（超大规模或复合索引）

对于具有“超大规模”索引的高性能矢量搜索：

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 矢量索引）

结合全文搜索的混合搜索场景：

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

选择正确的索引类型：

从 超大规模索引 开始，用于纯矢量搜索和大型数据集（缩放为数十亿）
当标量筛选器显著减少搜索空间时选择 复合索引 （适用于数千万到数十亿向量）
利用 搜索矢量索引 进行文本与矢量结合的混合搜索

矢量索引类型的详细比较

数据映射

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 连接器 （预览版）

概述

入门

使用查询集合（超大规模或复合索引）

使用搜索集合 （Seach 矢量索引）

索引类型比较

数据映射

不支持

不支持

其他资源

使用 Couchbase 连接器（预览版）

使用搜索集合（Seach 矢量索引）