4.0.0

Spring AI RAG Demo 4.0.0

本版本围绕知识库治理、可信引用、本地多语言检索和 RAG 质量评测进行了完整增强，建立了从文档导入、版本管理、证据召回到回答引用和质量验证的闭环。

This release delivers a comprehensive upgrade to knowledge-base governance, trustworthy citations, local multilingual retrieval, and RAG quality evaluation—from document ingestion and versioning to evidence retrieval, answer citations, and repeatable validation.

---

中文说明

✨ 核心新增功能

1. 租户级知识库管理

   • 支持创建、修改、启用、停用和删除知识库。
   • 支持为每个租户设置默认知识库。
   • 知识库、文档、向量检索和删除操作均进行租户隔离。
   • 增加跨租户访问保护，避免不同租户的数据相互影响。

2. 稳定的文档身份和版本管理

   • 为文档增加稳定的 documentId、版本号、状态和分片数量。
   • 支持文档上传、内容替换、重新导入和删除。
   • 文档状态包括 processing、ready、failed、superseded 和 deleted。
   • 新版本导入失败时保留上一可用版本，不会因替换失败导致原文档不可用。
   • 删除或淘汰文档版本时同步清理对应向量。

3. 本地多语言嵌入模型

   • 使用本地 paraphrase-multilingual-MiniLM-L12-v2 ONNX 模型和配套分词器。
   • 保持 384 维向量，增强中文及多语言语义检索能力。
   • 模型和分词器随项目通过 Git LFS 管理，运行期间不再临时下载模型。
   • 增加模型文件、固定哈希、ONNX 会话和中文分词能力校验。

4. 更加可靠的文档导入流程

   • 文档解析、分片、嵌入和向量写入在数据库短事务之外执行。
   • 增加文本长度、分片数量、Token 数量和写入批次限制。
   • 导入失败时记录错误摘要并清理失败版本产生的向量。
   • 支持短 TXT、PDF、Word 和 Excel 等文档导入。

5. 可信的 RAG 回答引用

   • 回答引用只允许来自当前问答实际召回的文档证据。
   • 引用与回答使用同一轮检索结果，不会为了生成引用再次执行向量检索。
   • 后端会过滤不存在、未使用或超出范围的引用编号。
   • 非流式响应增加 citations 字段。
   • SSE 流式响应在 delta 之后、done 之前返回 citations 事件。
   • 历史消息保存引用快照，文档后续被替换或删除也不会改变已有回答的历史证据。

6. 问答模式优化

   • auto 模式同时支持受管 RAG 和业务 Tool。
   • knowledge 模式专注知识库检索。
   • data 模式保持仅访问业务 Tool，不执行向量检索。
   • 修复历史消息中 RAG 文档数量始终记录为 0 的问题。
   • 保留原有会话、计费、图表和流式取消逻辑。

7. 知识库前端增强

   • 增加知识库选择、创建、编辑、启停和删除功能。
   • 增加文档上传、替换、删除、版本和状态展示。
   • 旧模型文档会明确显示“需重新导入”。
   • 问答结果增加引用卡片，可查看来源、文档版本和相关内容。
   • 保持原有零构建静态前端，不新增 npm、CDN 或前端构建依赖。

8. 版本化 RAG 质量评测

   • 新增包含 50 个场景的版本化评测数据集。
   • 覆盖单文档、多文档、同义改写、无答案、跨租户和跨知识库隔离场景。
   • 增加召回、答案、引用、隔离和清理结果统计。
   • 增加引用错误、跨租户召回、清理失败和基线下降等质量门禁。
   • 真实模型评测通过独立 Maven Profile 执行，不影响默认离线构建。

🔄 数据库与兼容性

• 新增 a_knowledge_base 和 a_knowledge_document 表。
• a_chat_message 增加可空的知识库 ID 和引用快照字段。
• 数据库变更在应用启动时幂等执行。
• 新增请求参数均为可选字段，原有接口调用保持兼容。
• 保留 /api/load 和 /api/upload，默认代理到当前租户的默认知识库。
• 旧历史消息继续按无知识库、无引用方式正常展示。
• Dockerfile 和 docker-compose.yml 的原有使用方式保持不变。

