YugabyteDB

YugabyteDB 是一个分布式 SQL 数据库，在提供 PostgreSQL 兼容性的同时，兼具跨多区域的水平可扩展性与高可用性。YugabyteDB 借助 pgvector 扩展提供的原生向量搜索能力，使其成为在分布式环境中存储与查询向量嵌入的出色选择。

Maven 依赖

NOTE

由于 YugabyteDB 支持属于 langchain4j-community，它将从 1.22.0-beta32 或更新版本起可用。

xml

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-yugabytedb</artifactId>
    <version>1.22.0-beta32</version>
</dependency>

API

YugabyteDB 集成提供了三个主要类：

`YugabyteDBEmbeddingStore`

存储与搜索向量嵌入的主接口。它实现了 LangChain4j 的 EmbeddingStore 接口，提供以下方法：

添加嵌入（单条或批量）
搜索相似嵌入
移除嵌入
按元数据过滤

`YugabyteDBEngine`

使用 HikariCP 管理数据库连接与连接池。该类：

处理 JDBC 连接配置
管理连接池设置（最大池大小、超时等）
同时支持 PostgreSQL JDBC 驱动与 YugabyteDB Smart Driver
提供 SSL/TLS 配置选项

`YugabyteDBSchema`

定义数据库结构配置，包括：

表名与列名
向量索引类型（HNSW 或 NoIndex）
距离度量（COSINE、EUCLIDEAN、DOT_PRODUCT）
元数据存储配置
建表设置

用法示例

基本的 YugabyteDBEmbeddingStore

下面是创建 YugabyteDBEmbeddingStore 实例的方式：

java

YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .<builderParameters>
    .build();

其中 <builderParameters> 必须包含 dimension 与 engine，以及其他可选项。

参数总览

YugabyteDBEngine 参数

参数	描述	默认值	必填/可选
`host`	YugabyteDB 服务器的主机名	`localhost`	使用 engine builder 时必填
`port`	YugabyteDB 服务器的端口号	`5433`	使用 engine builder 时必填
`database`	要连接的数据库名	`yugabyte`	使用 engine builder 时必填
`username`	数据库认证的用户名	`yugabyte`	使用 engine builder 时必填
`password`	数据库认证的密码	`""`（空）	使用 engine builder 时必填
`schema`	数据库 schema 名	`public`	可选
`usePostgreSQLDriver`	使用 PostgreSQL JDBC 驱动而非 YugabyteDB Smart Driver	`false`	可选
`useSsl`	为数据库连接启用 SSL/TLS	`false`	可选
`sslMode`	SSL 模式配置	`disable`	可选
`maxPoolSize`	连接池中的最大连接数	`10`	可选
`minPoolSize`	连接池中的最小空闲连接数	`5`	可选
`connectionTimeout`	连接超时（毫秒）	`10000`	可选
`idleTimeout`	空闲超时（毫秒）	`300000`	可选
`maxLifetime`	连接的最大存活时间（毫秒）	`900000`	可选
`applicationName`	用于连接标识的应用名	`langchain4j-yugabytedb`	可选

YugabyteDBEmbeddingStore 参数

Parameter	Description	Default Value	Required/Optional
`engine`	The `YugabyteDBEngine` instance for database connections	None	Required
`dimension`	The dimensionality of the embedding vectors. This should match the embedding model being used. Use `embeddingModel.dimension()` to dynamically set it.	None	Required
`tableName`	The name of the database table used for storing embeddings	`langchain4j_embeddings`	Optional
`schemaName`	Database schema name	`public`	Optional
`idColumn`	Name of the ID column	`id`	Optional
`contentColumn`	Name of the content/text column	`content`	Optional
`embeddingColumn`	Name of the embedding vector column	`embedding`	Optional
`metadataColumn`	Name of the metadata column	`metadata`	Optional
`metricType`	Distance metric for similarity search: `COSINE`, `EUCLIDEAN`, or `DOT_PRODUCT`	`COSINE`	Optional
`vectorIndex`	Vector index configuration (see Index Configuration below)	`HNSWIndex` with default settings	Optional
`createTableIfNotExists`	Specifies whether to automatically create the embeddings table	`true`	Optional
`metadataStorageConfig`	Configuration object for handling metadata associated with embeddings. Supports three storage modes: • `COMBINED_JSONB`: For dynamic metadata stored in JSONB format for optimized querying (recommended) • `COMBINED_JSON`: For dynamic metadata stored as JSON • `COLUMN_PER_KEY`: For static metadata when you know the metadata keys in advance	`COMBINED_JSONB`	Optional

