Java 21+Spring Boot 3构建企业级RAG与智能体工作流

1. 项目概述：为什么在企业级AI工程中，Java 21 + Spring Boot 3 是 RAG 与智能体落地的“稳态选择”

别卷 Python 了——这句话不是唱衰 Python，而是直击当前 AI 工程化落地中最常被忽视的现实矛盾：原型快 ≠ 上线稳，单点强 ≠ 全链路可控，开发爽 ≠ 运维省。我过去三年带过 7 个 AI 应用交付项目，其中 5 个初期用 Python（FastAPI + LangChain）快速搭出 PoC，但最终全部重构为 Java 技术栈上线。不是因为 Python 不行，而是当 RAG 系统要接入 ERP、对接 OA 审批流、承载日均 20 万次知识查询、要求 SLA 99.95%、审计日志需满足等保三级时，Java 生态的成熟度、可观测性、事务一致性、线程模型和 JVM 调优体系，成了不可替代的底盘。

这个项目标题里的每个词，都是经过真实产线反复验证后的技术选型结论。“Java 21”不是为了追新，而是因为它原生支持虚拟线程（Virtual Threads），让高并发 RAG 检索+LLM 调用+工作流编排的混合负载不再卡在传统线程池瓶颈上；“Spring Boot 3”强制要求 Jakarta EE 9+ 和最低 JDK 17，它带来的模块化依赖收敛、自动配置剥离、以及对 GraalVM 原生镜像的开箱支持，直接解决了 AI 微服务冷启动慢、内存占用高、容器镜像臃肿三大顽疾；“企业级 RAG”意味着我们不只做向量检索，还要处理非结构化文档解析（PDF/Word/Excel/PPT）、多源异构数据同步（数据库变更捕获 + 文件系统监听）、语义分块策略动态切换（按章节/按表格/按代码段）、以及检索结果的可信度打分与溯源标注；而“智能体工作流引擎”，则完全跳出了 LangGraph 的 Python 运行时绑定，用 Spring State Machine + 自研 DSL 实现了可持久化、可回滚、可审计、可人工干预的多步骤决策流——比如一个销售智能体，收到客户询价后，自动触发：① 检索产品知识库 → ② 查询 CRM 中该客户历史订单 → ③ 调用定价规则引擎计算折扣 → ④ 生成报价单 PDF → ⑤ 推送至企业微信并等待销售确认，任意一步失败都可降级或转人工，全程状态可查、操作可溯。

这整套方案，面向的是真正要“把 AI 装进业务流水线”的团队：不是算法研究员，而是懂业务逻辑的后端工程师；不是个人开发者，而是需要通过 CI/CD 流水线、APM 监控、日志中心、配置中心统一纳管的运维团队；不是追求 Demo 震撼效果，而是要求每次响应延迟 <800ms、错误率 <0.3%、故障恢复时间 <3 分钟的 SRE 团队。如果你正在评估是否要把 RAG 或智能体从 Jupyter Notebook 推向生产环境，这篇内容就是你该抄的第一份作业。

2. 架构设计与技术选型逻辑：为什么不用 LangChain/LangGraph，而选择自研引擎内核

2.1 整体分层架构：从“胶水代码”到“可治理服务”

整个系统采用清晰的四层架构，每层职责明确、边界清晰、技术栈解耦：

• 接入层（Ingress Layer）：Spring Cloud Gateway + JWT/OAuth2 认证网关，统一处理鉴权、限流（Sentinel）、灰度路由、请求染色。所有智能体调用必须携带x-agent-id和x-session-id，为后续全链路追踪打下基础。这里不使用 Nginx 做反向代理，是因为我们需要在网关层注入业务上下文（如租户 ID、渠道来源），而 Spring Cloud Gateway 可以无缝集成 Spring Security 和自定义 Filter。

