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