⚠️ 升级前必读

旧版本向量缺少知识库、稳定文档 ID、文档版本、分片 ID 和嵌入模型身份，且旧模型与新模型的语义空间不同，因此：

1. 升级前请备份 MySQL、PgVector 数据和原始文档。
2. 升级后，仍需使用的旧文档必须通过原始文件重新导入。
3. 不要将旧模型生成的向量与新模型向量混用。
4. 文档显示“需重新导入”时，不会进入新的受管检索和可信引用链路。
5. 部署节点需要使用支持 AVX2 的 x86-64 CPU。

详细步骤请参考：4.0.0 知识库与 RAG 引用迁移说明。

🐳 Docker 镜像

本次发布提供以下两个标签，它们指向同一个镜像：

docker pull ly753/spring-ai-rag-demo:4.0.0
docker pull ly753/spring-ai-rag-demo:latest

使用项目现有 Compose 配置启动：

docker compose pull
docker compose up -d

镜像摘要：

sha256:aa8c1c0bdbce95c2d0015fdc4c4892163a7bf4744a1a3278a141971ad93711d1

✅ 验证情况

• 50 个测试类、343 项自动化测试全部通过。
• 测试结果：0 Failures / 0 Errors / 0 Skipped。
• Spring Bean 构造器依赖检查通过，未发现循环依赖。
• 11 份 OpenSpec 主规范严格校验通过。
• 本地 Docker 环境完成数据库升级、文档重新导入和中文检索验证。
• 应用容器启动正常、重启次数为 0，首页返回 HTTP 200。
• 真实模型质量评测需要单独配置模型 Key，并通过 rag-eval Profile 显式执行，不属于默认构建流程。

---

English

✨ Highlights

1. Tenant-isolated knowledge-base management

   • Create, update, enable, disable, and delete knowledge bases.
   • Configure a default knowledge base for each tenant.
   • Enforce tenant isolation across metadata, documents, vector retrieval, citations, and cleanup.
   • Prevent cross-tenant access and retrieval.

2. Stable document identity and versioning

   • Add stable document IDs, versions, states, and chunk counts.
   • Support managed upload, replacement, re-import, and deletion.
   • Track processing, ready, failed, superseded, and deleted states.
   • Preserve the previous ready version when a replacement fails.
   • Clean up vectors belonging to deleted or superseded document versions.

3. Local multilingual embedding model

   • Use the local paraphrase-multilingual-MiniLM-L12-v2 ONNX model and tokenizer.
   • Preserve the existing 384-dimensional vector format while improving Chinese and multilingual retrieval.
   • Manage model resources through Git LFS with no runtime model download.
   • Validate model hashes, ONNX session creation, and Chinese tokenization.

4. Reliable document ingestion

   • Run parsing, chunking, embedding, and vector writes outside short database transactions.
   • Enforce limits for document text, chunks, tokens, and write batches.
   • Record failure summaries and remove vectors created by failed versions.
   • Support short TXT, PDF, Word, and Excel documents.

5. Trustworthy RAG citations

   • Only return citations backed by evidence retrieved during the current request.
   • Generate answers and citations from the same retrieval result without a second vector search.
   • Reject unknown, unused, or out-of-range citation numbers.
   • Add a citations field to non-streaming responses.
   • Emit a citations SSE event after delta events and before done.
   • Persist immutable citation snapshots for conversation history and replay.

6. Improved assistant modes

   • auto combines managed RAG with business Tools.
   • knowledge focuses on knowledge-base retrieval.
   • data remains Tool-only and does not access the vector store.
   • Fix persisted RAG document counts that previously remained at zero.
   • Preserve existing conversation, billing, chart, and streaming-cancellation behavior.