• 编排层（Orchestration Layer）：这是本项目最核心的创新点——基于 Spring State Machine 的可持久化智能体工作流引擎。它不依赖任何 Python 运行时，所有节点（Node）定义为 Spring Bean，每个节点实现AgentNode接口，包含execute()（执行逻辑）、rollback()（回滚逻辑）、next()（下一跳决策）三个方法。工作流定义采用 YAML DSL 描述，例如一个“工单初筛智能体”的片段如下：

  id: ticket-initial-screening initial: parse-ticket states: - id: parse-ticket type: action bean: ticketParserNode transition: success: check-knowledge-base failure: escalate-to-human - id: check-knowledge-base type: action bean: ragRetrieverNode config: index: it-service-faq top-k: 3 transition: success: generate-answer failure: escalate-to-human

  引擎运行时会将该 DSL 解析为 StateMachineConfiguration，并在 Redis 中持久化每个实例的状态（state:check-knowledge-base,context:{ticketId:"T2024001",...}）。这意味着即使服务重启，未完成的工单流程也能自动续跑——这是 LangGraph 在无外部存储时无法做到的。

• 能力层（Capability Layer）：提供原子能力封装，包括 RAG 检索服务、LLM 接入适配器、规则引擎、文档解析器、向量数据库客户端等。关键设计是能力即服务（Capability-as-a-Service）：每个能力对外暴露标准 REST 接口（如/rag/retrieve），内部可自由替换实现（Elasticsearch/KNN 插件 or PGVector or Milvus），上层编排层只认接口契约，不关心具体技术。这种设计让我们在某次压测中发现 PGVector 性能瓶颈后，仅用 2 小时就将 RAG 后端无缝切换为 Elasticsearch + dense vector plugin，零代码修改上层逻辑。

• 数据层（Data Layer）：采用多模态存储策略。原始文档存 MinIO（兼容 S3 协议），元数据与向量化结果存 PostgreSQL（含pgvector扩展），实时日志与 trace 存 Loki + Grafana，工作流状态存 Redis（主从+哨兵），审计日志存 Elasticsearch。特别说明：我们没有用 MongoDB 存文档，因为其事务支持弱、JSON Schema 约束松散，不符合金融/政务类客户对数据一致性的硬性要求。

2.2 关键技术选型背后的“血泪教训”

• 放弃 LangChain/LangGraph 的根本原因：不是它们不好，而是它们的设计哲学与企业级交付目标存在结构性冲突。LangChain 是“开发者友好型框架”，强调快速组合、灵活调试；而企业级系统是“运维友好型服务”，强调可预测性、可观测性、可审计性。举个真实案例：某次上线后发现 LLM 调用耗时突增 300%，排查发现是 LangChain 的ConversationBufferMemory在高并发下因共享messages列表引发锁竞争，但该类问题在 LangChain 源码中属于“隐式状态管理”，没有明确的线程安全契约，导致定位耗时 17 小时。而我们的LLMAdapter接口强制要求每个execute()调用必须传入独立的ExecutionContext，天然规避状态污染。