索引配置

HNSW 索引参数

参数	描述	默认值	必填/可选
`m`	每层的最大连接数。值越高 = 召回越好但更耗内存	`16`	可选
`efConstruction`	构建期间动态候选列表的大小。值越高 = 索引质量越好但构建更慢	`64`	可选
`metricType`	距离度量：`COSINE`、`EUCLIDEAN` 或 `DOT_PRODUCT`	`COSINE`	可选
`name`	自定义索引名	自动生成	可选

NoIndex

使用 new NoIndex() 进行无索引的顺序扫描。最适合小数据集（少于 10,000 个向量）或需要精确结果时。

基本用法

java

// Create engine first
YugabyteDBEngine engine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .usePostgreSQLDriver(true) // Use PostgreSQL JDBC driver
    .build();

// Minimal configuration
YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(384)
    .build();

// Custom configuration
YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(768)
    .tableName("my_embeddings")
    .metricType(MetricType.EUCLIDEAN)
    .build();

使用 YugabyteDBEngine

要对连接设置有更多控制，请使用 YugabyteDBEngine：

java

// Create engine with custom settings
YugabyteDBEngine engine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .maxPoolSize(20)
    .minPoolSize(5)
    .connectionTimeout("30000")
    .idleTimeout("300000")
    .maxLifetime("900000")
    .useSsl(false)
    .usePostgreSQLDriver(false) // Use YugabyteDB Smart Driver
    .build();

// Use engine in embedding store
YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(384)
    .tableName("embeddings")
    .build();

向量索引配置

YugabyteDB 支持不同的向量索引类型以优化相似度搜索：

HNSW 索引（推荐）

java

// Create engine
YugabyteDBEngine engine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .build();

// HNSW index with custom parameters
HNSWIndex hnswIndex = HNSWIndex.builder()
    .m(16)                    // Maximum connections per layer
    .efConstruction(64)       // Construction quality
    .metricType(MetricType.COSINE)
    .name("my_hnsw_index")
    .build();

YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(384)
    .vectorIndex(hnswIndex)
    .build();

无索引（顺序扫描）

java

// Create engine
YugabyteDBEngine engine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .build();

// No index for exact search (slower but exact)
YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(384)
    .vectorIndex(new NoIndex()) // Sequential scan
    .build();

添加与搜索嵌入

java

// Create engine first
YugabyteDBEngine engine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .build();

// Create embedding store
YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(384)
    .build();

// Add embeddings
TextSegment segment1 = TextSegment.from("YugabyteDB is a distributed SQL database");
Embedding embedding1 = embeddingModel.embed(segment1).content();
String id1 = store.add(embedding1, segment1);

TextSegment segment2 = TextSegment.from("PostgreSQL compatibility with horizontal scalability");
Embedding embedding2 = embeddingModel.embed(segment2).content();
String id2 = store.add(embedding2, segment2);

// Search embeddings
Embedding queryEmbedding = embeddingModel.embed("What is YugabyteDB?").content();
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
    .queryEmbedding(queryEmbedding)
    .maxResults(5)
    .minScore(0.7)
    .build();

List<EmbeddingMatch<TextSegment>> matches = store.search(request).matches();
matches.forEach(match -> {
    System.out.println("Score: " + match.score());
    System.out.println("Text: " + match.embedded().text());
});

元数据存储配置

YugabyteDB 支持不同的元数据存储模式：

java

// Create engine
YugabyteDBEngine engine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .build();