7. Knowledge-base UI

   • Add knowledge-base selection and lifecycle management.
   • Add document upload, replacement, deletion, version, and status views.
   • Clearly identify legacy documents that require re-import.
   • Display citation cards with source, document version, and supporting content.
   • Keep the existing zero-build static frontend without npm, CDN, or a new frontend toolchain.

8. Versioned RAG evaluation

   • Add a versioned dataset containing 50 evaluation scenarios.
   • Cover single-document, multi-document, paraphrased, no-answer, tenant-isolation, and knowledge-base-isolation cases.
   • Report retrieval, answer, citation, isolation, and cleanup metrics.
   • Add hard gates for invalid citations, cross-tenant retrieval, cleanup failures, and baseline regressions.
   • Keep live-model evaluation behind an explicit Maven Profile so the default build remains offline.

🔄 Database and compatibility

• Add the a_knowledge_base and a_knowledge_document tables.
• Add nullable knowledge-base and citation-snapshot fields to a_chat_message.
• Apply database changes idempotently during application startup.
• Keep all new request parameters optional.
• Preserve /api/load and /api/upload as compatibility endpoints for the tenant’s default knowledge base.
• Replay legacy messages without fabricated knowledge-base or citation data.
• Preserve the existing Dockerfile and docker-compose.yml workflow.

⚠️ Before upgrading

Legacy vectors do not contain the new knowledge-base, document, version, chunk, and embedding-model identities. The previous and current embedding models also use different semantic spaces even though both produce 384-dimensional vectors.

1. Back up MySQL, PgVector, and all original documents before upgrading.
2. Re-import every legacy document that must remain searchable.
3. Do not mix vectors generated by the old and new embedding models.
4. Documents marked as requiring re-import are excluded from managed retrieval and trusted citations.
5. Deployment requires an x86-64 CPU with AVX2 support.

See the 4.0.0 Knowledge Base and RAG Citation Migration Guide for the complete upgrade and rollback procedure.

🐳 Docker images

Both tags below point to the same image:

docker pull ly753/spring-ai-rag-demo:4.0.0
docker pull ly753/spring-ai-rag-demo:latest

Start the application with the existing Compose configuration:

docker compose pull
docker compose up -d

Image digest:

sha256:aa8c1c0bdbce95c2d0015fdc4c4892163a7bf4744a1a3278a141971ad93711d1

✅ Validation

• 343 automated tests across 50 test classes passed.
• Result: 0 Failures / 0 Errors / 0 Skipped.
• Spring Bean constructor dependency checks passed with no circular dependencies.
• All 11 main OpenSpec specifications passed strict validation.
• Local Docker validation covered database migration, document re-import, and Chinese retrieval.
• The application container started successfully with zero restarts and returned HTTP 200.
• Live-provider quality evaluation requires a separately configured model key and an explicit rag-eval Profile; it is not part of the default build.

---

Full Changelog: 3.0.4...4.0.0

3.0.4

What's Changed

• docs(readme): 使用 GIF 替换静态演示截图 by @ly1836 in #9

Full Changelog: 3.0.3...3.0.4

3.0.3

What's Changed

• docs(readme): 修正环境变量示例并补充许可证说明 by @ly1836 in #8

Full Changelog: 3.0.2...3.0.3

3.0.2

注意：docker-compose.yml改了默认密码，如果前面已经运行过且使用的默认密码需要自己手动去更新一下。

What's Changed

• chore(docker): 更新数据库默认密码 by @ly1836 in #7

Full Changelog: 3.0.1...3.0.2

3.0.1

What's Changed

• chore(docker): 统一默认应用镜像为 latest by @ly1836 in #6

Full Changelog: 3.0.0...3.0.1

3.0.0

3.0.0 更新说明

3.0.0 为主要功能版本，新增业务 Tool 查询结果图表可视化能力，并增强知识文档导入、知识问答、流式响应和历史会话回放。

✨ 核心功能

Tool 结果图表可视化

业务 Tool 查询到结构化数据后，可在返回文字答案的同时生成图表：

