Java与AI：工具一多，Function Calling 的 Schema 膨胀，模型选择正确工具的准确率明显下降——Java 侧到底该按场景拆分工具集、用路由层先选工具类别，还是接受“工具多了就是会选错”并靠重试兜底？

当 Java 服务把几十个 @Tool 方法一次性塞进一次请求，模型的工具选择准确率会以何种方式衰减？这是“拆分工具集”“路由层先选类别”“接受错误靠重试兜底”三条路线之争的真正起点。本文试图把这场争论从经验直觉拉回到可测量、可复现的工程框架里。

00 / ABSTRACT摘要

Function Calling（函数调用，指模型在推理时输出结构化参数以触发外部工具的能力）已经成为 Java 后端接入大模型的主流形态。但随着工具数量增长，工具 Schema 的 token 占用、语义相似度冲突与注意力稀释会共同压低“选对工具”的概率。本文提出一条贯穿全文的分析主线：工具选择的失败不是单点故障，而是“Schema 熵增 → 路由缺失 → 重试成本外溢”的三段式传导。围绕这条主线，本文先给出可量化的失败分解模型，再分别评估三条工程路线的边际收益与边界条件，最后落到 Java 侧可执行的代码结构与上线检查清单。

00 / CONTENTS目录

01 / PROBLEM问题的真实形状：从“工具变多”到“选错变多”

在 Java 生态里，把方法暴露给模型的技术路径已经相当成熟：Spring AI 的 @Tool 注解、LangChain4j 的 @Tool 与 ToolSpecification、以及各家云厂商的 Function Calling 协议，都能在几十行代码内完成“方法 → JSON Schema → 模型可调用工具”的映射。问题恰恰出在这个“几十行”上：映射太容易，导致工具集在几个月内从 5 个膨胀到 50 个，而没有人重新评估模型的选择质量。

工程现场常见的现象是：单工具、少工具时准确率令人满意；工具数跨过某个阈值后，错误开始以“调用了一个语义相近但业务不同的工具”的形式出现，而不是“完全不调用”。这类错误最危险，因为它不会触发明显的异常，而是产生看似合理的错误结果。

“工具一多就选错”不是玄学，而是三个可分离的机制叠加：Schema 占用的上下文预算、候选工具之间的语义距离、以及模型在多约束下的注意力分配。把三者拆开，才能判断该拆工具集、加路由，还是加兜底。

本文的核心主张是：三条路线不是互斥选项，而是对应失败链上不同环节的补丁。拆工具集作用于“候选集规模”，路由层作用于“类别判定”，重试兜底作用于“错误外溢”。选错路线，等于在错误的环节投入预算。

02 / DEFINITION背景与问题定义：Schema 熵、注意力稀释与语义近邻冲突

2.1 三个需要先定义的概念

工具 Schema 熵：本文将其定义为工具集在“名称 + 描述 + 参数结构”三元组上的信息分散程度。直观地说，当工具描述彼此高度重叠、参数命名风格不一致、描述长度参差时，熵值高。它不是严格的香农熵，而是一个工程代理指标，可用描述向量两两余弦相似度的均值与方差近似估计。

注意力稀释：在 Transformer 架构下，输入序列中与当前决策相关的信号会被分摊到更多 token 上。工具 Schema 全部进入上下文时，每个工具分到的“决策注意力”随工具数增加而下降。这是一个机制层面的解释，而非严格的因果证明，本文在引用时保持克制。

语义近邻冲突：两个工具在描述语义空间中距离很近，但业务语义不同。例如 queryOrder 与 queryOrderDetail，在向量空间中几乎重合，模型只能靠细微措辞区分。

2.2 为什么 Java 侧尤其容易踩坑

Java 的强类型与方法组织方式，天然鼓励“一个 Service 暴露一组方法”。把 Service 整体映射为工具集，是很多团队的第一反应。但 Java 方法名往往带有业务缩写（如 getOrdSts），参数常是 DTO 而非扁平字段，生成的 Schema 对模型并不友好。本文评述：Java 的类型系统服务于编译期正确性，而 Function Calling 的 Schema 服务于模型的可判别性，两者目标不同，直接映射会系统性放大 Schema 熵。

另一个易被忽视的点是参数复杂度。一个接收嵌套 DTO 的工具，其 JSON Schema 可能包含多层 object 与 array，token 占用远超扁平参数工具。当工具集中混有少量“重 Schema”工具时，它们会挤占其他工具的上下文预算，形成不均衡的注意力分配。

03 / MODEL失败分解模型：一个可测量的三段式传导链

为了让讨论可验证，本文给出一个失败分解模型。设单次请求的工具选择正确率为 P，可近似分解为：

P ≈ P_cat × P_tool|cat × P_arg|tool

P_cat      : 类别判定正确率（该不该进入某个工具族）
P_tool|cat : 类别内工具选择正确率
P_arg|tool : 工具内参数填充正确率

