🎯 今日核心问题

  1. 模型选错工具,是模型笨还是 schema 写得烂?怎么快速区分?
  2. description 里的哪些成分真正影响命中率,哪些纯属浪费 token?
  3. 嵌套对象、枚举、时间格式这些类型,怎么描述才不会让模型自由发挥?
  4. 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。

【四】常见误区

💻 代码示例

先看一份"烂"的和一份"好"的 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。