🎯 今日核心问题
- 模型选错工具,是模型笨还是 schema 写得烂?怎么快速区分?
- description 里的哪些成分真正影响命中率,哪些纯属浪费 token?
- 嵌套对象、枚举、时间格式这些类型,怎么描述才不会让模型自由发挥?
- LangChain4j 的
@Tool/@P注解到底生成什么样的 JSON Schema,我怎么控制它?
📖 精读提纲
【一】schema 是模型的唯一说明书,不是给编译器看的
写 Java 接口时你关心类型和注解;写工具 schema 时你关心的应该是模型读到这段话会怎么理解。模型看到的只有三个东西:工具名、description、每个参数的 type + description。它不知道你的 OrderStatus 枚举有哪些值,不知道 orderNo 是必填还是可以模糊查询,更不知道"查订单"和"查物流"在你系统里是两个不同的表。所有它该知道而不知的,都是你的责任写清楚。所以判断标准很简单:把 schema 给一个刚入职的实习生看,他能不看代码就说清该在什么场景调用、参数怎么填吗?做不到,模型也做不到。
【二】四个决定命中率的描述要素
第一,触发条件而不是功能罗列。"查询订单"是功能,"用户想知道某笔订单当前状态、发货时间或能否退款时调用"是触发条件,后者命中率明显更高。第二,负向边界。工具之间最容易被混淆,必须显式写"不要用它查物流轨迹,那是 getShippingTrace 的职责"。第三,参数格式给例子。"订单号,形如 A123 或 B20261027001" 比 "订单号" 强十倍,能消掉大部分幻觉值。第四,返回什么要预告。description 里写"返回 status/shippedAt/refundable 三个字段",模型就知道一次调用够不够,减少无谓的重复调用。
【三】实战应用:Spring Boot 场景
在分层结构里,工具类应该是一个独立的 @Component(或 @Service),只依赖 Repository / 外部 Client,不依赖其它业务 Service,避免循环依赖和事务边界混乱。方法命名用动词开头、单一职责、不超过两个参数;超过两个就抽成 @ToolMemoryId 之外的 DTO 参数,用 @JsonPropertyDescription 给 DTO 字段写描述。枚举字段务必用 String 接收入参再在内部转换,因为模型对 Java 枚举名大小写极不稳定。查询类工具一律返回分页结构,别返回 List 全量——模型会把上千条记录全塞进上下文,直接爆 token。
【四】常见误区
- ❌ 用中文成语式命名工具,如
处理订单相关事项——一个工具干三件事,模型永远不知道什么时候该用它。 - ❌ description 写"这是一个查询订单的工具"就结束——零信息量,纯占 token。
- ❌ 参数用
Map<String,Object>——schema 变成空 object,模型只能瞎猜字段名。 - ❌ 工具数量堆到 30 个不分层——选择准确率会断崖下跌,应该按领域拆成多个 Agent 或加一层工具路由。
💻 代码示例
先看一份"烂"的和一份"好"的 schema 对比:
// ❌ 烂:模型只能靠猜
{
"name": "query",
"description": "查询订单",
"parameters": {
"type": "object",
"properties": { "no": { "type": "string" } },
"required": ["no"]
}
}
// ✅ 好:触发条件 + 格式示例 + 负向边界 + 返回预告
{
"name": "getOrderDetail",
"description": "查询单笔订单的当前状态、发货时间与是否可退款。当用户询问某笔订单是否发货、到货时间、能否退货退款时调用。不要用它查物流轨迹(请用 getShippingTrace)或查用户历史订单(请用 listUserOrders)。返回字段:status、shippedAt、refundable、refundReason。",
"parameters": {
"type": "object",
"properties": {
"orderNo": {
"type": "string",
"description": "订单号,形如 A123(短号)或 B20261027001(长号),不含空格"
},
"withItems": {
"type": "boolean",
"description": "是否返回订单商品明细,默认 false。仅在用户询问具体买了什么时设为 true"
}
},
"required": ["orderNo"],
"additionalProperties": false
}
}
用 LangChain4j 注解等价实现,DTO 字段描述靠 Jackson 注解传递:
public record OrderQuery(
@JsonPropertyDescription("订单号,形如 A123 或 B20261027001,不含空格")
String orderNo,
@JsonPropertyDescription("是否返回商品明细,仅在用户询问具体买了什么时设为 true")
Boolean withItems
) {}
public record OrderView(
String orderNo, String status, String shippedAt,
boolean refundable, String refundReason, List<ItemView> items) {
static OrderView from(Order o, boolean withItems) {
return new OrderView(o.getOrderNo(), o.getStatus().name(),
o.getShippedAt().toString(), o.isRefundable(), o.refundReason(),
withItems ? o.getItems().stream().map(ItemView::from).toList() : null);
}
}
@Component
@RequiredArgsConstructor
public class OrderTools {
private final OrderRepository repo;
@Tool("""
查询单笔订单的当前状态、发货时间与是否可退款。
当用户询问某笔订单是否发货、到货时间、能否退货退款时调用。
不要用它查物流轨迹(用 getShippingTrace)或查用户历史订单(用 listUserOrders)。
返回 status、shippedAt、refundable、refundReason。
""")
public OrderView getOrderDetail(OrderQuery q) {
Order o = repo.findByOrderNo(q.orderNo())
.orElseThrow(() -> new ToolNotFound("订单不存在: " + q.orderNo()));
// 长号才允许带明细,防止上下文被撑爆
boolean withItems = Boolean.TRUE.equals(q.withItems()) && q.orderNo().startsWith("B");
return OrderView.from(o, withItems);
}
}
想知道注解到底生成了什么 schema,直接打印出来核对——这是调优的第一步,不要凭想象:
@Test
void dumpSchema() throws Exception {
ToolSpecification spec = ToolSpecifications.toolSpecificationFrom(
OrderTools.class.getMethod("getOrderDetail", OrderQuery.class));
System.out.println(spec.toJson());
}
// 输出后逐项检查:description 是否包含边界说明、orderNo 是否有示例、
// additionalProperties 是否为 false(LangChain4j 默认不加,需要时自定义 ToolSpecification 补)
✏️ 今日动手
1)运行 dumpSchema(),把你的真实工具类 schema 打印出来存档;把 additionalProperties: false 手动补进 ToolSpecification 的 parameters 里,验证模型不再编造字段。
2)建一个 20 条问题的测试集(每条标注应该调用的工具名),写个 JUnit 用两版 description 各跑一遍,统计命中率。这是你后面所有工具优化的基准线。
3)故意把 getOrderDetail 的 description 改成"查询订单信息",再跑测试集,观察模型是否开始混用 listUserOrders,把失败案例抄进笔记。
🔖 明日预告
schema 写好了,接下来是工程问题:怎么在 Spring Boot 里做到"加一个 @Tool 就自动注册",而不是每个工具都在 AiServices.tools() 里手工列一遍。明天讲工具注册表、Bean 扫描与反射调用,含一个能动态增删工具的 DynamicToolRegistry。