mirror of https://github.com/jeecgboot/JeecgBoot.git synced 2026-08-18 10:48:47 +00:00

JEECG 2ebe098b5c 升级langchain4j从1.12.2到1.17.2、apache-tika.version>3.3.1、langchain4j-pgvector切回官方版本(官方已解决pgvector向量数据库不支持2000维度问题)

2026-07-09 11:33:41 +08:00

10 KiB

Raw Permalink Blame History

LangChain4j 升级日志： 1.17.2

适用模块：jeecg-boot-module-airag 升级日期：2026-07-09 官方仓库：https://github.com/langchain4j/langchain4j/tree/main/langchain4j-pgvector

一、版本概览

组件	旧版本	新版本
`langchain4j-bom`	1.3.0	1.17.2
`langchain4j-pgvector`	1.3.0-beta9（独立 beta）	1.17.2（正式稳定版）
`langchain4j-community-bom`	1.3.0-beta9	1.17.2-beta27
`com.pgvector:pgvector` 驱动	~0.1.4	0.1.6
`org.postgresql:postgresql`	~42.6.x	42.7.11

重要：langchain4j-pgvector 在 1.3.0 周期中仍是独立 beta 版本（1.3.0-beta9），到 1.17.2 正式毕业为稳定版（GA），API 不再有 breaking change 风险。

二、核心变更：pgvector 向量维度限制修复

问题背景

旧版 com.pgvector:pgvector Java 驱动（~0.1.4）在创建 PGvector 对象时存在维度上限约束，导致使用超过 1000 维的嵌入模型（如 text-embedding-3-large 的 1536 维、部分 3072 维模型）时报错。

JeecgBoot 为此维护了一份自定义 fork以绕过该限制。

修复结果

升级到官方 com.pgvector:pgvector:0.1.6 后，配合 pgvector PostgreSQL 扩展 0.7.0+，最大支持维度提升至 2000，可直接使用官方版本，无需 fork。

<!-- 切回官方版本，通过 BOM 统一管理 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-bom</artifactId>
    <version>1.17.2</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-pgvector</artifactId>
    <!-- 无需指定 version，由 BOM 管理 -->
</dependency>

三、新功能

3.1 混合检索（Hybrid Search）

PR #4288，2026-02-03

新增 SearchMode 枚举，支持向量检索 + 全文检索融合排名（Reciprocal Rank Fusion，RRF）。

新增 Builder 参数

参数	类型	默认值	说明
`searchMode`	`SearchMode`	`VECTOR`	检索模式
`textSearchConfig`	`String`	`"simple"`	PostgreSQL 全文搜索配置
`rrfK`	`Integer`	`60`	RRF 融合算法的 k 参数

// SearchMode 枚举值
public enum SearchMode {
    VECTOR,   // 纯向量检索（默认，与旧版行为一致）
    HYBRID    // 向量 + 全文检索，RRF 融合排名
}

使用示例

// 纯向量检索（默认，保持向后兼容）
PgVectorEmbeddingStore store = PgVectorEmbeddingStore.builder()
    .host("localhost").port(5432)
    .user("postgres").password("xxx").database("mydb")
    .table("embeddings")
    .dimension(1536)
    .useIndex(true).indexListSize(100)
    .build();

// 混合检索（新功能）
PgVectorEmbeddingStore store = PgVectorEmbeddingStore.builder()
    .host("localhost").port(5432)
    .user("postgres").password("xxx").database("mydb")
    .table("embeddings")
    .dimension(1536)
    .useIndex(true).indexListSize(100)
    .searchMode(SearchMode.HYBRID)   // 开启混合检索
    .textSearchConfig("simple")       // PG 全文配置，中文推荐 "simple"，英文可用 "english"
    .rrfK(60)                         // RRF k 参数，值越大重排范围越大
    .build();

HYBRID 模式原理：同时执行向量 ANN 检索和 PostgreSQL tsvector 全文检索，然后通过 RRF 算法合并两组结果的排名，提升稀疏词语（专有名词、代码片段）的召回率。

3.2 DatasourceBuilder — 外部 DataSource 注入

较新版本新增

新增 PgVectorEmbeddingStore.datasourceBuilder() 工厂方法，适用于已有 Spring 连接池的场景，避免重复创建数据库连接。

// 旧版：只能由 pgvector 内部创建 DataSource
PgVectorEmbeddingStore.builder()
    .host("...").port(5432)...

// 新版：直接注入 Spring 管理的 DataSource
@Autowired
DataSource dataSource;   // Spring 的主数据源或专用 DataSource

EmbeddingStore<TextSegment> store = PgVectorEmbeddingStore.datasourceBuilder()
    .datasource(dataSource)              // 注入外部 DataSource
    .table("embeddings")
    .dimension(1536)
    .createTable(true)
    .searchMode(SearchMode.VECTOR)
    .build();

注意：datasourceBuilder() 和 builder() 支持相同的配置参数（searchMode、textSearchConfig、rrfK、skipCreateVectorExtension 等）。

3.3 `skipCreateVectorExtension` — 跳过扩展创建

PR #4576，2026-02-12

.skipCreateVectorExtension(true)  // 默认 false

适用场景：云数据库（AWS RDS、阿里云 PolarDB）或受管 PostgreSQL 中，数据库用户无 superuser 权限，无法执行 CREATE EXTENSION IF NOT EXISTS vector。由 DBA 预装 pgvector 扩展后，应用侧设置此参数跳过。