• LLM 只负责选择图表类型和标题。
• 后端根据真实 Tool 数据自动完成来源选择、字段绑定、数据转换和安全校验。
• 前端通过本地 ECharts 直接渲染图表。
• 每次问答最多返回一个图表，同一会话中的后续问答仍可继续生成图表。
• 图表生成失败时自动降级为纯文本，不影响业务回答。
• 图表随助手消息保存，支持历史记录和续聊回放。
• 不重新查询业务数据库，不允许 LLM 直接提交业务数值或任意 ECharts 配置。

支持以下 23 种图表：

• 环形图
• 旭日图
• 条形图
• 瀑布图
• 子弹图
• 面积图
• 阶梯图
• 雷达图
• 散点图
• 气泡图
• 直方图
• 箱线图
• 热力图
• 桑基图
• 矩形树图
• 甘特图
• 漏斗图
• 词云图
• 仪表盘图
• 水位图
• 平行坐标图
• 折线图
• 饼图

知识库能力增强

• knowledge 模式使用独立的知识问答提示词，不再受 ERP 业务范围提示限制。
• 支持回答用户导入的 Java、JVM、RabbitMQ 等非 ERP 技术文档。
• 增加知识库召回数量并调整相似度阈值，改善中文技术文档召回效果。
• knowledge 模式不装配业务 Tool，继续保持租户隔离。
• 同租户、同来源文档重新导入时自动覆盖旧向量。

大文档受控导入

上传限制调整为：

• 单文件最大 500MB
• 单次请求最大 550MB

同时增加多层资源保护：

• 限制文档提取后的最大字符数。
• 限制单文档最终分片数量。
• 使用实际 ONNX WordPiece 分词器进行二次切分。
• 保证每个向量分片不超过 128 Token。
• 向量数据按 100 条分批写入。
• 写入失败时清理当前来源的残留数据，避免留下半成品向量。

🚀 流式响应优化

• 流式接口统一使用类型化 SSE。
• 支持 delta、chart、done、error 四类事件。
• 恢复正文实时逐段输出效果。
• 图表在正文完成后发送并渲染。
• 异常和用户取消只执行一次消息、计费及 Tool 流水收口。
• 修复查询、重试和图表规划等内部英文旁白泄漏问题。
• 修复最终答案边界跨网络分片时可能泄漏协议残片的问题。
• SSE 错误复用当前助手消息，避免生成空白或重复气泡。

Important

GET /api/ask/stream 已从历史纯文本 SSE 升级为类型化 SSE，属于协议变更。项目内置前端已同步升级；独立接入该接口的客户端需要适配新的事件结构。

🧩 会话历史与数据安全

• 助手消息增加可空 chart_spec 字段。
• 历史详情和续聊可直接回放已保存图表。
• 历史回放不会重新调用 LLM 或业务 Tool。
• 旧消息没有图表字段时继续正常展示文本。
• 非法或不兼容的历史图表自动降级为 chart = null。
• 会话读取、归档和状态查询增加租户及当前用户所有权校验。
• 原始业务 Tool 数据只在当前请求生命周期内使用，请求结束后自动清理。
• Tool 结果按 trace、租户和会话隔离，禁止跨请求或跨租户复用。

🏗️ 架构调整

为降低核心问答服务复杂度，本版本拆分了 ErpAssistantService 的部分职责：

• AssistantClientProvider

  • 负责模型 Provider、模式路由、RAG 和 Tool 装配。

• AssistantLifecycleService

  • 负责消息持久化、计费、Tool 流水和终止收口。

• BusinessDataTurnGuard

  • 保证业务数据问题使用当前轮查询结果。

• AssistantAnswerSanitizer

  • 负责最终答案边界处理和内部旁白净化。

图表能力按职责拆分至：

• chat/chart/model
• chat/chart/capture
• chat/chart/compile
• chat/chart/protocol
• chat/chart/selection
• chat/chart/tool

同时增加 Spring Bean 构造器依赖图测试，防止后续重构引入循环依赖。

