项目亮点与设计原则

片段，每个分块自动携带表头，确保独立可读 HTML 模式下采用行级完整性保障：同一行数据绝不会被拆分到不同分片中，即使该行超过 chunkSize，也保证至少包含一行。分块间通过共享表头实现上下文自足，解决了大表格跨分片后的信息丢失问题。文件格式检测通过文件头魔数实现（ZIP 头 → .xlsx，OLE 头 → .xls，逗号+换行 → .csv），不依赖文件扩展名，防止用户重命名导致的解析错误。同时支持 BOM 编码自动检测（UTF-8/UTF-16BE/UTF-16LE）。

🔥 表格与图片跨分片完整性保障

Markdown 文档中的表格和图片在被 chunkSize 二次切割时面临语义截断风险，本系统通过以下机制解决： - 父子分段保留完整原文：超出 chunkSize 的分片会保留一份完整原文（标记 skipEmbedding = 1，不参与向量检索），同时生成多个子分片（携带 parentChunkId）。检索时命中子分片后，自动通过 parentChunkId 回溯到 Redis 缓存中的父分片完整文本进行替换，确保表格和图片的上下文完整性 - 兄弟分段自动补全：通过 brotherChunkId + brotherChunkIndex + brotherChunkTotal 元数据，检索命中任一子分片时自动补全同级所有兄弟分段，拼出完整内容 - 代码块保护：Markdown 切片器识别 ``` 代码围栏，将整个代码块作为一个不可分割的单元处理，避免代码被截断

🔥 虚拟线程 + Flash 模型 — 异步标题生成零延迟

新会话首条消息发出后，系统通过 Thread.ofVirtual().name("title-summary-" + conversationId).start(...) 启动 Java 21 虚拟线程，异步调用 qwen3.5-flash 轻量模型生成对话标题并回写数据库。关键设计： - 零阻塞：虚拟线程不占用平台线程，不阻塞 SSE 流式响应的首 Token 输出 - Flash 模型选型：使用 qwen3.5-flash 而非 qwen-max，标题生成任务对推理能力要求低，Flash 模型响应更快、成本更低 - 关闭思考模式：通过 customParameters(Map.of("enable_thinking", false)) 关闭 qwen3.5-flash 的 CoT 思考过程，进一步降低延迟 - 优雅降级：标题生成失败时保留临时标题，不影响对话功能

🔥 意图识别 — LLM Structured Output 约束

通过 LangChain4j 的 @AiService + @SystemMessage + @JsonPropertyDescription 注解体系，将意图识别结果约束为 IntentRecognitionResult Record 类型，包含 reasoning（推理过程）、related（是否相关）、intent（意图分类）、entities（结构化实体）四个字段。LLM 输出被强制对齐到 Java 类型系统，避免了自由文本输出的不确定性。识别流程在 RAG 管道前端通过 Mono.fromCallable().subscribeOn(Schedulers.boundedElastic()) 调度，不阻塞 WebFlux 事件循环。

🔥 多级缓存 Chunk 检索 — HashMap + Redis + MySQL 三级缓存

KnowledgeSegmentServiceImpl.getTextByChunkId() 实现了 HashMap → Redis → MySQL 的三级缓存策略，用于父子分段检索时快速获取父分段完整文本： - L1 缓存（HashMap）：以 chunkId 为 Key，在当前线程缓存父分段完整文本，避免同一次检索中重复查询 Redis 和数据库 - L2 缓存（Redis）：以 chunkId 为 Key，30 秒 TTL，命中即返回 - L3 回源（MySQL）：Redis 未命中时查询 knowledge_segment 表，结果写入 Redis - 防缓存击穿：查询结果为空时缓存空字符串，避免同一不存在的 chunkId 反复穿透到数据库 这一机制在父子分段检索场景下尤为关键：每条检索结果都可能触发父分段回溯，三级缓存将数据库查询压力降低一个量级。 在文档检索权限体系中，L2 缓存同时缓存权限元数据（accessibleBy），检索时在 EmbeddingSearchRequest 中注入 Filter 条件按当前用户身份过滤，权限变更时通过事件驱动批量失效关联缓存并更新 ES 索引，确保权限变更实时生效。权限过滤与版本过滤（docVersion）均通过 ES Filter 条件实现，与三级缓存协同工作，在保障数据安全的同时不影响检索性能。

🔥 LLM JSON 输出修复 — 7 步容错管道

LLM 在结构化输出场景中经常产生不符合 JSON 规范的结果（如包裹 Markdown 代码块、使用中文引号、尾部多余逗号等）。JsonUtil.fixJson() 实现了 7 步修复管道： 1. Markdown 代码块提取：剥离 json ... 包裹 2. 前后垃圾字符移除：定位首个 { / [ 到末尾 } / ] 之间的有效 JSON 3. 引号修复：中文引号 → 英文引号，单引号 → 双引号 4. 尾部逗号修复：移除 }, / ], 中的多余逗号 5. 缺失引号修复：为无引号的键名自动添加双引号 6. 转义字符修复：清理字符串中的非法换行符、制表符 7. 最终容错：以上修复后仍无效，将原始文本包装为 {"content": "..."} 结构 修复后通过 ObjectMapper.readTree() 验证有效性，确保下游代码始终拿到合法 JSON。该工具广泛用于意图识别、查询路由、查询改写等所有依赖 LLM 结构化输出的环节。

🔥 工厂模式多策略切片 — DocumentSplitterFactory

DocumentSplitterFactory 通过工厂模式封装 5 种切片策略，根据用户选择的 SplitType 动态创建对应的 DocumentSplitter： | 切片策略 | 实现类 | 适用场景 | | --- | --- | --- | | LENGTH | DocumentByWordSplitter | 纯文本按字数切分 | | TITLE | MarkdownHeaderParentTextSplitter | Markdown 按标题层级切分，保留父子关系 | | REGEX | DocumentByRegexSplitter | 自定义正则表达式切分 | | SEPARATOR | DocumentByRegexSplitter | 按指定分隔符切分 | | SMART | MarkdownHeaderParentTextSplitter | 智能切分，自动计算 overlap（chunkSize × 10%） |

Excel/CSV 类型文档则独立走 ExcelSplitter 处理，不经过工厂模式。前端 upload.html 根据选择的切片方式动态显示/隐藏参数组（overlap、titleLevel、regex、separator），实现配置与策略的联动。

🔥 查询改写异步回写 — 虚拟线程不阻塞主流程

KnowEngineQueryTransformer 在完成查询改写后，通过 Thread.ofVirtual().name("query-transform-" + chatMessageId).start(...) 将改写结果异步回写到 chat_message 表的 transformContent 字段。回写操作与主流程完全解耦：即使回写失败，也不影响改写后的 Query 继续进入检索和生成环节。这一设计使得查询改写的 4 维策略（简洁改写、抽象概念改写、错别字纠正、车型信息标准化）在提升检索质量的同时，对端到端延迟零贡献。

设计原则

• 事件驱动优于直接调用：文档处理流程通过 Spring Event 解耦，Controller 瘦身，职责清晰；权限变更同样通过事件驱动批量更新 ES 索引；权限变更同样通过事件驱动批量更新 ES 索引
• 最终一致性：事件驱动 + XXL-Job 补偿，“异步优先，定时兜底”
• 流式优先：全链路 Reactor 响应式，SSE 逐 Token 推送，进度可见；多渠道输出（Web/钉钉）共享同一流式管道；多渠道输出（Web/钉钉）共享同一流式管道
• 声明式并发控制：@DistributeLock 注解一行搞定幂等保护
• 本地推理优先：Reranking 在 JVM 进程内完成，省去网络往返，降低延迟
• 虚拟线程优先：所有 LLM 辅助调用（标题生成、查询改写回写）均使用虚拟线程，零阻塞主流程
• 容错优先：LLM JSON 输出修复管道、缓存空值防击穿、标题生成失败保留临时标题、Text2Cypher 降级回退 ES，处处留有余地
• 分布式 ID 全链路：雪花算法生成的 ChunkId 贯穿切片 → 存储 → 检索 → 扩展，全局唯一可追溯；版本链路通过 parentVersionDocId 关联，时序可追溯
• 权限内建：权限信息从文档写入切片 metadata → ES 索引 → 检索 Filter，全链路内建，变更实时生效 ```