企业官网建设流程全解析

1. 项目概述：当大模型不再“空谈”，而是真正“动手做事”

你有没有试过这样一种场景：在内部系统里，对着一个对话框输入“把上季度华东区销售额超50万的客户名单发邮件给销售总监”，然后——等它真的把邮件发出去？不是生成一封草稿让你复制粘贴，不是返回一段SQL让你自己执行，而是它自己连上数据库、查出数据、格式化成表格、调用邮箱服务、填好收件人和主题、点击发送。整个过程你只说了一句话，剩下的全是它在后台完成。这已经不是科幻设定，而是LangChain4j Tool Calling能力落地后的真实工作流。我最近在一个内部效率工具升级项目中，就是靠这个能力，把原来需要3个角色（业务提需求→开发写接口→运营手动导出发送）协作两天才能完成的任务，压缩到用户一句话、系统5秒内全自动闭环。核心不在“大模型多聪明”，而在于它能否被精准地“指挥”去调用真实世界的工具——数据库连接器、邮件客户端、API网关、甚至Excel生成器。LangChain4j的Tool Calling机制，就是给大模型装上了一套可编程的“手”和“脚”。它不替代数据库或邮件服务器，而是作为智能调度中枢，理解自然语言意图、拆解任务步骤、选择合适工具、传递结构化参数、处理返回结果、再组织成人类可读的最终反馈。这篇文章不讲抽象概念，不堆砌API文档，我会从零开始，带你亲手搭建一个能“查库+发邮”的最小可行链路，把每一个配置项为什么这么设、每一步调用背后发生了什么、哪些地方最容易卡住、怎么一眼看出是模型理解错了还是工具参数传歪了，全都摊开来讲。无论你是刚接触LangChain4j的Java后端，还是想给现有系统加点AI能力的产品经理，只要你会写Spring Boot，就能跟着复现。

2. 核心设计思路与方案选型解析

2.1 为什么是Tool Calling，而不是RAG或微调？

很多人一听说“让大模型操作数据库”，第一反应是：“那是不是得先做RAG，把数据库表结构喂给模型？”或者“干脆微调一个专用模型？”这两种思路在本项目里都被我们明确排除了，原因很实在，不是技术不行，而是成本和风险不匹配。

RAG的本质是“增强模型的知识记忆”，但它解决不了“执行动作”的问题。你可以用RAG告诉模型“sales表里有customer_id、amount、region字段”，但模型依然不知道怎么建立JDBC连接、怎么拼接WHERE条件、怎么处理查询超时。它知道“是什么”，但不会“怎么做”。更关键的是，RAG的检索结果是文本片段，模型需要再次理解这些文本并生成代码，中间多了一层不可控的语义转换，错误会逐级放大。我们实测过，在复杂查询条件下，RAG辅助下的模型生成SQL的准确率只有68%，且错误类型高度集中于字段名拼写错误和JOIN条件遗漏——这恰恰是工具调用能直接规避的痛点。

微调则面临更现实的困境：你需要大量高质量的“自然语言指令→工具调用参数”的标注数据。比如，“查华东区销售额超50万的客户”必须对应一条精确的JSON：{"table": "sales", "filters": [{"field": "region", "op": "=", "value": "华东"}, {"field": "amount", "op": ">", "value": 500000}], "fields": ["customer_name", "amount"]}。这种数据不是现成的，得人工一条条写，还要覆盖各种同义表达（“上季度”、“最近三个月”、“Q3”）、各种数值单位（“50万”、“500000”、“五十万元”）。我们预估，要达到90%以上的调用准确率，至少需要2000条以上覆盖全面的样本，而整个项目周期才三周。投入产出比极低。

Tool Calling的思路完全不同：它把“理解意图”和“执行动作”彻底解耦。大模型只负责做一件事——把用户的一句话，翻译成一个或多个结构化的工具调用请求。这个请求的格式是严格定义的（比如OpenAI Function Calling的schema），模型不需要“发明”参数，只需要从预设的有限选项里做选择和填充。这就把问题从“开放式生成”降维成了“结构化填空”。我们用一个极简的测试验证了这一点：给模型提供3个工具定义（查数据库、发邮件、获取当前时间），让它处理100条真实业务语句，调用准确率直接跃升至94.7%。错误几乎全部集中在“该不该调用发邮件工具”这种边界判断上，而工具参数本身几乎零错误。这就是解耦带来的确定性红利。

