Java后端集成大模型实战：LangChain4j从入门到生产落地

说实话，Java后端接大模型这件事，过去一直很拧巴。我身边不少朋友在Python圈用LangChain用得风生水起，回到Java项目里就只能手写HTTP请求封装，自己搞prompt拼接，再流着泪处理流式输出和上下文管理。直到我认真用上LangChain4j，这种感觉才彻底改变。LangChain4j是专门为Java生态设计的LLM应用开发框架，核心思想是把你熟悉的Spring式编程习惯迁移到AI领域：依赖引入、接口定义、注解声明、链式装配，一套流程下来非常顺滑。这篇文章我直接从新手视角出发，带你完整跑一遍LangChain4j的实战链路——从环境搭建、第一个对话Demo，到工具调用、RAG知识库问答，最后把生产环境容易踩的坑一并梳理清楚。适合刚接触大模型开发、想在Java项目里落地AI能力的后端工程师，也适合看了大量LangChain文档却不知道怎么翻译成Java代码的同学。

1. 项目冷启动：先把环境搞干净

1.1 版本选择：JDK 17起步，别再用Java 8裸奔

LangChain4j官方标注的最低要求是Java 8，但我强烈建议直接用JDK 17或21，原因有两点。第一，框架内部大量使用了动态代理、反射和java.lang.invoke相关能力，在老JDK上跑不是不行，而是遇到诡异问题基本查不到资料。第二，现在主流Spring Boot 3.x已经把基线抬到JDK 17，你的AI模块大概率要嵌在Spring Boot项目里，没必要为了兼容Java 8给自己埋坑。我刚接触时曾在Java 8环境跑过0.35版本，碰到过一次方法句柄初始化异常，换到JDK 17后问题彻底消失。

构建工具Maven和Gradle都可以，本文统一用Maven写示例。你不需要马上建立一个多复杂的工程，一个普通的Maven项目就足够跑通前几个Demo。如果你打算集成到Spring Boot，建议新建干净的空项目，避免后面依赖冲突时还要怀疑是不是自己业务代码的问题。

1.2 用BOM统一版本，别一个个手写版本号

LangChain4j不是一个单包，而是拆成了几十个模块：核心模块、模型提供商适配模块、嵌入模型、存储扩展、流式API等等。新手最容易犯的错误就是去GitHub上各模块仓库找最新版本号，然后手动填version，结果因为版本不一致出现ClassNotFoundException。正确做法是引入它的BOM，让版本号统一由父级POM管理。

<dependencyManagement> <dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-bom</artifactId> <version>0.36.2</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

引入BOM之后，加依赖就不用再写版本号了。比如先加核心包和一个模型适配包：

<dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> </dependency> </dependencies>

这里选langchain4j-open-ai而不是某个厂商专用模块，是因为它支持通过baseUrl指向任何兼容OpenAI协议的端点。国内模型服务像通义千问、DeepSeek、Kimi、智谱都提供了OpenAI兼容模式，你只需要换一个baseUrl和modelName就能切换模型供应商，业务代码完全不用动。这个兼容层带来的便利，等你真正需要做多模型切换时体会最深。

1.3 三个必须知道的模块划分

新手面对一堆模块名容易懵，我把常用模块按用途分成三组：

记住一个原则：核心包必加，模型适配包按需选一个，存储包等做到RAG阶段再加。别一次性把整个生态全部引入，依赖冲突和启动耗时都会教你做人。

2. 核心概念拆解：LangChain4j的五个关键抽象

2.1 ChatLanguageModel：一切对话的入口

ChatLanguageModel是整个框架的门面，任何模型供应商最终都会实现这个接口。你只需要面向它编程，不用关心底层是OpenAI的Chat Completion还是通义千问的DashScope协议。最基础的方法是generate(String userMessage)，传入一句话返回模型生成的字符串。这个接口适合快速验证连通性。

实际开发时我的建议是再往上走一层，使用统一的消息列表方式。因为真实对话永远是多轮的，单字符串方法只适合跑通链路，不适合做产品。chat(List<ChatMessage>)能表达完整的历史对话和系统设定，后续所有高级功能都建立在这套消息模型之上。

2.2 Message与ChatMemory：让模型“记住”上下文

大模型本身无状态，它每次只根据你传进去的文字做预测。所谓记忆，本质是"把历史消息再塞回上下文"。LangChain4j用四类消息表达对话：SystemMessage（系统设定）、UserMessage（用户输入）、AiMessage（模型回复）、ToolMessage（工具调用结果）。

