Java 转 AI 路线：先跑通知识服务，再接真实模型

IT枫斗者2026/11/6大约 11 分钟学习路线Java AIRAG

适合已有 Java、Spring Boot、SQL 和 HTTP 接口基础，准备增加 AI 应用能力的同学。主项目是Java 知识库服务，源码位于 examples/knowledge-service，也可下载源码包。沿同一条“登录 → 文档 → 检索 → 引用”链路动手，逐层检查实现与结果。

前六步是本地检索与后端验收主线，可按每周 8—10 小时、约六周安排。真实模型与生成另留时间，按环境和验证结果推进。还不能独立开发接口时，先补基础准备。

先看清你准备运行哪一层

层次	当前项目提供什么	这条路线怎样验收
默认本地模式	H2 持久化、认证、版本和权限；`local-lexical-extractive` 词项检索，返回原文摘录	前六步亲自运行接口、核对引用；不需要模型密钥或 Docker
可选向量模式	Maven 与运行时两个 `ai` 开关，使用 Spring AI EmbeddingModel 和 PgVectorStore；回答仍为原文摘录	现有报告的真实 pgvector 测试使用确定性三维测试向量；真实 embedding API 要在扩展一中另行验证
生成式问答	当前服务没有聊天模型生成链路	扩展二在自己的练习副本中新增；提示词、上下文、引用和生成效果都需单独验收

现有项目验证报告区分这些范围，其中真实模型 API 与语义质量未测。编译通过、向量存储通过、模型调用成功和回答正确是四件不同的事。以下检查点是你的练习目标，实际结果需要执行后填写。

第一步：启动服务，查到自己的第一份文档

阅读： 首次运行教程、项目页的最小运行与接口说明，以及源码包内的 README.md、API.md。
任务： 准备 JDK 21、Maven 3.9+，进入项目目录，Windows 执行 .\start.cmd，Linux/macOS 执行 sh start.sh。访问 http://127.0.0.1:8085/，检查 GET /api/health，使用本地演示账号 admin 登录（密码见包内 README），并调用 GET /api/me。创建一份合成文档，例如标题“年假规则”、正文“本地练习：年假五天。”、minRole=READER，再向 POST /api/search 提交 {"question":"年假","topK":3}。
产物： 环境卡、启动命令、文档创建请求与响应、检索响应；标出 mode、answer 和 citations 中的文档 ID、版本与原文。共享记录移除 Bearer token。
检查点： 能按 Api.java → Auth.java / Knowledge.java → 数据库 画出请求链，知道数据保存在启动目录的 data/knowledge.mv.db。健康检查只验证数据库连通，登录和检索要各自成功。
卡住怎么办： 按使用帮助先查 JDK、Maven、8085 端口和启动目录。认证后请求要带 Authorization: Bearer <token>；网页刷新后重新登录。先完成默认模式，不在这一步接模型。

第二步：改同一份文档，检查版本与删除

阅读： 包内 API.md 的更新与删除请求，Knowledge.java 的 update、delete、search；配合文档更新与删除指南理解更复杂系统的设计。
任务： 保存第一步返回的文档 ID，用 PUT /api/documents/{id} 携带当前 expectedVersion，将五天改为十天；同一问题复查引用版本。再次携带旧版本更新，检查冲突响应。最后用 DELETE /api/documents/{id}?expectedVersion=当前版本 删除，再查同一问题。实验时避免其他同主题文档干扰。
产物： 更新前、更新后、旧版本冲突和删除后的请求与响应，附同一 ID 的版本变化表。
检查点： 更新只引用当前允许版本，旧版本写入得到 409；删除后该 ID 不再作为引用，不能回退旧版。知道墓碑删除保留历史，不代表物理擦除。指南中的分块、异步索引和补偿方案不等于本项目已经实现。
卡住怎么办： 更新原 ID，不要通过再次 POST 创建“新版”。创建时省略 expectedVersion，更新或删除时使用最新成功响应里的版本。样例导入脚本重复运行会创建新文档，不具备去重幂等能力；先用单文档手工验证。

第三步：用两个身份验证权限，再补一个无证据问题

阅读： 包内 README 的演示身份与权限表，Auth.java 中的服务端身份、Knowledge.java 的 list 和 allowed，以及首次运行教程。
任务： 用 alpha 租户的 admin 和 beta 租户的 other 各建一份同名、内容带不同合成标记的文档，各自查询“年假”。再在 alpha 将一份文档的当前版本设为 ADMIN 可读，分别使用 admin 与 reader 查询和直接读取。另提一个与现有词项不重合的问题，记录无命中行为；最后退出登录并复用已撤销 token 发请求。
产物： 一张“用户、租户、角色、文档、预期、实际”对照表，附检索引用、直接读取状态和撤销后的响应。
检查点： 跨租户或不可见文档的直接读取为 404；reader 写入为 403；认证缺失或 token 已撤销为 401。检索无命中仍是正常接口响应，应核对 refused=true 与空引用。授权正例也必须可用，不能靠全部拒答过关。
卡住怎么办： 先调用 /api/me 核对每个 token 的身份，确认复制请求时没有混用。minRole 是文档访问级别；请求体多加 tenant 或 role 字段会得到 400，不能借此切换调用者身份。使用新建、内容明确的小文档排除已有数据干扰。

第四步：先写预期，再逐题做检索验收