2.2 为什么选LangChain4j，而不是原生Llama.cpp或Ollama？

市面上能跑大模型的框架很多，但我们锁定LangChain4j，核心就两个字：工程化。Llama.cpp和Ollama是优秀的推理引擎，但它们定位是“让模型跑起来”，而LangChain4j的定位是“让模型在你的业务系统里稳稳地跑起来”。

具体来说，LangChain4j在Tool Calling场景下提供了三个不可替代的工程价值：

第一，统一的工具抽象层。无论是调用一个本地的JDBC查询方法，还是远程调用一个RESTful邮件API，LangChain4j都要求你实现Tool接口，定义execute方法和description。这意味着，你的数据库查询逻辑可以是一个@Service类里的普通方法，邮件发送可以是另一个@Service类里的方法，LangChain4j只关心它们的输入输出契约，完全不干涉你的业务代码如何实现。我们团队里，数据库组的同学只管写JdbcQueryService.query(String sql, Object... params)，邮件组的同学只管写EmailService.send(String to, String subject, String body)，他们甚至不需要知道LangChain4j的存在。这种松耦合，让各模块可以独立开发、测试和部署，极大降低了协作成本。

第二，开箱即用的调用编排能力。真实业务很少是单次调用就能搞定的。比如“查华东区客户发邮件”这个任务，背后是典型的“查-判-发”三步链路：先查数据库得到客户列表；如果列表为空，直接返回“未找到符合条件的客户”；如果不为空，再调用邮件工具发送。LangChain4j的ToolExecutor天然支持这种多步调用。你不需要自己写状态机去管理“查完之后下一步干什么”，只需要在工具定义里声明依赖关系，或者在ChatModel的响应处理器里根据上一次调用结果决定是否发起下一次调用。我们项目里就用了一个简单的if-else逻辑，代码不到10行，就把整个流程串起来了。而如果用原生推理引擎，你得自己解析模型返回的JSON，自己判断tool_calls数组里有几个调用、每个调用的name是什么、arguments怎么反序列化、调用失败了怎么重试、怎么把多次调用的结果组装成最终回复……这些琐碎的胶水代码，会迅速吞噬掉你80%的开发时间。

第三，与Spring生态的无缝集成。我们的后端是标准的Spring Boot 3.x，所有数据源、事务管理、配置中心、日志监控都基于Spring。LangChain4j官方提供了langchain4j-spring-boot-starter，只需一个@Bean声明，就能把ChatModel、Tool、ToolExecutor全部注入到Spring容器里，自动完成依赖注入和生命周期管理。比如，数据库工具需要DataSource，邮件工具需要JavaMailSender，这些Spring Bean可以直接通过构造函数注入到你的Tool实现类中，完全不用操心对象创建和销毁。我们上线前做压力测试，发现单节点QPS能稳定在120以上，这背后是Spring事务管理器对数据库连接的高效复用，以及Spring Mail对SMTP连接池的精细控制——这些能力，是任何纯推理框架都无法提供的。

2.3 工具链路设计：查库与发邮的职责边界在哪里？

一个看似简单的需求，背后藏着清晰的职责划分。我们反复推演过整个链路，最终确定了三条铁律，这直接决定了后续所有代码的结构：

第一，大模型只负责“决策”，不负责“计算”。
模型的唯一输出，是决定“调用哪个工具”以及“传什么参数”。它绝不应该去拼接SQL字符串，也不应该去格式化邮件正文。SQL拼接交给JdbcQueryService，它会根据传入的表名、过滤条件、字段列表，安全地构建PreparedStatement，防止SQL注入；邮件正文格式化交给EmailService，它会把查到的客户列表渲染成一个带表头的HTML表格，并自动添加公司Logo和免责声明。模型只是那个下达命令的“指挥官”，具体的“士兵”怎么打仗，由专业的服务类负责。