🎨 前端更新

• 本地引入 Apache ECharts。
• 本地引入词云图和水位图扩展。
• 新增统一的 chart-adapter.js 图表适配器。
• 不依赖 CDN，不增加前端构建工具。
• 支持实时问答、非流式回答、历史记录和续聊图表展示。
• 支持图表实例释放和消息重新渲染。
• 甘特图使用项目内固定水平时间范围实现。
• 图表渲染异常时保留 Markdown 文本答案。
• 中英文 README 增加图表能力介绍、测试话术和实际效果截图。

🔐 图表安全与可靠性

• LLM 不能提交来源 Tool、字段绑定、转换规则、业务数据或任意 ECharts option。
• 图表类型由统一枚举约束。
• Tool 结果、规划输入和最终图表协议均设置大小、深度、宽度、节点数、行数和维度限制。
• 自动排除订单号、工单号等数值型业务标识，避免被误选为业务指标。
• 支持纯分类业务数据按真实记录数生成统计图表。
• 多个业务 Tool 返回结果时只选择一个可信来源，不自动合并不同 Tool 数据。
• 内部图表规划 Tool 不计入业务 Tool 命中次数、调用流水或动态 Tool 管理列表。
• 图表失败、空结果和不可图表化数据均安全降级为文本回答。

🗄️ 数据库变更

ERP MySQL 的 a_chat_message 表增加可空字段：

• chart_spec JSON NULL

数据库初始化逻辑支持：

• 新数据库自动创建字段。
• 已有数据库幂等增加字段。
• 重复启动不会重复修改表结构。
• 历史消息无需迁移，原有文本数据继续兼容。

⚠️ 升级注意事项

从 2.1.1 升级到 3.0.0 时请注意：

1. 使用项目数据库初始化逻辑或手工确认 a_chat_message.chart_spec 字段已创建。
2. 独立调用 /api/ask/stream 的客户端需要适配类型化 SSE。
3. 项目内前后端必须作为同一版本一起部署。
4. 如需让已导入文档使用新的真实 Token 切分和覆盖导入逻辑，可重新导入对应文档。
5. 本版本不迁移历史向量数据，也不要求迁移历史纯文本消息。
6. ECharts 及扩展已经内置在静态资源中，部署环境不需要访问外部 CDN。

✅ 验证结果

• Java 测试：194 项通过
• 测试失败：0
• 测试错误：0
• 前端图表 fixture：33 项通过
• Spring Bean 依赖图检查：通过，未发现循环依赖
• OpenSpec 主规范严格校验：8 项通过，0 项失败
• 图表类型、流式事件、历史回放和异常降级均有自动化测试覆盖
• 中英文 README 图表话术和本地图片引用检查通过

📚 文档

• 更新中文 README
• 更新英文 README
• 新增 20 条可直接复制的图表测试话术
• 新增环形图、条形图、瀑布图、子弹图、面积图、阶梯图和甘特图等效果截图
• 完成 tool-result-chart-visualization OpenSpec change 归档
• OpenSpec 任务完成度：169/169

📦 变更规模

• 修改文件：102 个
• 新增代码及文档：约 16,430 行
• 删除或调整：约 765 行

Full Changelog

2.1.1...3.0.0

2.1.1

What's Changed

• build(docker): 更新应用镜像版本到 2.1.1 by @ly1836 in #4

Full Changelog: 2.1.0...2.1.1

2.1.0

What's Changed

• feat(llm-tools): 支持动态 Tool 管理和命中追踪 by @ly1836 in #3

Full Changelog: 2.0.1...2.1.0

2.0.1

What's Changed

• docs: 同步 Spring AI 2 技术栈说明 by @ly1836 in #2

Full Changelog: 2.0.0...2.0.1

2.0.0

What's Changed

• 升级到 Spring AI 2 并更新应用镜像版本 by @ly1836 in #1

New Contributors

• @ly1836 made their first contribution in #1

Full Changelog: 1.0.0...2.0.0