// JSONB storage (recommended for PostgreSQL compatibility)
MetadataStorageConfig jsonbConfig = MetadataStorageConfig.builder()
    .storageMode(MetadataStorageMode.COMBINED_JSONB)
    .build();

// JSON storage
MetadataStorageConfig jsonConfig = MetadataStorageConfig.builder()
    .storageMode(MetadataStorageMode.COMBINED_JSON)
    .build();

// Column-per-key storage
MetadataStorageConfig columnConfig = MetadataStorageConfig.builder()
    .storageMode(MetadataStorageMode.COLUMN_PER_KEY)
    .build();

YugabyteDBEmbeddingStore store = YugabyteDBEmbeddingStore.builder()
    .engine(engine)
    .dimension(384)
    .metadataStorageConfig(jsonbConfig)
    .build();

驱动配置

YugabyteDB 同时支持 PostgreSQL JDBC 驱动与 YugabyteDB Smart Driver：

java

// PostgreSQL JDBC Driver (standard SQL compatibility)
YugabyteDBEngine postgresEngine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .usePostgreSQLDriver(true)
    .build();

YugabyteDBEmbeddingStore postgresStore = YugabyteDBEmbeddingStore.builder()
    .engine(postgresEngine)
    .dimension(384)
    .build();

// YugabyteDB Smart Driver (advanced distributed features)
YugabyteDBEngine smartEngine = YugabyteDBEngine.builder()
    .host("localhost")
    .port(5433)
    .database("yugabyte")
    .username("yugabyte")
    .password("")
    .usePostgreSQLDriver(false) // Default: use Smart Driver
    .build();

YugabyteDBEmbeddingStore smartStore = YugabyteDBEmbeddingStore.builder()
    .engine(smartEngine)
    .dimension(384)
    .build();

索引类型

HNSW（ybhnsw）- 推荐

最适合：大多数用例，尤其是大型数据集
性能：快速的近似相似度搜索，召回率高
参数：
- m（默认：16）：每层最大连接数
- efConstruction（默认：64）：构建质量

NoIndex - 顺序扫描

最适合：小数据集（少于 10,000 个向量）或需要精确结果时
性能：精确搜索，但随着数据集增长会变慢

已知限制

YugabyteDB 需要启用 pgvector 扩展才能进行向量操作
同一表中所有嵌入的向量维度必须保持一致
HNSW 索引参数（m、efConstruction）会同时影响性能与内存占用
顺序扫描（NoIndex）仅推荐用于小数据集（少于 10,000 个向量）

性能考量

HNSW 索引：最适合大型数据集中的生产使用，提供快速的近似搜索
NoIndex：仅适合小数据集或需要精确结果时
连接池：根据你的工作负载配置 maxPoolSize 与 minPoolSize
驱动选择：YugabyteDB 推荐使用 PostgreSQL JDBC 驱动以获得更好的兼容性

示例

YugabyteDBEmbeddingStoreExample - 结合 Testcontainers 的基本示例
YugabyteDBEmbeddingStoreWithMetadataExample - 结合 JSONB 存储的元数据过滤
YugabyteDBWithPostgreSQLDriverExample - 使用 PostgreSQL JDBC 驱动
YugabyteDBWithSmartDriverExample - 使用 YugabyteDB Smart Driver

语言模型

嵌入存储

决策模型

YugabyteDB

Maven 依赖

API

`YugabyteDBEmbeddingStore`

`YugabyteDBEngine`

`YugabyteDBSchema`

用法示例

基本的 YugabyteDBEmbeddingStore

参数总览

YugabyteDBEngine 参数

YugabyteDBEmbeddingStore 参数

索引配置

HNSW 索引参数

NoIndex

基本用法

使用 YugabyteDBEngine

向量索引配置

HNSW 索引（推荐）

无索引（顺序扫描）

添加与搜索嵌入

元数据存储配置

驱动配置

索引类型

HNSW（ybhnsw）- 推荐

NoIndex - 顺序扫描

已知限制

性能考量

示例

友情链接