企业官网建设流程全解析

1. 为什么是 LangChain4j，而不是直接上 Spring AI 或手写胶水代码？

LangChain4j 这个名字刚出来时，我第一反应是：“又一个套壳项目？”——毕竟 Java 生态里早就有不少封装 LLM 调用的工具：有人用 OkHttp + Jackson 手拼 JSON 请求，有人基于 Feign 做了轻量适配，还有团队在 Spring Boot 启动时注入一堆 RestTemplate Bean，再配上自定义拦截器处理 token、重试、日志。但真正跑通一个带记忆、能调用工具、支持流式响应、还要对接向量库的完整链路后，我才意识到：LangChain4j 不是“又一个轮子”，而是 Java 工程师终于等来的语义层基础设施。

它解决的不是“怎么发请求”这个 HTTP 层问题，而是“怎么让大模型像人一样思考和协作”这个抽象层问题。比如，你让模型“查一下上周销售最高的三个产品”，背后要拆解为：① 理解时间范围（“上周”需转成具体日期区间）；② 明确数据源（是 MySQL 还是 Elasticsearch？字段名是product_name还是item_title？）；③ 构建查询逻辑（是否需要 JOIN？是否要过滤下架商品？）；④ 处理结果格式（返回纯文本摘要，还是结构化 JSON 供前端渲染？）。LangChain4j 把这些环节抽象成可插拔组件：ChatMemory管上下文，ToolExecutor封装业务逻辑，RetrievalAugmentor注入知识片段——你不再写“if-else 判断用户是不是在问库存”，而是定义一个InventoryTool，声明它的输入参数、执行逻辑和返回 Schema，框架自动完成意图识别、参数提取、调用分发与结果组装。

这和 Spring AI 的定位有本质区别。Spring AI 更像一个“LLM 驱动的 Spring 生态粘合剂”，它强在与 Spring 生态无缝集成（比如自动把@Bean注册为 Tool），但对非 Spring 环境支持弱，且核心链路抽象粒度较粗。而 LangChain4j 是纯 Java 实现，无框架依赖，连main方法都能跑起来。我曾在一个嵌入式设备管理后台里用它做自然语言指令解析（如“重启 192.168.1.102 的网关服务”），整个项目连 Spring 都没引入，只依赖langchain4j-core和langchain4j-openai两个 jar，启动耗时不到 200ms。这种轻量性，恰恰是很多传统 Java 项目最需要的：不推翻现有架构，就能给老系统加上“会说话”的能力。

提示：别被“LangChain”这个名字误导。它和 Python 版 LangChain 并非同一套代码，也不是简单翻译。Java 版从设计之初就放弃了“完全兼容 Python API”的执念，转而拥抱 Java 的强类型和模块化特性。比如 Python 里用字典传参，Java 版则强制定义@ToolMethod接口；Python 里靠装饰器注册工具，Java 版则用ToolProviderSPI 机制实现运行时发现——这使得 IDE 能直接跳转到工具实现类，编译期就能检查参数类型，大幅降低调试成本。

关键词里虽然空着，但实际落地中，你绕不开这几个核心概念：ChatModel（大模型接口）、AiMessage（AI 返回消息）、UserMessage（用户输入）、SystemMessage（系统指令）、Tool（工具函数）、EmbeddingModel（向量化模型）、EmbeddingStore（向量存储）。它们不是孤立的类，而是一套协同工作的协议。比如Tool接口要求实现execute方法并返回ToolExecutionResult，这个返回值会被自动序列化成 JSON 字符串，再塞进下一轮ChatModel的tool_calls字段里——整个过程对开发者透明，你只需关注业务逻辑本身。

我见过太多团队踩的第一个坑，就是试图用 LangChain4j 替代所有后端逻辑。结果写了一堆@Tool方法，每个都包含数据库查询、缓存校验、权限判断，最后发现性能瓶颈卡在 JDBC 连接池，而不是模型推理。正确的做法是：LangChain4j 只负责“决策中枢”，真正的“手脚”必须交给成熟的业务服务。比如InventoryTool内部不应直接写 SQL，而应调用已有的InventoryService.queryByDateRange()方法——这样既能复用现有事务、熔断、监控能力，又能让 LangChain4j 专注做它最擅长的事：理解用户意图、协调多个工具、生成自然语言反馈。

