# 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。
```xml
dev.langchain4j
langchain4j-bom
1.17.2
pom
import
dev.langchain4j
langchain4j-pgvector
```
---
## 三、新功能
### 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 参数 |
```java
// SearchMode 枚举值
public enum SearchMode {
VECTOR, // 纯向量检索（默认，与旧版行为一致）
HYBRID // 向量 + 全文检索，RRF 融合排名
}
```
#### 使用示例
```java
// 纯向量检索（默认，保持向后兼容）
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 连接池的场景，避免重复创建数据库连接。
```java
// 旧版：只能由 pgvector 内部创建 DataSource
PgVectorEmbeddingStore.builder()
.host("...").port(5432)...
// 新版：直接注入 Spring 管理的 DataSource
@Autowired
DataSource dataSource; // Spring 的主数据源或专用 DataSource
EmbeddingStore 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**
```java
.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 写入（幂等写入、增量同步场景）：
```java
// 旧版：ID 由 pgvector 自动生成（UUID）
List ids = store.addAll(embeddings, segments);
// 新版：支持外部预分配 ID
List 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 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 配置
```xml
dev.langchain4j
langchain4j-bom
1.17.2
pom
import
dev.langchain4j
langchain4j-community-bom
1.17.2-beta27
pom
import
dev.langchain4j
langchain4j-pgvector
```
### 7.2 代码兼容性
`EmbeddingHandler.java` 中现有的 Builder 调用**无需修改**，1.17.2 完全向后兼容：
```java
// 现有代码，升级后继续有效
EmbeddingStore 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 可选：开启混合检索提升效果
```java
// 如需开启混合检索，在现有 builder 后追加即可
EmbeddingStore 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 自动管理） |