LangChain4j不是LangChain的Java版，而是JVM原生LLM应用框架

1. LangChain4j不是LangChain的Java版而是为Java生态重新设计的LLM应用架构很多人第一次看到LangChain4j下意识会想“哦这是LangChain官方出的Java移植版”然后直接去翻Python文档、照搬Chain构造逻辑、硬套PromptTemplate语法——结果跑不通、报空指针、Agent死循环、RAG检索结果乱码。我去年带三个Java团队落地智能客服知识库时就踩过这个坑两个组按“LangChain Java版”思路硬啃两周没跑通一个可用链第三个组静下心读完LangChain4j的core模块源码后第三天就搭出了支持多路召回重排序的生产级RAG流水线。根本原因在于LangChain4j不是LangChain的翻译或封装而是一次面向JVM特性的架构重写。它没有复用Python版的BaseChain抽象不依赖CallbackManager做异步钩子也不走Runnable泛型链式调用路径。它的核心契约是ChatModel接口——一个纯粹的、符合Java函数式编程习惯的FunctionChatRequest, ChatResponse实现。你传入ChatRequest含messages、temperature、maxTokens等字段它返回ChatResponse含content、toolCalls、usage等结构中间不掺杂任何Python风格的动态属性注入或运行时元编程。这带来三个关键差异点第一生命周期管理完全不同。LangChain Python版里LLMChain实例可被反复调用状态隐式保留在memory中LangChain4j里ChatModel是无状态的纯函数所有上下文必须显式构造进ChatRequest.messages。你不能指望chatModel.invoke(prompt)自动记住上一轮对话——必须自己维护ListChatMessage并每次完整传入。这不是缺陷而是JVM对线程安全和内存可控性的刚性要求。第二工具调用Tool Calling机制彻底重构。Python版用tool装饰器注册函数运行时通过字符串匹配调用LangChain4j强制要求实现ToolSpecification接口并在ChatModel初始化时显式注入ListToolSpecification。每个工具必须声明name、description、parametersJSON Schema格式模型返回的toolCalls字段才可能被正确解析。我见过太多人把Python版的weather_tool Tool.from_function(...)直接翻译成Java的new Tool(...)却忘了parameters字段必须是合法JSON Schema字符串——少一个引号整个工具链就静默失败。第三RAG的抽象层级更高、更贴近Java工程实践。LangChain Python版的RetrievalQA是黑盒链你只管喂retrieverLangChain4j的RetrievalAugmentor是明确的策略接口它接收ChatRequest返回增强后的ChatRequest。你可以轻松插入自定义逻辑比如对用户问题做实体识别提取关键词再用关键词加权检索或者对召回的Document列表做语义去重不是简单比对pageContent字符串再按相关性分数截断。这种设计让RAG不再是“配个retriever就能跑”的玩具而是可调试、可监控、可灰度的生产组件。提示别被“LangChain4j”这个名字迷惑。把它当成一个全新框架来学——就像学Spring Boot不能靠Spring MVC经验一样。它的包结构、异常体系、配置方式、测试模式全部遵循Java生态的惯用法。强行套用Python思维只会让你在NullPointerException和IllegalArgumentException里反复横跳。2. 从零启动LangChain4j项目Maven依赖、基础配置与第一个Hello World链很多Java开发者卡在第一步连Hello World都跑不起来。不是代码写错而是依赖选错了版本、配置漏了关键项、甚至JDK版本不兼容。我整理了过去半年在6个不同客户现场验证过的最小可行配置确保你复制粘贴就能跑通。2.1 Maven依赖避开三个高危陷阱LangChain4j的Maven坐标看似简单但版本组合极易出问题。最新稳定版是0.32.0截至2024年7月但直接写version0.32.0/version会埋下三个雷雷一OpenAI依赖冲突。langchain4j-openai模块默认拉取openai-client:0.12.0但它依赖com.fasterxml.jackson.core:jackson-databind:2.15.2而你的Spring Boot 3.2.x项目可能已升级到2.16.1。运行时会抛NoSuchMethodError。解决方案强制排除旧版Jackson显式声明新版dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-openai/artifactId version0.32.0/version exclusions exclusion groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /exclusion /exclusions /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.16.1/version /dependency雷二Embedding模型绑定过死。langchain4j-embeddings-all-minilm-l6-v2这个starter包会把all-MiniLM-L6-v2模型文件下载到~/.langchain4j/embeddings/目录。但该模型是ONNX格式需要ai.djl.pytorch:pytorch-engine支持。如果你项目里没引入PyTorch引擎启动时就会卡在Downloading model...无限等待。生产环境强烈建议改用langchain4j-embeddings-hugging-face它通过HTTP调用Hugging Face Inference API无需本地模型文件dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-embeddings-hugging-face/artifactId version0.32.0/version /dependency雷三Spring Boot自动配置失效。LangChain4j提供了langchain4j-spring-boot-starter但它只在spring-boot-starter-parent:3.2.0下生效。如果你用的是Spring Boot 2.7.x仍有大量老系统在用必须手动配置Bean且不能用EnableLangChain4j注解。此时应降级使用langchain4j-spring-boot-starter:0.28.0并确认其spring-boot-dependencies版本匹配。最终推荐的最小依赖集Spring Boot 3.2.x OpenAI HuggingFace Embeddingdependencies !-- 核心框架 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.32.0/version /dependency !-- OpenAI大模型 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-openai/artifactId version0.32.0/version exclusions exclusion groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /exclusion /exclusions /dependency !-- HuggingFace嵌入模型避免本地模型下载 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-embeddings-hugging-face/artifactId version0.32.0/version /dependency !-- Jackson新版 -- dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.16.1/version /dependency /dependencies2.2 基础配置application.yml里的四行生死线LangChain4j的Spring Boot Starter会自动扫描application.yml但有四个配置项是启动必填的缺一不可# application.yml langchain4j: # 1. 必填指定使用的ChatModel类型值必须是类全名 chat-model: implementation: dev.langchain4j.model.openai.OpenAiChatModel # 2. 必填OpenAI API Key生产环境务必用环境变量 open-ai: api-key: ${OPENAI_API_KEY:sk-xxx} # 本地开发可临时写死上线必须移除 # 3. 必填Embedding模型配置HuggingFace需填API Token hugging-face: api-token: ${HUGGING_FACE_API_TOKEN:hf_xxx} model-name: sentence-transformers/all-MiniLM-L6-v2 # 4. 必填日志级别否则看不到关键执行链路 logging: level: dev.langchain4j: DEBUG特别注意chat-model.implementation字段它不是字符串枚举而是具体的Java类名。如果你换成AzureOpenAiChatModel这里就必须写dev.langchain4j.model.azure.AzureOpenAiChatModel。写错一个字母Spring Boot启动时不会报错但后续调用ChatModelBean时会抛NoSuchBeanDefinitionException——因为自动配置类找不到匹配的实现类。2.3 第一个Hello World链三行代码背后的执行逻辑别急着写复杂Chain先用最简代码验证环境Service public class HelloWorldService { Autowired private ChatModel chatModel; // Spring Boot Starter自动注入 public String sayHello(String userName) { // 构造标准ChatRequest必须包含messages列表且至少有一个UserMessage ChatRequest request ChatRequest.builder() .messages(UserMessage.from(你好我是 userName 请用一句话介绍你自己)) .build(); // 同步调用返回ChatResponse ChatResponse response chatModel.generate(request); // 提取模型返回的文本内容 return response.content().text(); } }这段代码背后发生了什么我们拆解执行链路chatModel.generate(request)调用的是OpenAiChatModel的generate方法它内部将ChatRequest转换为OpenAI API所需的JSON payloadPayload中messages字段被序列化为[{role:user,content:你好我是张三...}]temperature等参数取默认值0.7HTTP请求发往https://api.openai.com/v1/chat/completions响应体被反序列化为ChatResponseresponse.content().text()从ChatResponse的content字段类型为AiMessage中提取text属性。为什么强调“必须用UserMessage.from(...)”因为LangChain4j严格区分消息角色UserMessage、AiMessage、SystemMessage、ToolExecutionResultMessage。如果你直接传String框架会尝试用UserMessage构造器包装但某些版本会因类型推导失败而抛ClassCastException。显式调用UserMessage.from()是最安全的写法。注意首次运行会触发OpenAI API调用确保网络能访问api.openai.com。如果公司内网有代理需额外配置okhttp3.OkHttpClientBean设置proxy属性——这点官方文档完全没提但90%的企业环境都需要。3. RAG实战如何构建支持多路召回、语义重排、结果去重的生产级知识库RAG检索增强生成是LangChain4j最常落地的场景但网上90%的教程只教你怎么用InMemoryEmbeddingStore塞几条数据然后retriever.retrieve(Java面试题)——这离生产环境差了十万八千里。真实业务中你会遇到用户问“怎么解决ArrayList并发修改异常”但知识库里只有“CopyOnWriteArrayList原理”和“Collections.synchronizedList用法”两篇文档单路检索必然漏掉关键信息或者召回的10个片段里有3个讲的都是同一道面试题的不同解法内容高度重复。LangChain4j的RetrievalAugmentor接口就是为解决这些问题而生的。它不像Python版的RetrievalQA那样黑盒而是给你一个清晰的扩展点输入原始ChatRequest输出增强后的ChatRequest。我们以某金融客户的真实知识库为例构建一个支持三路召回Cross-Encoder重排语义去重的RAG流水线。3.1 多路召回融合向量检索、关键词检索、图谱关系检索单一向量检索的短板很明显对“ArrayList并发修改异常”这种技术名词组合语义向量可能把“ConcurrentModificationException”和“ArrayList”分开编码导致相似度偏低。我们采用三路并行召回策略召回通道技术实现优势LangChain4j适配方式向量检索HuggingFace Embedding InMemoryEmbeddingStore捕捉语义相似性EmbeddingStoreRetriever关键词检索Apache LuceneIndexSearcher精准匹配术语、缩写、错误拼写自定义Retriever实现findRelevant方法图谱关系检索Neo4j Cypher查询获取“异常-解决方案-示例代码”三元组自定义Retriever返回Document时设置metadata标注来源类型关键代码构建复合RetrieverBean public RetrieverDocument hybridRetriever( EmbeddingStoreRetriever vectorRetriever, KeywordRetriever keywordRetriever, GraphRetriever graphRetriever) { return query - { // 并行执行三路召回 ListDocument vectorDocs vectorRetriever.findRelevant(query); ListDocument keywordDocs keywordRetriever.findRelevant(query); ListDocument graphDocs graphRetriever.findRelevant(query); // 合并并去重按documentId return Stream.of(vectorDocs, keywordDocs, graphDocs) .flatMap(List::stream) .collect(Collectors.collectingAndThen( Collectors.toMap( Document::id, Function.identity(), (d1, d2) - d1), // 冲突时保留第一个 map - new ArrayList(map.values()) )); }; }这里Document.id是业务唯一标识如知识库文章ID不是LangChain4j自动生成的UUID。我们必须自己保证ID的全局唯一性否则toMap去重会丢失数据。3.2 语义重排Reranking用Cross-Encoder替代BM25传统RAG用BM25或向量相似度排序但它们只看Query和Document的独立表示。Cross-Encoder能联合建模Query-Document对效果提升显著。LangChain4j原生不支持Cross-Encoder但我们可以通过RetrievalAugmentor注入自定义重排逻辑Component public class CrossEncoderReranker implements RetrievalAugmentor { private final CrossEncoderModel crossEncoder; // 自研轻量级Cross-Encoder Override public ChatRequest augment(ChatRequest originalRequest, ListDocument retrievedDocuments) { String query extractUserQuery(originalRequest); // 从messages中提取用户问题 // 对每个Document计算Cross-Encoder打分 ListDocumentScore scoredDocs retrievedDocuments.stream() .map(doc - new DocumentScore(doc, crossEncoder.score(query, doc.text()))) .sorted((d1, d2) - Double.compare(d2.score, d1.score)) // 降序 .collect(Collectors.toList()); // 取Top 5用于后续增强 ListDocument top5 scoredDocs.stream() .limit(5) .map(DocumentScore::document) .collect(Collectors.toList()); // 构造增强后的ChatRequest在system message中注入召回内容 String systemPrompt buildRagSystemPrompt(top5); ListChatMessage enhancedMessages new ArrayList(originalRequest.messages()); enhancedMessages.add(0, SystemMessage.from(systemPrompt)); return ChatRequest.builder() .messages(enhancedMessages) .build(); } }buildRagSystemPrompt方法生成的system prompt长这样你是一个资深Java技术专家正在回答用户关于Java开发的问题。 以下是与问题相关的权威知识片段请严格基于这些片段回答不要编造 【片段1】标题ArrayList并发修改异常解决方案 内容使用CopyOnWriteArrayList替代ArrayList它在写操作时复制整个数组... 【片段2】标题Collections.synchronizedList详解 内容synchronizedList返回的对象在遍历时仍需手动同步...这个prompt结构经过AB测试验证相比直接拼接Document.text()加上【片段X】标题...的引导能让模型更准确地定位信息源减少幻觉。3.3 结果去重基于语义而非字符串的深度去重RetrievalAugmentor返回的ChatRequest其messages里已包含增强的system prompt。但用户真正看到的是模型生成的ChatResponse.content().text()。这时可能出现模型在回答中反复提及“CopyOnWriteArrayList”但知识库其实有3篇文档都讲了它——用户会觉得答案啰嗦、不精炼。LangChain4j提供ResponseFilter接口让我们在ChatResponse生成后、返回给前端前做最后处理Component public class SemanticDeduplicator implements ResponseFilter { Override public ChatResponse filter(ChatResponse originalResponse) { String rawText originalResponse.content().text(); // 将回答按句号/分号/换行切分为句子列表 ListString sentences splitIntoSentences(rawText); // 对每句话计算语义向量用MiniLM与知识库向量比对 ListString dedupedSentences new ArrayList(); SetString seenVectorHashes new HashSet(); for (String sentence : sentences) { if (sentence.trim().isEmpty()) continue; String vectorHash calculateSemanticHash(sentence); // MD5(encode(sentence)) if (!seenVectorHashes.contains(vectorHash)) { dedupedSentences.add(sentence); seenVectorHashes.add(vectorHash); } } String dedupedText String.join( , dedupedSentences); AiMessage aiMessage AiMessage.from(dedupedText); return ChatResponse.from(aiMessage, originalResponse.tokenUsage()); } }calculateSemanticHash是关键它调用MiniLM模型将句子编码为512维向量再对向量做MD5哈希。这样即使句子表述不同如“CopyOnWriteArrayList是线程安全的” vs “CopyOnWriteArrayList能保证多线程下的数据一致性”只要语义相近向量就接近MD5哈希也大概率相同。实测在Java技术文档场景去重准确率达92%远高于字符串级别的HashSetString去重。实战心得RAG不是“配个retriever就行”的功能开关而是一条需要精细调优的流水线。我们给客户部署时会固定三件事1向量模型用all-MiniLM-L6-v2小而快适合边缘部署2Cross-Encoder用bge-reranker-baseHuggingFace开源精度够用3去重阈值设为0.85余弦相似度低于此值才视为不同句子。这些参数来自200次线上A/B测试不是拍脑袋定的。4. Agent深度解析LangChain4j Agent不是“自动调用工具”而是状态机驱动的决策引擎网上很多教程把LangChain4j Agent讲成“模型自动选择工具并调用”这严重误导了开发者。真正的Agent是一个带状态、有记忆、能自我修正的决策循环。它不是一次调用就结束而是Plan → Execute → Observe → Reflect → Plan...的持续迭代。LangChain4j的DefaultAgent实现正是基于这个思想构建的状态机。4.1 Agent的核心循环从AgentExecution到AgentState当你调用agent.execute(查一下北京今天天气)实际发生的是AgentExecution创建初始AgentState包含messages用户问题、tools可用工具列表、maxIterations最大循环次数默认5进入while (state.iteration() maxIterations)循环每轮循环Plan阶段ChatModel接收当前state.messages返回AiMessage其中可能含toolCallsExecute阶段若AiMessage有toolCalls则逐个调用对应ToolExecutor将结果封装为ToolExecutionResultMessageObserve阶段将ToolExecutionResultMessage追加到state.messages末尾Reflect阶段检查AiMessage是否含content即模型已给出最终答案若是则跳出循环否则state.incrementIteration()进入下一轮。这个循环设计解决了Agent的三大痛点防死循环maxIterations硬性限制避免模型反复调用同一工具可追溯性AgentState.messages完整记录每一步的UserMessage、AiMessage、ToolExecutionResultMessage调试时可直接打印整个trace可中断性AgentState是不可变对象每次更新都生成新实例天然支持异步中断和状态快照。4.2 工具Tool注册的底层逻辑ToolSpecification与ToolExecutor的分离LangChain4j强制将工具的描述ToolSpecification和执行ToolExecutor分离这是比Python版更工程化的体现。ToolSpecification是纯数据对象只包含name、description、parametersJSON Schema字符串。它被序列化后发送给LLMLLM据此生成toolCallsToolExecutor是函数式接口FunctionToolExecutionRequest, ToolExecutionResult负责真正执行业务逻辑。为什么这样设计因为ToolSpecification.parameters必须是JSON Schema而Java的Parameter注解无法生成标准Schema。我们必须手动编写{ type: object, properties: { location: { type: string, description: 城市名称如北京 } }, required: [location] }而ToolExecutor的实现可以是public class WeatherToolExecutor implements ToolExecutor { Override public ToolExecutionResult execute(ToolExecutionRequest request) { String location request.argumentsAsMap().get(location).toString(); String weather weatherService.getWeather(location); // 真实调用天气API return ToolExecutionResult.builder() .content(weather) .build(); } }关键点在于request.argumentsAsMap()它把LLM返回的toolCalls中的argumentsJSON字符串反序列化为MapString, Object。LangChain4j用的是Jackson所以arguments必须是标准JSON不能是Python风格的{location: 北京}单引号非法。4.3 生产级Agent避坑指南五个必须处理的边界情况我在三个金融项目中部署Agent总结出五个高频崩溃点每个都附带修复代码坑一工具调用参数缺失LLM可能返回{name: weather, arguments: {}}导致argumentsAsMap()为空get(location)抛NPE。// 修复在ToolExecutor中校验必填参数 Override public ToolExecutionResult execute(ToolExecutionRequest request) { MapString, Object args request.argumentsAsMap(); if (!args.containsKey(location) || args.get(location) null) { return ToolExecutionResult.builder() .content(工具调用失败缺少必要参数location) .build(); } // ...正常逻辑 }坑二工具执行超时天气API可能慢于10秒导致Agent循环卡住。必须设置超时Bean public ToolExecutor weatherToolExecutor() { return new TimeoutToolExecutor( new WeatherToolExecutor(), Duration.ofSeconds(8) // 8秒超时 ); }坑三模型拒绝调用工具LLM可能返回AiMessage含content如“我不知道北京天气”但toolCalls为空。此时Agent应终止循环而不是继续迭代。// DefaultAgent源码中已处理但需确认版本0.30.0 // 低版本需自定义Agent实现在Plan阶段检查content非空则break坑四工具返回敏感信息天气API返回的JSON可能含apiKey: xxx被ToolExecutionResult原样返回给模型造成泄露。// 修复在ToolExecutor中过滤敏感字段 String safeJson json.replace(\apiKey\:\.*?\, \apiKey\:\***\); return ToolExecutionResult.builder().content(safeJson).build();坑五Agent状态爆炸每轮循环都追加ToolExecutionResultMessage10轮后messages列表过大影响性能。// 修复在AgentState构建时只保留最近5轮的交互 ListChatMessage recentMessages state.messages().subList( Math.max(0, state.messages().size() - 5), state.messages().size() );最后分享一个血泪教训不要在Agent里调用数据库查询工具。我们曾让Agent查MySQL获取用户订单结果高峰期Agent并发100数据库连接池瞬间打满。正确做法是把数据库查询封装成REST APIAgent调用HTTP工具由API网关控制QPS和熔断。Agent的职责永远是“决策”不是“执行”。5. 性能调优与可观测性如何让LangChain4j在生产环境稳定扛住5000 QPSLangChain4j默认配置是为开发调试设计的开箱即用的OpenAiChatModel在压测时QPS不到200延迟抖动极大。要让它在生产环境稳定服务5000 QPS必须做三件事1模型客户端连接池调优2Embedding缓存穿透防护3全链路可观测性埋点。这三点官方文档一个字都没提。5.1 OkHttp连接池从默认5个连接到200个连接的实测对比LangChain4j的OpenAiChatModel底层用OkHttp发送HTTP请求。默认配置是// OkHttp默认配置 new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .connectionPool(new ConnectionPool()) // 默认5个空闲连接5分钟超时在5000 QPS压测下这个配置会导致连接池耗尽新请求排队等待P99延迟飙升至8秒频繁创建销毁TCP连接CPU占用率超80%ConnectionPool的evictAll()被频繁触发缓存失效。我们实测调整为Bean public OkHttpClient okHttpClient() { return new OkHttpClient.Builder() .connectTimeout(5, TimeUnit.SECONDS) // 缩短连接超时 .readTimeout(15, TimeUnit.SECONDS) // 缩短读超时 .writeTimeout(15, TimeUnit.SECONDS) // 缩短写超时 .connectionPool(new ConnectionPool( 200, // 最大空闲连接数 5, // 每个路由最大空闲连接数 TimeUnit.MINUTES.toNanos(10) // 空闲连接10分钟超时 )) .build(); } Bean public ChatModel chatModel(OkHttpClient okHttpClient) { return OpenAiChatModel.builder() .baseUrl(https://api.openai.com/v1) .apiKey(System.getenv(OPENAI_API_KEY)) .client(okHttpClient) // 注入自定义OkHttpClient .build(); }效果对比阿里云ECS 8C16GJDK17配置QPSP50延迟P99延迟CPU使用率默认配置187120ms8200ms78%优化配置523095ms320ms42%关键点ConnectionPool的maxIdleConnections设为200但maxPerRoute必须设为5。因为OpenAI的api.openai.com是一个域名所有请求都走同一个Route如果maxPerRoute也设200可能导致单个域名连接过多被OpenAI限流他们对单IP的并发连接数有限制。5.2 Embedding缓存防止HuggingFace API被击穿的三级缓存策略langchain4j-embeddings-hugging-face模块默认不带缓存每次embed(text)都发起HTTP请求。Hugging Face免费API有严格限流每小时10000次5000 QPS下1秒就超限。我们设计三级缓存L1Caffeine本地缓存毫秒级内存L2Redis分布式缓存秒级跨节点共享L3本地磁盘缓存分钟级进程重启不丢Component public class CachedHuggingFaceEmbeddingModel extends HuggingFaceEmbeddingModel { private final CacheString, Embedding caffeineCache; private final RedisTemplateString, byte[] redisTemplate; private final File diskCacheDir; Override public ListEmbedding embedAll(ListString texts) { ListEmbedding results new ArrayList(); for (String text : texts) { // 1. 先查Caffeine Embedding embedding caffeineCache.getIfPresent(text); if (embedding ! null) { results.add(embedding); continue; } // 2. 再查Redis String cacheKey embedding: DigestUtils.md5Hex(text); byte[] bytes redisTemplate.opsForValue().get(cacheKey); if (bytes ! null) { embedding deserializeEmbedding(bytes); caffeineCache.put(text, embedding); results.add(embedding); continue; } // 3. 最后调用API embedding super.embed(text); // 同时写入三级缓存 caffeineCache.put(text, embedding); redisTemplate.opsForValue().set(cacheKey, serializeEmbedding(embedding), Duration.ofMinutes(10)); writeDiskCache(text, embedding); results.add(embedding); } return results; } }缓存键用MD5(text)而非原文避免Redis Key过长磁盘缓存用MappedByteBuffer写入避免频繁IO。实测后Hugging Face API调用量下降99.2%P99延迟从1200ms降至85ms。5.3 全链路可观测性用Micrometer埋点监控Agent决策质量LangChain4j自身不提供指标但我们可以用Micrometer在关键路径埋点。重点监控三个维度Agent决策质量agent_decision_success_rate成功返回答案的比率工具调用健康度tool_execution_duration_seconds各工具P95耗时RAG召回效果rag_retrieval_precision召回文档中真正被模型引用的比例Component public class AgentMetricsAspect { private final MeterRegistry meterRegistry; Around(annotation(dev.langchain4j.agent.Agent)) public Object monitorAgentExecution(ProceedingJoinPoint joinPoint) throws Throwable { long start System.nanoTime(); String agentName joinPoint.getSignature().getName(); try { Object result joinPoint.proceed(); // 计算决策成功率检查result是否为ChatResponse且含content boolean success result instanceof ChatResponse ((ChatResponse) result).content() ! null StringUtils.hasText(((ChatResponse) result).content().text()); Timer.builder(agent.decision.success.rate) .tag(agent, agentName) .register(meterRegistry) .record(success ? 1 : 0, TimeUnit.NANOSECONDS); return result; } finally { long duration System.nanoTime() - start; Timer.builder(agent.execution.duration) .tag(agent, agentName) .register(meterRegistry) .record(duration, TimeUnit.NANOSECONDS); } } }配合Grafana看板我们能实时看到当agent_decision_success_rate低于95%时自动告警当tool_execution_duration_seconds的P95超过2秒时触发工具降级如天气工具超时则返回“暂无法获取天气信息”。最后说个容易被忽略的点JVM参数调优。LangChain4j大量使用CompletableFuture和Stream必须关闭-XX:UseParallelGC并行GC会抢占CPU改用-XX:UseZGCZGC停顿时间10ms。我们在生产环境实测ZGC让P99延迟降低40%GC时间占比从12%降至0.3%。