2026年6月22日/ 案例

SmartKB 企业智能知识库

Java 21 + Spring AI 的可解释企业 RAG 服务，覆盖异步入库、Milvus/OpenSearch 双路检索、BGE 重排、低置信度拒答、引用追踪和持久化会话。

项目概览

主线、难点和结果。

负责范围

后端 RAG 主链路与工作台演示：文档上传、异步入库、检索编排、流式问答、引用定位、会话和评测。

核心难点

让文档生命周期、双路检索、回答证据和失败降级都能被观察、重试和复盘。

检索架构

Milvus 负责稠密召回，OpenSearch 负责关键词召回与过滤，随后做加权 RRF 和 BGE 重排；旧 pgvector 仅保留兼容路径。

验证结果

102 项测试通过；完整 Docker Compose 和紧凑 K3d 离线演示环境均完成验收。

关键流程

主链路怎么跑起来。

下面按顺序记录项目里真正跑通的几个环节。

异步入库

文件先落 MinIO，再由 RabbitMQ 驱动可重试任务

上传会创建文档和任务状态，解析、切片、Embedding、双索引写入完成后才进入 READY；失败任务保留原因并支持重试。

双路检索

稠密与关键词召回并行，再做融合和重排

Milvus 与 OpenSearch 使用统一 chunk 身份和过滤条件；健康后端可以单独完成降级检索，两个后端都不可用时返回明确错误。

会话与追踪

PostgreSQL 保存事实，Redis 只做可失效缓存

长期会话、引用、检索候选和 trace 写入 PostgreSQL；Redis 只缓存近期上下文、热点结果和短期协调状态。

交付验收

Compose 与 K3d 都能重复验证

完整 Compose 验证 PostgreSQL、Redis、RabbitMQ、MinIO、Milvus、OpenSearch、Reranker 和 SmartKB；K3d 提供紧凑离线演示路径。

102

Tests

Retrieval backends

Delivery paths

运行画面

兼容 Advanced RAG 演示覆盖文档入库、检索、BGE 重排、低置信度拒答、引用定位和答案质量 Judge。

SmartKB Advanced RAG 阶段反馈 — 兼容问答链路展示查询改写、检索、过滤、重排和生成阶段。

SmartKB 引用片段定位 — 引用片段可以回到原始文档 chunk，用于检查回答来源。

SmartKB RAG 评测报告 — 评测页记录 Recall@K、Top1、MRR 和引用覆盖等指标。

SmartKB 低置信度拒答 — 证据不足时跳过生成模型，返回证据置信度和明确拒答原因。

SmartKB 答案质量 Judge — LLM-as-Judge 分别评估 Faithfulness、Answer Relevance 和 Context Relevance。

问题

企业知识库不只要回答问题，还要保证文档入库可追踪、检索可降级、会话可恢复、引用可复盘，并能在本地重复交付。

方案

我把 SmartKB 拆成文档生命周期、双路检索和证据追踪三条链路：MinIO/RabbitMQ 负责异步入库，Milvus/OpenSearch 负责召回与过滤，PostgreSQL 保存会话、引用和 retrieval trace，BGE 负责候选重排，证据不足时直接拒答。

展示重点

SmartKB 现在主要记录三条可复盘链路：文档如何可靠入库、检索如何在双后端之间融合、回答如何留下证据和 trace。

Upload -> MinIO -> RabbitMQ -> Parse / Chunk / Embed
       -> Milvus + OpenSearch -> RRF + BGE -> Confidence
       -> Generate / Refuse -> Cite -> Trace -> Persist

The public demo still includes the compatible Advanced RAG flow, while the enterprise path adds asynchronous ingestion, dual-index consistency, durable conversations, retrieval traces and repeatable Compose/K3d delivery.

实现细节

当前企业链路从文件上传开始：原始文件保存到 MinIO，PostgreSQL 创建文档事实和 ingestion job，RabbitMQ 驱动解析、切片和 Embedding。只有 Milvus、OpenSearch 和 PostgreSQL 状态都完成后，文档才进入 READY。

查询时同时走 Milvus 稠密召回和 OpenSearch 关键词召回，使用统一的 knowledgeBaseId、documentId 和 chunkId 做过滤与融合，再交给本地 BGE Reranker。任一后端故障时保留可解释的单后端降级，两端都不可用时返回 RETRIEVAL_UNAVAILABLE。

企业问答通过 SSE 输出阶段事件，并把引用、候选、融合模式、耗时和 traceId 保存下来。旧的 Advanced RAG 接口仍保留 pgvector 兼容写入，直到迁移完成；这条兼容路径不代表企业检索主架构。

会话事实、消息、引用和检索追踪保存在 PostgreSQL。Redis 只缓存近期上下文、热点检索结果和短期任务状态，缓存不可用时不会丢失历史。

验证覆盖 102 项测试、Milvus/OpenSearch 检索 smoke、单后端故障降级、完整 Docker Compose 和紧凑 K3d 离线运行。项目文档没有把单次健康检查吞吐写成 RAG 容量承诺。

The enterprise path starts with an upload: the original file is stored in MinIO, PostgreSQL creates the document fact and ingestion job, and RabbitMQ drives parsing, chunking and embedding. A document becomes READY only after Milvus, OpenSearch and PostgreSQL state are complete.

Queries run dense retrieval in Milvus and keyword retrieval in OpenSearch, using shared knowledgeBaseId, documentId and chunkId filters before fusion and local BGE reranking. One backend can degrade explicitly; both failures return RETRIEVAL_UNAVAILABLE.

Enterprise QA emits SSE stage events and persists citations, candidates, fusion mode, latency and traceId. The legacy Advanced RAG API still receives compatibility writes to pgvector during migration; that path is not the enterprise retrieval architecture.

Durable conversations, messages, citations and retrieval traces live in PostgreSQL. Redis caches recent context, hot retrieval results and short-lived job state, so cache failure does not erase history.

Verification covers 102 tests, Milvus/OpenSearch retrieval smoke, single-backend degradation, full Docker Compose and a compact K3d air-gap runtime. The project does not turn a one-off health check into a RAG capacity claim.

复盘

把 pgvector 换成专用检索后端不是重点，重点是统一 chunk 身份、READY 门禁、删除顺序和故障降级。

Redis 适合缓存和协调，不应该成为长期会话事实；缓存失效时，PostgreSQL 仍然能恢复历史。

本地部署验收要和 RAG 质量评测分开记录，健康端点的吞吐不能冒充问答性能。