2. 从零搭建第一个可运行 Demo：三步走清逻辑，拒绝“复制粘贴即崩溃”

很多新手教程一上来就甩出 50 行配置代码，然后说“运行即可看到效果”。结果你照着敲完，控制台报NoClassDefFoundError: io.github.langchain4j.model.chat.ChatModel，查半天才发现漏加了langchain4j-openai依赖，或者版本号和文档不匹配。LangChain4j 的入门门槛不在概念，而在环境一致性。下面这个 Demo，是我给某高校实验室新同学做的实操训练，全程不依赖任何外部服务（连 OpenAI Key 都不用），用本地模型模拟真实交互，确保每一步都能验证。

2.1 第一步：最小依赖集，精准锁定 Maven 坐标

不要直接抄官网的<dependency>示例。LangChain4j 模块划分极细，盲目引入会导致类冲突或功能缺失。以 Java 17 + Maven 3.8+ 为基准，仅需以下三个依赖：

<dependency> <groupId>io.github.langchain4j</groupId> <artifactId>langchain4j-core</artifactId> <version>0.32.0</version> </dependency> <dependency> <groupId>io.github.langchain4j</groupId> <artifactId>langchain4j-openai</artifactId> <version>0.32.0</version> </dependency> <dependency> <groupId>io.github.langchain4j</groupId> <artifactId>langchain4j-in-memory</artifactId> <version>0.32.0</version> </dependency>

注意三点：

1. 版本号必须严格一致：0.32.0是当前（2024年中）最稳定的版本，0.31.x存在ToolExecutor线程安全问题，0.33.0-SNAPSHOT则缺少关键文档；
2. langchain4j-in-memory不是可选的：它提供InMemoryEmbeddingStore，是后续做 RAG（检索增强生成）的基石，即使现在不用，也建议提前引入，避免后期补依赖引发版本错乱；
3. 绝对不要引入langchain4j-spring-boot-starter：新手阶段强行绑定 Spring，会掩盖底层调用链路，导致你连ChatModel.generate()报错都不知道是网络问题还是参数问题。

注意：如果你用的是 Gradle，请务必使用implementation而非compile（后者已被废弃），且在repositories中添加 Maven Central 镜像源，否则可能拉取到旧版 SNAPSHOT 包。

2.2 第二步：手写第一个 ChatModel，绕过所有配置陷阱

别急着写@SpringBootApplication。先用最原始的方式创建ChatModel实例，确认基础通信正常：

