如果你翻过市面上关于 RAG 的技术文章。大概率会看到这样一个公式：

RAG = 向量数据库 + 大模型 API

这个公式本身没有错——但它描述的是 Demo，不是产品。

当你真的要把 RAG 落到公司的知识库场景里你会发现 Demo 里从来不出现的东西才是真正的工程量：文档怎么入库？长文档怎么切，中文检索关键词怎么抽？向量召回了 N 条，哪 K 条最该送进上下文？Rerank 挂了怎么办？说起来，使用者怎么知道这次回答引用了哪些原文？按理说，这还只是“能用”层面。到“好用”层面你还得回答：检索参数应该是多少？怎么知道自己调参调对了还是调废了？

下面把整个项目的骨架摊开。讲清楚一条能从 上传 → 检索 → 回答 的公司级 RAG 链路到底长什么样，每个模块解决什么问题，还有我是怎么把它们串起来的。按理说，

说到先定边界。这个项目做什么不做什么

痛点一：范围漂移导致无限迭代、资源浪费

做项目最怕的不是技术难，而是范围漂移。在动第一行代码之前，我先划了三条线：

• 做什么：
  • 完整 RAG 主链路：文档上传 → 解析 → 分块 → 向量化 → 混合检索 → 可选重排 → 上下文组装 → LLM 问答
  • 配套管理控制台：知识库管理、文档生命周期、Chunk 级可观测、检索参数调优
  • 检索评测闭环这方面。能跑评测集、能看到每次检索命中了什么、能对比不同参数的实际效果
• 不做什么：
  • 多租户和权限程序——中小公司场景下一个知识库通常就一个团队在用，过早抽象租户只会增加无谓复杂度。 老实说，
  • 复杂的文档预处理流水线——先用 Apache Tika 做通用解析，够用。按理说，表格提取、图片 OCR、层级结构保留等留待第二阶段。说起来，
  • 自研 Embedding 模型——直接对接 OpenAI 兼容接口。你接 DeepSeek、接通义千问、接本地部署的 BGE 模型都行，我不绑你。

这个边界一划。范围就清楚了：一条链路，一个控制台，一套评测闭环。

从整体架构来看，一条 RAG 链路穿过 7 个模块

痛点二：程序各层耦合度高。改动需要跨多个目录查找代码

下面给出项目首页示意图。菜单栏正好对应 RAG 主链路上的每个阶段，把链路拉直后大概是这样：

使用者上传文档 → Tika 解析纯文本 → 段落优先分块 →
Embedding 向量化 ↓
使用者提问 → 向量召回 + 关键词召回 →
可选 Rerank → 邻居 Chunk 补全 ↓
组装上下文 → LLM 生成回答 → 带引用的最终响应

链路上的每个方块在后端对应一个独立的 Java Package：

Package	职责	主要类
document	文档上传、异步索引、状态机管理	DocumentIndexService
	文件格式解析	TikaDocumentParserService
	段落优先切分，支持长段落滑窗	ParagraphTextChunker
	调用 OpenAI 兼容 Embedding API	OpenAiCompatibleEmbeddingService
	QdrantVectorStoreService
retrieval	混合检索编排：向量+关键词+融合	RetrievalService
rerank	精排服务调用。挂了自动降级	HttpRerankService
chat	问答编排：检索→上下文→LLM→引用	ChatService
evaluation	检索评测：用例管理+跑分	RagEvaluationService
knowledgebase	知识库及其参数设置	KnowledgeBaseService
audit	问答日志持久化	RagQaLog

每个 Package 按领域拆分，而不是按层拆分——document 包里既有 Controller 又有 Service 与 Entity，这样改功能只需要在一个包里跳转，不会在六七个包之间横跳。

The front‑end routes map one‑to‑one to se packages,ensuring UI only shows what operators truly need:

// frontend/src/router/index.ts
{ path: "/workspace",component: => import,meta: { title: "工作台" } },{ path: "/knowledge-bases",component: => import,meta: { title: "知识库" } },{ path: "/documents",component: => import,meta: { title: "文档" } },{ path: "/chunks",component: => import,meta: { title: "Chunk" } },{ path: "/settings"。component: => import,meta: { title: "参数设置" } },{ path: "/chat",component: => import,meta: { title: "问答" } },{ path: "/evaluation",component: => import,meta: { title: "评测" } },

再看基础设施，3 个容器 + 1 个 Spring Boot 应用 + Nginx 代理层

痛点三：单体部署难以满足持久化、安全和 需求 

存放文档元数据、Chunk 信息、审计日志等结构化数据；不能用于向量搜索 向量存储与最近邻搜索；MySQL 无法完成稠密向量匹配 原始文件对象存储；文件太大不适合塞进关系型数据库 文本转向量；外部调用或本地零延迟零费用均可接受

服务 / 容器 用途 为何非可选
MySQL
Qdrant
MinIO
Embedding API / 本地模型容器
Reranker 容器 & Nginx API 鉴权层	CPU 跑 Cross‑Encoder 精排提高召回质量；Nginx 为所有模型提供统一鉴权入口防止未授权访问

Simplified Deployment Command:     D OCKER COMPOSE –ENV-FILE .ENV UP - D

CODE

---