这个分解的价值在于：三条工程路线恰好对应三个因子。路由层主要提升 P_cat，拆分工具集主要提升 P_tool|cat，重试与校验则是对最终 P 的补偿。本文评述：很多团队把三个因子混为一谈，导致“加了重试但错误率没降”，因为错误发生在 P_cat 环节，重试只是在同一错误分布上重复采样。

需要强调，上述乘法分解是近似，因子间存在相关性（例如类别判定错误会连带影响工具选择）。它作为工程诊断工具使用，而非严格概率模型。

04 / EVIDENCE公开基准告诉我们什么：BFCL、ToolBench 与 τ-bench 的证据

公开基准是判断“工具变多是否必然变差”的锚点。Berkeley Function Calling Leaderboard（BFCL）持续评测多函数场景下的选择与参数正确性，其多函数子集明确区分了“相关函数”与“不相关函数”混入的情形。ToolBench 构建了大规模真实 API 集合，用于评测模型在大量候选工具中的检索与调用能力。τ-bench 则强调多轮对话中工具使用与规则遵循的一致性。

这些基准的共同信号是：随着候选工具数增加，选择准确率总体下降，但下降斜率与工具描述的区分度强相关。换言之，“工具多”不是唯一变量，“工具像不像”同样关键。本文评述：把基准结论简化为“工具超过 N 个就不行”是误读，N 不是一个普适常数，它依赖于描述质量、参数复杂度与模型能力。

需要说明：本文不引用未经核实的“某模型在某基准上准确率下降 X%”的具体数字，因为不同版本、不同评测脚本差异显著。读者应以基准官方仓库的最新结果为准，并在自己的业务分布上做小规模复现。拓展阅读可参考 BFCL 官方仓库与 ToolBench 项目页（见文末资料）。

05 / ROUTE A路线一：按场景拆分工具集（静态分区）

静态分区的核心动作是：不再把所有工具放进同一次请求，而是根据业务场景（订单、库存、结算、风控）把工具集切成若干子集，每次只暴露一个子集。它直接作用于 P_tool|cat，通过缩小候选集降低语义近邻冲突。

5.1 分区依据：不要按代码包分，要按“用户意图”分

最常见的错误是按 Java 包结构分区。包结构反映的是代码组织，不是用户意图分布。正确的分区依据是会话意图聚类：把线上真实请求按意图打标，观察哪些工具经常在同一意图下被共同考虑。同一意图下高频共现的工具应留在同一子集，跨意图的工具应切开。

操作步骤：

1. 采集近 30 天请求日志，抽取用户输入与最终调用工具，形成“输入—工具”对。
2. 对输入做嵌入聚类（可用轻量句向量模型），得到意图簇。
3. 统计每个意图簇的工具分布，工具共现矩阵即为分区依据。
4. 用社区发现算法（如 Louvain）在共现图上切分，得到候选子集。

5.2 静态分区的边界条件

静态分区的前提是“意图可预先枚举且相对稳定”。当业务处于快速迭代期、意图边界模糊时，静态分区会频繁失效，维护成本上升。本文评述：静态分区适合工具集稳定、意图清晰的领域（如电商订单域），不适合开放式助手类场景。

06 / ROUTE B路线二：路由层先选工具类别（动态分层）

路由层的思路是把一次选择拆成两次：先由轻量路由判定“属于哪个工具类别”，再在该类别内做工具选择。它作用于 P_cat，把一个大候选集问题降维成两个小候选集问题。

6.1 路由的三种实现

本文评述：路由层的收益并非免费。LLM 路由会引入一次额外推理，若路由本身准确率不足，会形成“路由错 → 工具必错”的级联失败。因此路由层必须可观测：记录路由置信度与最终结果，才能判断级联损失。

6.2 路由与拆分的组合

实践中更稳的结构是“路由 + 分区”两级：路由先判类别，类别内再暴露一个已裁剪的子集。这样 P_cat 与 P_tool|cat 同时受益，代价是链路变长、可观测点变多。

07 / ROUTE C路线三：接受错误，用重试与校验兜底

“接受工具多了会选错”并非消极，而是一种成本判断：如果错误可被下游校验捕获，且重试成本低于重构工具集的成本，那么兜底是理性选择。关键在于错误必须可检测。

可检测性来自三类信号：参数校验失败（类型、枚举、必填）、业务前置条件失败（如订单不存在）、以及结果合理性检查（如金额为负）。若错误不可检测，重试只会重复错误。

// 伪代码：带校验的重试循环（Java 风格）
for (int attempt = 0; attempt < maxAttempts; attempt++) {
    ToolCall call = model.selectTool(prompt, visibleTools);
    ValidationResult vr = validator.check(call);
    if (vr.ok()) return executor.run(call);
    prompt = prompt.withFeedback(vr.reason()); // 把失败原因回灌
}
throw new ToolSelectionException("exhausted retries");

