项目整体架构与核心功能

本项目是一个基于 RAG 架构的企业知识管理与智能问答系统，实现从文档接入、智能切片、向量化存储到多源检索、意图路由、流式对话的全链路闭环。

整体架构分层

系统采用分层架构设计，自上而下分为 5 层：

知识入库流程

文档从上传到可检索的完整链路：

对话流程

用户提问到获取回答的完整链路：

模块划分

项目源码按职责划分为 7 个核心包： | 模块 | 包路径 | 职责 | | --- | --- | --- | | AI 能力层 | ai/ | 意图识别、通用对话、Prompt 路由、标题摘要生成 | | 对话管理层 | chat/ | 对话编排（RAG 管道）、会话管理、消息持久化、多轮记忆 | | 文档管理层 | document/ | 文档上传/转换/切片/向量化、知识库管理、事件驱动处理 | | RAG 检索增强层 | rag/ | 查询改写、查询路由、多源检索、Reranking、进度感知 | | 业务数据层 | business/ | 业务实体管理、知识库CRUD、数据转换 | | 基础设施层 | infra/ | 分布式锁注解、雪花ID生成器、JSON修复工具 | | 全局配置层 | config/ | 线程池、MyBatis-Plus、XXL-Job、元数据填充 |

代码结构：

know-engine/
├── ai/                          # AI 能力层
│   ├── config/                  #   Memory 配置
│   ├── constant/                #   意图枚举
│   ├── model/                   #   意图识别结果模型
│   └── service/                 #   意图识别、通用对话、Prompt 路由、标题摘要
├── chat/                        # 对话管理层
│   ├── constant/                #   会话状态、消息类型、检索来源
│   ├── controller/              #   对话/会话/消息 REST 接口
│   ├── entity/                  #   会话与消息实体
│   ├── mapper/                  #   MyBatis-Plus Mapper
│   └── service/                 #   对话应用服务（RAG 管道编排）
├── config/                      # 全局配置
│   ├── AsyncConfig              #   线程池配置
│   ├── MyMetaObjectHandler      #   自动填充时间戳
│   ├── MybatisPlusConfig        #   分页插件、乐观锁插件
│   └── XxlJobConfig             #   XXL-Job 执行器配置
├── document/                    # 知识文档管理层
│   ├── config/                  #   MinIO 配置
│   ├── constant/                #   文档状态、文件类型、知识库类型
│   ├── controller/              #   文档/切片 REST 接口
│   ├── entity/                  #   文档与切片实体
│   ├── event/                   #   Spring 事件（Converted/Chunked）
│   ├── job/                     #   XXL-Job 补偿任务
│   ├── mapper/                  #   MyBatis-Plus Mapper
│   ├── service/                 #   文档处理、切片、向量化、文件存储
│   └── util/                    #   文件类型检测 (Tika)
├── infra/                       # 基础设施
│   ├── json/                    #   JSON 工具
│   ├── lock/                    #   分布式锁注解 + AOP 切面
│   └── snowflake/               #   雪花 ID 生成器
└── rag/                         # RAG 检索增强层
    ├── config/                   #   ES / Neo4j 配置
    ├── constant/                 #   元数据 Key 常量
    ├── controller/               #   检索测试接口
    ├── model/                    #   路由结果模型
    └── modules/                  #   RAG 核心模块
        ├── KnowEngineQueryTransformer   # 查询改写器
        ├── KnowEngineQueryRouter        # 三源路由器
        ├── KnowEngineElasticsearchContentRetriever  # ES 检索器（父子分段扩展）
        ├── ProgressAwareContentAggregator          # 进度感知聚合器
        ├── reranker/              #   BGE-RERANKER 本地单例
        └── splitter/              #   文档切片器（Markdown/Excel）

技术栈

RAG 管道核心组件

核心功能

1. 全链路知识接入 (Ingestion Pipeline)

从原始文档到可检索知识，全程自动化： - 多格式解析：支持 PDF（MinerU 深度解析）、Word、Excel、Markdown、TXT、Excel等 - 智能切片（5 种策略，工厂模式按需选择）： - MarkdownHeaderParentTextSplitter — 基于标题层级切片，保留父子分段关系（Parent-Child Chunking），支持 chunkSize / overlap 精细控制、代码块保护、超出 chunkSize 自动二次切割 - MarkdownHeaderBrotherTextSplitter — 兄弟分段关联，检索时自动补全同级上下文 - ExcelSplitter — 针对结构化数据的双模式切片（键值对模式 & HTML 表格模式），按 chunkSize 智能分块，确保同一行数据不被拆分 - DocumentByWordSplitter / DocumentByRegexSplitter — 按长度 / 正则 / 分隔符切分，满足不同文档结构需求 - SMART 智能切分 — 自动使用 MarkdownHeaderParentTextSplitter，overlap 为 chunkSize 的 10% - 事件驱动处理：Spring ApplicationEvent 串联 文档转换 → 切片 → 向量化，每个阶段独立解耦 - 补偿机制：XXL-Job 定时扫表，自动重试失败任务，保障最终一致性

2. 关键检索增强

