Java 工程师 LLM 工程化

Appearance

变更日志：版本升级时先看这里 ​

1. 本节产出 ​

一份随课程更新的变更记录：框架版本变化带来的 API 变更、已验证的版本组合、以及每次升级需要检查的清单。

2. 前置依赖 ​

3. 为什么变更日志必须有 ​

AI 框架迭代极快，一个季度前写的代码可能就跑不起来了。三个真实场景：

场景没有变更日志时
学员按课程跑不通不知道是自己错了还是版本变了，只能放弃
你要升级项目不知道哪些 API 变了，只能全部试一遍
出了诡异 bug不知道是不是某次升级引入的

变更日志是「课程可信度」的一部分：学员能看到你在持续维护，而不是写完就跑。

4. 核心原理 ​

4.1 记录什么 ​

类型例子
破坏性变更defaultFunctions → defaultTools
新增能力新增某种 Advisor / 向量库支持
行为变化某参数的默认值变了
已验证组合Boot 4.0.x + AI 2.0.x 已跑通全部 demo
已知问题某版本下某功能异常

只记「对使用者有影响的变化」，不记内部重构。

4.2 升级检查清单 ​

升级 Spring AI 版本前：
  □ 查本页的破坏性变更清单
  □ 检查 starter 命名是否变化
  □ 检查配置项前缀是否变化
  □ 跑一遍全部 demo 的测试
  □ 重跑评测集（阈值可能需要重新标定）
  □ 更新 00-03 版本矩阵
  □ 在本页追加一条记录

「重跑评测集」这一条最容易漏：框架升级后效果可能变化，阈值（similarityThreshold 等）需要重新标定。

4.3 版本冻结策略 ​

课程维护一个「推荐版本组合」，每季度验证一次：
  - 全部 demo 能跑通
  - 全部测试通过
  - 评测集结果达标

非推荐组合标记为「未验证」，学员自行承担风险

5. 变更记录 ​

5.1 当前推荐组合 ​

组件版本状态
JDKJava 21已验证
Spring Boot4.x已验证
Spring AI2.0.x已验证
PGVectorpgvector/pgvector:pg16已验证
Redis7-alpine已验证
Elasticsearch8.x已验证（混合检索用）

本课程正文以此组合编写。 使用 Boot 3.5 + AI 1.1 的学员，主要差异见下。

5.2 Spring AI 1.x → 2.x 的主要变化 ​

变化1.x2.x影响
starter 命名spring-ai-openai-spring-boot-starterspring-ai-starter-model-openai依赖拉不到
工具注册.defaultFunctions(...).defaultTools(...)工具不生效（可能不报错）
工具回调FunctionCallback 体系ToolCallback 体系自定义工具需改写
Advisor API部分类名调整以实际 BOM 为准编译错误
向量库 starter命名各异统一 spring-ai-starter-vector-store-*依赖坐标变化

提示：这张表是「升级时最可能踩的坑」，不是完整变更清单。完整清单以官方 Release Notes 为准（见 官方资料索引）。

5.3 版本记录 ​

日期变更影响章节
2026-10-03课程初版，基于 Boot 4.x + Spring AI 2.0.x全部
2026-10-03补充离线分发与官方资料索引99-01

5.4 待验证项 ​

项状态说明
Milvus starter 在 2.x 下的完整验证待做02-06 提供了配置，未完整跑通
各厂商 Rerank 接口的统一封装待做各厂商差异大，需逐个适配
Elasticsearch 中文分词（ik）配置待做02-09 用了默认分词

6. 跑起来 ​

升级前对照检查清单逐项确认。

检查项通过标准
破坏性变更已列出能查到 1.x → 2.x 的主要变化
推荐组合已验证标注了验证日期
升级清单可用逐项可勾选
待验证项可见未验证的能力被明确标注

7. 生产避坑 ​

  1. 升级后必须重跑评测集并重新标定阈值。框架版本变化会改变效果（尤其是 Embedding 相关的相似度分布），沿用旧阈值会导致检索质量悄悄下降且不报错。
  2. 不要把「未验证」的组合写成「支持」。学员按未验证的组合搭建环境失败，会直接导致退课。明确标注验证状态，是对学员负责也是对自己负责。
  3. 每季度重跑一次全部 demo。框架迭代快，一次升级可能让多个 demo 同时失效。把「季度重跑」做成定期任务，不要等到学员反馈。

8. 延伸与锚点 ​