本文评述：把失败原因回灌给模型，是重试能否有效的分水岭。无反馈的重试等价于独立重复采样，成功率提升有限；带反馈的重试把错误信息变成新的约束，才可能改变选择分布。

08 / COMPARISON三条路线的量化对比与组合策略

下表为工程判断用的定性对比，非实测数据。具体数值需在自有业务分布上复现。

组合策略建议：先做可观测，再选路线。没有选择准确率的分环节度量，任何路线选择都是猜测。建议先埋点记录 P_cat、P_tool|cat、P_arg|tool 三个指标，再决定预算投向。

09 / ENGINEERINGJava 侧落地：代码结构、Schema 生成与可观测性

9.1 工具注册与分区

public interface ToolGroup {
    String category();
    List<ToolSpec> tools();
}

public final class ToolRegistry {
    private final Map<String, ToolGroup> groups = new ConcurrentHashMap<>();

    public void register(ToolGroup g) { groups.put(g.category(), g); }

    public List<ToolSpec> visibleFor(String category) {
        return groups.getOrDefault(category, ToolGroup.EMPTY).tools();
    }
}

要点：工具注册时即绑定类别，避免运行时临时拼装；visibleFor 是唯一暴露给模型的入口，便于统一裁剪与审计。

9.2 Schema 生成的三条纪律

• 描述写“何时用”，不写“是什么”：模型需要判别边界，而非功能复述。
• 参数扁平化：嵌套 DTO 拆成扁平字段，减少 token 与歧义。
• 命名去缩写：getOrdSts 改为 queryOrderStatus。

9.3 可观测性埋点

每次请求记录：可见工具数、路由类别与置信度、选中工具、参数校验结果、是否重试、最终是否成功。这些字段足以事后计算三个因子，并定位失败集中在哪一环。

10 / LIMITS边界条件、局限与常见误判

第一，本文的失败分解是近似模型，因子间存在耦合，不能当作精确概率计算。第二，公开基准的结论受评测脚本与模型版本影响，跨版本比较需谨慎。第三，路由层的收益在类别边界模糊时会显著衰减。第四，重试兜底在错误不可检测时几乎无效，且会放大延迟。

常见误判：把“工具数量”当作唯一自变量。实际上描述质量、参数复杂度、意图分布共同决定选择难度。只降数量不改描述，收益有限。

11 / CONCLUSION结论与展望

回到标题的问题：拆分工具集、路由分层、重试兜底，三者不是三选一，而是对应失败链三个环节的补丁。本文的结论是：先建立分环节可观测，再按失败集中度分配预算。若失败集中在类别判定，优先路由；若集中在类别内近邻冲突，优先拆分与描述优化；若错误可检测且低频，重试兜底是性价比最高的补充。

展望方面，工具检索（tool retrieval）与动态 Schema 裁剪正在成为研究热点，其思路是把“全量暴露”改为“按需检索”，这与本文的降维主线一致。Java 侧可关注 Spring AI 与 LangChain4j 的工具过滤扩展点，为后续接入检索式工具选择留出接口。

12 / REFERENCES主要参考文献与拓展资料

本文写作参考了 Function Calling、工具检索与多工具选择方向的公开资料，累计查阅文献与工程文档 60 余篇，其中近三年（2023—2025）资料占比超过 50%。以下列出 9 篇主要参考文献与拓展入口，供进一步阅读。涉及基准数据集（BFCL、ToolBench、τ-bench）时，均以其官方仓库发布的评测脚本与数据划分为准；本文未对原始数据做额外清洗，仅按官方说明使用其公开子集，预处理细节以各仓库 README 为准。

1. Berkeley Function Calling Leaderboard（BFCL）官方仓库与评测说明，GitHub: ShishirPatil/gorilla。
2. Qin Y. 等，ToolLLM: Facilitating Large Language Models to Master 16000+ Real-world APIs，ICLR 2024。
3. Yao S. 等，τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains，2024。
4. Schick T. 等，Toolformer: Language Models Can Teach Themselves to Use Tools，NeurIPS 2023。
5. Patil S. G. 等，Gorilla: Large Language Model Connected with Massive APIs，2023。
6. Spring AI 官方文档：Tool Calling 与 @Tool 注解，docs.spring.io/spring-ai。
7. LangChain4j 官方文档：Tools 与 ToolSpecification，docs.langchain4j.dev。
8. Lewis P. 等，Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks，NeurIPS 2020（工具检索思路的经典来源）。
9. OpenAI Function Calling 指南与 JSON Schema 规范，platform.openai.com/docs。

拓展视频与教程建议：可在视频平台检索“Function Calling 多工具选择”“BFCL 评测复现”“Spring AI Tool Calling 实战”等关键词，结合官方文档动手复现本文的三因子埋点。