整体架构
本页基于 SparkX 后端源码(
sparkx.sparkshop)与数据库设计,自顶向下介绍系统的分层架构、核心子系统、RAG 流水线与数据模型。
1. 技术栈
| 层 | 技术选型 |
|---|---|
| 后端框架 | Java 17 + Spring Boot 3.4 + MyBatis-Plus |
| 大模型封装 | LangChain4j 1.18(统一封装)+ langchain4j-mcp(MCP 协议)+ langchain4j-community-neo4j(知识图谱) |
| 文档解析 | Apache Tika / PDFBox / POI + MinerU(复杂版面)+ HanLP(中文分词) |
| 存储 | PostgreSQL(带 pgvector 向量扩展)+ Redis(Redisson 分布式锁/缓存)+ MinIO(对象存储)+ Neo4j(知识图谱,可选) |
| 可观测 | Spring Boot Actuator + Micrometer(OpenTelemetry 桥接)+ 自研 @RagTraceNode AOP |
| 流式输出 | SSE(Server-Sent Events) |
2. 顶层架构
SparkX 采用前后端分离架构,后端按职责划分模块,包根为 sparkx.sparkshop:
sparkx.sparkshop/
├── common/ # 通用基础设施(config / constant / core / exception / utils)
├── config/ # 全局配置
├── system/ # 系统模块(用户 / 鉴权 / 登录)
├── knowledge/ # ★ 知识库 / RAG / 智能体子系统(最大,自包含)
├── workflow/ # 工作流编排引擎
└── evaluation/ # 评测(意图分类评估)
模块职责
| 模块 | 职责 | 关键能力 |
|---|---|---|
system |
用户鉴权 | 登录、JWT、admin_user |
knowledge |
RAG / Agent 核心子系统 | 知识库、文档入库、检索、意图、图谱、MCP、记忆、智能体对话 |
workflow |
工作流编排 | 可视化节点图执行、调试 |
evaluation |
评测 | 意图分类准确率评估 |
common |
基础设施 | 配置、异常、工具、AOP |
💡
knowledge是后端最大的子系统,内部进一步按 pipeline / retrieval / ingest / intent / graph / infra / mcp / memory / agent / prompt / query / fallback 分包,换模型供应商不用改业务代码,加检索通道不用动生成逻辑。
3. 系统分层
自顶向下分四层:
┌──────────────────────────────────────────────────────────┐
│ Controller 层(REST 入口 / SSE) │
│ LoginController / KnowledgeController / AgentTest... │
├──────────────────────────────────────────────────────────┤
│ Service 层(业务编排) │
│ AgentChatService / DocumentIngestService / Workflow... │
├──────────────────────────────────────────────────────────┤
│ 核心引擎层 │
│ RagPipeline(11 stages) / Retrieval / Workflow Engine │
│ Model Routing(三态熔断)/ Intent Tree / Ingest Pipeline │
├──────────────────────────────────────────────────────────┤
│ 基础设施层 │
│ PostgreSQL(vector) / Redis / MinIO / Neo4j / LLM Client │
└──────────────────────────────────────────────────────────┘
Controller 层
主要 REST 入口(共 18 个 Controller):
| 领域 | Controller |
|---|---|
| 鉴权 | LoginController、AdminController |
| 知识库 | KnowledgeController、KnowledgeDocumentController、ParagraphController、QuestionController |
| 智能体 | KnowledgeAgentController、AgentTestController、ChatSessionController |
| 模型 | AiModelController、ExtServiceConfigController |
| 意图 | IntentNodeController |
| 图谱 | KnowledgeGraphController |
| MCP | McpServerController |
| 样例 | SampleQueryController |
| 入库管线 | PipelineController |
| 工作流 | WorkflowController |
| 评测 | EvaluationController |
4. RAG 流水线(核心)
一次用户提问,在 SparkX 里经过的完整链路。这是整个系统最核心的设计。
knowledge/pipeline/RagPipeline 按 Spring @Order 自动装配所有 stage,PipelineStage 定义 CONTINUE / FALLBACK / COMPLETE 三态契约,PipelineContext 贯穿各阶段共享上下文。
11 个 Stage 及执行顺序
| Order | Stage | 作用 | 可短路 |
|---|---|---|---|
| 5 | SampleQueryStage | 样例查询优先匹配,命中直接返回标准答案(零 LLM) | ✅ COMPLETE |
| 10 | RewriteSplitStage | 查询改写 + 多子问题拆分 + 闲聊预判 | |
| 20 | IntentStage | 规则闸门:问候 / 闲聊零成本拦截 | ✅ |
| 30 | TreeIntentStage | 意图树分类:按子问题并行分类 + 配额控制 | |
| 40 | GuidanceStage | 歧义引导:置信度不足时反问澄清 | ✅ |
| 50 | VagueQueryClarifyStage | 模糊查询澄清 | ✅ |
| 60 | RetrieveStage | 多通道检索:向量 + 关键词 + 图谱 + 意图驱动 | |
| 70 | RerankStage | 重排精排 | |
| 80 | MergeStage | 多源结果合并 | |
| 90 | FallbackStage | 兜底:检索为空 / 模型失败时的降级 | |
| 100 | GenerateStage | 大模型生成最终回答 |
用户提问
│
▼
[5 样例查询]──命中──► 直接返回(结束,零 LLM)
│未命中
▼
[10 改写拆分]──► [20 规则闸门]──闲聊──► 直接回复(结束)
│ │
│ ▼ 业务问题
▼
[30 意图分类]──► [40 歧义引导]──► [50 模糊澄清]
│
▼
[60 多通道检索]──► [70 重排]──► [80 合并]
│
▼
[90 兜底]──检索为空──► 固定回复 / 模型降级
│有结果
▼
[100 生成]──► 返回回答
💡 任一 stage 可通过
COMPLETE短路直返(如样例命中、闲聊拦截、歧义澄清),异常统一走FallbackStage兜底,保证用户永远能收到一个体面的回应。
5. 检索引擎
多通道检索
retrieval/ 模块采用策略模式,检索通道独立执行、互不影响,通过线程池并行调度:
| 检索通道 | 类 | 说明 |
|---|---|---|
| 向量+关键词混合 | VectorKeywordHybridChannel |
向量语义 + 关键词全文检索 |
| 意图驱动 | IntentDirectedChannel |
按意图路由定向检索 |
由 HybridContentRetriever 编排多通道,接口统一为 ConditionalRetrievalChannel(意图驱动是否启用)。
后处理链(责任链模式)
检索结果按顺序串联精炼:
| 后处理器 | 作用 |
|---|---|
DeduplicationPostProcessor |
去重 |
RerankPostProcessor / MmrReranker |
重排 + MMR 去冗余 |
ParentExpansionPostProcessor |
子块命中扩展到父块(父子分块) |
FusionPostProcessor |
多通道 RRF(Reciprocal Rank Fusion)融合 |
6. 模型路由与容错
生产环境不能只依赖一个模型供应商。
infra/chat/+infra/model/构建了完整的容错层。
RoutingLLMService(路由入口)
│
▼
ModelSelector(按策略选模型)
│
▼
多 Provider 客户端
┌──────────────────┬──────────────────┐
│ OpenAICompatible │ OllamaChat │
└──────────────────┴──────────────────┘
│
▼
ModelHealthStore(三态熔断:CLOSED → OPEN → HALF_OPEN)
│
▼
LlmFirstPacketProbe(首包探测,切换无感知)
| 组件 | 职责 |
|---|---|
RoutingLLMService |
路由入口,统一调度 |
ModelSelector |
按优先级 / 策略选模型 |
ModelHealthStore |
三态熔断(CLOSED 正常 / OPEN 熔断 / HALF_OPEN 半开放探测) |
ModelRoutingExecutor |
路由执行 |
LlmFirstPacketProbe |
首包探测,保证模型切换对用户无感知 |
OpenAICompatibleChatClient / OllamaChatClient |
具体模型客户端实现 |
容错机制:每个模型独立维护健康状态,失败次数达阈值自动熔断,冷却期后进入半开放状态放行探测请求,探测成功恢复、失败继续熔断。配合优先级降级链,一个模型挂了自动切下一个候选。
7. 文档入库 Pipeline
ingest/ 模块,文档从上传到可检索经过一条节点编排的流水线:
fetch → parse → chunk → enrich → enhance → index
抓取 解析 分块 增强 优化 入库
| 环节 | 实现 |
|---|---|
| 解析 | Apache Tika / PDFBox / POI 多格式;PDF 复杂版面走 MinerU(ingest/mineru/,自建/云端可配) |
| 分块 | AdaptiveDocumentSplitter(自适应)+ ParentChildSplitter(父子分块)+ SpreadsheetRowSplitter(表格按行) |
| 结构化切片 | ingest/block/:基于版面识别段落/标题/列表/表格/图片/代码块,保留 Provenance 溯源 |
| 索引 | KgEntityIndexer(图谱实体)、SampleQueryIndexer(样例)、QuestionIndexer(问答对) |
入库任务和每个节点都有独立执行日志(t_ingestion_task_node / t_ingestion_pipeline_node),出问题能精确定位到哪一步。
8. 工作流引擎
workflow/engine/ 模块,基于 AntV X6 的可视化节点图执行:
| 组件 | 职责 |
|---|---|
FlowNodeParser |
解析前端保存的节点图 JSON,构建执行拓扑 |
IWorkflowNode |
节点执行器接口 |
NodeProvider |
节点工厂,按类型分发 |
WorkflowChatService |
工作流对话总入口 |
节点执行器
| 节点 | 执行器 | 作用 |
|---|---|---|
| 开始 | (内置) | 提供系统变量 |
| 意图分类 | PurposeNode |
模型分类,按分支路由 |
| LLM | LlmNode |
调用大模型生成 |
| 知识检索 | DatasetNode |
向量召回 |
| 知识图谱 | GraphNode |
图谱召回 |
| Agent | AgentNode |
调用智能体 |
| 回复 | AnswerNode |
返回最终回答(终点) |
| 条件分支 | SwitchNode |
IF/ELSEIF/ELSE,12 种操作符 |
9. 数据库设计
数据库为 PostgreSQL(带 pgvector 扩展),向量检索直接用 PgSQL 的 vector 能力,无需额外向量数据库。共 29 张业务表,按业务域分组:
知识库域
| 表 | 作用 | 关键字段 |
|---|---|---|
knowledge_base |
知识库 | embedding_model_id(绑定向量模型)、dimension、kg_enabled |
document |
文档 | kb_id、file_name、storage_url、ingestion_summary、chunk_count |
chunks |
文档分块(子块) | kb_id、content、embedding(向量)、tsv(关键词向量)、metadata |
parent_chunks |
父块(父子分块) | kb_id、content |
knowledge_question |
问答对 | 问题 + 答案索引 |
💡
chunks.embedding是 pgvector 向量列,tsv是 tsvector 关键词列 —— 一张表同时支撑向量检索和全文检索。
智能体域
| 表 | 作用 | 关键字段 |
| — | — |
| knowledge_agent | 智能体配置 | knowledge_base_ids、chat_model_id、system_prompt、temperature、embedding_top_k、vector_threshold、rerank_、fallback_、sample_query_* |
| t_chat_session | 对话会话 | 用户会话 |
| t_chat_message | 对话消息 | 单轮消息记录 |
| t_agent_test_session | 智能体调试会话 | 调试用 |
| t_agent_test_message | 调试消息 | 调试用 |
对话记忆域
| 表 | 作用 |
|---|---|
t_conversation_message |
对话历史消息(含 rag_context 检索证据、thinking_content 思考过程) |
t_conversation_summary |
会话话题摘要(L2 记忆压缩) |
t_persistent_memory |
跨会话持久记忆(L3,原理预研,默认关闭) |
意图与样例域
| 表 | 作用 | 关键字段 |
|---|---|---|
t_intent_node |
意图树节点 | parent_id、level、kind、examples、mcp_tool_id、prompt_template |
sample_query |
样例查询 | 问题 + 标准答案(向量化后匹配) |
sample_query_config |
样例查询全局配置 | 匹配阈值等 |
入库流水线域
| 表 | 作用 |
|---|---|
t_ingestion_task_node |
入库任务节点 |
t_ingestion_pipeline_node |
入库管线节点 |
AI 模型域
| 表 | 作用 | 关键字段 |
| — | — |
| ai_model | 模型配置 | type(对话/向量/重排/视觉)、provider、credential、models(逗号分隔多模型)、priority、supports_thinking |
| ext_service_config | 外部服务配置 | MinerU 等外部服务 |
知识图谱域
| 表 | 作用 |
|---|---|
kg_config |
图谱配置 |
kg_entity |
图谱实体 |
kg_extraction_record |
实体抽取记录 |
MCP 域
| 表 | 作用 | 关键字段 |
|---|---|---|
mcp_server |
MCP 服务 | transport_type、url、auth_type、auth_config、headers、timeout_sec |
mcp_tool |
MCP 工具(自动发现) | server_id、tool_name、input_schema |
工作流域
| 表 | 作用 | 关键字段 |
|---|---|---|
workflow |
工作流定义 | flow_data(节点图 JSON) |
workflow_runtime |
运行时记录 | workflow_id、user_id |
workflow_runtime_context |
运行时上下文 | node_type、step、output_data、model_data |
系统域
| 表 | 作用 |
|---|---|
admin_user |
管理员用户 |
10. 设计模式实战
SparkX 不是为用模式而用,每个模式都对应一个具体的工程问题:
| 设计模式 | 应用场景 | 解决的问题 |
|---|---|---|
| 策略模式 | 检索通道、后处理器、MCP 工具执行器、节点执行器 | 可插拔替换,加新通道不改老代码 |
| 模板方法 | PipelineStage 基类、IWorkflowNode | 统一执行流程,子类只关注核心逻辑 |
| 责任链模式 | 后处理器链、RAG Pipeline stages、模型降级链 | 多步骤按顺序串联,灵活组合 |
| 装饰器模式 | 首包探测回调(ProbeStreamBridge) | 不改原有回调的前提下增加探测能力 |
| 注册表模式 | MCP 工具注册中心、意图节点、节点工厂(NodeProvider) | 组件自动发现与注册,新增零配置 |
| 工厂模式 | NodeProvider(按类型创建节点执行器) | 解耦创建与使用 |
| AOP | @RagTraceNode 链路追踪切面 |
追踪逻辑与业务代码解耦 |
11. 扩展点
SparkX 的核心模块都预留了扩展点,加能力不改框架代码:
| 想扩展 | 实现方式 |
|---|---|
| 新增检索通道 | 实现 ConditionalRetrievalChannel 接口,注册为 Spring Bean |
| 新增 RAG 阶段 | 实现 PipelineStage,加 @Component @Order(n) 自动并入流水线 |
| 新增后处理器 | 实现后处理接口,加入责任链 |
| 新增 MCP 工具 | 配置 MCP Server,自动发现 |
| 新增模型供应商 | 实现 ChatClient 接口,配置候选列表参与路由 |
| 新增工作流节点 | 实现 IWorkflowNode,注册到 NodeProvider |