import io.github.langchain4j.model.chat.ChatModel; import io.github.langchain4j.model.openai.OpenAiChatModel; public class FirstDemo { public static void main(String[] args) { // 关键：显式指定模型名称和 API Key（测试用，后续再优化） ChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") // 此处填你的 OpenAI Key，若无则跳至 2.3 节 .modelName("gpt-3.5-turbo") .temperature(0.0) .maxTokens(256) .logRequests(true) // 开启请求日志，调试必备 .logResponses(true) .build(); String response = model.generate("你好，请用中文简单介绍你自己"); System.out.println("AI 回复：" + response); } }

这段代码看似简单，但藏着三个关键点：

• logRequests/logResponses必须设为true：它会打印完整的 HTTP 请求头、请求体和响应体。当出现401 Unauthorized时，你能立刻看到 Authorization Header 是否正确拼接；当返回{"error": {"message": "Invalid request..."}}时，能直接对比请求体 JSON 结构是否符合 OpenAI API 规范；
• temperature=0.0是新手友好设置：它强制模型输出确定性结果，避免每次运行回复不同，方便你验证逻辑是否正确；
• maxTokens=256是防崩保险：防止模型陷入无限生成，消耗 Token 配额。

如果这一步失败，90% 的原因是网络或 Key 问题。此时不要怀疑代码，而是打开终端执行：

curl -X POST https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-xxx" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "你好"}], "temperature": 0.0, "max_tokens": 256 }'

如果 curl 成功而 Java 代码失败，说明是 Java 环境问题（如代理设置、SSL 证书）；如果 curl 也失败，则是 Key 或网络问题。这是排查链路的黄金起点。

2.3 第三步：用本地模型替代 OpenAI，彻底摆脱外部依赖

没有 OpenAI Key？没关系。LangChain4j 支持通过StreamingChatModel接口接入任意模型。我推荐用llama.cpp的 Java 绑定llama-java（轻量、纯本地、无需 GPU）：

1. 下载预编译的llama.bin模型文件（推荐phi-3-mini，仅 2GB，CPU 即可运行）；
2. 添加依赖：

<dependency> <groupId>com.github.haas85</groupId> <artifactId>llama-java</artifactId> <version>0.1.0</version> </dependency>

3. 替换ChatModel创建逻辑：

import com.github.haas85.llama.LlamaModel; import io.github.langchain4j.model.chat.StreamingChatModel; import io.github.langchain4j.model.chat.StreamingResponseHandler; // 加载本地模型（路径需替换为你的实际路径） LlamaModel llama = new LlamaModel("/path/to/phi-3-mini.Q4_K_M.gguf"); StreamingChatModel localModel = new StreamingChatModel() { @Override public void generate(List<ChatMessage> messages, StreamingResponseHandler<AiMessage> handler) { String prompt = messages.stream() .map(m -> m.type() + ": " + m.text()) .collect(Collectors.joining("\n")); String result = llama.generate(prompt, 256); // 生成 256 个 token handler.onResponse(new AiMessage(result)); } };

这样，你的 Demo 就完全脱离了网络和 Key 限制。虽然本地模型效果不如 GPT，但足以验证 LangChain4j 的核心流程：消息组装 → 模型调用 → 响应解析。这才是新手最该掌握的能力——把框架当成可调试的黑盒，而不是不可知的魔法。

3. 让 AI “记住”上下文：ChatMemory 的三种实战形态与选型逻辑

很多教程讲ChatMemory，只说“它能保存历史对话”，然后贴一段MessageHistory代码。结果你一用就发现：用户问“刚才说的第三点是什么？”，AI 却答“我不记得之前聊过什么”。问题不在代码，而在你没理解 LangChain4j 的内存模型本质：它不保存“对话”，而是保存“消息对象”；它不负责“理解”，只负责“传递”。ChatMemory的作用，是把上一轮的UserMessage和AiMessage，原封不动地塞进下一轮ChatModel.generate()的messages参数列表里。至于模型能不能利用这些历史，取决于模型自身能力和提示词设计。

所以，选型的关键不是“哪个内存实现更快”，而是“哪种形态匹配你的业务场景”。我根据实际项目经验，总结出三种必须掌握的形态：

3.1 InMemoryChatMemory：单会话、低延迟、无持久化的“白板模式”

这是最简单的实现，适合客服机器人、命令行工具等场景。它的原理就是一个ConcurrentLinkedDeque，按时间顺序存消息：

ChatMemory memory = InMemoryChatMemory.builder() .maxMessages(10) // 仅保留最近 10 条消息，防内存溢出 .build(); // 每次调用前，将历史消息注入 List<ChatMessage> messages = new ArrayList<>(memory.messages()); messages.add(new UserMessage("今天天气怎么样？")); String response = model.generate(messages); memory.add(new UserMessage("今天天气怎么样？")); memory.add(new AiMessage(response));

这里有两个易错点：

• maxMessages必须设！否则用户聊 100 轮后，内存里存了 200 条消息，generate()时会把全部消息传给模型，极大增加 Token 消耗和响应延迟；
• memory.add()必须在model.generate()之后调用！如果先加再调用，会导致当前轮次的消息被错误地当作历史传入下一轮。

提示：InMemoryChatMemory的线程安全性是“弱安全”。它用ConcurrentLinkedDeque保证 add/remove 不抛异常，但不保证多线程并发调用messages()时返回的 List 是实时一致的。因此，严禁在 Web 应用中用单例InMemoryChatMemory处理多个用户会话。它只适用于单线程 CLI 工具或单元测试。

3.2 SessionChatMemory：基于 Session ID 的隔离式内存，Web 场景标配

当你需要支持多个用户同时聊天时，必须用SessionChatMemory。它内部维护一个ConcurrentMap<String, ChatMemory>，用sessionId作为 key：

// 全局单例，线程安全 SessionChatMemory sessionMemory = SessionChatMemory.builder() .chatMemorySupplier(() -> InMemoryChatMemory.builder().maxMessages(20).build()) .build(); // 用户 A 的会话 String sessionIdA = "user_a_123"; ChatMemory memoryA = sessionMemory.get(sessionIdA); memoryA.add(new UserMessage("你好")); memoryA.add(new AiMessage("您好！请问有什么可以帮您？")); // 用户 B 的会话（完全隔离） String sessionIdB = "user_b_456"; ChatMemory memoryB = sessionMemory.get(sessionIdB); memoryB.add(new UserMessage("Hi there")); memoryB.add(new AiMessage("Hello! How can I help?"));

关键技巧在于chatMemorySupplier：它不是一个固定实例，而是一个 Supplier 函数。这意味着每次get(sessionId)时，都会创建一个新的InMemoryChatMemory实例。这样既保证了会话隔离，又避免了单个内存实例过大。我在某电商后台项目中用它支撑了 500+ 客服坐席并发，实测单个InMemoryChatMemory实例在 20 条消息时，内存占用稳定在 1.2MB 以内，GC 压力极小。

3.3 RedisChatMemory：分布式会话、跨服务共享、高可用保障

当你的系统拆分为多个微服务（如前端服务、AI 服务、订单服务），且需要在服务间同步会话状态时，RedisChatMemory是唯一选择。它把消息序列化为 JSON 存入 Redis，用sessionId作为 key：

// 使用 Jedis 连接 Redis JedisPool jedisPool = new JedisPool("redis://127.0.0.1:6379"); ChatMemory memory = RedisChatMemory.builder() .jedisPool(jedisPool) .sessionId("session_xxx") .maxMessages(50) .timeToLiveInSeconds(3600) // 1 小时后自动过期 .build();

这里有个隐藏巨坑：Redis 存储的是ChatMessage的 JSON 序列化结果，而非原始对象。LangChain4j 默认用 Jackson，但如果你的ChatMessage包含自定义字段（如source: "web"），必须手动注册 Jackson Module，否则反序列化会丢失字段。解决方案是继承RedisChatMemory并重写serialize/deserialize方法，或在项目启动时全局配置 Jackson：

ObjectMapper mapper = new ObjectMapper(); mapper.registerModule(new JsonMessageModule()); // 自定义模块，处理 ChatMessage 子类 RedisChatMemory.builder().objectMapper(mapper).build();

我曾在某金融项目中因忽略此点，导致 Redis 里存的SystemMessage被反序列化成UserMessage，AI 开始胡言乱语。排查了两天才发现是 Jackson 的类型擦除问题——这提醒我们：分布式内存不是“开箱即用”，而是需要深度理解序列化契约。

4. 让 AI “调用工具”：从定义 Tool 到构建 ToolExecutor 的全链路拆解

LangChain4j 最强大的能力，是让 AI 不再只是“回答问题”，而是能“执行任务”。但新手常陷入两个误区：一是把所有业务方法都标为@Tool，导致工具爆炸；二是认为ToolExecutor会自动处理异常，结果线上服务因一个数据库超时而雪崩。下面我用一个真实的库存查询场景，带你走通从定义到上线的完整链路。

4.1 定义 InventoryTool：强类型、可测试、职责单一

不要写public class InventoryTool { @ToolMethod public String query(String productId) { ... } }。这种写法违反了 Java 的强类型原则，且无法在编译期校验参数。正确姿势是定义接口：

public interface InventoryTool { /** * 查询指定商品的实时库存 * @param productId 商品 ID（必填） * @param warehouseCode 仓库编码（可选，默认主仓） * @return 库存数量，-1 表示查询失败 */ @ToolMethod int getStock(@ToolParam(description = "商品唯一标识") String productId, @ToolParam(description = "仓库编码，如 BJ01") String warehouseCode); }

注意三个细节：

• @ToolParam的description字段至关重要：LangChain4j 会把描述拼接到系统提示词里，指导模型理解参数含义。没有描述，模型可能把warehouseCode当成商品名称；
• 返回值必须是基础类型或 POJO：int、String、JsonObject均可，但不能是Optional或ResponseEntity，否则序列化失败；
• 方法必须是public且无throws声明：所有异常必须在方法体内捕获并转换为业务错误码。

然后实现它：

@Component // 若用 Spring，否则用普通类 public class InventoryToolImpl implements InventoryTool { private final InventoryService inventoryService; // 依赖已有的业务服务 @Override public int getStock(String productId, String warehouseCode) { try { // 复用现有服务，保证事务、缓存、监控能力 return inventoryService.getStock(productId, StringUtils.defaultString(warehouseCode, "MAIN_WAREHOUSE")); } catch (InventoryException e) { log.warn("库存查询失败，productId={}, warehouse={}", productId, warehouseCode, e); return -1; // 返回明确错误码，便于前端处理 } } }

4.2 构建 ToolExecutor：线程安全、超时控制、降级策略

ToolExecutor不是简单地反射调用方法。它需要处理并发、超时、熔断等生产级问题。LangChain4j 提供了DefaultToolExecutor，但默认配置不适合生产：

// 错误示范：直接 new DefaultToolExecutor(tools) ToolExecutor executor = DefaultToolExecutor.builder() .tools(Arrays.asList(inventoryTool)) // 工具列表 .maxConcurrency(10) // 最大并发数，防打爆下游 .timeout(Duration.ofSeconds(5)) // 单次调用超时，必须设！ .fallback((toolName, arguments, throwable) -> { // 降级逻辑：返回兜底值或错误提示 if ("getStock".equals(toolName)) { return ToolExecutionResult.from("库存查询暂时不可用，请稍后再试"); } return ToolExecutionResult.from("服务繁忙"); }) .build();

这里的关键参数：

• maxConcurrency=10：限制同时最多 10 个工具调用在执行。如果下游库存服务 QPS 为 100，而你的 AI 服务有 1000 个并发用户，这个参数能防止雪崩；
• timeout=5s：必须小于ChatModel的总超时（如 30s），否则模型会一直等待工具返回，浪费 Token；
• fallback：不是可选项，而是生产必需。它让你能在工具不可用时，优雅地返回“服务暂不可用”，而不是让 AI 胡编乱造。

我曾在线上环境观察到：未设timeout时，getStock因数据库慢查询卡住 30 秒，导致ChatModel生成中断，用户看到“正在思考...”长达半分钟。加上超时后，5 秒内未返回则触发降级，用户体验立即提升。

4.3 集成到 ChatModel：让 AI 主动发起工具调用

最后一步，把ToolExecutor注入ChatModel，并启用工具调用：

ChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") .modelName("gpt-4-turbo") .enableToolCalling(true) // 关键：开启工具调用能力 .toolExecutor(executor) .build(); // 发送带工具描述的请求 String userQuery = "帮我查一下商品 ABC123 在北京仓的库存"; List<ChatMessage> messages = new ArrayList<>(); messages.add(SystemMessage.from("你是一个电商客服助手。你可以调用工具查询库存。")); messages.add(UserMessage.from(userQuery)); AiMessage response = model.generate(messages); // 如果 response.toolExecutionRequest() 不为空，说明模型决定调用工具 if (response.toolExecutionRequest() != null) { ToolExecutionRequest request = response.toolExecutionRequest(); ToolExecutionResult result = executor.execute(request); // 将工具结果作为新消息加入上下文，再调用模型生成最终回复 messages.add(response); messages.add(AiMessage.from(result.toString())); String finalReply = model.generate(messages); System.out.println("最终回复：" + finalReply); }

这个流程揭示了一个重要事实：LangChain4j 的工具调用是“两轮交互”。第一轮模型输出toolExecutionRequest，第二轮你执行工具并将结果喂回模型，由模型生成自然语言回复。这不是自动化的魔法，而是需要你显式编排的流程。很多新手卡在这里，以为enableToolCalling(true)就万事大吉，结果发现模型根本不调用工具——原因往往是SystemMessage里没写清楚“你可以调用工具”，或者工具描述太模糊，模型无法理解何时该调用。

5. RAG 实战：从 Embedding 到 RetrievalAugmentor，构建企业级知识库

当用户问“我们的退货政策是什么？”，你不可能把整本《客户服务手册》喂给模型。RAG（检索增强生成）是解决这个问题的标准方案：先从知识库中检索相关片段，再把片段和问题一起交给模型生成答案。LangChain4j 的 RAG 实现，比想象中更轻量，但也更需精细调优。

5.1 EmbeddingModel 选型：本地 vs 云端，精度 vs 成本

Embedding 模型负责把文本转成向量。LangChain4j 支持多种实现，但新手常犯的错误是盲目追求“最强模型”。实际上，选型要看你的知识库规模和更新频率：

对于新手，我强烈推荐从text-embedding-3-small开始。它的 API 和 LangChain4j 无缝集成，且质量远超本地模型：

EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder() .apiKey("sk-xxx") .modelName("text-embedding-3-small") .dimensions(256) // 降低维度，节省向量库空间 .build();

dimensions=256是关键优化：默认 1536 维，但对大多数企业文档，256 维已足够区分语义，向量库存储空间减少 83%，检索速度提升 2 倍。

5.2 EmbeddingStore 选型：InMemory vs Redis vs PostgreSQL

向量库是 RAG 的心脏。LangChain4j 内置InMemoryEmbeddingStore，但它只适合 Demo。生产必须选持久化方案：

• Redis Stack：支持向量搜索的 Redis 增强版，部署简单，性能优秀。适合中小规模（< 100 万向量）；
• PostgreSQL + pgvector：利用现有数据库，运维成本低，支持复杂 SQL 关联。适合已有 PG 集群的企业；
• 专用向量库（Qdrant/Milvus）：功能最全，但运维复杂，适合超大规模（> 1000 万向量）。

我推荐从 Redis Stack 入手。它的RedisEmbeddingStore配置极其简洁：

RedisClient redisClient = RedisClient.create("redis://127.0.0.1:6379"); EmbeddingStore<TextSegment> store = RedisEmbeddingStore.builder() .redisClient(redisClient) .indexName("knowledge_index") // Redis 中的索引名 .vectorDimension(256) // 必须和 embeddingModel 一致 .distanceType(RedisEmbeddingStore.DistanceType.COSINE) .build();

关键点：vectorDimension必须和EmbeddingModel的输出维度严格一致，否则插入失败。我曾因embeddingModel.dimensions(256)和store.vectorDimension(1536)不匹配，导致所有向量插入后检索结果为空，排查了 3 小时才发现是配置错位。

5.3 RetrievalAugmentor：如何让模型“看见”检索结果

RetrievalAugmentor是连接检索和生成的桥梁。它不负责检索，只负责把检索到的TextSegment注入ChatModel的上下文。标准用法：

RetrievalAugmentor augmentor = DefaultRetrievalAugmentor.builder() .embeddingModel(embeddingModel) .embeddingStore(store) .maxResults(3) // 最多返回 3 个相关片段 .queryEmbeddingPromptTemplate("将以下内容转为向量查询：{{it}}") .build(); // 使用时，先检索，再生成 String userQuestion = "退货需要哪些材料？"; List<TextSegment> relevantSegments = augmentor.augment(userQuestion); // 将片段拼成系统消息 String context = relevantSegments.stream() .map(TextSegment::text) .collect(Collectors.joining("\n---\n")); List<ChatMessage> messages = new ArrayList<>(); messages.add(SystemMessage.from("你是一个客服助手。以下是公司退货政策：\n" + context)); messages.add(UserMessage.from(userQuestion)); String answer = model.generate(messages);

这里有个高级技巧：动态调整maxResults。对简单问题（如“退货地址在哪？”），1 个片段足够；对复杂问题（如“不同商品类别的退货时效和材料要求？”），可能需要 5 个片段。我在线上系统中实现了自适应逻辑：先用embeddingModel对问题做粗筛，计算问题向量与各知识库分类向量的相似度，再决定maxResults。实测将平均响应准确率从 78% 提升到 92%。

注意：RetrievalAugmentor不是银弹。它无法解决“知识库未覆盖的问题”。比如用户问“iPhone 15 Pro 的退货政策”，而知识库只有“手机类退货政策”，模型可能过度泛化。此时需要配合Tool调用实时查询数据库，形成 RAG + Tool 的混合架构——这才是企业级应用的真实形态。

6. 生产避坑指南：十个血泪教训，来自真实项目的故障复盘

写了上千行 LangChain4j 代码，踩过无数坑，我把最痛的十个教训浓缩成清单。它们不教你怎么写代码，而是告诉你：在生产环境，什么会让你的 AI 服务在凌晨三点报警。

6.1 Token 超限：模型静默失败，而非抛异常

LangChain4j 的ChatModel.generate()在输入 Token 超限时，不会抛RuntimeException，而是返回一个AiMessage，其text()为空字符串，且toolExecutionRequest()也为 null。这导致你的代码继续往下走，最终返回空响应给用户。解决方案是：永远检查response.content()是否为空，并记录response.tokenUsage()：

AiMessage response = model.generate(messages); if (StringUtils.isBlank(response.text())) { log.error("模型返回空内容，输入Token:{}, 输出Token:{}", response.tokenUsage().inputTokenCount(), response.tokenUsage().outputTokenCount()); throw new AiServiceException("模型生成失败，请重试"); }

6.2 工具调用死循环：模型反复调用同一个工具

当InventoryTool.getStock()返回-1（表示失败），而你的fallback又返回“请重试”，模型可能陷入“调用→失败→重试→调用”的死循环。LangChain4j 默认不限制工具调用次数。必须手动加锁：

int maxToolCalls = 3; for (int i = 0; i < maxToolCalls; i++) { AiMessage response = model.generate(messages); if (response.toolExecutionRequest() != null) { ToolExecutionResult result = executor.execute(response.toolExecutionRequest()); messages.add(response); messages.add(AiMessage.from(result.toString())); } else { break; // 模型决定不调用工具，生成最终回复 } }

6.3 日志泄露敏感信息：API Key 和用户隐私

logRequests=true很方便，但会把apiKey和用户消息原样打到日志里。生产环境必须禁用，改用结构化日志脱敏：

// 自定义日志拦截器 public class SafeLoggingInterceptor implements ChatModelInterceptor { @Override public ChatResponse before(ChatRequest request) { // 脱敏 apiKey String safeApiKey = request.apiKey().replaceAll(".{4}$", "****"); log.info("ChatRequest: model={}, messages={}, apiKey={}", request.modelName(), request.messages().size(), safeApiKey); return null; } }

6.4 向量库连接泄漏：Redis 连接数暴涨

RedisEmbeddingStore的redisClient必须是单例，且需配置连接池。否则每次augment()都新建连接，很快耗尽 Redis 连接数。正确配置：

RedisClient redisClient = RedisClient.create(RedisURI.create( "redis://:password@127.0.0.1:6379" )); // 设置连接池 redisClient.setOptions(ClientOptions.builder() .pingBeforeActivateConnection(true) .build());

6.5 系统消息长度失控：超过模型最大上下文

SystemMessage里塞太多规则（如“你不能说脏话”“你必须用中文回答”“你不能透露内部信息”），会快速占满上下文。GPT-3.5 Turbo 最大上下文 16K，但SystemMessage占 2K，UserMessage占 1K，留给RetrievalAugmentor的只剩 13K。解决方案：把长规则拆成短提示，用Tool动态注入。例如，“禁止透露内部信息”这条，可在ToolExecutor的fallback里统一处理，而非写死在SystemMessage中。

6.6 模型降级失效：fallback未覆盖所有异常类型

ToolExecutor.fallback()只捕获RuntimeException，但SQLException、TimeoutException是Exception的子类，不会触发 fallback。必须用try-catch包裹：

try { return inventoryService.getStock(productId, warehouseCode); } catch (Exception e) { // 捕获所有异常 log.warn("库存查询异常", e); return -1; }

6.7 时间戳处理错误：LocalDateTime未序列化

当TextSegment的元数据包含LocalDateTime字段时，Jackson 默认序列化为数组[2024, 5, 15, 10, 30]，反序列化失败。必须注册JavaTimeModule：

ObjectMapper mapper = new ObjectMapper(); mapper.registerModule(new JavaTimeModule()); RedisEmbeddingStore.builder().objectMapper(mapper).build();

6.8 编码不一致：中文乱码导致检索失败

`Embed