企业官网建设流程全解析

1. 这不是又一个“Hello World”式RAG教程，而是我在真实交付项目里反复重装、调参、推翻重来的血泪笔记

Spring AI + RAG 实战——光看标题，你可能以为又是那种“三步跑通demo、五步调出结果、十分钟学会”的速成课。但我要先说清楚：这篇内容不讲概念定义，不画抽象架构图，不堆砌API文档截图。它是我过去8个月在三个不同行业客户现场（制造业设备知识库、金融合规文档助手、医疗器械说明书问答系统）落地Spring AI+RAG时，亲手拆过、调过、崩过、修过的完整过程复盘。核心关键词就五个：Spring AI、RAG、知识库问答系统、分块调优、踩坑——每一个词背后，都对应着至少一次凌晨三点的服务器日志排查，或一次被业务方指着PPT问“为什么搜不到第7页PDF里的那句话”的尴尬。

我见过太多人卡在第一步：用Spring AI官方示例跑通了，一上真实文档就返回“未找到相关信息”；也见过团队花两周搭完框架，结果用户上传一份200页的PDF手册，系统响应时间飙到12秒，准确率还不到40%。问题从来不在“会不会用”，而在于对RAG底层数据流的理解偏差——你以为Embedding模型只负责把文本变向量，其实它在悄悄过滤语义；你以为Chunking只是切段落，其实它在决定模型“能看到什么”；你以为Retriever只是查数据库，其实它在和LLM共谋一场语义幻觉。这篇内容要做的，就是把这层窗户纸捅破：告诉你每个环节的真实作用域、可调节杠杆、以及那些官网文档绝不会写的“隐性约束”。

适合谁读？如果你正准备用Spring Boot快速集成AI能力，手头有几十份PDF/Word/Excel格式的业务文档，想让非技术人员也能自然语言提问并获得精准答案——那你不是在学技术，是在建一个“数字员工”。这篇文章就是为你写的。它不假设你懂LangChain或LlamaIndex，但要求你熟悉Spring Boot基础配置；它不回避Java生态的复杂性，但会把每一步依赖冲突、版本兼容、线程安全问题摊开讲透。接下来所有内容，都来自生产环境的真实日志、压测报告、用户反馈录音转文字稿——没有虚构场景，没有理想化假设，只有可验证、可复现、可归因的操作路径。

2. 为什么必须放弃“LangChain式思维”，转向Spring AI原生RAG设计

2.1 Spring AI不是LangChain的Java移植版，而是重新定义了RAG的职责边界

很多从Python生态转过来的开发者，第一反应是：“Spring AI是不是LangChain for Java？”——这个认知偏差，直接导致后续所有架构决策失误。我拿一个真实案例说明：某制造企业需要解析设备维修手册（含大量表格、流程图标注、故障代码对照表），团队按LangChain习惯，先用UnstructuredIO解析PDF，再用RecursiveCharacterTextSplitter切块，最后丢给ChromaDB存向量。结果上线后，用户问“E307错误码对应哪个传感器”，系统返回三页无关的液压系统维护步骤。排查发现：UnstructuredIO把表格识别成纯文本，切块时把“E307→温度传感器A”这行关键映射，硬生生切到了两个chunk里，检索时只匹配到“E307”或“温度传感器”，语义断裂。

Spring AI的设计哲学完全不同。它把文档解析、分块策略、向量存储、检索逻辑全部解耦为可插拔组件，且强制要求每个环节明确声明其语义保真度。比如它的DocumentReader接口，不接受“把PDF转成字符串”这种模糊实现，而是要求你实现read(InputStream input)方法，并在注释中声明该实现是否保留表格结构、是否处理页眉页脚、是否提取图像OCR文本。这种设计看似繁琐，实则堵死了语义流失的第一道缺口。我们最终采用的是自定义PdfBoxDocumentReader，它调用PDFBox的PDFTextStripper时启用setShouldSeparateByBeads(false)，并重写writeString方法，对检测到的表格区域插入<table>标记——这样后续分块器就能识别结构化内容，避免跨行切割。

提示：Spring AI 1.0.0-M3起，DocumentReader已支持SPI机制。不要自己写死实现类，把你的PdfBoxDocumentReader打成jar包，放在META-INF/services/org.springframework.ai.document.DocumentReader文件里，Spring Boot启动时自动加载。这是避免版本升级时手动改配置的关键技巧。