• 为什么选 Java 21 虚拟线程而非 Kotlin Coroutines：Kotlin 协程生态在 Spring 中支持尚不完善（尤其 WebFlux 与 R2DBC 的深度集成仍有坑），且协程的调试体验远不如虚拟线程直观。更重要的是，虚拟线程是 JVM 层面的原生支持，jstack可直接看到VirtualThread[#123]/runnable，而协程堆栈是层层封装的Continuation对象，SRE 团队看不懂。我们做过对比测试：相同 RAG 检索任务（PDF 解析 + 向量检索 + LLM 重排），在 500 并发下，虚拟线程方案平均延迟 420ms，Kotlin 协程方案 680ms，且后者 GC 压力高 35%。

• Spring Boot 3 的“强制升级”价值：很多人抱怨 SB3 升级麻烦，但我们发现其带来的收益远超成本。第一，spring-boot-starter-validation默认启用 Jakarta Bean Validation 3.0，让我们能用@NotBlank、@Size(max=500)等注解直接校验用户输入的 RAG 查询语句，避免无效请求穿透到向量库；第二，spring-boot-starter-actuator的/actuator/metrics端点原生支持 Micrometer 1.11+，可一键采集每个智能体节点的execution.time.max、execution.count、error.rate，无需额外埋点；第三，SB3 的spring-boot-maven-plugin生成的 fat jar 默认启用--enable-preview，让虚拟线程特性开箱即用，省去运维手动加 JVM 参数的麻烦。

提示：不要为了“用新技术”而用新技术。我们评估过 Quarkus 和 Micronaut，最终放弃是因为其生态对 Spring 生态（如 Spring Security、Spring Data JPA）的兼容性不足，而现有团队 80% 的技能栈都在 Spring 上。技术选型的第一原则是“降低团队认知负荷”，而不是“技术先进性”。

3. 核心模块实现详解：RAG 知识库构建与智能体工作流引擎编码实录

3.1 RAG 知识库构建：从文档摄入到语义检索的全链路控制

企业级 RAG 的最大痛点不是“检不检索得到”，而是“检出来的东西靠不靠谱”。我们的解决方案是构建一个闭环可控的知识加工流水线，共分五步，每步均可配置、可监控、可回溯。

第一步：文档摄入（Ingestion）
不依赖第三方爬虫，而是提供三种标准接入方式：

• 文件系统监听：通过WatchService监听指定目录（如/data/kb/manuals/），新增 PDF/DOCX/XLSX 文件时触发解析；
• 数据库变更捕获：集成 Debezium，监听 MySQLkb_articles表的INSERT/UPDATE事件，自动提取title、content、category字段；
• API 主动推送：提供/ingest/pushREST 接口，支持 JSON 格式批量提交，字段包括source_id（唯一业务标识）、content_type（text/html/markdown）、raw_content（Base64 编码原文）。

关键设计：所有摄入请求必须携带ingestion_id（UUID），该 ID 将贯穿后续所有环节，用于全链路追踪。例如，当某份 PDF 解析失败时，可通过ingestion_id快速定位是 OCR 识别问题还是格式解析异常。

第二步：内容解析（Parsing）
针对不同格式采用专用解析器，全部实现为 Spring Bean：

• PdfBoxParser：基于 Apache PDFBox，重点解决扫描版 PDF 的 OCR 问题。我们集成 Tesseract 5.3，但做了关键优化——不全文 OCR，而是先用 PDFBox 提取文本坐标，仅对“文本密度低但图像占比高”的页面触发 OCR，速度提升 4.2 倍；
• Docx4jParser：解析 Word 文档时，保留原有标题层级（Heading 1/2/3），为后续“按章节分块”提供结构依据；
• HtmlParser：使用 Jsoup 清洗 HTML，移除<script>、<style>标签，但保留<h1>~<h6>标签语义，确保知识库能理解“这是产品功能介绍”而非“一堆杂乱文字”。

第三步：语义分块（Chunking）
这是 RAG 效果的分水岭。我们摒弃简单的“固定长度切分”，提供四种策略并支持运行时切换：

• 按标题分块（Title-Based）：适用于手册、FAQ 类文档。利用解析器提取的标题层级，将每个h2及其子内容作为一个 Chunk，保证语义完整性；
• 按表格分块（Table-Based）：检测到<table>标签时，将整个表格及其前后 2 行文本作为独立 Chunk，避免表格被截断导致信息丢失；
• 按代码段分块（Code-Based）：对pre或code标签内容，单独提取为 Chunk，并标记language:java/python，便于后续检索时加权；
• 滑动窗口分块（Sliding Window）：对纯文本（如会议纪要），采用 512 token 窗口 + 128 token 重叠，平衡召回率与精度。

所有分块逻辑封装在ChunkingStrategy接口下，通过@Qualifier注入，配置文件中指定kb.type: manuals时自动选用TitleBasedStrategy。

第四步：向量化与索引（Embedding & Indexing）
向量模型选用 BGE-M3（中文场景 SOTA），但关键创新在于动态嵌入缓存：

• 首次向量化时，将chunk_id+embedding_vector存入 Redis，设置 TTL 7 天；
• 后续相同chunk_id的请求，直接从 Redis 读取，避免重复调用大模型 API；
• 当检测到文档更新（ingestion_id变更），自动失效对应chunk_id的缓存。

向量库选用 PostgreSQL +pgvector，因其与业务数据库同源，简化运维。建表语句关键点：

CREATE TABLE kb_chunks ( id SERIAL PRIMARY KEY, ingestion_id UUID NOT NULL, source_id VARCHAR(100) NOT NULL, -- 业务唯一标识 content TEXT NOT NULL, embedding VECTOR(1024), -- BGE-M3 输出维度 chunk_type VARCHAR(20) CHECK (chunk_type IN ('title','table','code','text')), created_at TIMESTAMP DEFAULT NOW() ); CREATE INDEX ON kb_chunks USING IVFFLAT (embedding vector_cosine_ops) WITH (lists = 100);

IVFFLAT索引比HNSW更适合写多读少的企业知识库场景，且lists=100是我们压测得出的最优值（召回率 92.3%，P95 延迟 18ms）。

第五步：混合检索（Hybrid Retrieval）
不只依赖向量相似度，而是融合三种信号：

• 向量相似度（Vector Score）：cosine_similarity(embedding, query_embedding)；
• 关键词匹配度（BM25 Score）：在 PostgreSQL 中启用tsvector，对content字段建立全文索引，计算ts_rank_cd(to_tsvector('chinese', content), to_tsquery('chinese', '查询词'))；
• 元数据权重（Metadata Weight）：根据chunk_type动态加权，如table类型 Chunk 的权重设为 1.5，code类型为 1.3，text类型为 1.0。

最终得分公式：final_score = 0.5 * vector_score + 0.3 * bm25_score + 0.2 * metadata_weight。该公式在 12 个业务知识库上 A/B 测试，相比纯向量检索，准确率提升 27.6%，且 Top3 结果中至少 1 个为表格或代码的概率达 89%。

3.2 智能体工作流引擎：从 DSL 解析到状态持久化的完整实现

引擎核心是WorkflowEngine类，其生命周期管理严格遵循 Spring Bean 规范。以下是关键代码片段及设计意图：

DSL 解析器（YamlWorkflowDefinitionParser）

public class YamlWorkflowDefinitionParser { public WorkflowDefinition parse(String yamlContent) { // 使用 SnakeYAML 解析，但关键点：禁用动态类型加载 // 防止恶意 YAML 注入执行任意代码（曾有客户反馈此风险） Yaml yaml = new Yaml(new SafeConstructor()); Map<String, Object> map = yaml.load(yamlContent); WorkflowDefinition def = new WorkflowDefinition(); def.setId((String) map.get("id")); def.setInitialState((String) map.get("initial")); List<Map<String, Object>> states = (List<Map<String, Object>>) map.get("states"); for (Map<String, Object> stateMap : states) { StateConfig config = new StateConfig(); config.setId((String) stateMap.get("id")); config.setType((String) stateMap.get("type")); // action / choice / end // 关键：Bean 名称必须来自白名单，防止反射调用任意类 String beanName = (String) stateMap.get("bean"); if (!ALLOWED_BEAN_NAMES.contains(beanName)) { throw new IllegalArgumentException("Illegal bean name: " + beanName); } config.setBeanName(beanName); // 解析 transition 映射 Map<String, Object> transition = (Map<String, Object>) stateMap.get("transition"); config.setTransitions(transition); def.addState(config); } return def; } }

注意：ALLOWED_BEAN_NAMES是硬编码的白名单（如"ragRetrieverNode","llmReRankerNode"），杜绝 YAML 中通过!!java.lang.Class等方式触发任意类加载，这是企业安全审计的硬性要求。

状态机配置（WorkflowStateMachineConfiguration）

@Configuration @EnableStateMachineFactory public class WorkflowStateMachineConfiguration extends StateMachineConfigurerAdapter<String, String> { @Override public void configure(StateMachineConfigurationConfigurer<String, String> config) throws Exception { config .withConfiguration() .autoStartup(false) // 禁用自动启动，由 WorkflowEngine 控制 .listener(stateMachineListener()); // 注入自定义监听器 } @Override public void configure(StateMachineTransitionConfigurer<String, String> transitions) throws Exception { // 此处不硬编码 transition，而是由 WorkflowEngine 动态注册 // 基于 DSL 解析结果，在运行时调用 transitions.withExternal() 构建 } @Bean public StateMachineListener<String, String> stateMachineListener() { return new WorkflowStateMachineListener(); // 记录状态变更到审计日志 } }

状态持久化（RedisWorkflowRepository）

@Repository public class RedisWorkflowRepository { private final RedisTemplate<String, Object> redisTemplate; public void saveInstanceState(String workflowId, String instanceId, String currentState, Map<String, Object> context) { String key = "workflow:state:" + workflowId + ":" + instanceId; HashOperations<String, String, Object> hashOps = redisTemplate.opsForHash(); // 存储当前状态 hashOps.put(key, "state", currentState); // 存储上下文（JSON 序列化，但关键字段如 ticketId 单独存，便于 Lua 脚本原子操作） hashOps.put(key, "context", objectMapper.writeValueAsString(context)); // 存储时间戳，用于超时清理 hashOps.put(key, "updated_at", String.valueOf(System.currentTimeMillis())); // 设置过期时间：30 分钟（业务最长流程耗时） redisTemplate.expire(key, Duration.ofMinutes(30)); } public WorkflowInstance loadInstanceState(String workflowId, String instanceId) { String key = "workflow:state:" + workflowId + ":" + instanceId; HashOperations<String, String, Object> hashOps = redisTemplate.opsForHash(); Map<Object, Object> entries = hashOps.entries(key); if (entries.isEmpty()) return null; WorkflowInstance instance = new WorkflowInstance(); instance.setWorkflowId(workflowId); instance.setInstanceId(instanceId); instance.setCurrentState((String) entries.get("state")); instance.setContext(objectMapper.readValue( (String) entries.get("context"), Map.class)); return instance; } }

实操心得：Redis 存储状态时，我们刻意将context作为整体 JSON 存储，而非拆成多个 field，是因为业务上下文结构复杂（可能嵌套 Map/List），拆分会导致 Lua 脚本维护成本爆炸。但ticketId等高频查询字段，我们会额外存一个workflow:ticket:xxx的 key 指向instanceId，实现 O(1) 反查。

4. 实战部署与性能调优：从本地开发到 K8s 生产环境的全流程踩坑记录

4.1 本地开发环境搭建：5 分钟启动可调试的全链路

很多团队卡在“本地跑不起来”，根源在于环境依赖太重。我们的方案是用 Docker Compose 封装所有依赖，但保持应用代码可热部署：

# docker-compose.yml version: '3.8' services: postgres: image: postgres:15 environment: POSTGRES_DB: rag_engine POSTGRES_PASSWORD: password volumes: - ./postgres-data:/var/lib/postgresql/data ports: - "5432:5432" redis: image: redis:7-alpine command: redis-server --save 60 1 --loglevel warning ports: - "6379:6379" minio: image: minio/minio:latest command: server /data --console-address ":9001" environment: MINIO_ROOT_USER: minioadmin MINIO_ROOT_PASSWORD: minioadmin volumes: - ./minio-data:/data ports: - "9000:9000" - "9001:9001" # 注意：不启动应用服务，留给 IDE 运行

开发者只需：

1. docker-compose up -d启动依赖；
2. 在 IDEA 中配置 Spring Boot 启动项，JVM 参数添加-Dspring.profiles.active=dev；
3. 关键技巧：在application-dev.yml中配置spring.devtools.restart.additional-paths=src/main/resources/workflows/，这样修改 YAML 工作流定义后，IDEA 会自动触发 Spring Boot DevTools 重启，无需手动 stop/start。

我们实测，从拉取代码到首次成功调用curl -X POST http://localhost:8080/agent/ticket-initial-screening，平均耗时 4 分 32 秒，其中 3 分钟是等待 MinIO 初始化，真正开发时间不到 2 分钟。

4.2 K8s 生产部署：资源申请、HPA 策略与 JVM 调优黄金参数

生产环境采用 Kubernetes，但配置绝非简单套用模板。以下是经过 3 个客户集群验证的黄金参数：

Deployment 配置要点

apiVersion: apps/v1 kind: Deployment metadata: name: rag-engine spec: replicas: 3 template: spec: containers: - name: app image: registry.example.com/rag-engine:1.2.0 # 关键：资源限制必须精确，避免 OOMKilled resources: requests: memory: "2Gi" # JVM 初始堆大小 cpu: "1000m" # 保证 1 核 CPU limits: memory: "4Gi" # JVM 最大堆大小 cpu: "2000m" # 防止 CPU 被抢占 # JVM 参数：针对虚拟线程优化 env: - name: JAVA_TOOL_OPTIONS value: >- -Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+UseVirtualThreads -Dfile.encoding=UTF-8 # 就绪探针：检查工作流引擎是否初始化完成 readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 60 periodSeconds: 10 # 存活探针：检查 JVM 是否假死 livenessProbe: exec: command: ["sh", "-c", "jcmd | grep 'rag-engine' || exit 1"] initialDelaySeconds: 120 periodSeconds: 30

Horizontal Pod Autoscaler（HPA）策略
不采用 CPU/Memory 指标，因为 RAG 负载具有突发性（如月结时大量查询），CPU 使用率可能滞后。我们自定义指标：

• 核心指标：http_server_requests_seconds_count{application="rag-engine", status=~"5.."} > 10（5xx 错误率）；
• 辅助指标：jvm_memory_used_bytes{area="heap"}（堆内存使用率 > 85%）；
• 扩缩容逻辑：当 5xx 错误率连续 3 分钟 > 10%，或堆内存使用率连续 5 分钟 > 85%，触发扩容；当两项指标连续 10 分钟低于阈值，触发缩容。

该策略在某银行客户上线后，成功将月结高峰期间的 P95 延迟从 2.1s 降至 680ms，且避免了“虚假扩容”（因瞬时 CPU 高而扩容，实际是 GC 导致）。

JVM 虚拟线程调优实录
虚拟线程不是“开了就赢”，必须配合 G1 GC 调优：

• -XX:MaxGCPauseMillis=200：G1 的目标停顿时间，必须设为 200ms，因为 RAG 检索+LLM 调用的总耗时目标是 800ms，GC 不能占大头；
• -XX:+UseStringDeduplication：对 RAG 返回的大量重复文本（如“根据《XX管理办法》第X条”）进行字符串去重，实测减少堆内存占用 12%；
• -XX:ActiveProcessorCount=2：显式告诉 JVM 容器内只有 2 个可用 CPU，避免虚拟线程调度器过度创建线程。我们曾因忽略此参数，在 4C 机器上虚拟线程数飙升至 10 万+，导致调度开销剧增。

注意事项：不要在生产环境用-XX:+PrintGCDetails，日志量太大。改用jstat -gc <pid>实时观察，重点关注G1-YGC（年轻代 GC 次数）和G1-OGCMN（老年代最小容量）。我们设定的告警阈值是：G1-YGC每分钟 > 50 次，或G1-OGCMN持续增长，即触发内存泄漏排查。

4.3 全链路监控与问题定位：如何 5 分钟内定位一次 RAG 响应超时

没有监控的 AI 系统等于裸奔。我们构建了三层监控体系：

第一层：基础设施监控（Prometheus + Grafana）
采集节点级指标：CPU、内存、网络 IO、磁盘 IO。关键看板：

• Redis 连接池饱和度：redis_connected_clients / redis_maxclients> 80% 时告警，说明工作流状态查询压力过大；
• PostgreSQL 连接数：pg_stat_activity_count> 90% 时告警，RAG 检索可能阻塞；
• MinIO 请求延迟 P99：minio_bucket_operation_latency_seconds{bucket="kb-docs",quantile="0.99"}> 2s 时告警，文档摄入环节出问题。

第二层：应用性能监控（Micrometer + Prometheus）
Spring Boot Actuator 原生支持，我们重点暴露：

• http_server_requests_seconds_count{uri="/agent/{id}",status="200"}：各智能体调用次数；
• workflow_node_execution_seconds_sum{node="ragRetrieverNode",status="success"}：各节点执行耗时总和；
• rag_retrieval_results_count{index="it-service-faq",top_k="3"}：各知识库检索返回结果数。

关键技巧：在@Timed注解中添加percentiles={0.5,0.95,0.99}，直接暴露 P50/P95/P99，无需 Grafana 计算。

第三层：分布式追踪（OpenTelemetry + Jaeger）
这是定位 RAG 超时的终极武器。一次典型调用链路包含：

1. Gateway 接收请求 → 2. WorkflowEngine 创建实例 → 3. ragRetrieverNode 调用 PostgreSQL → 4. llmReRankerNode 调用 LLM API → 5. generateAnswerNode 生成最终响应。

当发现某次调用耗时 3.2s（超时），进入 Jaeger 查看 Trace：

• 发现ragRetrieverNode耗时 2.8s，其中PostgreSQL Query子 Span 耗时 2.7s；
• 点击该 Span，查看 SQL：SELECT * FROM kb_chunks WHERE ... ORDER BY embedding <=> $1 LIMIT 3；
• 进入 PostgreSQL，执行EXPLAIN ANALYZE，发现IVFFLAT索引未命中，正在全表扫描；
• 原因：lists=100参数在数据量增长后已不适用，需调整为lists=500。

整个过程从告警到根因定位，平均耗时 4 分 17 秒。没有分布式追踪，这类问题至少需要 2 小时。

5. 常见问题与避坑指南：那些只有踩过才懂的“幽灵 Bug”

5.1 RAG 相关高频问题速查表

5.2 智能体工作流引擎典型故障与修复

故障一：“工作流卡在某个节点不动”
现象：Jaeger 中看到ragRetrieverNode的 Span 状态为RUNNING，但无结束时间，且 Redis 中对应workflow:state:xxx的updated_at时间停滞。
排查思路：

1. 检查ragRetrieverNode的日志，发现Connection refused错误；
2. 登录 PostgreSQL，执行SELECT * FROM pg_stat_activity WHERE state = 'active';，发现连接数已达max_connections=100上限；
3. 追查源头：ragRetrieverNode使用了JdbcTemplate，但未配置连接池最大值，默认为Integer.MAX_VALUE，导致瞬间创建数百连接。
   修复：在application.yml中显式配置：

spring: datasource: hikari: maximum-pool-size: 20 # 严格限制 connection-timeout: 30000

并增加熔断机制：当HikariPool-1 - Connection is not available日志出现 3 次/分钟，自动触发WorkflowEngine的降级模式（跳过 RAG，直接走规则引擎）。

故障二：“同一工单被处理两次”
现象：CRM 系统收到两条重复的报价单生成请求。
根因：WorkflowEngine的幂等性设计缺陷。初始版本仅用ingestion_id作为幂等 Key，但工单系统在重试时会生成新的ingestion_id。
修复：引入业务级幂等 Key。在ticket-initial-screening工作流的parse-ticket节点中，从工单 JSON 中提取ticket_number字段，作为 Redis 的幂等 Key：

String idempotentKey = "idempotent:ticket:" + ticketNumber; Boolean isExist = redisTemplate.opsForValue().setIfAbsent(idempotentKey, "1", Duration.ofMinutes(30)); if (!isExist) { throw new IdempotentException("Ticket " + ticketNumber + " is being processed"); }

同时