ChatMemory接口负责管理这些消息。最常用的实现是WindowChatMemory，你可以指定最多保留多少条：

ChatMemory chatMemory = WindowChatMemory.builder() .maxMessages(20) .build();

为什么是20而不是50或者100？因为上下文窗口是稀缺资源。保留的历史越多，能用于生成回复的token越少，响应越慢，费用越高。而且超出模型上下文长度会直接报错，不会自动裁剪。我的经验是：普通客服场景保留10到20条足够，涉及代码分析或长文总结时再按需调大。

2.3 AiServices：面向任务的声明式编程

AiServices是整个框架里我最喜欢的部分，它把AI调用封装成"定义一个接口，声明要做什么，然后拿代理对象直接用"。底层原理是动态代理：框架在运行时替你组装提示词、管理消息历史、触发工具调用，你只负责定义业务方法。

interface CustomerAssistant { String chat(String userMessage); }

配合注解可以定制系统提示词：

interface CustomerAssistant { @SystemMessage("你是一个耐心、专业的电商客服助手。回答要简洁准确，不要编造订单信息。") String chat(String userMessage); }

然后一行代码拿到代理对象：

CustomerAssistant assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(model) .build(); String answer = assistant.chat("我的订单为什么还没发货？");

看起来只是个普通接口，实际调用时已经经历了完整的提示词组装和模型调用。这种模式的好处是业务代码零侵入，后续加工具、加记忆、加RAG都只是链式配置而已。

2.4 Tool：让模型调用你的Java方法

Tool（Function Calling）是把LLM从"聊天机器人"变成"执行者"的关键能力。你可以把任意Java方法暴露给模型，当用户提问需要真实数据时，模型会在回答里附加一个函数调用意图，框架拦截后反射执行你的方法，再把返回值交还给模型生成最终答案。

LangChain4j里加一个工具极其简单。在任意类的公有方法上打@Tool注解，描述里写清楚这个方法什么时候用、参数是什么含义：

class OrderTool { @Tool("根据订单号查询订单状态，当用户询问订单进度时调用") String queryOrderStatus(String orderId) { return "订单 " + orderId + " 已发货，预计3天内送达"; } }

然后注册进AiServices：

CustomerAssistant assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(model) .tools(new OrderTool()) .build();

工具调用的底层流程是：框架把方法名、描述、参数Schema转换成JSON结构，在模型请求里声明"你有这些函数可用"。模型判断用户问题匹配某个函数时，返回一个特殊消息而不是普通文本，框架解析后反射调用Java方法，再把结果作为ToolMessage送回模型，最终得到面向用户的回答。

这里有一个新手高频翻车点：@Tool描述写得太模糊。描述越模糊，模型越容易误判或漏判。比如"查询订单"就远不如"根据订单号查询订单当前物流状态，适用于用户询问包裹发货、配送进度、异常件等情况时调用"来得可靠。工具描述就是给模型的说明书，值得多花几分钟打磨。

2.5 Embedding与RAG：给模型外挂知识库

Embedding是把一段文本转成一串高维向量，语义相近的文本向量距离也近。RAG（检索增强生成）的思路是：先把私域知识文档切块并向量化存入向量库，用户提问时先在库里检索最相关的几段内容，连同问题一起交给模型，让模型基于这些事实来回答。这样既不用微调模型，又能让模型知道你私有数据里的细节。

LangChain4j的RAG链路设计得很清晰：文档分割器（DocumentSplitter）、嵌入模型（EmbeddingModel）、向量库（EmbeddingStore）、检索器（ContentRetriever）各司其职。接入方式我会在第5章完整演示，这里先记住一个核心结论：检索结果的质量主要取决于文档切分策略和向量召回阈值，而不是生成模型本身的强弱。

3. 实战：5分钟跑通第一个对话应用

3.1 注册模型服务并配置API Key

这一节我用通义千问的OpenAI兼容模式作为示例，其他兼容服务商的配置几乎一模一样。先去阿里云百炼或DashScope控制台申请一个API Key，然后选择模型，比如qwen-plus，注意确认服务支持compatible-mode端点。

API Key建议通过环境变量传入，而不是硬编码在代码里，防止误提交到Git仓库。这里我使用一个简单的读取方式：

export LLM_API_KEY=sk-xxxxxxxxxxxx

代码里用System.getenv("LLM_API_KEY")读取。即便只是做Demo，也要养成这个习惯，后面上生产会少踩一次泄漏事故的坑。

