LangChain4j Tool Calling实战：让大模型自动查数据库发邮件

1. 从一句自然语言到两个真实动作这个项目到底在做什么第一次看到“让大模型自动查数据库发邮件”这个描述时我脑子里冒出来的画面是用户在聊天框里敲一句“帮我看看上周注册的用户里有多少还没激活顺便给这些人发封提醒邮件”然后系统自己就把这两件事干了——先去数据库里跑一条查询拿到结果再调用邮件服务把内容发出去。整个过程不需要用户点任何按钮也不需要开发者提前把“查数据库”和“发邮件”写成一个固定的业务流程。这就是LangChain4j Tool Calling要解决的核心问题。LangChain4j 是 Java 生态里做 LLM 应用集成的一个框架Tool Calling有些地方也叫 Function Calling是它提供的一种机制你把若干个 Java 方法注册成“工具”把每个工具的名字、用途、参数结构描述给大模型大模型在对话过程中自己判断“现在该调用哪个工具、传什么参数”框架负责把模型的意图翻译成真实的 Java 方法调用再把执行结果回传给模型让模型继续往下推理。这个项目适合谁参考三类人最直接一是已经在用 Java 做后端、想给现有系统加一层自然语言交互能力的开发者二是正在评估“要不要上 Agent”但被 Python 生态绑住、团队主力是 Java 的技术负责人三是想搞明白 Tool Calling 底层到底怎么跑通、而不是只会调 API 的进阶学习者。它解决的问题很具体——把“模型只会说”变成“模型能做事”而且是在 Java 技术栈里做不用为了一个 AI 功能把整个后端重写成 Python。我先把结论放前面Tool Calling 本身不复杂复杂的是工具描述怎么写、参数怎么校验、多轮调用怎么收敛、失败怎么兜底。这四件事决定了你的 Demo 能不能变成生产可用的东西。下面我按实际落地的顺序一层层拆开讲。2. 整体设计思路为什么是“工具注册 模型决策 框架执行”这套组合2.1 传统写法和 Tool Calling 的本质区别不用 Tool Calling 也能实现“查库发邮件”最朴素的做法是写一个 Service 方法里面按顺序调用 DAO 查询、再调用邮件客户端发送。这种写法的问题是流程是写死的。用户想查“上周注册未激活”你得写一个方法明天想查“本月付费但没续费的”你得再写一个方法。业务方的需求千变万化你的接口数量会爆炸。Tool Calling 换了个思路你不再描述“流程”而是描述“能力”。你告诉模型“我有一个工具能执行 SQL 查询”“我有一个工具能发邮件”至于什么时候用、怎么组合交给模型在对话中自己决定。这带来的直接好处是组合爆炸问题被转移了——你只需要维护 N 个原子工具模型可以组合出远多于 N 种的任务路径。我个人的判断是工具数量在 5 到 20 个之间时Tool Calling 的收益最明显。少于 5 个写死流程更省事多于 20 个模型选错工具的概率会上升需要引入工具分组或路由层。这个经验值不是拍脑袋来的后面讲参数设计时我会解释原因。2.2 为什么选 LangChain4j 而不是自己撸一套自己实现 Tool Calling 在技术上完全可行定义一套 JSON Schema 描述工具把用户输入和工具描述拼成 Prompt 发给模型解析模型返回的调用意图反射执行 Java 方法再把结果拼回去。但真做起来你会遇到一堆脏活不同模型厂商的 function calling 协议格式不一样OpenAI 一套、别的厂商又一套适配成本高多轮调用的消息历史管理很繁琐工具结果要以特定角色塞回对话流式输出和工具调用混在一起时事件顺序处理容易出错参数反序列化、类型转换、异常包装每个工具都要重复写。LangChain4j 把这些都封装了。你只需要用注解标记方法框架自动生成工具描述、自动处理协议差异、自动管理调用循环。选它的核心理由不是“功能多”而是“省掉了协议适配这层脏活”让团队能把精力放在工具本身的业务逻辑上。2.3 整体架构分层我把这个项目的结构拆成四层这样后面讲细节时你能对上号层级职责关键组件接入层接收用户输入、维护会话Controller、会话存储编排层模型交互、工具调用循环AiServices、ChatModel工具层具体能力实现带注解的 Java 方法基础设施层数据库、邮件、日志DataSource、MailClient编排层是核心它负责把用户的话变成工具调用序列。工具层是你要花最多心思的地方因为工具描述的质量直接决定模型调用的准确率。基础设施层反而是最成熟的用你现有的组件就行。提示不要一上来就设计十几个工具。先用两三个工具把整条链路跑通确认模型能正确调用、结果能正确回传再逐步扩充。我见过太多项目在工具设计阶段就陷入“到底该拆多细”的纠结结果链路一直没跑通。3. 核心细节解析工具描述、参数设计和调用循环3.1 工具描述怎么写才能让模型“看懂”模型决定调不调用一个工具靠的是你给它的文字描述。描述写得好模型调用准确率能到 90% 以上写得含糊可能一半的请求都调错工具。我总结了一个工具描述的三段式模板一句话说明这个工具做什么用动词开头比如“查询指定时间范围内的用户注册数据”说明什么时候该用它比如“当用户询问注册量、激活率等统计信息时使用”说明什么时候不该用它比如“不要用它执行写操作或删除操作”。第三点很多人会忽略但它特别重要。模型在没有明确边界时容易把“查询”工具拿去干“修改”的活。你明确告诉它“这个工具只读”它就会收敛。参数描述同样关键。每个参数都要写清楚含义、格式、取值范围。比如一个startDate参数你不能只写“开始日期”要写“开始日期格式 yyyy-MM-dd例如 2024-01-01”。模型对格式的敏感度很高你写清楚了它生成的参数基本不用二次修正。3.2 参数类型的选择为什么我倾向用简单类型LangChain4j 支持把复杂对象作为工具参数模型会生成嵌套的 JSON。但我的经验是能用 String、int、boolean 就别用嵌套对象。原因有两个。第一嵌套结构会显著增加模型生成错误的概率。层级越深模型漏字段、写错字段名的可能性越大。第二嵌套结构让参数校验变复杂你需要在工具方法里做多层判空。如果确实需要传多个相关参数我倾向于拆成多个平铺参数而不是包一个对象。比如查询用户用status、startDate、endDate三个平铺参数比传一个QueryCondition对象更稳。代价是参数列表变长但换来的是调用成功率提升这笔账划算。3.3 调用循环是怎么跑起来的一次完整的 Tool Calling 大致经历这几个阶段用户输入进入 AiService框架把系统提示、历史消息、工具描述一起发给模型模型返回一个“我要调用某工具、参数是这些”的响应而不是直接回答框架解析这个响应反射调用对应的 Java 方法拿到返回值框架把工具返回值作为一条新消息追加到对话历史再次发给模型模型基于工具结果生成最终回答或者决定再调用下一个工具重复 2 到 5直到模型不再请求工具调用输出最终文本。这里有个容易踩的坑循环没有硬性上限。如果模型陷入“调用工具→结果不满意→再调用”的死循环你的接口会一直转。LangChain4j 允许你配置最大调用轮数我一般设成 5 到 8 轮。超过这个数还没收敛基本可以判定是工具描述有问题或者任务本身超出了模型能力直接返回兜底提示比继续转下去更明智。3.4 工具方法的返回值怎么设计工具返回值会原样塞回给模型所以它的可读性直接影响模型下一步的判断。我见过有人让工具返回一个巨大的 JSON里面几十个字段模型看完直接懵了。正确的做法是只返回模型需要的信息并且用自然语言或简洁的结构化文本。比如查询用户数量返回上周注册用户共 1234 人其中未激活 456 人就比返回{total:1234,inactive:456,queryTime:...}更好。前者模型能直接理解后者还要多绕一层。如果确实需要结构化数据字段名也要用有意义的英文单词别用f1、f2这种。4. 实操过程从零把查库发邮件这条链路跑通4.1 环境准备与依赖引入假设你用的是 Maven 项目核心依赖是 LangChain4j 的主包和对应模型的集成包。版本选择上我建议用较新的稳定版因为 Tool Calling 相关的 API 在早期版本里变动比较频繁。dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency数据库和邮件用你项目里现有的组件就行我用 JDBC 和 JavaMail 举例换成 MyBatis、JPA、Spring Mail 原理一样。JDK 版本建议 17 以上LangChain4j 对高版本 JDK 支持更好。4.2 定义工具类两个原子能力先写查询工具。注意方法上的注解和参数描述这是模型能看懂的关键public class UserQueryTool { private final DataSource dataSource; public UserQueryTool(DataSource dataSource) { this.dataSource dataSource; } Tool(查询指定时间范围内注册的用户统计信息包括注册总数和未激活数量。当用户询问注册量、激活率等统计问题时使用。不要用于查询单个用户的详细信息。) public String queryUserStats( P(开始日期格式 yyyy-MM-dd例如 2024-01-01) String startDate, P(结束日期格式 yyyy-MM-dd例如 2024-01-07) String endDate) { // 实际查询逻辑 String sql SELECT COUNT(*) AS total, SUM(CASE WHEN activated 0 THEN 1 ELSE 0 END) AS inactive FROM users WHERE register_date BETWEEN ? AND ?; // 执行查询并格式化为自然语言 return 该时间段注册用户共 total 人其中未激活 inactive 人; } }再写邮件工具public class EmailTool { private final MailSender mailSender; Tool(向指定邮箱地址发送提醒邮件。当用户要求给某些人发送通知、提醒时使用。发送前请确认收件人列表和邮件内容已经明确。) public String sendReminder( P(收件人邮箱地址多个地址用英文逗号分隔) String recipients, P(邮件主题简洁明了) String subject, P(邮件正文内容) String content) { // 实际发送逻辑 mailSender.send(recipients, subject, content); return 邮件已成功发送至 recipients; } }两个工具都返回 String且是自然语言描述。这样模型拿到结果后能直接理解不需要额外解析。4.3 组装 AiService 并绑定工具把工具实例注册进 AiService框架会自动扫描注解生成工具描述public interface Assistant { SystemMessage(你是一个数据助手可以帮用户查询用户统计数据并发送邮件。 查询数据时使用 queryUserStats 工具发送邮件时使用 sendReminder 工具。 如果用户的需求需要多个步骤请按顺序依次调用工具。) String chat(String userMessage); } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .tools(new UserQueryTool(dataSource), new EmailTool(mailSender)) .build();系统提示里我特意强调了“按顺序依次调用工具”这是为了引导模型在多步任务中不要跳步。实测下来加了这句话之后模型在“先查再发”这类任务上的表现明显更稳定。4.4 跑通第一个多步任务用户输入“帮我查一下 2024-01-01 到 2024-01-07 注册的用户有多少没激活然后给这些用户发一封提醒邮件。”模型的处理路径大致是识别出需要先查询调用queryUserStats参数startDate2024-01-01、endDate2024-01-07拿到结果“注册 1234 人未激活 456 人”识别出需要发邮件但收件人列表它并不知道于是它会在最终回答里向用户询问收件人地址用户补充收件人后模型调用sendReminder完成发送。这里有个细节值得注意模型不会凭空编造收件人邮箱。因为我在工具描述里写了“发送前请确认收件人列表和邮件内容已经明确”模型会主动追问。如果你希望它自动从数据库里取邮箱那就需要再写一个“查询未激活用户邮箱”的工具让模型先调这个工具拿到邮箱列表再传给邮件工具。这就是工具拆分的艺术——拆得越细模型能组合的路径越多但调用轮数也越多。4.5 参数校验与异常兜底模型生成的参数不一定总是合法。日期格式写错、邮箱格式不对、必填参数缺失这些都可能发生。我的做法是在工具方法内部做严格校验校验失败时返回一句明确的错误说明而不是抛异常。if (!startDate.matches(\\d{4}-\\d{2}-\\d{2})) { return 日期格式错误请使用 yyyy-MM-dd 格式重新调用; }返回错误说明而不是抛异常的原因是模型看到错误说明后有机会自我修正重新生成正确参数再调一次。如果直接抛异常整个调用链就断了。这个技巧在实际项目里非常有用能把很多“一次调用失败”变成“模型自动重试后成功”。5. 常见问题与排查技巧实录5.1 模型不调用工具直接编答案这是最常见的问题。用户问“上周注册了多少人”模型不调工具直接编一个“大约 500 人”。原因通常是工具描述不够明确模型没意识到自己有这个能力。排查思路先看系统提示里有没有明确告诉模型“涉及数据查询必须使用工具”。如果提示里没写模型倾向于用自己的知识回答。其次看工具描述是不是写得太笼统。我一般会在系统提示里加一句“所有涉及具体数据的回答都必须通过工具获取不得凭记忆回答”这句话能挡掉大部分编答案的情况。5.2 工具调用参数错误模型把日期写成“上周一”、把数量写成中文数字这类问题很常见。解决办法是在参数描述里给出明确示例并且在工具方法里做容错解析。比如日期参数除了标准格式我还会尝试解析“上周”“本月”这类相对时间解析成功就转换失败才返回错误提示。5.3 多轮调用不收敛模型调了工具拿到结果又觉得不满意再调一次来回好几轮。这种情况多半是工具返回值让模型“困惑”了。检查工具返回的内容是不是太啰嗦、格式是不是混乱。把返回值精简成一句话往往就能解决。5.4 常见问题速查表问题现象可能原因解决方向模型不调工具直接回答系统提示未强制、工具描述模糊提示里加“必须用工具”描述写具体调用了错误的工具工具之间描述边界不清每个工具补充“不适用场景”参数格式错误参数描述缺示例描述里加格式和例子方法内做容错调用轮数过多工具返回值不清晰精简返回值用自然语言死循环不结束无最大轮数限制配置最大调用轮数超限兜底邮件重复发送模型重复调用发送工具发送工具加幂等校验或提示里强调只发一次5.5 几个我踩过的坑第一个坑是工具方法里做了耗时操作。有一次查询工具里跑了一个没加索引的全表扫描模型等结果等了十几秒整个对话卡住。后来我给所有工具方法加了超时控制超过 5 秒直接返回“查询超时请缩小查询范围”。模型拿到这个提示后会引导用户缩小范围体验反而更好。第二个坑是工具数量太多导致选择困难。我一度注册了十几个工具结果模型经常选错。后来我把工具按业务域分组每组用一个“路由工具”先判断该用哪组再在组内选具体工具。这个分层思路借鉴了微服务里的网关模式效果不错。第三个坑是忽略了对话历史的长度。多轮工具调用会把每次的工具结果都塞进历史几轮下来 token 消耗暴涨。我的做法是只保留最近几轮的工具结果更早的用摘要替代。这个优化让单次对话的成本降了差不多一半。6. 工具拆分的粒度一个决定项目成败的隐形变量6.1 拆得太粗和太细都不行工具粒度是这个项目里最需要反复权衡的设计决策。拆得太粗比如一个工具叫“处理用户相关的一切事务”模型根本不知道该传什么参数调用成功率极低。拆得太细比如“查询用户总数”“查询未激活数”“查询活跃数”各一个工具模型要在多个相似工具里选选错的概率上升而且调用轮数变多。我的经验法则是一个工具对应一个明确的业务动作参数控制在 1 到 4 个之间。超过 4 个参数说明这个工具承担了太多职责应该拆少于 1 个参数也就是无参工具说明它太泛模型不知道什么时候该用。6.2 用“动词 名词”命名工具工具名是模型判断用途的第一线索。我坚持用“动词 名词”的结构比如queryUserStats、sendReminder、updateUserStatus。动词表明操作类型名词表明操作对象。模型看到query开头就知道是读操作看到send就知道是发送动作。避免用userService、dataHandler这种名词性命名模型很难从中判断用途。6.3 读写工具要分开查询工具和写入工具一定要分开而且要在描述里明确标注。原因很简单读操作可以重试写操作重试可能造成副作用。如果模型把“查询”和“更新”混在一个工具里一旦它误判意图可能在你只想查询的时候改了数据。分开之后你还可以对写工具加额外的确认机制比如要求模型在调用写工具前先向用户确认。7. 影响范围与扩展方向这套方案还能用在哪Tool Calling 的价值远不止“查库发邮件”这一个场景。任何“需要模型根据自然语言决定调用哪个后端能力”的地方都能套这套模式。我梳理了几个扩展方向都是我在实际项目里验证过或见过同行落地的。客服工单系统用户描述问题模型判断该查订单、查物流还是提交退款自动调用对应工具。工具层对接现有的订单服务和物流接口模型只负责意图识别和参数提取。内部运维助手运维人员用自然语言描述需求模型调用“查服务器状态”“重启服务”“查看日志”等工具。写操作工具加二次确认读操作工具直接执行。数据分析问答业务人员问“上个月华东区的销售额是多少”模型调用查询工具把自然语言转成 SQL 条件返回结果。这个场景对工具描述的要求最高因为查询维度组合非常多。流程自动化把审批、通知、归档等动作封装成工具模型根据用户描述自动编排流程。这个方向最接近 Agent 的概念也是目前落地难度最大的因为流程的容错要求高。扩展时有个通用原则先加读工具再加写工具。读工具风险低可以快速验证模型的理解能力写工具一旦出错影响大要等读工具跑稳了再上。这个顺序能让你在低风险的前提下逐步建立对模型的信任。8. 性能与成本几个容易被忽略的账8.1 Token 消耗比你想的高每次工具调用都要把完整的工具描述、对话历史、工具结果发给模型。工具描述本身可能就有几百 token多轮调用下来一次对话的 token 消耗可能是普通对话的三到五倍。如果你的工具描述写得很长这个倍数还会更高。优化方向有两个一是精简工具描述去掉冗余的客套话只留关键信息二是控制对话历史长度只保留必要的上下文。我实测过把工具描述从 200 字压到 80 字单次对话成本能降 20% 左右。8.2 延迟主要来自模型调用次数一次多步任务可能触发三到五次模型调用每次调用都有网络往返延迟。如果模型服务本身响应慢用户体验会很差。缓解办法是给工具方法加缓存相同参数的查询直接返回缓存结果减少一次工具执行时间。另外能并行调用的工具尽量并行LangChain4j 支持一定程度的并行工具调用用好了能省不少时间。8.3 成本控制的底线思维上线前一定要算一笔账单次对话平均消耗多少 token乘以预估的日活和人均对话次数得出日成本。如果这个数字超出预算就要在工具粒度、描述长度、历史保留策略上做取舍。我的建议是先按最保守的估算上线观察真实数据后再优化而不是一开始就追求极致压缩把体验做差了。9. 我个人在实际操作中的几点体会这套东西我从最早的原型到后来在项目里正式用前后折腾了小半年有几个体会是文档里不会写的。工具描述值得你花 80% 的调试时间。我一开始觉得工具描述就是随便写写结果模型调用准确率惨不忍睹。后来我把每个工具的描述当成“给一个新同事写操作手册”来写准确率立刻上了一个台阶。描述里的每一句话都在影响模型的判断这句话不是夸张。不要指望模型一次就对。多步任务里模型第一步调对了第二步可能就偏了。我的做法是在关键节点加“确认点”比如发送邮件前让模型先输出“我准备给这些人发这封邮件确认吗”用户确认后再执行。这个设计牺牲了一点自动化程度但换来的是可控性在涉及写操作的场景里非常必要。日志要打全。每次工具调用的入参、出参、耗时、模型原始响应全部记下来。出问题时这些日志就是你的救命稻草。我遇到过模型偶尔抽风调错工具的情况靠日志才定位到是某次工具描述更新后引入的歧义。最后分享一个小技巧如果你发现模型在某个任务上表现不稳定先别急着换模型试试在系统提示里把这个任务的步骤显式写出来。比如“第一步查询第二步整理第三步发送”模型有了明确的步骤指引稳定性会明显提升。这个技巧成本极低但效果经常出乎意料。这套方案后续还能往两个方向扩展一是引入工具调用的可观测性把每次调用的链路追踪接进现有的监控体系二是做工具的动态注册让业务方能在不改代码的情况下新增工具。这两个方向我都在探索等跑通了再找机会细聊。