架构设计

Knowledge 服务采用清晰的分层架构,各模块职责明确,支持灵活扩展。

整体架构

系统分为四层:

四层架构说明

层级	职责	核心组件
接入层	对外提供 API 接口	REST Controller、Feign Service
业务层	核心业务逻辑处理	知识库管理、文档管理、文档摄入、RAG 问答
检索层	检索引擎与流程编排	检索编排、向量检索、关键词检索、重排序、上下文扩展
存储层	数据持久化	MySQL、PgVector、Elasticsearch

---

核心模块

1. 知识库管理模块 (library)

负责知识库和文档的 CRUD 操作:

• 知识库管理 — 创建、编辑、删除知识库,支持系统级与用户级
• 文档管理 — 文档上传、元数据管理、状态跟踪
• 分片管理 — 查看、编辑分片,支持手工优化

2. 文档摄入模块 (ingest)

负责文档的自动化处理流程:

• 格式转换 — 调用外部转换服务,将各类文档转为 Markdown
• 智能分片 — 基于 Markdown 章节结构的递归分割
• 向量化存储 — 批量生成向量并存储到 PgVector
• 任务调度 — 异步任务队列,支持并发控制与重试

3. 检索引擎模块 (search)

提供多种检索方式:

• 向量检索 — 基于 Spring AI VectorStore 的语义检索
• 关键词检索 — Elasticsearch 全文检索 (或 Lucene 轻量级方案)
• 混合检索 — 向量 + 关键词双路召回,RRF 融合

4. 检索编排模块 (retrieval)

检索流程的四步流水线:

1. 基础检索 — 向量检索或混合检索
2. 信息补全 — 从数据库补全标题、位置、内容
3. 重排序 — qwen3-rerank 精排优化 (可选)
4. 上下文扩展 — 扩展相邻分片 (可选)

5. RAG 问答模块 (chat)

支持两种 RAG 模式:

• Standard RAG — 固定检索 → 生成流程
• Agentic RAG — LLM 自主决定检索时机

包含完整的会话管理、消息管理、引用文档管理。

---

核心流程

文档摄入流程

关键设计:

• 三阶段流水线 — CONVERT → SPLIT → VECTORIZE
• 并发控制 — 信号量限制并发任务数 (默认 3)
• 分布式锁 — 防止任务重复执行
• 失败重试 — 最大重试 3 次
• 超时重置 — 超时任务自动重置为待处理

Standard RAG 流程

响应流顺序:

1. conversationId — 会话 ID
2. userMessageId — 用户消息 ID
3. assistantMessageId — 助手消息 ID
4. hybridSearchWarning — 混合检索警告 (可选)
5. referencedDocs — 引用文档列表
6. thinking — 思考过程 (可选,多次)
7. content — 回答内容 (多次)
8. tokenUsage — Token 使用量
9. done — 结束标记

Agentic RAG 流程

与 Standard RAG 的区别:

• 检索时机 — LLM 自主决定,而非固定先检索
• 查询构建 — LLM 可改写查询词,而非简单拼接
• 灵活性 — 支持多步推理、多次检索

---

数据模型

核心实体关系

---

扩展点设计

自定义向量数据库

Knowledge 基于 Spring AI VectorStore 抽象,理论上支持任何 VectorStore 实现:

// 当前使用 PgVectorStore
@Bean
public VectorStore vectorStore(DataSource dataSource, EmbeddingModel embeddingModel) {
    return PgVectorStore.builder(dataSource, embeddingModel)
            .dimensions(1536)
            .initializeSchema(true)
            .build();
}

// 可替换为 Milvus、Redis 等

自定义分片策略

分片服务设计为可扩展:

// 默认实现: 基于 Markdown 章节分割
public class MarkdownSplittingService {
    public List<DocumentChunk> splitMarkdown(...) { ... }
}

// 可自定义其他分片策略:
// - 固定字符数分片
// - 按段落分片
// - 语义分片

自定义检索引擎

关键词检索采用接口设计:

public interface KeywordSearchService {
    List<SearchDocument> search(String query, KeywordSearchOptions options);
}

// 现有实现:
// - EsKeywordSearchService (Elasticsearch)
// - LuceneKeywordSearchService (Lucene, 轻量级备选)

// 可自定义其他实现 (如 Solr)

---

模块化配置

各检索组件可独立开关:

组件	配置项	默认值	说明
混合检索	molandev.rag.hybrid-search.enabled	false	启用 ES 关键词检索
重排序	molandev.rag.rerank.enabled	false	启用 qwen3-rerank
上下文扩展	molandev.rag.context-expansion.enabled	false	扩展相邻分片

这种设计允许根据场景灵活组合:

• 轻量模式 — 仅向量检索,资源消耗低
• 标准模式 — 向量检索 + 重排序,平衡效果与成本
• 完整模式 — 混合检索 + 重排序 + 上下文扩展,最佳效果
• Agent 模式 — 由前端 mode=agent 参数启用,LLM 自主检索,适合复杂对话

---

下一步

• 跟随 快速入门 快速搭建环境
• 查看 配置说明 了解完整配置项