Spring AI 的核心架构与工具调用

Spring AI 为 Spring 应用提供模型调用的抽象入口，并逐步覆盖结构化输出、向量存储和工具调用等常见能力。抽象能降低供应商切换成本，但不会自动解决工具授权或业务幂等问题。下面聚焦一次工具调用在应用中的实际路径。

典型调用链

应用通过 ChatClient 组织提示词、上下文与可用工具描述。模型可以返回普通文本，也可以返回工具调用请求。框架把工具请求映射到已注册的 Java 方法，执行结果再交给模型生成最终回答。模型负责提出选择，应用负责决定哪些工具可用以及如何执行。

@Bean
ChatClient supportClient(ChatClient.Builder builder, OrderTools tools) {
    return builder
        .defaultSystem("只根据已验证的订单信息回答。")
        .defaultTools(tools)
        .build();
}

接入时应对照项目实际使用的 Spring AI 版本确认 API 签名；本文强调架构流程，不承诺不同版本之间源码完全一致。

工具设计

工具应做一件小而明确的事。输入使用有约束的类型，处理可预期的空结果与业务错误，并避免直接把数据库实体暴露给模型。对写操作，工具内部仍要调用领域服务并遵循权限策略。

public record OrderLookupRequest(String orderId) {}

@Tool(description = "查询当前用户有权访问的订单摘要")
public OrderSummary lookupOrder(OrderLookupRequest request) {
    return orderService.findVisibleSummary(currentActor(), request.orderId());
}

currentActor() 必须来自可信的请求上下文，而不能由模型传入任意用户 ID。工具描述可以帮助模型选择，但它本身不是访问控制机制。

工程化检查点

• 设置连接与读取超时，并对可重试错误使用有上限的退避策略。
• 记录模型、耗时、用量和工具结果状态，同时对提示词及个人数据脱敏。
• 对工具输入做 Schema 与领域校验，返回面向模型的有限错误信息。
• 限制工具数量、调用次数和总执行预算。
• 为工具实现隔离测试，并为模型交互保留可替换的测试客户端。

工具调用成功只证明这条链路能跑通，不证明模型每次都会选对工具。把关键行为转成评测用例，并在变更模型、提示词或工具描述后重复验证。

参考资料

• Spring AI Reference
• Spring AI Tool Calling