3.4 `addAll` 支持预分配 ID

PR #2156，2024-12-04

新增 EmbeddingStore 接口方法重载，支持外部指定 ID 写入（幂等写入、增量同步场景）：

// 旧版：ID 由 pgvector 自动生成（UUID）
List<String> ids = store.addAll(embeddings, segments);

// 新版：支持外部预分配 ID
List<String> customIds = List.of("doc-001", "doc-002", "doc-003");
store.addAll(customIds, embeddings, segments);

四、Bug 修复 & 性能优化

4.1 搜索 SQL 重写，索引真正生效（PR #2485，2025-02-04）

问题：旧版 1.3.0-beta9 的查询 SQL 写法导致 IVFFlat 向量索引实际失效，数据量大时全表扫描，响应慢。

修复：重写搜索 SQL，useIndex(true) 设置后索引真正被使用，高数据量场景性能显著提升。

⚠️ 升级后建议：若生产环境已建立 IVFFlat 索引，升级后可用 EXPLAIN ANALYZE 验证查询是否走了索引。

4.2 减少不必要的数据库连接（PR #4422，2026-01-14）

旧版在 Store 初始化时会创建额外的 DB 连接用于检测，新版优化了连接获取逻辑，减少连接池压力，启动速度更快。

4.3 Schema 名称处理修复（PR #4592，2026-02-18）

问题：当 table 参数包含 schema 前缀（如 "myschema.embeddings"）时，创建索引的 SQL 会错误地将整个字符串当作表名，导致索引名含非法字符。

修复：建索引时自动从表名中剥离 schema 前缀，仅用纯表名生成索引名。

五、工程改进

5.1 去 Lombok（PR #2751，2025-03-21）

移除了 Lombok 注解（@Builder、@Data、@Getter 等），改为手写 Builder 和 getter 代码（Delombok）。

减少编译期注解处理器依赖
更好地兼容 Java 17+ / GraalVM 原生编译
IDE 代码提示更准确

5.2 依赖升级

依赖	旧版本	新版本	说明
`com.pgvector:pgvector`	~0.1.4	0.1.6	最大维度 1000 → 2000
`org.postgresql:postgresql`	~42.6.x	42.7.11	安全修复、性能优化

六、1.3.0-beta9 已有、未变更的功能

以下功能在 1.3.0-beta9 中已存在，1.17.2 保持兼容，无 breaking change：

功能	说明
`MetadataStorageConfig`	JSON / JSONB / COMBINED_JSONB / COLUMN_PER_KEY 四种元数据存储模式
`removeAll(Collection<String> ids)`	按 ID 批量删除向量
`removeAll(Filter filter)`	按 Filter 条件删除向量
`search(EmbeddingSearchRequest)`	带 Filter 的向量检索
`useIndex` / `indexListSize`	IVFFlat 索引（注意：旧版索引实际失效，4.1 已修复）
`createTable` / `dropTableFirst`	表生命周期管理
`host/port/user/password/database/table/dimension`	基础连接配置

七、JeecgBoot 迁移说明

7.1 pom.xml 配置

<!-- jeecg-boot-module-airag/pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-bom</artifactId>
            <version>1.17.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-community-bom</artifactId>
            <version>1.17.2-beta27</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- pgvector 切回官方版本，由 BOM 管理 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-pgvector</artifactId>
    </dependency>
</dependencies>

7.2 代码兼容性

EmbeddingHandler.java 中现有的 Builder 调用无需修改，1.17.2 完全向后兼容：

// 现有代码，升级后继续有效
EmbeddingStore<TextSegment> embeddingStore = PgVectorEmbeddingStore.builder()
    .host(embedStoreConfigBean.getHost())
    .port(embedStoreConfigBean.getPort())
    .database(embedStoreConfigBean.getDatabase())
    .user(embedStoreConfigBean.getUser())
    .password(embedStoreConfigBean.getPassword())
    .table(tableName)
    .dimension(embeddingModel.dimension())
    .useIndex(true)
    .indexListSize(100)
    .createTable(true)
    .dropTableFirst(false)
    .build();

7.3 可选：开启混合检索提升效果

// 如需开启混合检索，在现有 builder 后追加即可
EmbeddingStore<TextSegment> embeddingStore = PgVectorEmbeddingStore.builder()
    .host(embedStoreConfigBean.getHost())
    // ... 其他参数保持不变 ...
    .searchMode(SearchMode.HYBRID)   // 新增
    .textSearchConfig("simple")       // 新增，中文场景推荐 "simple"
    .build();

注意：HYBRID 模式的 EmbeddingSearchRequest.query() 需要包含文本内容（非空），否则全文检索部分会报错。

八、升级影响总结

变更项	影响级别	是否需要改代码
维度限制修复（2000 维）	🔴 高（核心原因）	否，透明修复
搜索 SQL 重写（索引生效）	🔴 高（性能改善）	否，透明修复
Hybrid Search	🟡 中（可选新功能）	按需添加 `.searchMode()`
DatasourceBuilder	🟡 中（可选优化）	按需迁移
skipCreateVectorExtension	🟢 低（云环境按需）	按需添加
addAll with IDs	🟢 低（可选新 API）	按需使用
去 Lombok	🟢 低（透明）	否
依赖版本升级	🟢 低	否（BOM 自动管理）

10 KiB Raw Permalink Blame History Unescape Escape