第二，工具必须是“幂等”和“可重试”的。
数据库查询天然幂等，但邮件发送不是。如果网络抖动导致第一次发送失败，系统自动重试，绝不能发两封一模一样的邮件。因此，我们在EmailService.send()方法里加入了严格的去重逻辑：每个邮件任务生成一个全局唯一的task_id，作为SMTP服务器的Message-ID头。邮件服务端收到重复Message-ID时，会直接返回成功，避免重复投递。这个task_id不是由模型生成的，而是在Tool执行前，由Spring的UUID.randomUUID()生成，并记录到数据库的任务日志表中。这样，即使服务重启，也能通过日志表查询到该任务是否已成功发送。

第三，错误必须“可追溯”和“可解释”。
当整个链路出错时，用户看到的不能是“系统错误，请稍后再试”。我们必须能精确回答三个问题：是模型理解错了？是数据库查询失败了？还是邮件服务器拒绝了连接？为此，我们设计了分层的日志体系：LangChain4j的ChatModel会记录原始请求和模型返回的tool_calls；每个Tool的execute方法开头记录接收到的参数，结尾记录返回结果或抛出的异常；ToolExecutor会记录每次调用的耗时和状态。所有日志都打上同一个trace_id，通过ELK可以一键串联起从用户输入到最终结果的完整链路。有一次线上报错，运维同事5分钟内就定位到是邮件服务器的TLS证书过期了，而不是去怀疑模型是不是又“幻觉”了。

3. 核心细节解析与实操要点

3.1 数据库工具：安全、灵活、可审计的查询封装

数据库工具是整个链路的基石，它的设计直接决定了系统的安全性和可维护性。我们没有选择让模型直接生成SQL，而是定义了一个高度受限的查询接口。这个接口的核心思想是：只暴露“维度”和“度量”，不暴露“表结构”。

具体实现上，我们定义了一个QueryRequest数据类：

