项目结构
本页介绍 SparkX 的整体目录组织,以及核心子系统
knowledge的二级目录详解,帮助你快速建立代码地图。
一、顶层结构
SparkX 采用前后端分离架构,仓库根目录下分三大块:
spark-x/
├── admin/ # Vue3 + Naive UI 管理后台(智能体/知识库/AI配置/编排/对话调试)
├── server/ # Spring Boot 3.4 后端(包根 sparkx.sparkshop)
└── docker/ # 一键编排(backend + frontend + PgSQL + Redis + MinIO)
| 目录 | 技术栈 | 职责 |
|---|---|---|
admin/ |
Vue 3 + TypeScript + Vite + Naive UI + AntV X6 | 可视化管理后台,覆盖智能体开发全生命周期 |
server/ |
Java 17 + Spring Boot 3.4 + MyBatis-Plus + LangChain4j | 后端服务,RAG/Agent/MCP/编排核心能力 |
docker/ |
Docker Compose | 一键拉起前后端 + PostgreSQL + Redis + MinIO |
二、后端核心模块
后端按职责划分模块,各模块相互独立、职责清晰:
| 模块 | 职责 |
|---|---|
knowledge/ |
知识库 / RAG / 智能体子系统(自包含,最大模块) |
workflow/ |
工作流编排引擎(可视化节点图执行) |
evaluation/ |
评测(意图分类评估面板) |
system/ |
系统模块(用户 / 鉴权 / 通用) |
common/ |
通用基础设施(config / exception / utils) |
💡
knowledge子系统内部进一步按 pipeline / retrieval / ingest / infra / mcp / intent / graph 分包 —— 换模型供应商不用改业务代码,加检索通道不用动生成逻辑。
三、knowledge 模块二级目录详解
knowledge 是后端最大的子系统,RAG / 智能体 / 意图 / 图谱 / MCP 全部自包含于此。完整目录结构如下:
knowledge/
├── pipeline/ # RAG 流水线引擎(按 @Order 自动装配)
│ └── stages/ # 11 个具体阶段(样例/改写/意图/检索/重排/生成…)
├── retrieval/ # 检索通道 + 后处理链(混合 / 去重 / MMR / RRF 融合)
├── ingest/ # 文档入库流水线(解析 / 分块 / 嵌入 / 索引)
│ ├── block/ # 基于版面的结构化分块(段落 / 标题 / 表格 / 代码…)
│ └── mineru/ # MinerU 复杂版面解析客户端封装
├── intent/ # 意图树 + 规则快路径 + LLM 分类 + 引导澄清
├── graph/ # 知识图谱(Neo4j 存储 + 抽取 + 检索通道)
├── infra/ # LLM / 嵌入 / 重排 基础设施
│ ├── chat/ # 模型客户端(路由 + 三态熔断 + 首包探测 + 流式)
│ └── model/ # 模型健康 / 路由选择 / 路由执行
├── mcp/ # MCP 工具注册中心 + 执行器
├── memory/ # 对话记忆(历史加载 + 摘要压缩)
├── agent/ # 智能体对话编排入口 + 评测
├── prompt/ # 提示词编排(场景路由 + 模板管理)
├── query/ # 查询改写 / 扩展 / 多子问题拆分
├── fallback/ # 模型兜底 / 降级策略
├── config/ # Spring Bean 装配与配置绑定
├── controller/ # REST 入口(各领域 HTTP 接口)
├── service/ + impl/ # 业务逻辑层(接口 + 实现)
├── mapper/ # MyBatis Mapper(各表 CRUD)
├── entity/ # 持久化实体(对应 26 张业务表)
├── vo/ # 出入参 DTO
├── validate/ # 入参校验(每场景一个 Validate 类)
└── common/ # 异常 + 全链路 Trace AOP
├── exception/ # RAG 统一异常
└── trace/ # @RagTraceNode 链路追踪切面
按职能分为六大组,逐一说明。
3.1 流水线核心
pipeline/—RagPipeline按@Order自动装配所有 stage;PipelineStage定义CONTINUE/FALLBACK/COMPLETE契约;PipelineContext贯穿各阶段共享上下文。pipeline/stages/— 11 个阶段:样例命中(5) → 改写拆分(10) → 意图分类(20/30) → 歧义澄清(40) → 引导(50) → 检索(60) → 重排(70) → 合并(80) → 生成(90);任一步可短路COMPLETE直返,异常走FallbackStage兜底。
3.2 检索(retrieval)
retrieval/—ConditionalRetrievalChannel接口 +VectorKeywordHybridChannel(向量+关键词)、IntentDirectedChannel(意图驱动);HybridContentRetriever编排多通道;后处理链DeduplicationPostProcessor/MmrReranker/ParentExpansionPostProcessor/FusionPostProcessor(RRF 融合)。
3.3 入库(ingest)
ingest/—DocumentIngestService入库总服务;AdaptiveDocumentSplitter/ParentChildSplitter/SpreadsheetRowSplitter分块策略;MultimodalDocumentParser/ImageOcrService多模态解析;KgEntityIndexer/SampleQueryIndexer/QuestionIndexer实体 / 样例 / 问答索引。ingest/block/— 基于版面的结构化切片:Block抽象 + 段落 / 标题 / 列表 / 表格 / 图片 / 代码块,BlockAwareChunker按结构分块并保留Provenance溯源。ingest/mineru/— MinerU 复杂 PDF 版面解析客户端封装(MinerUClient/MinerUDocumentParser/MinerUImageDescriber等)。
3.4 意图(intent)
intent/—IntentNode+IntentTreeCacheManager意图树;RuleBasedIntentRouter规则快路径(问候 / 闲聊零成本);IntentClassifier/LlmIntentClassifier低温 LLM 分类;AmbiguityChecker/VagueQueryClarifier/IntentGuidanceService歧义检测与引导澄清;IntentSeedService/IntentEvalService种子生成与评测。
3.5 知识图谱(graph)
graph/—GraphRepository接口 +Neo4jGraphRepository/NoopGraphRepository(未配 Neo4j 兜底);KnowledgeGraphChannel图谱检索通道并入 RAG;GraphExtractionService实体关系抽取;CommunityService社区检测(global 模式前置);EntityDisambiguator实体消歧。
3.6 模型基础设施(infra)
infra/—LLMServiceLLM 统一门面、EmbeddingModelProvider嵌入模型解析、TsVectorGenerator关键词检索向量生成。infra/chat/— 模型客户端:RoutingLLMService路由入口 +ModelSelector选模型 +ModelHealthStore三态熔断 +LlmFirstPacketProbe首包探测 +StreamCallback流式回调;OpenAICompatibleChatClient/OllamaChatClient具体实现。infra/model/—ModelHealthStore健康状态(CLOSED / OPEN / HALF_OPEN)、ModelSelector策略选模型、ModelRoutingExecutor路由执行。
3.7 工具与记忆
mcp/—McpToolRegistry注册中心 +McpToolService执行器 +McpClientManager客户端管理;远程 MCP 工具经mcp_server/mcp_tool表接入。memory/—ConversationMemoryService/ConversationMemoryStore历史加载 +ConversationMemorySummaryService摘要压缩,长对话不超 Token。
3.8 智能体与提示词
agent/—AgentChatService智能体对话总入口(驱动RagPipeline)、AgentEvalService评测、AgentRerankClient重排客户端。prompt/—PromptPlanner提示词编排(KB_ONLY / MCP_ONLY / MIXED / EMPTY 场景路由)+PromptTemplateLoader/PromptTemplateManager模板管理。query/—MultiQuestionRewriteService多子问题改写、QueryExpansionTransformer查询扩展、QueryTermMappingService词映射。
3.9 兜底与配置
fallback/—FallbackProvider接口 +ModelFallbackProvider/FixedFallbackProvider模型降级兜底。config/— Spring Bean 装配与配置绑定:RagProperties/AiModelProperties/AsyncConfig/LangChain4jConfig/McpBeansConfig/MinerUConfig/MinioConfig/KnowledgeGraphConfig等。
3.10 支撑层(通用)
controller/— 各领域 REST 入口(知识库 / 文档 / 智能体 / 意图 / 图谱 / MCP / 样例 / 会话 / 模型 / 管线)。service/+service/impl/— 业务逻辑接口与实现。mapper/— MyBatis Mapper(22 张表 CRUD)。entity/— 持久化实体(对应KnowledgeBase/Chunk/IntentNode/KgEntity/SampleQuery/McpTool/AiModel/Conversation… 等表)。vo/— 出入参 DTO(29 个)。validate/— 入参校验(38 个 Validate 类,每场景一个)。common/exception/—RagExceptionRAG 统一异常。common/trace/—RagTraceAspect/RagTraceNode全链路 Trace AOP 切面(每个环节耗时 / 输入输出记录)。
四、模块协作关系
一张图理解各子目录如何串联成完整的 RAG 链路:
用户提问
│
▼
agent/ ────────────► pipeline/ (RagPipeline 按 @Order 装配)
│ │
│ ▼
│ intent/ (意图路由:规则快路径 → LLM 分类)
│ │
│ ▼
│ query/ (改写/拆分) ──► retrieval/ (多通道检索 + 后处理)
│ │
│ ▼
│ graph/ (图谱检索) ──► 后处理链(去重/MMR/RRF 融合)
│ │
│ ▼
│ prompt/ (场景路由) ──► infra/chat/ (模型路由 + 熔断 + 流式生成)
│ │
│ ▼
│ fallback/ (兜底降级)
│ │
▼ ▼
memory/ (历史/摘要) common/trace/ (全链路追踪)
- mcp/ 在 MIXED 场景下被
prompt/调用,让模型调用外部工具 - ingest/ 独立于问答链路,负责文档入库(解析 → 分块 → 嵌入 → 索引),产物供
retrieval/使用
五、如何阅读源码
建议按以下顺序浏览,从核心到外围:
agent/AgentChatService—— 智能体对话总入口,理解整体调用链pipeline/RagPipeline—— RAG 流水线骨架,理解 11 个 stage 如何串联retrieval/—— 检索通道与后处理,理解混合检索与融合infra/chat/—— 模型路由与熔断,理解生产级容错ingest/—— 文档入库流水线,理解数据如何变成可检索的知识- 其余模块(
intent/graph/mcp/memory/prompt)按需深入
掌握以上结构后,可继续阅读 设计以及实现 了解架构思想。
