用户说“找几款华为手机,再看看有没有库存”。模型可以理解关键词和查询意图,但实际有哪些商品、价格多少、哪个 SKU 有货,只能由商城提供。
商品 Tool 的作用,就是把模型提出的查询请求,转换成受限制的 Java 业务调用。模型选择工具,Java 查询数据,模型再组织回答。读完这一篇,应能沿着一次请求解释:数据从哪里来,参数在哪校验,以及怎样证明工具确实执行了。
本文基于 AgentShop 的
PortalProductTools、PortalAiConfig和商品 Service,按 2026-09-28 源码核对。代码片段聚焦商品查询,完整 Assistant 还包含订单、售后、RAG 与 Memory。
1. Tool Calling 是一次来回,不是模型直接查库
一次典型的查询过程如下:
用户:查一下华为手机 ↓模型返回工具名与参数 ↓LangChain4j 执行 searchProducts ↓商品 Service 查询商城 ↓Java 返回精简商品数据 ↓模型读取结果,生成中文答案模型返回的是“调用哪个工具、使用什么参数”的结构化请求,不是已经查询完成的商品。Java 执行之后,还要把结果发回模型。
例如,工具请求可以包含:
{ "name": "searchProducts", "arguments": { "keyword": "华为", "pageNum": 1, "pageSize": 5 }}这是方便阅读的请求示意,不是供应商原始响应,也不是完整 JSON Schema。框架根据 Java 方法上的 @Tool、参数类型和 @P 生成模型可见的工具描述,再负责执行与结果回传。LangChain4j Tools
一次用户请求可能调用模型多次,因此要分别计算模型调用耗时、工具耗时和总耗时。
2. 先把工具设计成三个业务问题
当前商品工具有三个:
| 工具 | 回答的问题 |
|---|---|
| searchProducts | 哪些商品符合关键词? |
| getProductDetail | 这个商品的基本信息是什么? |
| getProductStock | 这个商品有哪些库存信息? |
它们都留在 mall-portal,调用已有 PmsPortalProductService。共享模块 mall-ai 提供模型基础能力,不依赖前台的具体商品逻辑。
PortalAiAssistantController → PortalAssistant → PortalProductTools → PmsPortalProductService → Mapper / 数据库同一个应用内不需要让 Tool 绕回 Controller 或重新发一遍 HTTP 请求。Controller 与 Tool 是两个入口,业务规则应由它们共同调用的 Service 承担。
工具粒度要让模型容易选择,也便于限制开销。不要直接提供“执行任意 SQL”,也不必把每个 Getter 都变成一个工具。搜索返回候选商品 ID,用户追问具体商品时再查详情,这样每一步的输入和结果都明确。
3. 参数描述帮助模型,Java 校验限制实际执行
搜索方法公开三个参数:
@Tool("Search published AgentShop products by keyword.")public String searchProducts( @P("Product keyword") String keyword, @P("Page number, starts from 1") Integer pageNum, @P("Page size, at most 5") Integer pageSize) { // 校验、查询和 DTO 转换见下文}这是缩减后的签名示意。实际限制不能停留在描述文字中。当前实现将页码限制在 1~100,每页最多 5 条,关键词最多 50 个字符。页大小的处理是:
private int sanitizePageSize(Integer pageSize) { if (pageSize == null || pageSize < 1) { return 5; } return Math.min(pageSize, 5);}空关键词先返回输入问题,不进行无条件全库搜索。商品 ID 也需要检查是否为有效正数。
限制后的实际参数应体现在结果里,让模型知道自己拿到的是第几页、多少条。静默把“我要 1000 条”改成 5 条,却让回答声称列出了全部商品,会产生另一种误导。
Tool 输入是外部请求数据:即使它由模型生成,也需要长度、范围和业务合法性校验。
4. 可见商品范围不能只写在工具说明里
搜索 Service 的查询条件包含:
criteria.andDeleteStatusEqualTo(0);criteria.andPublishStatusEqualTo(1);这决定了前台搜索只返回未删除、已发布的商品。
详情和库存按商品 ID 读取,不能因为模型“正常应该只使用搜索结果里的 ID”,就忽略可见性检查。用户可以直接提供 ID,模型也可能从旧历史中取得已经下架的 ID。
当前 Tool 会检查商品的删除和发布状态;不可见商品不应继续把 SKU、详情和内部信息交给模型。若多个业务入口都依赖这条规则,最好让可见性约束成为 Service 的统一契约,避免每个入口各写一套。
这里要区分两个问题:
- 能否看这个商品:由当前业务规则判断。
- 数据库是否成功返回:属于运行状态。
查询异常不能随意改写成“商城没有该商品”,否则用户会把系统故障当作真实搜索结果。
5. DTO 决定模型看见哪些数据
直接序列化 PmsProduct 或完整商品详情,会把很多与回答无关的字段送进上下文,也会让数据库结构变化影响模型行为。
当前 ProductToolDtos 提供摘要、详情和库存结果。搜索摘要主要包含商品 ID、名称、品牌、价格、库存等字段。对于一句“查几款手机”,应优先提供足够比较和继续查询的信息。
一个用于说明的搜索结果可以是:
{ "keyword": "华为", "pageNum": 1, "pageSize": 5, "returnedCount": 1, "products": [ { "productId": 1001, "name": "示例手机", "price": 3999.00, "stock": 20 } ]}这是裁剪后的演示数据,不代表商城真实商品。DTO 中没有需要回答的字段,就不应让模型凭空补充。
价格字段尤其需要解释清楚:商品标价、促销价和最终结算价不是同一概念。只有查询和校验了活动条件,才能向用户承诺优惠后的价格;实际支付金额仍以结算服务为准。
6. 明细可以截断,汇总口径要保持完整
一个商品可能有 20 个 SKU。把所有明细发送给模型成本较高,因此当前工具最多展示 10 条,但总库存应基于完整 SKU 列表计算。
完整 SKU 列表 ├─ 汇总可用库存 └─ 裁剪前 10 条作为展示明细响应同时表达截断情况:
{ "availableStock": 180, "skuCount": 20, "returnedSkuCount": 10, "skuDetailsTruncated": true}这些数字是示例,重点是“总数量”与“当前展示数量”分别有字段。如果先截断再求和,就会把局部明细错误地当成总库存。
项目根据 stock 与 lockStock 计算 SKU 可用量,缺少 SKU 数据时使用商品库存作为回退。回答需要说明查询口径,不能把商品总数当作用户选定颜色、容量的可售数量。
库存查询也不是库存预留。查询时有 20 件,不代表稍后下单一定成功;下单服务仍需以提交时的库存约束为准。
7. 工具注册决定模型能请求哪些能力
只演示商品能力时,绑定结构可以简化为:
PortalAssistant assistant = AiServices.builder(PortalAssistant.class) .chatModel(chatModel) .tools(portalProductTools) .maxToolCallingRoundTrips(3) .build();这是说明绑定关系的片段,不是当前 PortalAiConfig 的完整替换版本。当前完整配置还注册了订单和售后工具,并将往返上限设为 5。
往返上限控制的是工具交互轮数,不能把它直接理解成“最多执行 3 个 Java 方法”:一次模型响应可能请求多个工具。总时间、单个工具预算、结果大小与模型调用费用,仍要独立限制。
商品描述也可能包含与商品无关的指令。去 HTML、清理控制字符和截断长度有助于压缩内容,但不能可靠识别所有提示注入。模型收到的商品文本始终应当作数据;真正可执行的能力由注册的工具、Java 参数校验和 Service 规则限制。
前台 Assistant 不应注册后台商品编辑或全量订单管理工具。与其要求模型“不要使用”,更可靠的是前台根本不提供这些能力。
8. 三层测试分别能证明什么
Tool 方法测试
Mock 商品 Service,直接调用 Tool,检查参数限制、可见性、DTO 字段和 SKU 截断。它能证明 Java 逻辑是否符合约定,但还没有经过模型和框架。
特别要覆盖“20 个 SKU、只返回 10 个明细”的场景,断言汇总依旧使用全部 SKU。
框架协议测试
使用可控的假 ChatModel,第一轮返回 searchProducts 请求,第二轮检查是否收到 ToolExecutionResultMessage,再返回固定答案。
这能证明工具已注册、参数能绑定、Java 方法执行后结果能回到模型。假模型已经被安排选择这个工具,因此不能证明真实 DeepSeek 会正确选择工具。
项目中的 PortalAssistantToolCallingTest 适合检查这条协议链。
真实模型评测
准备一组真实表达,例如“华为手机有哪些”“第二款有货吗”“查一个不存在的商品”。观察实际工具名、参数、返回商品 ID 与最终答案是否一致。
不要只检查回答包含“已查询”三个字。模型可以说自己查过,却没有发生工具调用;反过来,工具正常返回,也不保证最终答案没有改错价格。
9. 用当前入口复现商品查询
前台仍调用 POST /ai/portal/chat,携带有效会员登录态:
{ "conversationId": "product-demo", "message": "查一下华为手机,并告诉我具体商品 ID"}然后在同一会话追问某个真实返回的商品 ID。检查三个结果是否对应:
- 工具轨迹中的查询参数。
- Tool Result 中的商品、价格与库存。
- 最终答案中的具体字段。
当前接口的 data 是包含 conversationId 与 answer 的对象,旧 /ai/chat 已移除,接入方式见模型接入篇。
本文核对了源码和现有测试结构,没有重新执行真实模型评测。商品查询连通以后,涉及“我的订单”的问题还需要订单归属约束,不能直接复用公开商品的访问方式。
If this article helped you, please share it with others!
Some information may be outdated