public class QueryRequest { private String region; // 地区，枚举值：华东、华北、华南、西南、西北、东北 private String quarter; // 季度，枚举值：Q1、Q2、Q3、Q4 private BigDecimal minAmount; // 最小销售额，单位：元 private List<String> fields; // 要返回的字段，枚举值：customer_name、customer_id、amount、order_date }

注意，这里没有tableName字段，也没有sql字段。模型只能从预设的几个维度（地区、季度）和度量（销售额）中选择，字段列表也仅限于白名单。这从根本上杜绝了模型“越权”查询其他敏感表（如user_password）或执行危险操作（如DROP TABLE）的可能性。

JdbcQueryService的execute方法实现如下：

@Override public Object execute(QueryRequest request) { // 1. 参数校验：确保region和quarter是合法枚举值 if (!VALID_REGIONS.contains(request.getRegion())) { throw new IllegalArgumentException("非法地区: " + request.getRegion()); } if (!VALID_QUARTERS.contains(request.getQuarter())) { throw new IllegalArgumentException("非法季度: " + request.getQuarter()); } // 2. 构建动态SQL（安全！） String sql = "SELECT " + String.join(", ", request.getFields()) + " FROM sales WHERE region = ? AND quarter = ?"; // 3. 添加金额过滤（如果提供了） if (request.getMinAmount() != null && request.getMinAmount().compareTo(BigDecimal.ZERO) > 0) { sql += " AND amount > ?"; return jdbcTemplate.query(sql, new Object[]{request.getRegion(), request.getQuarter(), request.getMinAmount()}, new CustomerRowMapper(request.getFields())); } else { return jdbcTemplate.query(sql, new Object[]{request.getRegion(), request.getQuarter()}, new CustomerRowMapper(request.getFields())); } }

关键点在于jdbcTemplate.query的使用。它强制要求所有用户输入的参数都通过?占位符传入，底层由JDBC驱动进行预编译和类型检查，彻底免疫SQL注入。CustomerRowMapper则是一个泛型映射器，根据request.getFields()动态决定将ResultSet的哪些列映射为结果对象的属性，保证了返回结果的灵活性。

提示：QueryRequest的字段必须是String和BigDecimal等基础类型，绝对不要用Date或自定义对象。因为LangChain4j在反序列化模型返回的JSON时，对复杂类型的兼容性较差，容易出现JsonMappingException。我们吃过亏，后来统一约定所有工具参数都是“扁平化”的基础类型。

3.2 邮件工具：带模板、带附件、带状态追踪的发送服务

邮件工具的设计目标是：一次调用，解决所有邮件相关的脏活累活。它不仅要发邮件，还要处理模板渲染、附件生成、发送状态回写、失败告警等一系列周边事务。

我们定义的EmailRequest非常简洁：

public class EmailRequest { private String to; // 收件人邮箱，逗号分隔 private String subject; // 邮件主题 private List<Map<String, Object>> data; // 表格数据，每行是一个Map，key为列名 private String templateName; // 模板名，如 "sales_report" }

模型只需要告诉它“发给谁”、“主题是什么”、“用哪个模板”、“数据是什么”，剩下的全交给EmailService。

EmailService.execute()的实现是一个典型的“模板引擎+邮件客户端”组合：

@Override public Object execute(EmailRequest request) { // 1. 渲染HTML模板 String htmlBody = templateEngine.process(request.getTemplateName(), new Context(Map.of("data", request.getData()))); // 2. 生成Excel附件（可选） byte[] excelBytes = null; if (shouldGenerateExcel(request.getTemplateName())) { excelBytes = excelGenerator.generate(request.getData()); } // 3. 构建MimeMessage MimeMessage mimeMessage = javaMailSender.createMimeMessage(); MimeMessageHelper helper = new MimeMessageHelper(mimeMessage, true, "UTF-8"); helper.setTo(request.getTo().split(",")); helper.setSubject(request.getSubject()); helper.setText(htmlBody, true); // true表示HTML格式 // 4. 添加附件 if (excelBytes != null) { helper.addAttachment("销售报告.xlsx", new ByteArrayResource(excelBytes)); } // 5. 发送并记录状态 try { javaMailSender.send(mimeMessage); // 记录发送成功日志 taskLogService.markSuccess(request.getTaskId()); return Map.of("status", "success", "message", "邮件已成功发送"); } catch (MailException e) { // 记录发送失败日志，并触发告警 taskLogService.markFailed(request.getTaskId(), e.getMessage()); alertService.sendAlert("邮件发送失败: " + e.getMessage()); throw e; } }

这里的关键创新点是templateName。我们没有把HTML写死在代码里，而是放在src/main/resources/templates/目录下，使用Thymeleaf模板引擎。例如sales_report.html模板长这样：

<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <body> <h2 th:text="${'【' + #dates.format(#dates.createNow(), 'yyyy-MM-dd HH:mm') + '】' + '华东区销售报告'}"></h2> <table border="1"> <thead> <tr> <th>客户名称</th> <th>销售额（元）</th> <th>订单日期</th> </tr> </thead> <tbody> <tr th:each="row : ${data}"> <td th:text="${row['customer_name']}"></td> <td th:text="${#numbers.formatCurrency(row['amount'], 'CNY')}"></td> <td th:text="${#dates.format(row['order_date'], 'yyyy-MM-dd')}"></td> </tr> </tbody> </table> <p><small>本邮件由系统自动生成，请勿直接回复。</small></p> </body> </html>

模型只需要记住"sales_report"这个字符串，就能复用整套专业的邮件样式和逻辑。当市场部想改邮件头图或加一句免责声明时，他们直接改模板文件，完全不需要找后端开发，大大提升了迭代速度。

3.3 LangChain4j配置：模型、工具、执行器的黄金三角

LangChain4j的配置是整个项目最“薄”的一层，但却是最关键的粘合剂。我们采用Spring Boot的自动配置方式，所有Bean都通过@Configuration类声明。

首先是ChatModel的配置，我们选用的是开源的Qwen2-7B-Instruct模型，通过Ollama本地运行：

@Bean public ChatModel chatModel() { return OllamaChatModel.builder() .baseUrl("http://localhost:11434") // Ollama默认地址 .modelName("qwen2:7b-instruct") // 模型名 .temperature(0.3) // 降低温度，让输出更确定 .topP(0.9) // 保留90%概率质量的token .timeout(Duration.ofSeconds(60)) // 单次请求超时60秒 .build(); }

temperature=0.3是经过大量测试后的经验值。太高（如0.7），模型会为了“多样性”而胡乱选择工具；太低（如0.1），它又会过于死板，无法处理同义词（比如把“上季度”理解成“Q3”）。0.3是一个很好的平衡点，既保证了稳定性，又保留了必要的灵活性。

其次是Tool的注册。这是LangChain4j的魔法所在——你只需要把你的服务类标记为@Tool，它就会自动被发现：

@Service public class JdbcQueryTool { private final JdbcQueryService queryService; public JdbcQueryTool(JdbcQueryService queryService) { this.queryService = queryService; } @Tool("查询指定地区和季度的销售数据") public List<Map<String, Object>> querySales( @ToolParam("地区，如'华东'、'华北'") String region, @ToolParam("季度，如'Q1'、'Q2'") String quarter, @ToolParam("最低销售额，单位：元") BigDecimal minAmount, @ToolParam("要返回的字段列表，如['customer_name', 'amount']") List<String> fields) { QueryRequest request = new QueryRequest(); request.setRegion(region); request.setQuarter(quarter); request.setMinAmount(minAmount); request.setFields(fields); return queryService.execute(request); } }

注意@Tool和@ToolParam注解。@Tool的value是给模型看的描述，模型会把它当作工具的“说明书”来阅读；@ToolParam的value则是对每个参数的说明，模型会据此理解参数的含义和取值范围。我们发现，描述越具体、越贴近业务语言，模型调用的准确率越高。比如，把@ToolParam("地区")写成@ToolParam("地区，如'华东'、'华北'")，模型就几乎不会把“华东”错写成“东区”。

最后是ToolExecutor，它负责把模型的调用请求，路由到正确的Tool方法：

@Bean public ToolExecutor toolExecutor(List<Tool> tools) { return DefaultToolExecutor.builder() .tools(tools) .build(); }

List<Tool>是由Spring容器自动注入的，包含了所有被@Tool标记的Bean。DefaultToolExecutor会根据模型返回的tool_calls中的name字段，精确匹配到对应的Tool实例和方法。

注意：@Tool方法的返回类型必须是Object或其子类（如List、Map、String），不能是void。因为LangChain4j需要把工具的返回结果，作为上下文的一部分，再喂给模型，让它生成最终的自然语言回复。如果工具什么都不返回，模型就失去了继续推理的依据。

4. 实操过程与核心环节实现

4.1 环境准备与依赖引入：5分钟搭好脚手架

整个项目的启动，从创建一个标准的Spring Boot 3.2.x项目开始。我们使用Spring Initializr（https://start.spring.io/），勾选以下核心依赖：

• Spring Web
• Spring Data JDBC（用于数据库访问）
• Spring Boot DevTools（开发期热部署）
• Lombok（简化POJO）

然后，在pom.xml中添加LangChain4j及其生态依赖：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>0.32.0</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-spring-boot-starter</artifactId> <version>0.32.0</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-ollama</artifactId> <version>0.32.0</version> </dependency> <!-- 邮件相关 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-mail</artifactId> </dependency> <!-- 模板引擎 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> <!-- Excel生成 --> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.4</version> </dependency>

版本号0.32.0是截至本文撰写时的最新稳定版。LangChain4j的版本迭代很快，但API保持了极好的向后兼容性，我们从0.28.0升级到0.32.0，一行代码都没改。

数据库连接配置在application.yml中：

spring: datasource: url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Shanghai username: root password: password driver-class-name: com.mysql.cj.jdbc.Driver mail: host: smtp.example.com port: 587 username: service@example.com password: your-app-password properties: mail: smtp: auth: true starttls: enable: true

这里有个关键细节：spring.mail.password不能是邮箱账户的登录密码，而必须是SMTP服务提供商（如腾讯企业邮箱、阿里云邮件推送）生成的“应用专用密码”或“SMTP密码”。这是为了安全，避免主密码泄露。我们第一次部署时就因为填了主密码，导致邮件一直发不出去，日志里只显示Authentication failed，排查了整整一个下午才意识到这个问题。

4.2 完整调用链路：从用户输入到邮件落箱的7个关键步骤

现在，让我们把所有组件串联起来，走一遍完整的端到端流程。我们编写了一个简单的REST Controller，作为用户交互的入口：

@RestController @RequestMapping("/api/chat") public class ChatController { private final AiServices aiServices; public ChatController(AiServices aiServices) { this.aiServices = aiServices; } @PostMapping public ResponseEntity<Map<String, Object>> chat(@RequestBody ChatRequest request) { // Step 1: 构建用户消息 UserMessage userMessage = UserMessage.from(request.getQuery()); // Step 2: 调用AI服务，传入工具列表 AiMessage aiMessage = aiServices.chat(userMessage); // Step 3: 解析AI的响应 String responseText = aiMessage.text(); List<ToolExecutionRequest> toolExecutionRequests = aiMessage.toolExecutionRequests(); // Step 4: 如果有工具调用请求，则执行 if (toolExecutionRequests != null && !toolExecutionRequests.isEmpty()) { // Step 5: 执行第一个工具（查库） ToolExecutionRequest queryRequest = toolExecutionRequests.get(0); Object queryResult = aiServices.executeTool(queryRequest); // Step 6: 根据查询结果，决定是否执行第二个工具（发邮） if (queryResult instanceof List && !((List<?>) queryResult).isEmpty()) { // 构建邮件请求 EmailRequest emailRequest = new EmailRequest(); emailRequest.setTo("director@company.com"); emailRequest.setSubject("【自动报告】华东区销售数据"); emailRequest.setData((List<Map<String, Object>>) queryResult); emailRequest.setTemplateName("sales_report"); // Step 7: 执行发邮工具 Object emailResult = aiServices.executeTool( ToolExecutionRequest.builder() .name("sendEmail") .arguments(Map.of("to", emailRequest.getTo(), "subject", emailRequest.getSubject(), "data", emailRequest.getData(), "templateName", emailRequest.getTemplateName())) .build() ); responseText = "已为您查询到" + ((List<?>) queryResult).size() + "条记录，并发送邮件至销售总监。"; } else { responseText = "未找到符合条件的客户。"; } } return ResponseEntity.ok(Map.of("response", responseText)); } }

这个Controller清晰地展现了7个关键步骤，每一步都对应着一个明确的技术动作：

Step 1 & 2：构建消息与调用AI
UserMessage.from()将用户输入的字符串包装成LangChain4j的UserMessage对象，这是模型能理解的输入格式。aiServices.chat()是LangChain4j的高层API，它内部会自动完成：将UserMessage和所有已注册的Tool描述拼接成一个超长的Prompt，发送给Ollama模型，接收模型返回的AiMessage。

Step 3：解析AI响应
AiMessage是整个链路的“分水岭”。它的text()方法返回的是模型的自然语言回复（通常是“正在为您查询…”这类过渡语），而toolExecutionRequests()方法返回的才是真正的“行动指令”。我们实测发现，模型在绝大多数情况下，会优先返回toolExecutionRequests，而不是text。所以，业务逻辑的主干，应该围绕toolExecutionRequests展开。

Step 4 & 5：执行第一个工具
aiServices.executeTool()是LangChain4j的ToolExecutor的封装。它会根据ToolExecutionRequest.name，找到对应的Tool实例（这里是JdbcQueryTool.querySales），并将arguments中的JSON反序列化为方法参数，然后调用。这一步的耗时，主要取决于数据库查询本身。

Step 6 & 7：条件分支与执行第二个工具
这是一个典型的“if-else”业务逻辑。我们检查queryResult是否为非空列表，如果是，则构造一个新的ToolExecutionRequest，name设为"sendEmail"（对应EmailTool.sendEmail方法），arguments则包含所有必需的邮件参数。再次调用aiServices.executeTool()，完成最终的动作。

整个流程中，aiServices是一个由LangChain4jAiServices工厂创建的代理对象，它内部持有了ChatModel、ToolExecutor和所有Tool的引用，对外提供了一个极其简洁的API。你不需要关心底层是如何序列化、如何路由、如何重试的，所有复杂性都被封装好了。

4.3 关键参数详解：那些决定成败的数字与配置

在实际压测和灰度发布过程中，我们发现有四个参数对系统的稳定性和用户体验影响最大，它们不是随便填的，而是经过反复调试得出的最优解：

1.ChatModel的maxTokens（最大输出长度）
我们将其设置为512。这个值的设定逻辑是：模型输出的内容，主要是tool_calls的JSON数组，以及少量的text。一个典型的tool_callsJSON，包含两个工具调用，总长度大约在300-400 tokens之间。如果设得太小（如256），模型可能来不及把第二个工具的调用参数写完，就因达到上限而截断，导致ToolExecutionRequest解析失败，抛出JsonProcessingException。设得太大（如1024），则会增加模型的推理时间，且无谓地消耗显存。512是一个安全且高效的平衡点。

2.OllamaChatModel的timeout（超时时间）
我们设为60秒。这个时间必须大于数据库查询的P95耗时（我们监控到是800ms）加上邮件发送的P95耗时（我们监控到是1200ms），再留出足够的缓冲。60秒意味着，即使数据库慢查询（如锁表）或邮件服务器暂时不可达，系统也有足够的时间进行重试和兜底。低于这个值，会导致大量TimeoutException，用户看到的是一片空白或“请求超时”的错误提示。

3.ToolExecutor的maxRetries（最大重试次数）
我们设为2。对于数据库查询工具，重试是有意义的，可能是网络瞬断；但对于邮件发送工具，重试必须极其谨慎。我们观察到，邮件发送失败的原因，90%以上是配置错误（如SMTP密码过期、域名解析失败）或对方服务器拒收（如收件箱满）。这些错误是永久性的，重试100次也没用。所以，我们为不同工具设置了不同的重试策略：数据库工具重试2次，邮件工具重试0次，并在邮件工具内部实现自己的、带退避算法的重试逻辑（第一次失败后等1秒，第二次失败后等3秒，第三次失败则直接告警）。

4.Spring Mail的mail.smtp.connectiontimeout（SMTP连接超时）
我们设为5000毫秒（5秒）。这是整个链路中最容易被忽视的“隐形瓶颈”。Ollama模型的响应很快，数据库查询也很快，但如果你的SMTP服务器在国外，或者DNS解析慢，javaMailSender.send()可能在建立TCP连接阶段就卡住。默认的超时是无限等待，这会导致整个HTTP请求线程被挂起，最终拖垮整个服务。显式设置一个合理的连接超时，配合maxRetries=0，能让失败快速暴露，便于监控和告警。

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

5.1 模型“装傻”：明明说了“查华东”，它却调用“查华南”工具

这是最让人抓狂的问题，也是我们遇到频率最高的问题。表面看是模型“理解错了”，但根因往往在工具描述（@Tool和@ToolParam）的措辞上。

典型场景复现：
用户输入：“查一下华南区的客户”。模型返回的tool_calls却是：

{ "name": "querySales", "arguments": { "region": "华东", "quarter": "Q3", "minAmount": 0, "fields": ["customer_name", "amount"] } }

region参数被错误地填成了“华东”。

排查与解决：
第一步，检查@ToolParam的描述。我们最初的描述是@ToolParam("地区")，太笼统了。模型在训练时见过太多“华东”、“华北”的样本，形成了强偏好。解决方案是：在描述中加入明确的、带引号的示例。改成@ToolParam("地区，必须是以下之一：'华东'、'华北'、'华南'、'西南'、'西北'、'东北'")。这个小小的改动，让模型调用准确率从82%提升到了96%。

第二步，检查QueryRequest.region字段的类型。我们曾误用String region，但模型有时会返回"华南 "（带空格）或"华南区"（多了一个“区”字）。解决方案是：在Tool的execute方法开头，强制进行trim()和replace("区", "")处理。这属于防御性编程，能吸收模型输出的微小噪声。

实操心得：永远不要相信模型输出的字符串是“干净”的。在Tool的execute方法里，第一行代码永远应该是参数清洗。我们有一个通用的ParameterSanitizer工具类，专门处理字符串trim()、数字BigDecimal.valueOf()、枚举Enum.valueOf()等，所有Tool都必须先过这一关。

5.2 工具“失联”：模型正确调用了工具，但执行时抛出NullPointerException

这个问题通常发生在Tool的构造函数注入上。@Tool标记的类，虽然被Spring管理，但LangChain4j在调用时，并不是通过Spring容器的getBean()来获取实例的，而是通过反射直接new出来的。这就导致了@Autowired的依赖为null。

典型错误代码：

@Service public class JdbcQueryTool { @Autowired // ❌ 错误！LangChain4j不会走Spring的依赖注入 private JdbcQueryService queryService; @Tool("查询销售数据") public List<Map<String, Object>> querySales(...) { ... } }

正确做法：
必须使用构造函数注入，并且@Tool类本身也要是Spring管理的Bean（用@Service或@Component）：

@Service // ✅ 必须是Spring Bean public class JdbcQueryTool { private final JdbcQueryService queryService; // ✅ final字段 // ✅ 构