3.2 用OpenAiChatModel构建模型，发起第一次对话

LangChain4j的OpenAI模块本身实现的就是OpenAI协议，所以配置好baseUrl就能指向任何兼容端点：

import dev.langchain4j.model.openai.OpenAiChatModel; import java.time.Duration; OpenAiChatModel model = OpenAiChatModel.builder() .apiKey(System.getenv("LLM_API_KEY")) .modelName("qwen-plus") .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1") .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build(); String answer = model.generate("你好，请用一句话说明LangChain4j是什么"); System.out.println(answer);

这里我特别把logRequests(true)和logResponses(true)打开了，新手阶段这是最好的调试工具。你能直接在控制台看到发给模型的结构化请求和模型返回的原始内容，尤其是后面调试工具调用和RAG时，看不到原始报文根本没法定位问题。

跑起来以后，控制台会输出请求里的messages、temperature等参数，日志格式非常完整。第一次看到这些日志不要嫌烦，它们是你排查一切问题的基础。如果这一步能正常输出文字，说明你的工程搭建、API Key、网络连通性、模型参数全部通过，可以继续往下走。

3.3 流式输出：让回复一个字一个字地蹦出来

对话类产品里，流式输出几乎是刚需。用户发完消息希望立刻看到回复正在生成，而不是傻等完整结果返回。LangChain4j的流式调用同样建立在模型对象上：

model.chat("给我讲一个程序员的幽默段子", new StreamingResponseHandler<AiMessage>() { @Override public void onPartialResponse(String token) { System.out.print(token); } @Override public void onCompleteResponse(ChatResponse<AiMessage> completeResponse) { System.out.println("\n--- 流式输出完成 ---"); } @Override public void onError(Throwable error) { error.printStackTrace(); } });

注意onPartialResponse回调里的token是增量内容，你要做的就是逐段推送到前端。在Spring Boot里，配合SseEmitter或WebFlux的Flux<String>都能轻松实现打字机效果。我的实践是先把流式单独封装成一个接口，不要和普通同步请求混在同一个Service方法里，否则后面接日志、接限流都会很别扭。

3.4 加入聊天记忆，让它记住你是谁

一个只能单轮问答的Demo没有产品意义。给它加上WindowChatMemory，让多轮对话连续起来。这里直接把记忆和AiServices配合使用，代码量最小：

ChatMemory chatMemory = WindowChatMemory.builder() .maxMessages(20) .build(); Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(chatMemory) .build(); System.out.println(assistant.chat("我叫小王，记住这个名字")); System.out.println(assistant.chat("我刚才告诉你我叫什么？"));

第二次提问时模型会准确回答"你叫小王"，因为历史消息已经被注入上下文。到这里，你已经拥有了一个具备基础记忆能力的对话机器人。

4. 实战进阶：用AiServices + 工具调用做一个订单查询助手

4.1 需求拆解：哪些信息必须走工具

假设你要做一个电商客服助手。用户会问"我的订单发货了没""什么时候到""帮我改地址"这类问题。这里有个关键判断：订单状态是存储在业务数据库里的实时数据，不可能让模型凭空编造，所以必须由工具方法查询真实数据。而"改地址"这类写操作，更建议用工具加人工确认的方式，不要让模型直接执行。

我们把需求收窄成两个明确动作：

• 查订单状态：输入订单号，返回发货状态和预计到达时间。
• 查物流轨迹：输入订单号和物流单号，返回最近几条轨迹信息。

这两个动作都对应数据库或第三方物流API查询，是典型的工具调用场景。

4.2 定义业务接口和工具实现

先定义AI服务接口：

interface CustomerAssistant { String chat(String userMessage); }

再实现工具类：

