From b653a7665ea60f40389c7d8485acaca22710d624 Mon Sep 17 00:00:00 2001 From: scott Date: Tue, 3 Nov 2026 02:06:23 -0500 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=E5=8E=86=E5=8F=B2=E6=97=A5?= =?UTF-8?q?=E5=BF=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- jeecg-boot/UPGRADE-3.9.3.md | 347 ----------------------- jeecg-boot/UPGRADE-langchain4j-1.17.2.md | 307 -------------------- 2 files changed, 654 deletions(-) delete mode 100644 jeecg-boot/UPGRADE-3.9.3.md delete mode 100644 jeecg-boot/UPGRADE-langchain4j-1.17.2.md diff --git a/jeecg-boot/UPGRADE-3.9.3.md b/jeecg-boot/UPGRADE-3.9.3.md deleted file mode 100644 index 9e688dc48..000000000 --- a/jeecg-boot/UPGRADE-3.9.3.md +++ /dev/null @@ -1,347 +0,0 @@ -# JeecgBoot 3.9.3 升级日志 - -> 发布日期:2026-07-07 - -## 概述 - -本次升级聚焦于基础设施现代化,将核心框架从 Spring Boot 3 迁移至 Spring Boot 4,同步升级 Spring Cloud、XXL-JOB、Nacos、Shiro、Sentinel 等关键组件,全面提升平台的技术栈基线。 - ---- - -## 一、Spring Boot 3 → 4 升级(3.5.5 → 4.1.0) - -### 1.1 框架版本 - -| 组件 | 旧版本 | 新版本 | -|------|--------|--------| -| Spring Boot | 3.5.5 | **4.1.0** | -| Spring Framework | 6.x | **7.0** | -| Spring Cloud | 2024.x | **2025.1.2** | -| Spring Cloud Alibaba | 2024.x | **2025.1.0.0** | - -### 1.2 兼容性修复 - -**Jackson 3 迁移** - -Spring Boot 4 使用 Jackson 3(`tools.jackson`),替代 Jackson 2(`com.fasterxml.jackson`)。移除 `jackson-module-kotlin`(Jackson 2 专有,与 Jackson 3 不兼容,会导致 `ClassCastException`)。 - -```xml - - - -``` - -**UriComponentsBuilder API 变更** - -Spring Framework 7 移除了 `UriComponentsBuilder.fromHttpUrl()`,改用 `fromUriString()`: - -```java -// OpenApiController.java -// 旧: UriComponentsBuilder.fromHttpUrl(url) -// 新: UriComponentsBuilder.fromUriString(url) -UriComponentsBuilder builder = UriComponentsBuilder.fromUriString(url); -``` - -**RedisMessageListenerContainer Bean 冲突** - -Spring Boot 4.1 自动创建 `redisMessageListenerContainer`,与 JeecgBoot 自定义的 `redisContainer` 冲突,`DragWebSocket` 注入时出现二义性。 - -修复方案:新增 `RedisContainerPrimaryConfig`,通过 `BeanDefinitionRegistryPostProcessor` 将 `redisContainer` 标记为 `@Primary`: - -```java -@Component -public class RedisContainerPrimaryConfig implements BeanDefinitionRegistryPostProcessor { - @Override - public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) { - if (registry.containsBeanDefinition("redisContainer")) { - registry.getBeanDefinition("redisContainer").setPrimary(true); - } - } -} -``` - -### 1.3 其他适配 - -- Shiro 配置适配 Spring Framework 7 API 变更 -- Druid 配置适配新版本 Spring Boot 自动装配 -- Swagger3 / Knife4j 配置适配 Spring Boot 4 -- 单元测试框架适配 - ---- - -## 二、XXL-JOB 2.4.1 → 3.4.2 升级 - -### 2.1 升级内容 - -| 组件 | 旧版本 | 新版本 | 说明 | -|------|--------|--------|------| -| xxl-job-core | 2.4.1 | **3.4.2** | 核心调度引擎 | -| xxl-sso-core | — | **2.4.0** | 新增,3.x 管理平台登录认证 | -| xxl-tool | — | **2.5.0** | 工具库 | -| mybatis-spring-boot-starter | 3.0.3 | **4.0.1** | MyBatis 适配 Spring Boot 4 | - -### 2.2 主要变更 - -**源码结构重组** -- 管理平台 controller 从 `com.xxl.job.admin.controller` 迁移到 `com.xxl.job.admin.business.controller` -- 调度器从 `com.xxl.job.admin.core.scheduler` 迁移到 `com.xxl.job.admin.business.scheduler` -- model/mapper 从 `core` 迁移到 `business` 包 - -**API 迁移:ReturnT → Response** - -XXL-JOB 3.x 全面使用 `Response` 替代 `ReturnT`: - -```java -// 旧 -ReturnT execute(String param) { return ReturnT.SUCCESS; } - -// 新 -Response execute(String param) { return Response.SUCCESS; } -``` - -**认证方式变更** -- 2.x:数据库 `xxl_job_user` 表 MD5 密码 -- 3.x:`xxl-sso` 单点登录框架,SHA-256 密码,默认账号 `admin/123456` - -**执行器注册机制** -- 3.x 引入了新的执行器注册和发现机制 -- `JeecgXxlJobSpringExecutor` 做了适配以支持 `@Bean` 方法上的 `@XxlJob` 注解扫描 - -**配置文件格式** -- application.yml → application.properties(解决 `xxl-sso.token.key` 等带点号/横线的 key 解析问题) - -**数据库** -- 新数据库名 `xxl_job`,表结构变化需重新导入 `db/tables_xxl_job.sql` - -### 2.3 保留的 JeecgBoot 定制 - -- `XxlJobAdminApplication` 启动日志 -- `jeecg.xxljob` 配置前缀支持 -- 邮件告警配置集成 JeecgBoot 邮件配置 -- Nacos 服务发现适配 - ---- - -## 三、Nacos 2.3.2 → 3.2.2 升级 - -### 3.1 升级策略 - -使用重新打包的 Nacos 3.2.2,解决官方 Nacos 依赖兼容性问题。 - -**去掉 pom 中 springboot3 命名空间**:Nacos 模块不再继承 `jeecg-boot-parent`(`org.jeecgframework.boot3`),改为直接以 `spring-boot-starter-parent 4.1.0` 为 parent,退出主项目的 springboot3 版本体系,独立管理依赖。 - -### 3.2 启动模式 - -从单阶段启动改为**三阶段启动**: - -```java -// 阶段1: Core Context(无 Web) -NacosServerBasicApplication → coreContext -// 阶段2: Server Web Context -NacosServerWebApplication → parent(coreContext) -// 阶段3: Console Context -NacosConsole → parent(coreContext) -``` - -启动类:`JeecgNacosApplication` - -### 3.3 依赖管理 - -**Hessian 版本统一** - -Nacos 3.x 多个依赖引入不同版本 Hessian(`com.caucho.hessian`、`com.alipay.sofa.hessian`),存在 API 冲突。排除所有传递 Hessian,统一使用 `com.caucho:hessian:4.0.66`。 - -```xml - -``` - -### 3.4 配置变更 - -- `application.yml` → `application.properties` -- 数据库名:`nacos`(新库,建表脚本 `db/tables_nacos.sql`) -- 控制台端口:`18080`,上下文路径:`/nacos` -- 部署模式:`merged`(三合一) -- 关闭 AI 扩展和广告开关 -- 新增 `logback-spring.xml` -- **删除 springboot3/springboot2 命名空间切换规则**:不再支持 springboot2,新库默认只提供 springboot3/4 的配置 - -### 3.5 JVM 参数 - -```bash ---add-opens java.base/java.lang=ALL-UNNAMED ---add-opens java.base/java.lang.reflect=ALL-UNNAMED ---add-opens java.base/java.util=ALL-UNNAMED ---add-opens java.base/java.io=ALL-UNNAMED -``` - ---- - -## 四、其他组件升级 - -| 组件 | 旧版本 | 新版本 | 说明 | -|------|--------|--------|------| -| MyBatis-Plus | 3.5.14 | **3.5.16** | ORM 框架 | -| Druid | — | **1.2.28** | 数据库连接池 | -| JSqlParser | — | **5.0** | SQL 解析器 | -| Shiro | < 2.0 | **3.0.0** | 安全框架 | -| shiro-redis | — | **4.1.0** | Shiro Redis 支持(切换到 `io.github.weir2010`) | -| Sentinel Dashboard | 1.8.3 | **1.8.10** | 流量控制(支持 JDK17) | -| MinIO | 8.5.7 | **9.0.3** | 对象存储客户端 | -| commonmark | — | **0.28.0** | Markdown 解析库 | -| AutoPoi | — | **2.0.5** | Excel/Word 工具类(Spring Boot 3/4 专版) | -| commons-io | — | **2.21.0** | Apache Commons IO 工具库 | -| LangChain4j | 1.12.2 | **1.17.2** | AI/LLM 集成框架(正式稳定版) | -| LangChain4j Community BOM | 1.12.2-beta9 | **1.17.2-beta27** | 社区模型(通义/文心/智谱等) | -| Apache Tika | — | **3.3.1** | 文档内容解析器(PDF/HTML/Office)| - -### 4.2 AI RAG 模块:LangChain4j 1.12.2 → 1.17.2 - -**langchain4j-pgvector 切回官方版本** - -1.17.2 官方正式支持 pgvector 向量维度超过 1000(最高 2000),无需再依赖自定义 fork 版本。直接通过 `langchain4j-bom` 管理版本即可: - -```xml - - - dev.langchain4j - langchain4j-bom - 1.17.2 - pom - import - - - - - dev.langchain4j - langchain4j-pgvector - -``` - -官方 pgvector 源码参考:https://github.com/langchain4j/langchain4j/tree/main/langchain4j-pgvector - -**主要升级亮点(1.12.2 → 1.17.2)** - -- `langchain4j-pgvector` 正式版(不再是 beta),支持 HNSW 索引(`IndexType.HNSW`),向量检索精度和性能优于 IVFFlat -- 新增 `schemaName()` 支持自定义 PostgreSQL schema -- 修复向量维度超过 1000(最高 2000)的限制问题 -- `EmbeddingStore` API 趋于稳定,`search(EmbeddingSearchRequest)` 完整支持 Filter 过滤 - -### 4.1 新增 jeecg-boot-starter-sentinel(按需引入) - -> ⚠️ **不兼容变更**:旧版 Sentinel 功能内置在 starter-cloud 中自动生效,新版改为**按需引入**,必须显式添加 `jeecg-boot-starter-sentinel` 依赖后才能使用 Sentinel 限流熔断功能。 - -本次封装了独立的 **jeecg-boot-starter-sentinel** 模块,将 Sentinel 限流降级能力抽离为公共 starter,与 `starter-cloud` 解耦。 - -**模块结构:** - -``` -jeecg-boot-starter-sentinel/ -├── JeecgSentinelAutoConfiguration.java # 自动配置(注册 Bean) -├── handler/ -│ └── JeecgUrlBlockHandler.java # 限流降级处理器(HTTP 429) -├── parser/ -│ └── JeecgHeaderRequestOriginParser.java # 请求来源解析器(IP/参数) -└── feign/ - ├── JeecgSentinelFeign.java # 自定义 Feign Builder - └── JeecgSentinelInvocationHandler.java # Feign 调用拦截处理器 -``` - -**功能要点:** -- Feign 熔断:支持 `@FeignClient` 的 `fallback`/`fallbackFactory` 自动注入 -- 限流降级响应:被 Sentinel 限流时返回 HTTP 429 + 统一 JSON -- 请求来源解析:基于请求参数 `origin` 或 `X-Forwarded-For` 头 -- 与 `starter-cloud` 解耦,按需引入 - -```xml - - org.jeecgframework.boot3 - jeecg-boot-starter-sentinel - -``` - ---- - -## 五、数据库变更 - -| 数据库 | 说明 | -|--------|------| -| `xxl-job` | XXL-JOB 3.4.2 新库,需导入 `db/tables_xxl_job.sql` | -| `nacos` | Nacos 3.2.2 新库,建表脚本 `db/tables_nacos.sql` | - -> ⚠️ Nacos 3.x 和 XXL-JOB 3.x 不会自动建表,需手动执行 `db/tables_nacos.sql` 和 `db/tables_xxl_job.sql`。 - ---- - -## 六、⚠️ 不兼容升级提醒 - -**Nacos 和 XXL-JOB 需要重新初始化数据库!** - -- Nacos 2.x → 3.x、XXL-JOB 2.x → 3.x 均为**大版本升级**,表结构不兼容,需用新库重新建表 -- **升级前请备份老库**,然后将老库中的配置(Nacos 配置项、XXL-JOB 任务等)手工迁移到新库 -- 建表脚本: - - Nacos:`db/tables_nacos.sql` - - XXL-JOB:`db/tables_xxl_job.sql` - -**访问地址变更** - -| 服务 | 旧地址 | 新地址 | -|------|--------|--------| -| Nacos 控制台 | `http://localhost:8848/nacos` | `http://localhost:18080/nacos` | -| XXL-JOB 管理 | `http://localhost:9080/xxl-job-admin` | `http://localhost:9080/` | - -> Nacos 端口从 8848 改为 18080;XXL-JOB 去掉了 `/xxl-job-admin` 项目后缀。 - ---- - -## 七、升级注意事项 - -1. **Java 版本**:仍需 Java 17+,Spring Boot 4 同时支持 Java 17/21/24 -2. **XXL-JOB 执行器**:确保 `jeecg-boot-starter-job` 模块排除旧版 `xxl-job-core`,统一使用 3.4.2 -3. **Nacos**:初次启动前需手动导入数据库表,三阶段启动完成后访问 `http://localhost:18080/nacos` -4. **Spring Boot 4**:注意 `jakarta` 命名空间(无变化,3.x 已采用);Jackson 3 替代 Jackson 2 -5. **线上部署**:微服务模块的 Dockerfile 中 jar 包名已更新为 `3.9.3` -6. **IDE 编码**:项目使用 Tab 缩进,properties/YAML 文件使用 UTF-8 编码 -7. **jeecg-boot-starter 3.9.4 未上传至 Maven Central**:`jeecg-boot-starter` 3.9.4 版本**未上传至 Maven Central 官方仓库**,需在 `pom.xml` 中配置 jeecg 私有仓库方可下载: - -```xml - - - jeecg - jeecg Repository - https://maven.jeecg.com/nexus/content/repositories/jeecg - - false - - - -``` - ---- - -## 八、版本号对照 - -``` -JeecgBoot: 3.9.2 → 3.9.3 -Spring Boot: 3.5.5 → 4.1.0 -Spring Cloud: 2024.x → 2025.1.2 -SC Alibaba: 2024.x → 2025.1.0.0 -XXL-JOB: 2.4.1 → 3.4.2 -Nacos Server: 2.3.2 → 3.2.2 -Shiro: <2.0 → 3.0.0 -shiro-redis: — → 4.1.0 -MyBatis-Plus: 3.5.14 → 3.5.16 -MyBatis-Starter: 3.0.3 → 4.0.1 -Druid: — → 1.2.28 -JSqlParser: — → 5.0 -Sentinel: 1.8.3 → 1.8.10 -MinIO: 8.5.7 → 9.0.3 -LangChain4j: 1.12.2 → 1.17.2 -LC4j Community: 1.12.2-beta9 → 1.17.2-beta27 -Apache Tika: — → 3.3.1 -commonmark: — → 0.28.0 -AutoPoi: — → 2.0.5 -commons-io: — → 2.21.0 -``` diff --git a/jeecg-boot/UPGRADE-langchain4j-1.17.2.md b/jeecg-boot/UPGRADE-langchain4j-1.17.2.md deleted file mode 100644 index c096d393f..000000000 --- a/jeecg-boot/UPGRADE-langchain4j-1.17.2.md +++ /dev/null @@ -1,307 +0,0 @@ -# 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 自动管理) |