阅读： 验收手册的环境卡、更新、权限与空白记录；RAG 评估指南用于理解指标和分母。
任务： 先整理约十条适合当前模式的题目，覆盖正常命中、无命中、跨租户、角色受限、更新、删除和版本冲突。逐题写明测试身份、当前文档、预期引用或状态，再执行。手册里的缓存、生成、异步任务用例按实际能力挑选，尚未实现的标为待验证。
产物： 文档快照、运行模式、逐题请求和原始响应、人工判定与失败原因；给调试题和留待最后复查的题分组。
检查点： 引用的 ID、版本、权限与原文一起核对。默认接口提供的是引用，不提供分块 ID 或生成上下文，相关字段填“不适用”。词项分数表示覆盖程度，不能当作答案正确率；同义词漏检和碰巧命中都要保留。
卡住怎么办： 先完成一条授权正例和一条拒答题，再逐项增加。预期不明确就先人工核对文档；不要边看实际响应边改标准答案，也不要把手册的七题成绩抄进自己的记录。

第五步：找到一处失败，留下自己的改动

阅读： RAG 故障排查、包内已有回放工具，以及与失败相关的 Knowledge.java 或错误处理代码。接外部依赖前可先读接口超时预算。
任务： 从第四步挑一个失败或缺少证据的边界，固定一份文档、一个身份和一个问题。先沿身份、当前版本、可见文档、匹配词项和引用定位；再在自己的练习副本中补一项当前未覆盖的回放断言，或增加一处必要的脱敏诊断信息。改动前后都执行同一输入，并回放已有正常场景。
产物： 最小复现、首个证据断点、个人提交或代码差异、原始失败与复跑记录。没有业务缺陷时，可以交付新增回放或诊断改进，不必虚构一次修复。
检查点： 能区分授权阻断、词项漏检与存储故障；当前主线没有模型生成，不能把失败归因于“模型幻觉”。每项改动能解释用途，日志不保存令牌或不必要的正文。
卡住怎么办： 去掉批量导入和多身份，只保留最小请求。缺哪段证据先补哪段；无法稳定重现就记录条件和下一次采集动作，不提前写“已解决”。

第六步：演示已完成的部分，列出下一层缺口

阅读： 项目故事与证据、项目简历资料和项目到简历路线。
任务： 从新启动的服务开始演示登录、查询、更新或权限变化，以及一个失败分支。用三分钟说明请求链、本人改动、验证依据和未完成项；将前五步材料整理成能再次执行的说明。
产物： 演示步骤、证据索引、一份个人改动说明和一段讲解录音或提纲。
检查点： 清楚区分运行原项目、阅读原代码、本人新增与本人验证。只完成默认模式时，描述为本地知识库检索实践，明确尚未接入语义向量或生成模型。
卡住怎么办： 先演示一份文档的一次状态变化，讲清引用为什么变化，再扩大范围。缺少个人实现时如实写复现和验收，不把下载运行写成独立研发整套系统。

扩展一：接入真实 embedding API 与 pgvector

这是前六步之后的可选练习，可能涉及付费模型 API。现有项目提供适配代码，现有报告没有执行真实模型调用；存储测试向量不能证明模型语义效果。

阅读： 包内 README 的“真实 Spring AI + pgvector”、src/ai/java/cn/itfeng/knowledge/AiConfiguration.java、application-ai.properties，以及项目页的向量模式说明。
任务： 按包内说明准备独立 PostgreSQL/pgvector 和模型配置，同时启用 Maven -Pai 与运行时 ai profile。记录模型标识、维度与数据库条件，重新写入同一组文档并运行自己的验收集，再增加同义表达问题。H2 与 PostgreSQL 是独立库，切换模式不会自动迁移文档。
产物： 脱敏配置、启动命令、真实调用记录、逐题引用和失败；真实调用未完成时明确写原因，结果留空。
检查点： 确认 mode 为 spring-ai-pgvector-extractive，并有实际 embedding 调用证据；核对过滤及返回候选后的当前版本检查。回答仍是原文，没有聊天生成。相似度阈值 0.75 是当前配置，不是语义质量合格线。
卡住怎么办： 分别检查模型认证、维度、数据库连接与 profile；只启 Maven profile 不会启用真实调用。更换维度先使用独立实验库或明确迁移方案，不混用旧向量。暂时没有条件时保留前六步产物，将此项写为未验证。

扩展二：在有效证据之上增加生成回答

这一步需要新增实现。当前 /api/search 没有完成生成式问答，下面的目标不能作为已有功能或已测效果介绍。

阅读： RAG 评估指南、故障排查与接口超时预算。
任务： 在练习副本中把已认证、当前允许的检索证据交给聊天模型，记录模型、提示词与最终上下文版本，返回可核对的引用。增加有证据、无证据、证据不足、文档诱导指令和模型超时场景；无可用证据时停止生成，依赖故障要有明确失败结果。
产物： 新增代码差异、接口约定、脱敏上下文与生成响应、逐题人工判定，以及调用失败和耗时记录。
检查点： 每个事实能回指本次授权证据；引用存在还不够，必须支持所说内容。检索命中、答案正确、证据支撑、拒答与依赖失败分别检查。没有运行的数据不填准确率、延迟或费用收益。
卡住怎么办： 只保留一个问题和一份允许文档，依次查检索候选、最终上下文和生成输出。先确认相关证据确实送入模型，再改提示词；没有完成真实生成时，演示继续使用原文摘录并明确范围。

接下来可按项目到简历路线整理自己真正完成的层次。每次新增能力都重新留下运行记录，资料集中在Java AI 资料，短练习可参考7 天知识库验收练习。