2.2 RAG不是“检索+生成”，而是“检索约束下的可控生成”

另一个致命误区，是把RAG当成两阶段流水线：先让Retriever找几个相似chunk，再让LLM基于这些chunk回答问题。但在Spring AI里，Retriever返回的不是文本片段，而是Document对象集合，每个对象携带metadata、score、content三元组。这意味着你可以用metadata做业务规则过滤——比如维修手册里，不同设备型号的章节需隔离检索，我们就在解析时给每个Document打上model: "XG-5000"标签，Retriever配置里加filter: "model:'${user.model}'"，彻底规避跨型号误检。

更关键的是，Spring AI的ChatClient调用时，传入的不是原始prompt，而是ChatRequest对象。其中options字段支持设置temperature=0.1（抑制发散）、maxTokens=256（防超长截断）、甚至stopSequences=["\n\n"]（强制在段落结束处停）。我们曾遇到LLM把检索到的“更换轴承步骤”续写成“建议搭配使用本厂润滑油”，而实际文档里根本没提润滑油——这就是因为没设stopSequences，模型自由发挥过度。现在所有生产环境请求都强制配置stopSequences=["。", "！", "？", "\n"]，确保输出严格限定在检索内容范围内。

2.3 知识库问答系统的本质，是构建“可验证的语义索引”

很多人纠结“该用Chroma还是Milvus”，却忽略了一个事实：向量数据库只是索引载体，真正的知识库质量，取决于文档预处理链路的语义保真度。我们做过对比实验：同一份《GB/T 19001-2016 质量管理体系要求》PDF，在三种预处理方案下，用相同Embedding模型（BGE-M3）生成向量，再测试“设计和开发策划应包括哪些活动？”这个问题的Top3召回率：

结论很残酷：选再快的向量库，也救不了烂的预处理。Spring AI的价值，正在于它把预处理链路标准化——DocumentReader→DocumentTransformer→VectorStore形成清晰责任链，每个环节可单独压测、可灰度发布、可AB测试。我们现在的CI/CD流程里，新增一个文档类型，必须提交三份报告：1）Reader解析效果截图（重点看表格/公式/页眉）；2）Transformer切块后的chunk长度分布直方图；3）VectorStore入库后的平均cosine相似度（应>0.85）。没这三份报告，代码不允许合入主干。

3. 分块调优：不是调参数，而是重建文档语义骨架

3.1 别再迷信“512字符”魔咒，Chunk Size必须按业务实体动态计算

网上教程千篇一律教“用RecursiveCharacterTextSplitter，chunkSize=512，chunkOverlap=50”。但在真实业务文档里，这等于把手术刀当菜刀使。我拿医疗设备说明书举例：一份呼吸机操作指南，包含“安全警告”“操作步骤”“故障排除”“技术参数”四大模块。其中“安全警告”每条独立成段，平均80字；“技术参数”是表格，每行含型号、流量范围、噪音值等字段，平均120字；而“操作步骤”是带编号的流程，每步300-500字。如果统一用512切块，会出现什么？

• 安全警告被强行合并：把“禁止在易燃环境使用”和“请定期校准传感器”塞进同一chunk，检索“易燃环境”时，返回结果里混着校准提醒，干扰用户判断；
• 技术参数表格被撕裂：流量范围和噪音值分属两个chunk，用户问“XX型号的最大噪音是多少”，系统只能返回“流量范围：20-80L/min”，关键字段丢失；
• 操作步骤被截断：第3步“连接氧气管路”和第4步“开启主机电源”被切开，LLM看到不完整的动作链，生成“先开机再接管路”的错误指令。

我们的解决方案是：为每种文档类型定义专属分块策略。Spring AI的DocumentTransformer接口支持链式调用，我们实现SectionAwareSplitter：