• 查询改写（KnowEngineQueryTransformer）：4 维改写策略 — 简洁改写、抽象概念改写、错别字纠正、车型信息标准化。改写结果还通过 Java 21 的虚拟线程异步回写到数据库，不阻塞主流程。
• 父子分段扩展（KnowEngineElasticsearchContentRetriever）：命中子分段时，自动回溯父分段获取完整语义上下文。
• 本地 Reranking（BgeScoringModel）：基于 ONNX Runtime 加载 BGE-RERANKER 模型，进程内推理，零网络延迟
• 查询路由（KnowEngineQueryRouter）：三路由检索架构，由 LLM 智能识别问题，判断通过不同的数据源做检索
• Text2SQL（SqlDatabaseContentRetriever）：LLM 根据数据库 Schema 自动生成 SQL 并通过 JDBC 执行查询，支持结构化业务数据（订单、保险、召回信息等）的自然语言查询。基于 table_meta 表存储的表结构元数据驱动 Schema 感知，自动注入当前日期等上下文变量；查询结果以自然语言格式返回
• Text2Cypher（Neo4jText2CypherRetriever）：LLM 根据图数据库 Schema 自动生成 Cypher 查询语句，在 Neo4j 中执行实体关系检索，适用于车型图谱、零部件供应链、故障影响链等关系型场景。Cypher 查询失败时自动降级回退到 ES 检索，保障系统鲁棒性；查询结果与 ES 向量检索结果通过 ContentAggregator 统一聚合，经 Reranking 后共同参与最终生成 | 数据源 | 检索方式 | 适用场景 | | --- | --- | --- | | Elasticsearch | KNN 向量检索 + 全文检索 + 混合检索 | 语义相似性匹配、非结构化知识 | | MySQL | Text2SQL（LLM 生成 SQL） | 结构化数据查询，如订单、保险、召回信息 | | Neo4j | Text2Cypher（LLM 生成 Cypher + 降级回退） | 实体关系查询，如车型图谱、零部件供应链、故障影响链 |

3. 意图识别与动态 Prompt

• 6 大意图分类：售前咨询与购买、售后维修与保养、车辆使用与技术指导、投诉与维权、汽车营销政策、其他
• 相关度判断：LLM 首先判断用户问题是否与汽车领域相关，不相关问题直接走通用对话，避免 RAG 误检索
• 结构化实体提取：车型、订单号、经销商、故障描述、预约时间、零部件、车辆功能
• Prompt 动态路由：根据识别结果加载对应的领域 Prompt 文件，Prompt 使用 ConcurrentHashMap 本地缓存，避免重复 IO
• LangChain4j Structured Output：通过 @JsonPropertyDescription 注解约束 LLM 输出为 IntentRecognitionResult Record，确保意图识别结果结构化、可编程处理

4. 流式对话体验

• SSE 实时推送：基于 Reactor Flux 的全链路流式输出，Token 级逐字推送
• 进度可见：RAG 管道每个环节（意图识别 → 问题改写 → 问题路由 → 排序筛选 → 生成回答）均向前端推送 [PROGRESS] 事件，消除等待焦虑
• RAG 引用溯源：检索结果携带文档来源、分片内容、Rerank 分数，支持可解释性审查
• 异步标题生成：新对话自动以 Java 21 虚拟线程 + qwen3.5-flash 轻量模型异步生成摘要标题，不阻塞首 Token 延迟；失败时保留临时标题，保障主流程不受影响
• 交互卡片输出：SSE 流式响应中支持 [CARD] 结构化卡片事件，将车型对比、订单详情、召回信息等结构化数据以卡片形式呈现。LLM 通过 Prompt 引导在特定场景输出结构化 JSON 标记，后端解析后转换为 [CARD] 事件，前端根据卡片类型（vehicle_info / order_detail / recall_notice / comparison_table）渲染对应 UI 组件，支持点击展开详情、跳转链接等交互操作
• 钉钉机器人接入：接入钉钉机器人，支持单聊和群聊 @机器人两种模式。钉钉消息回调经签名验证后转换为 KnowEngine 统一对话接口调用，流式收集完整回复后通过钉钉 API 回复；群聊模式自动识别 @内容 作为用户问题

5. 知识库管理

• 双类型知识库：DOCUMENT_SEARCH（语义检索型）和 DATA_QUERY（数据查询型）
• 完整文档生命周期：INIT → UPLOADED → CONVERTING → CONVERTED → CHUNKED → VECTOR_STORED
• 文档多版本管理：支持同一知识文档的多版本共存，knowledge_document.extension JSON 字段存储版本元数据（version、parentVersionDocId、changeLog）。新版本发布后旧版本自动归档，检索时默认使用最新版本；版本切换通过修改 ES 中 docVersion 的 Filter 条件实现热切换，无需重新向量化；expire_date 字段支持文档到期后自动从检索结果中过滤；版本回滚一键切回历史版本，ES Filter 实时生效
• 文档检索权限体系：基于角色和组织的文档访问控制，knowledge_document.accessible_by 字段存储文档可见范围。切片时将 accessibleBy 写入 knowledge_segment.metadata，向量化时同步到 ES 索引，检索时在 EmbeddingSearchRequest 中注入 Filter 条件按当前用户身份过滤。
• MinIO 对象存储：文档文件统一存储，支持 URL 直接访问
• 乐观锁 + 逻辑删除：数据安全，防并发冲突