class OrderTool { @Tool("根据订单号查询订单当前状态、是否发货以及预计送达时间") String queryOrderStatus(String orderId) { // 这里替换成真实的订单服务调用 if ("O20240315001".equals(orderId)) { return "订单状态：已发货；预计送达：3天内；承运商：顺丰"; } return "未查询到订单 " + orderId + "，请确认订单号是否正确"; } @Tool("根据订单号和物流单号查询最近三条物流轨迹，适用于用户询问包裹到哪了、配送进度等场景") String queryLogisticsTrace(String orderId, String trackingNo) { // 模拟物流查询 return "轨迹1: 3月14日 10:00 快件已从杭州发出；轨迹2: 3月15日 08:30 到达上海转运中心；轨迹3: 等待下一站更新"; } }

注意方法返回类型我用了String而不是复杂对象。工具调用的最终结果要拼进模型上下文，复杂对象在序列化时容易出意外，也容易把无关字段灌给模型。如果查询结果本身是对象，建议在工具方法里整理成简明字符串再返回。

组装并测试：

CustomerAssistant assistant = AiServices.builder(CustomerAssistant.class) .chatLanguageModel(model) .tools(new OrderTool()) .build(); String reply = assistant.chat("帮我查一下订单 O20240315001 现在到哪了？"); System.out.println(reply);

模型会看到用户问题里的订单号，匹配到queryOrderStatus或queryLogisticsTrace。因为这个问题没提供物流单号，它有较高概率先调用订单状态查询，再基于返回的真实状态组织回答。

4.3 从日志里看懂工具调用过程

打开logRequests(true)后，你能看到请求体里多了一个tools字段，里面是每个方法的名称、描述、参数JSON Schema。模型判断需要调用时，响应里会出现toolCalls，包含方法名和参数。框架接着执行方法，随后带着ToolMessage再请求一次模型。整个过程报文顺序是：

1. 请求：系统消息 + 用户问题 + 可用工具定义。
2. 响应：模型说"我要调用queryOrderStatus，参数是O20240315001"。
3. 框架执行Java方法，拿到真实结果。
4. 请求：系统消息 + 用户问题 + 工具调用记录 + 工具返回结果。
5. 响应：模型基于真实结果组织最终回答。

新手最容易懵的是第一步：看到工具定义被塞进请求就以为框架把工具代码传给了模型。其实模型只知道方法名、描述和参数格式，并不知道方法内部逻辑。边界在这里：模型负责决策，Java负责执行。这个边界理解到位，工具调用就没什么神秘可言了。

4.4 工具调用的三个设计建议

第一，参数尽量用简单类型。String、Long、Integer这类，模型从用户话里提取参数的准确率最高。如果你定义一个QueryOrderRequest对象，模型虽然也能填字段，但复杂嵌套结构容易填错。第二，方法名要动词开头，描述里明确触发条件和参数含义。第三，工具不是越多越好。每次请求都会把所有工具定义发给模型，工具太多既费token又降低模型识别准确率。建议单场景下工具控制在10个以内，功能相近的合并成一个方法，用参数区分。

5. 实战进阶：RAG本地知识库问答

5.1 场景与数据准备

很多企业知识库场景并不需要模型记住全部文档，只需要模型"看过"相关文档后回答问题。比如员工手册、产品FAQ、内部规章制度，文档更新频繁，不可能每次更新都微调模型。RAG就是最优解。

我先准备一个简单的测试文档handbook.txt，内容取员工手册节选，放在src/main/resources/docs下。内容不用太长，几百字足够验证链路通了。关键是要有明确的事实点，比如"试用期三个月""年假每年5天"这类可被检索和核对的表述。

5.2 引入嵌入模型与向量库依赖

RAG链路里有两个新组件：嵌入模型和向量库。这里我继续使用兼容OpenAI协议的接口，通义千问的文本嵌入模型text-embedding-v3可以走同一个baseUrl。向量库为了演示直接使用内存实现InMemoryEmbeddingStore，它适合Demo和小数据量场景，生产环境再替换成PGVector或Milvus。

EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder() .apiKey(System.getenv("LLM_API_KEY")) .modelName("text-embedding-v3") .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1") .build(); EmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>();

5.3 文档分割：切得好不好直接决定回答质量

文档不能整个丢给嵌入模型，因为单次请求有长度限制，且一个段落里混着多个主题会稀释语义。所以要先切块。LangChain4j提供了DocumentSplitter，我用递归切分器，按每块500字符、重叠100字符的方式切。

DocumentSplitter splitter = DocumentSplitters.recursive(500, 100);

为什么要有重叠？切块会让原本相邻的句子被分到不同块，重叠部分相当于给每块补上了"切缝处"的上下文。为什么是500字符？太小了语义不完整，太大了检索时浪费token且容易命中不相关内容。这两个参数需要根据文档类型微调，技术文档可以适当放大到800，FAQ类问题可以缩小到300。

导入文档：

EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); Document document = Document.fromFile(Paths.get("src/main/resources/docs/handbook.txt")); ingestor.ingest(document);

真正执行时，框架会把文档切成多个块，逐个调用嵌入接口，把向量和原文一起存入向量库。执行完可以打印总数确认切分是否正确：

System.out.println(embeddingStore.countAll());

5.4 配置ContentRetriever，完成RAG问答

检索器负责在向量库里找出和用户问题最相关的块，再把它作为上下文拼进模型请求。我用EmbeddingStoreContentRetriever：

ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(3) .minScore(0.7) .build();

maxResults控制检索几块内容，minScore是相似度阈值，低于这个分的内容不返回。阈值太高会漏掉相关内容，导致回答变成"我不知道"；阈值太低会混入无关内容，导致模型答非所问。我建议先在0.6到0.75之间试，再根据业务反馈微调。

然后在AiServices里挂上检索器：

interface Assistant { @SystemMessage("你是一个严谨的企业知识库助手，只能依据提供的资料回答问题，资料中没有的信息要明确说明不知道。") String chat(String question); } Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build(); String ans = assistant.chat("员工试用期是多久？"); System.out.println(ans);

系统提示词里那句"只能依据提供的资料回答"非常重要。没有这句，模型经常会自由发挥，把检索来的资料当参考而不是事实依据，幻觉满天飞。加上这句之后，回答边界立刻清晰。

5.5 RAG链路性能的关键：先召回，还是先生成？

这里补充一个容易踩的误区。有人觉得RAG慢是生成模型的问题，其实大部分时候瓶颈在向量检索和文档处理。如果文档几千块，每次都全量检索，内存向量库会越来越吃力。生产环境的方案是把InMemoryEmbeddingStore换成PGVector，并给向量列建索引。如果检索召回的内容相关性差，优先调整切分策略和minScore，而不是换更强的生成模型。生成模型再强，喂进去的资料错了也无济于事。

6. 常见问题与排查技巧实录

6.1 依赖冲突：slf4j与jackson的版本风暴

很多Spring Boot项目引入LangChain4j之后，启动报NoSuchMethodError或ClassNotFoundException，九成是日志或JSON库冲突。LangChain4j底层用SLF4J做日志、Jackson做JSON序列化，而Spring Boot对这两个库的版本有强管控。解决思路是：在dependencyManagement里让Spring Boot BOM优先管理版本；或者针对langchain4j相关传递依赖排除冲突项。

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <exclusions> <exclusion> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> </exclusion> </exclusions> </dependency>

不过要注意，排除slf4j-api之后要确保项目中显式引入了Spring Boot能接受的slf4j版本，否则日志崩得莫名其妙。

6.2 请求超时跟重试怎么配才算稳

大模型接口不像普通REST接口那么快，复杂模型生成几千字可能要几十秒。默认超时往往只有10秒，大概率会超时。我建议至少配60秒，长文生成场景直接给120秒。

OpenAiChatModel.builder() .timeout(Duration.ofSeconds(60)) .maxRetries(2) .build();

maxRetries不要配大。模型调用失败后重试相当于再花一次钱，而且很多接口虽然幂等但绝不免费。1到2次足够，更多次数造成的延迟和费用都不划算。特别提醒：如果你的工具方法里有副作用操作（比如写数据库），模型调用失败重试可能导致工具被重复执行，这类操作要自己保证幂等。

6.3 Token超限：上下文窗口塞爆了怎么办

报错信息里经常出现context length exceeded或maximum context length。这是ChatMemory窗口设大了，或者单轮输入本身超过了模型限制。处理思路有三步：先缩小WindowChatMemory.maxMessages；再检查系统提示词和工具描述是否冗长，精简掉无关内容；最后，如果长对话产品必须保留大量上下文，可以引入摘要式记忆——把达到一定长度的历史对话压缩成一句摘要再塞进系统提示词。这是LangChain4j里自定义压缩工具的活，效果比简单截断好很多。

6.4 工具调用不生效：从报文里找真相

我调试工具调用时的标准动作：先打开logRequests(true)和logResponses(true)，再看原始请求里tools字段是否存在。如果工具定义没进请求，说明工具注册没生效，检查是否忘了调.tools()。如果工具定义在但模型始终不调用，大概率是方法描述和用户问题的匹配度不够，或者模型本身不支持function calling（部分小参数模型确实不支持）。如果模型调用了但Java方法没执行，检查方法是否是public，以及返回类型能否被正确序列化。把这几层排查完，绝大部分问题都能定位。

6.5 问题排查速查表

7. 性能优化与工程化落地建议

7.1 控制并发：模型API不是你家的线程池

项目一上线，第一个问题是"每秒能处理多少个AI请求"。这里要冷静：大模型API的单次响应耗时通常在1到10秒，如果直接开50个线程并发调，不仅API端会限流，自己机器的线程池也会被占满。建议用独立的线程池管理模型调用，核心线程数根据API配额和业务量评估，别和普通RPC请求共用线程池。同步调用场景用ThreadPoolTaskExecutor，流式场景注意连接数是OkHttp线程池的两倍左右，否则高并发下连接建立会拖垮响应。

7.2 缓存：相同问题不该重复烧钱

很多咨询类问题其实是重复的，尤其知识库场景，"试用期是多久"这种问题一天可能被问几百次。给AiServices套一层缓存是非常有效的降本手段。用Caffeine按问题内容做短期缓存，命中则直接返回。但要注意：涉及实时数据的工具调用结果不该长期缓存，比如订单状态变了，缓存旧状态会误导用户。我的做法是：纯知识问答缓存5分钟，涉及实时数据查询的不缓存。

Cache<String, String> answerCache = Caffeine.newBuilder() .expireAfterWrite(Duration.ofMinutes(5)) .maximumSize(10000) .build(); String answer = answerCache.getIfPresent(question); if (answer == null) { answer = assistant.chat(question); answerCache.put(question, answer); }

7.3 模型路由：让每个请求用最合适的模型

预算充足不等于可以浪费。简单问题用便宜快速的轻量模型，复杂推理用重量模型，文档嵌入统一用专用嵌入模型。LangChain4j里可以封装一个ChatLanguageModelProvider，根据问题的关键词、长度、业务线动态返回不同模型实例。判断规则不用搞得多复杂，先按业务场景分：客服闲聊走轻量模型，专业分析走重量模型。这一层路由做好，账单能降三分之一。

7.4 安全与合规：API Key和敏感数据

API Key必须走环境变量或配置中心，禁止硬编码。日志打印时，模型请求响应里可能包含用户隐私，生产环境不要把logRequests一直开着，或者只对部分调试账号开启。工具方法返回的内容如果是用户订单、手机号，在递给模型之前先做脱敏，因为模型生成文本时可能会原样复述这些信息，一旦日志外泄就是事故。另外，对话数据留存要遵循业务合规要求，该删的删，该加密的加密，不要让AI项目成为数据安全的突破口。

7.5 可观测性：给AI调用加上完整链路

AI调用比普通接口更需要可观测性，因为你不知道每次调用到底花费了多少token、响应时间多长、模型是否走了工具调用。建议每次调用都记录：用户ID、模型名称、输入token数、输出token数、耗时、是否使用了工具、最终回答质量评估。LangChain4j有ChatModelListener机制，可以在自定义Listener里采集这些指标，再打到日志或监控系统。成本统计、异常告警、prompt效果迭代，全靠这份数据支撑。

8. 从Demo到生产的个人体会

跑通这几个Demo不难，真正难的是认清AI应用开发的边界在哪。我见过不少团队把业务逻辑一股脑写进提示词里，结果模型一升级，全部行为漂移。用LangChain4j的正确姿势是：模型负责理解意图和生成自然语言，工具负责确定动作和获取事实，RAG负责提供私域知识，三者各管一段，互不越界。查询助手场景里，订单状态必须走工具，制度问答必须走RAG，只有寒暄和总结才让模型自由发挥。

从成本角度看，建议所有接AI的业务先想三个问题：这个问题一定要大模型参与吗？能用规则解决吗？能缓存吗？AI不是银弹，用在该用的地方才划算。我在实际项目中已经踩过"把所有问题都丢给模型"的坑，后来改成规则过滤加模型生成，账单和响应速度都明显改善。

还有一个细节想分享：调试AI功能时，一定要学会利用框架日志，而不是盯着模型返回的结果看。模型输出是经过包装的，只有原始请求响应才能告诉你它到底有没有理解你的工具定义、检索到了什么内容、哪一步消耗了token。打开日志、读懂报文，多花十分钟换来的是后面少排查几小时。

现在LangChain4j已经是我Java后端项目的标配依赖了。它把AI这层复杂度封装得足够像"普通Java框架"，给不熟悉Python、又不想引入第二套技术栈的团队提供了一个很舒服的落地方案。照着这篇文章的步骤，你完全可以先跑通第一个对话应用，再慢慢往里面加工具、加知识库、加路由策略。这条路我已经替你趟过了，剩下的交给你的业务想象力。