public class SectionAwareSplitter implements DocumentTransformer { @Override public List<Document> transform(List<Document> documents) { return documents.stream() .flatMap(doc -> { String content = doc.getContent(); // 按四级标题分割：#### 安全警告 → #### 故障排除 String[] sections = content.split("(?=\n#### )"); return Arrays.stream(sections) .filter(s -> !s.trim().isEmpty()) .map(section -> { // 每个section内，再按换行符切最小语义单元 String[] lines = section.split("\n"); return Arrays.stream(lines) .filter(line -> line.trim().length() > 10) // 过滤空行和短标题 .map(line -> new Document(line, Map.of("section", extractSectionTitle(section), "doc_id", doc.getMetadata().get("id")))) .collect(Collectors.toList()); }) .flatMap(Collection::stream); }) .collect(Collectors.toList()); } }

这个transformer先按语义区块（####标题）粗分，再在区块内按行细分，确保每个Document对应一个原子业务单元。上线后，“故障代码E307”的检索准确率从61%提升到94%，因为每个故障代码描述现在都是独立Document，不再受邻近内容干扰。

3.2 Chunk Overlap不是防信息割裂，而是建语义缓冲区

几乎所有教程都说“overlap=50是为了防止句子被切断”。错。在Spring AI里，overlap的真实作用是为Embedding模型提供上下文锚点。BGE-M3这类多语言模型，对孤立短句的编码能力很弱——“温度传感器A”单独embedding，和“E307错误码对应温度传感器A”一起embedding，向量距离能差0.3以上。我们的压测数据显示：当overlap从0增加到100时，跨chunk语义关联召回率提升27%，但计算耗时只增12%。关键是要让overlap内容有意义。

我们废弃了随机取前N字符的overlap方式，改为提取当前chunk的实体关键词，向前追溯至包含该实体的最近完整句。例如chunk开头是“...校准周期为12个月。每次校准需使用标准气体...”，实体关键词是“校准周期”，那么overlap就取“校准周期为12个月”整句，而不是硬截50字符。实现上，用OpenNLP的SentenceDetector定位句子边界，再用正则匹配实体。这样overlap不再是冗余信息，而是语义锚定句，让向量空间里“校准周期”和“标准气体”天然靠近。

注意：Spring AI的VectorStore默认对Document做去重。如果你的overlap导致相邻chunk内容高度相似，入库时会被合并！必须在VectorStore配置里设deduplicationStrategy: NONE，并在Document的metadata里加chunk_index: 123唯一标识，否则检索时根本不知道返回的是哪个chunk。

3.3 元数据不是附加信息，而是检索的第二维度

新手常把metadata当备注字段，只存source: "manual.pdf"。但在高精度问答场景，metadata是救命稻草。我们给每个Document打7类metadata：

这些metadata全部参与向量检索的filter条件。比如用户问“最新版手册里关于E307的处理方式”，Retriever的query变成：

{ "filter": "doc_type == 'troubleshooting' && entity_list contains 'E307' && update_timestamp > '2024-01-01'", "topK": 3 }

这比单纯靠向量相似度排序可靠得多。我们甚至用metadata实现了“版本感知RAG”：当用户没指定版本时，自动取update_timestamp最新的3个Document；当用户说“对比V2.1和V3.0”，则分别检索两个时间范围的文档，让LLM做差异分析。

4. 实操全流程：从空项目到生产可用的12个关键节点

4.1 环境准备：Spring Boot 3.2+JDK17是唯一安全组合

别信“Spring Boot 2.7也能跑Spring AI”的说法。我们踩过最深的坑，就是用SB2.7+Spring AI 0.8.0，结果ChatClient调用时抛NoSuchMethodError: org.springframework.ai.chat.ChatClient.create()。根源是Spring AI 0.8.0依赖spring-boot-starter-webflux3.2.0，而SB2.7自带的是2.7.x版本，Reactor API不兼容。官方文档小字写着“推荐SB3.2+”，但没人告诉你不满足会怎样。

正确姿势：

<!-- pom.xml --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> <!-- 必须≥3.2.0 --> <relativePath/> </parent> <properties> <java.version>17</java.version> <!-- JDK17是硬性要求 --> <spring-ai.version>1.0.0-M3</spring-ai.version> </properties>

JDK17不是可选项。Spring AI的Document类用record语法定义，JDK11不支持；其异步流处理依赖CompletableFuture的orTimeout()方法，JDK17才引入。我们试过JDK11+SB3.2，编译通过但运行时报UnsupportedClassVersionError——因为Spring AI的jar包编译目标是17。

实操心得：创建新项目时，直接用 start.spring.io ，选Spring Boot 3.2.5、Java 17、Dependencies加Spring Web、Spring AI、Spring Data Redis（用于缓存检索结果）。不要手动改pom，版本锁死是避免依赖地狱的唯一办法。

4.2 文档解析：PDFBox+Apache Tika双引擎才是工业级方案

只用PDFBox解析PDF？你会丢失所有表格和图像。只用Tika？它对中文排版支持极差，经常把“第3章”识别成“第 3 章”（多空格）。我们的生产方案是：PDFBox做结构解析，Tika做内容增强。

public class HybridPdfReader implements DocumentReader { private final PdfBoxDocumentReader pdfBoxReader; private final TikaDocumentReader tikaReader; @Override public List<Document> read(InputStream input) throws IOException { // 第一步：PDFBox提取文本+坐标+表格结构 List<Document> baseDocs = pdfBoxReader.read(input); // 第二步：对baseDocs中content为空的Document（即图片/图表），用Tika提取OCR文本 for (Document doc : baseDocs) { if (doc.getContent().trim().isEmpty() && "image".equals(doc.getMetadata().get("type"))) { String ocrText = tikaReader.extractOcrText( (byte[]) doc.getMetadata().get("raw_bytes")); doc = new Document(ocrText, doc.getMetadata()); } } return baseDocs; } }

关键细节：PDFBox的PDFTextStripper必须设setSortByPosition(true)，否则多栏排版会乱序；Tika的OCR需集成Tesseract，且中文模型tessdata必须放在src/main/resources/tessdata下，否则启动报Error opening data file。我们打包时用Maven Resources Plugin把tessdata复制到target/classes。

4.3 向量存储选型：ChromaDB本地够用，但必须关掉auto-delete

ChromaDB轻量、易部署，适合中小知识库。但它有个致命默认行为：persist_directory下，每次启动会清空旧collection，重载数据。我们在测试环境吃过亏——半夜自动重启后，整个知识库变空，用户第二天上班发现所有问答都返回“未找到相关信息”。

解决方案：在application.yml里显式禁用auto-delete：

spring: ai: vectorstore: chroma: url: http://localhost:8000 collection-name: manual_kb # 关键！禁用自动清理 reset: false

同时，ChromaDB的hnsw索引参数必须调优。默认ef_construction=100，对百万级向量检索慢。我们压测后设为：

chroma: hnsw: ef_construction: 200 m: 32

ef_construction越大，索引构建越慢但查询越快；m是每个节点的连接数，32是平衡点。实测10万文档下，QPS从8提升到22，P95延迟从1.2s降到0.38s。

4.4 Embedding模型：BGE-M3开源版足够，但必须量化部署

别被“千亿参数大模型”忽悠。BGE-M3（bge-m3）在中文长文本检索上，SOTA指标比text-embedding-3-large高3.2%，且免费。但它默认是FP16，显存占用1.8GB。我们用ONNX Runtime量化到INT8：

# export_bge_m3.py from transformers import AutoTokenizer, AutoModel import onnxruntime as ort from optimum.onnxruntime import ORTModelForFeatureExtraction model = AutoModel.from_pretrained("BAAI/bge-m3") tokenizer = AutoTokenizer.from_pretrained("BAAI/bge-m3") ort_model = ORTModelForFeatureExtraction.from_pretrained( model, tokenizer, export=True, provider="CUDAExecutionProvider" # GPU加速 ) ort_model.save_pretrained("./bge-m3-int8")

量化后显存降至0.6GB，推理速度提升2.3倍。Spring AI调用时，配置：

spring: ai: embedding: bge-m3: model-name: "bge-m3-int8" base-url: "http://localhost:8001/embeddings"

注意：ONNX模型服务必须用FastAPI+Uvicorn部署，端口8001，且/embeddings接口要符合OpenAI格式（接收input数组，返回data[].embedding）。

4.5 检索增强：Hybrid Search不是噱头，而是解决长尾问题的刚需

纯向量检索在专业文档里，对“缩写词”“代号”“故障码”召回率极低。比如用户搜“E307”，向量检索可能返回“E305”“E309”等相似编码，但漏掉真正的E307条目。我们的方案是：向量检索+关键词检索双通道融合。

Spring AI的Retriever支持MultiRetriever：

@Bean public Retriever<Document> hybridRetriever(VectorStore vectorStore, KeywordRetriever keywordRetriever) { return MultiRetriever.builder() .retriever(vectorStore.asRetriever()) // 向量检索 .retriever(keywordRetriever) // 关键词检索（基于Lucene） .build(); }

KeywordRetriever用Lucene实现，对Document.content建倒排索引。关键优化点：对metadata里的entity_list字段单独建索引，用户搜“E307”时，优先命中entity_list含E307的Document，再用向量排序。实测长尾查询召回率从54%提升到89%。

4.6 Prompt工程：不是写提示词，而是设计LLM的思考路径

别再写“你是一个 helpful assistant...”这种废话。Spring AI的ChatClient支持PromptTemplate，我们要做的是把业务逻辑编译进prompt。例如故障排除场景，prompt模板：

你是一名资深设备工程师，正在根据以下维修手册内容回答用户问题。 【检索到的手册内容】 {{retrievedDocuments}} 【用户问题】 {{userQuestion}} 【回答要求】 1. 仅基于【检索到的手册内容】回答，禁止编造信息； 2. 若内容中含步骤编号（如“1.”“2.”），严格按编号顺序输出； 3. 若涉及安全警告，必须以“⚠️警告：”开头； 4. 若未找到直接答案，回复“手册中未提及此问题，请联系技术支持”。

这个模板把4条业务规则硬编码进去。我们甚至用FreeMarkerTemplateEngine动态注入：当doc_type=="safety_warning"时，自动加⚠️警告：前缀；当is_table_cell==true时，用表格格式输出。LLM不是在自由创作，是在执行确定性指令。

4.7 缓存策略：Redis不只是存结果，而是存“检索意图”

单纯缓存question→answer？用户问“E307怎么处理”，缓存答案；再问“E307错误码对应什么”，因question字符串不同，缓存失效。我们的方案是：缓存key基于语义指纹，而非原始question。

用MiniLM-L6量化模型，对question生成128维向量，再用Redis的HNSW模块做近似最近邻搜索：

// 生成question指纹 float[] questionEmbedding = miniLmEmbedder.embed(question); String fingerprint = Arrays.toString(questionEmbedding).hashCode() + ""; // 缓存结构：hash key=fingerprint, field=answer, value=answer_text redisTemplate.opsForHash().put("qa_cache", fingerprint, answer);

这样“E307怎么处理”和“E307错误码怎么办”会映射到同一fingerprint，缓存命中率从31%升到79%。更重要的是，fingerprint可复用：当用户连续问“E307怎么处理”“E307需要什么工具”，第二次检索时，直接复用第一次的retrievedDocuments，省去向量检索耗时。

4.8 监控告警：不看TPS，要看“语义漂移率”

传统监控看QPS、延迟、错误率。但RAG系统真正的健康指标是语义漂移率——即LLM回答与检索内容的语义偏离程度。我们用BERTScore计算：

double bertScore = BERTScore.compute( retrievedDoc.getContent(), // 检索到的原文 llmResponse.getText() // LLM生成的回答 ); if (bertScore < 0.65) { // 触发告警：语义漂移，可能检索失败或LLM幻觉 alertService.send("SemanticDriftAlert", "BERTScore=" + bertScore + ", question=" + question); }

BERTScore>0.85为优质，0.7-0.85为可接受，<0.7需人工审核。上线后，我们发现73%的低分回答，根源是检索返回了错误chunk——这比看“500错误率”更能定位RAG链路的真实瓶颈。

4.9 权限控制：不是RBAC，而是文档级访问策略

用户A能看设备手册，用户B只能看操作视频脚本。Spring AI本身不提供权限，但我们把权限逻辑注入Retriever：

@Bean public Retriever<Document> securedRetriever(VectorStore vectorStore, UserContext userContext) { return query -> { // 在检索前，动态添加filter String filter = "tenant_id == '" + userContext.getTenantId() + "'"; if ("engineer".equals(userContext.getRole())) { filter += " && doc_type != 'internal_notes'"; } return vectorStore.similaritySearch(query, 3, filter); }; }

UserContext从JWT token解析，tenant_id和role字段决定filter条件。这样同一套知识库，不同角色看到不同子集，无需建多个collection。

4.10 A/B测试：用Shadow Traffic验证新分块策略

上线新分块策略前，不能直接切流。我们用Spring Cloud Gateway做影子流量：

spring: cloud: gateway: routes: - id: rag-main uri: lb://rag-service predicates: - Path=/api/rag/** filters: - StripPrefix=1 - id: rag-shadow uri: lb://rag-service-shadow predicates: - Path=/api/rag/** - Header=X-Shadow-Enabled, true

用户请求带X-Shadow-Enabled:true头，流量同时发给主服务和影子服务。影子服务用新分块策略，但不返回结果，只记录question→retrievedDocuments→llmResponse全链路日志。一周收集10万条，对比新旧策略的BERTScore、人工评估准确率，达标后再全量切换。

4.11 回滚机制：不是删collection，而是版本化知识库

ChromaDB不支持collection版本管理。我们的方案是：每个知识库更新生成唯一versionId，存入MySQL。

CREATE TABLE kb_version ( id VARCHAR(36) PRIMARY KEY, kb_name VARCHAR(100), version VARCHAR(20), -- v20240501.1 status ENUM('active','inactive'), created_at TIMESTAMP );

VectorStore配置里，collection name动态拼接：manual_kb_v20240501.1。回滚时，只需更新kb_version表，把旧version设为active，新version设为inactive，重启服务即可。整个过程30秒内完成，零停机。

4.12 上线 checklist：12项必须验证的硬性指标

最后，这是我们在客户现场签署交付确认书前，必须逐项验证的清单：

少一项不签字。这不是技术洁癖，而是让知识库真正成为可信赖的生产力工具的前提。

5. 踩坑实录：那些让项目延期两周的“小问题”

5.1 PDFBox内存泄漏：不是OOM，而是DirectByteBuffer堆积

现象：系统运行24小时后，老年代内存持续增长，Full GC频繁，但heap dump里找不到大对象。最终定位到PDFBox的RandomAccessFile未关闭。PDFBox 3.0.3修复了此问题，但Spring AI 1.0.0-M3依赖的PDFBox是2.0.27。解决方案：升级PDFBox到3.0.3，并在PdfBoxDocumentReader里显式关闭：

try (PDDocument document = Loader.loadPDF(input)) { // ... processing } // 自动关闭

注意：必须用try-with-resources，不能只调document.close()，因为PDFBox内部用DirectByteBuffer，GC不回收。

5.2 ChromaDB连接池耗尽：不是并发高，而是Query未释放

现象：高并发时，ChromaDB报Connection refused，但netstat -an | grep 8000显示连接数只有10个。查ChromaDB日志，发现Too many open files。根源是Spring AI的ChromaVectorStore默认maxConnections=10，且Query执行后不主动close。解决方案：在application.yml里配：

spring: ai: vectorstore: chroma: max-connections: 50 connection-timeout: 5000

并确保每次检索后调用vectorStore.close()——但这违反Spring Bean生命周期。最终方案：用@Scope("prototype")声明VectorStore，每次@Autowired都新建实例，用完由Spring容器自动销毁。

5.3 BERTScore计算阻塞：不是模型慢，而是线程饥饿

现象：BERTScore计算耗时2秒，拖慢整个请求。查线程dump，发现ForkJoinPool.commonPool-worker-1线程占满。原因是BERTScore默认用ForkJoinPool并行计算，但Spring Boot的WebMvc默认线程池只有200线程，被BERTScore抢占。解决方案：为BERTScore单独配线程池：

@Bean public ExecutorService bertScoreExecutor() { return Executors.newFixedThreadPool(4, new ThreadFactoryBuilder().setNameFormat("bert-score-%d").build()); }

计算时用bertScoreExecutor.submit(() -> BERTScore.compute(...))，避免阻塞Web线程。

5.4 Redis缓存穿透：不是Key不存在，而是空结果未缓存

现象：大量无效question（如乱码、单字符）涌入，每次都要走完整RAG链路，CPU飙升。原因是空结果没进缓存。解决方案：对空结果也缓存，但TTL设为60秒：

if (response.isEmpty()) { redisTemplate.opsForValue() .set("qa_cache:" + fingerprint, "NOT_FOUND", Duration.ofSeconds(60)); }

同时加布隆过滤器预判：BloomFilter<String> questionFilter = BloomFilter.create(Funnels.stringFunnel(Charset.defaultCharset()), 1000000, 0.01);，拦截99%的无效question。

5.5 Spring AI版本冲突：不是依赖错，而是Spring Boot Starter覆盖

现象：引入spring-ai-spring-boot-starter后，RestTemplate莫名失效。查mvn dependency:tree，发现starter里带的spring-web:6.1.0覆盖了SB3.2.5的spring-web:6.0.12。解决方案：在pom里强制指定：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>3.2.5</version> <!-- 锁死版本 --> </dependency>

并用mvn enforcer:enforce检查依赖树，禁止spring-web版本漂移。

6. 最后分享一个技巧：用“问题-答案对”反向生成测试文档

所有测试都用真实文档？太慢。我们发明了一种高效测试法：用LLM生成合成测试文档。给ChatClient喂入100个真实用户问题，让它生成对应的“标准答案”，再用这些答案反向构造