ToolACE: Winning the Points of LLM Function Calling

§1 Motivation — 2024-09 那个时间点为什么还需要造数据

ToolACE 提交 arXiv 时 (2024-09-02),function-calling 这条赛道的训练数据格局大致是:

"real function-calling data is challenging to collect and annotate, while synthetic data from existing pipelines often lack coverage and accuracy... ToolACE comprehensively incorporates the broadest range of APIs and domains, supports complex nested parameters, accommodates both parallel and dependent function calls, and addresses various types of tool-related data." — abstract + Table 1 caption

论文 §1 + Table 1 的论点很直白:

• 规模上: ToolBench 16K → ToolACE 26K (50% 提升),但更重要的是多样性: 引入 nested 参数(参数本身是 list-of-list / list-of-dict)、parallel calls、dependent calls(后一个 call 的参数来自前一个 return)、multi-type(混合 tool-use 和不调用 tool 的 dialog)四种类型。同期没有任何数据集同时覆盖这四种。
• 准确性上: 旧数据集做 verification 多半只有"能不能解析成 JSON"这种 syntax check,ToolACE 提出 rule + model 双层 verification,论文 §2.4 + Figure 3 ablation 显示双层比无验证 overall 高若干 pp(后面 §4 详细谈)。
• complexity 上: 论文核心 thesis 是"LLMs learn most effectively when data complexity slightly exceeds their current capability"(引 Du et al. 2023)— 所以他们提出 用待训 LLM 当 complexity evaluator(self-guided),这一步是 ToolACE 区别于所有同期工作的方法论新意。

§2 三件套 TSS / SDG / DLV — 论文的 headline contribution

2.1 TSS — Tool Self-Evolution Synthesis (§2.2)

TSS 是造 API schema 的流水线,三阶段 Speciation → Adaptation → Evolution 命名直接借了生物学演化论的术语。

2.2 SDG — Self-Guided Dialog Generation (§2.3)

SDG 把 API schema 变 dialog,核心两个子模块:

2.2.1 Complexity Evaluator(论文的 novelty 所在)

论文观察到三件事(基于 LLM loss 的 empirical):

• data sample 的 loss 正相关于 (1) 候选 API 数; (2) 实际调用 API 数; (3) user query 和 API description 的相似度反距离。
• 所以可以把 用待训 LLM 自己跑数据,看 loss 大小当 complexity 度量。
• 训练数据的 complexity 应当 "略高于" LLM 当前能力(否则学不到东西,要么过简单要么过难)。

所以 complexity evaluator = 待训 LLM 本身。它评估当前 dialog 的 loss,如果太低就告诉 generator "再难一点"(加更多候选 API / 让 user 提更模糊的 query),太高就反向。

2.2.2 Multi-Agent Dialog Generator

三个 agent 各扮一角(三个 LLM instance):

四种 dialog 类型按比例混合: single function calls / parallel function calls / dependent function calls / non-tool-use dialogs — 后者(non-tool-use)是为了训 irrelevance detection 的关键。

2.3 DLV — Dual-Layer Validation (§2.4)

双层过滤,后一层比前一层贵。

Layer 1: Rule Verification (廉价)

规则 checker 检查 4 件事:

• API definition clarity: API 描述是否清晰、参数说明是否完整
• Function calling executability: API name 是否在 tool list 里 + 必需参数全提供 + 参数格式用 regex 验证 pattern
• Dialog correctness: 对话 role 切换正确 + JSON 解析通过
• Data sample consistency: 同一 dialog 内部信息不矛盾

Layer 2: Model Verification (贵)

Rule 通过的 sample 进 LLM 检查。这一步 论文发现一个工程教训: 直接把整条 dialog 给 LLM 让它判断对错,效果不好。改进方式是 把任务分解 成几个子查询,每个子查询由一个独立的 expert agent 负责,主要覆盖三件事(论文 §2.4 列出但 abbreviated, exact list see paper):

• API 调用顺序 / 参数语义是否合理
• response 是否对应 query
• 是否有重复、无意义 token

Ablation 结果(§3.3.1 + Figure 3)

论文用 LLaMA-3.1-8B-Instruct + LoRA 在三种数据上各训一个模型并测 BFCL:

• w.o. dual — 完全不过滤的原始合成数据 (数据量最大)
• w.o. model — 只过 rule checker
• Final — 双层都过(数据量最小,但质量最高)

结论: 更多过滤 → 数据更少但模型更好。Rule checker 单独已经能拉一些 executable accuracy,model checker 在 AST + overall 上贡献最大。这是经典 "质 > 量" 的实证。

§3 数据 — 26,507 API / 11,300 公开 dialog / 类型分布

3.1 数字精确清点

3.2 4 种 dialog 类型(论文反复对比的 4 维)

消融 (§D 附录): 论文逐一去掉某一类后训 LLaMA-3.1-8B 重测 BFCL,关键发现:

• 去掉 parallel → Non-live AST / Exec 都跌(BFCL 这些子项重度依赖 parallel)
• 去掉 multi-type(即 non-tool-use)→ irrelevance detection 直接掉到 6.99%(模型遇到无关 query 也强行调工具,无法说"这个不需要调工具")
• 去掉 nested / dependent → 影响很小 — 因为 BFCL 测样本几乎没要嵌套参数,也几乎没真 dependent

3.3 难度分层 (ToolACE-easy/medium/hard, §3.3.2)

论文用 Eq.(1) 的复杂度公式给每条样本打分,然后 按 bottom / middle / top 60,000 分别取出 ToolACE_easy / ToolACE_medium / ToolACE_hard 三个 60K 子集(stratified equal-size sampling, 控制 sample size 单一变量看 complexity 影响)。

§4 训练 + BFCL/API-Bank 结果 — 8B 真的追上 GPT-4 了吗

4.1 训练细节

4.2 BFCL-v3 主表(论文 Table 2, 截图 2024-09-20)

BFCL-v3 (即 V3 第一版) 当时分 Single-turn / Multi-turn / Hallucination 三大类,Overall 是 weighted average。论文 Table 2 列了 Top-20。关键数字:

数据来源: 论文 Table 2(从 HTML 提取). GPT-4 系列具体小数因 PDF 表格未完整截出, 未在 HTML 里 verbatim 确认; ToolACE-8B 这一行所有数字均 verbatim. ToolACE-8B 是当时第 3 名,前两名是 GPT-4-turbo 与 GPT-4o (都是 frontier closed model)。

论文自报的 4 个 highlight (§3.2):

1. Single-turn 89.27/90.07 几乎打平 GPT-4 系列;
2. Relevance 85.37 + Irrelevance 83.81 双高且平衡 — 论文称 "excellent balance",其它 model 多半 single 项很强但 irrel 很差(如 xLAM-7b-fc-r irrel 73.13 但 multi-turn 0%);
3. 显著强于 xLAM-7b-fc-r(同尺寸 function-calling 专用 fine-tune)在所有 category;
4. 对比 Functionary 等公开 fc 模型也全面领先。

4.3 API-Bank 结果(论文 Table 3)

API-Bank (Li et al. 2023) 是另一个 function-calling benchmark, 评测 metric 包括 call accuracy / response accuracy。ToolACE-8B 在 API-Bank 上:

• 显著优于所有开源 fc 模型;
• 媲美 GPT-4 系列(论文原话 "comparable performance with GPT-4-series models") — 这点在两个 benchmark 上都成立,所以是个 robust finding。

4.4 Generalization tests — 不只是 BFCL 上调好

论文 §3.3.3 + Figure 8 在 MMLU / HumanEval / GSM8K / CommonSenseQA 四个一般能力 benchmark 上对比:

• ToolACE-8B vs xLAM-7B-fc-r: 在 MMLU / GSM8K / CommonSenseQA 上 显著高 — 暗示 xLAM 训太狠把 general 能力洗掉了, ToolACE 数据"没洗丢通用能力";
• ToolACE-8B vs raw LLaMA-3.1-8B-Instruct: negligible degradation,在 BFCL 上则大涨;
• ToolACE-8B vs GPT-4: 在 reasoning / understanding 上仍有"clear limitations" — 模型 scale 限制。

结论: ToolACE 数据的"non-disruptive" 性质是它和 xLAM 系列拉开的关键。这其实是 ICLR 2025 reviewer 最看重的 generalization 故事 — 不是"造个 specialist 模型",而是"训完后还是个 general LLM, 但 fc 能力极强"。

4.5 Backbone 通用性(§3.3.3)

论文还用 ToolACE 数据训了一系列其它 8B-scale model(Qwen1.5-7B-Chat / Mistral-7B / LLaMA-2-7B 等),BFCL 全部大涨。Scaling law 实验(Qwen1.5 0.5B/1.8B/4B/7B)显示 fc 能力大致线性 scale up。这意味着 ToolACE 数据本身是 backbone-agnostic 的,可以喂任何 base model。

§5 License + 开源清单 — Apache-2.0 校订 + 团队全部资产清点

5.1 实地验证 — HF API 输出

$ curl -s https://huggingface.co/api/datasets/Team-ACE/ToolACE | jq '.cardData.license'
"apache-2.0"
$ curl -s https://huggingface.co/api/models/Team-ACE/ToolACE-8B | jq '.cardData.license'
"apache-2.0"
$ curl -s https://huggingface.co/api/models/Team-ACE/ToolACE-2-Llama-3.1-8B | jq '.cardData.license'
"apache-2.0"
$ curl -s https://huggingface.co/api/models/Team-ACE/ToolACE-2.5-Llama-3.1-8B | jq '.cardData.license'
"apache-2.0"

HF dataset README 头部 verbatim(2026-05-18 抓):

---
license: apache-2.0
task_categories:
- text-generation
language:
- en
- zh
tags:
- synthetic
- tools
size_categories:
- 10K<n<100K
---

HF model README 头部 verbatim:

---
license: apache-2.0
datasets:
- Team-ACE/ToolACE
language:
- en
metrics:
- accuracy
base_model: meta-llama/Meta-Llama-3.1-8B-Instruct
tags:
- code
new_version: Team-ACE/ToolACE-2-8B
---

结论 verdict: ToolACE 数据 + 三代 ToolACE/ToolACE-2/ToolACE-2.5 model 权重 全部 Apache-2.0, 可商用。 论文本身 (arXiv) 没专门声明 license,论文 acknowledgments 也没提 NC 字眼。所有可获得的 license signal 都指向 Apache-2.0。

5.2 那 "CC-BY-NC" 的传言哪来的

溯源后大概率是 把 xLAM 数据 (Salesforce 的 60K) 的 NC license 与 ToolACE 混淆 —— xLAM 数据集是 CC-BY-NC-4.0 的那个真 NC 资产,而 ToolACE 和它是同期、同主题但不同团队(华为 vs Salesforce)。一个可能的传链是: 早期 survey / blog 把"function-calling NC 数据"列成 xLAM, ToolACE, Hammer,后被引用者照抄,后来传到本系列 #31 §10.1.1。本笔记纠正:

5.3 Team-ACE 在 HF 上的完整资产清单 (2026-05-18)

5.4 GitHub 状况

实地确认: 华为团队没有公开 GitHub repo 发 ToolACE 代码或 pipeline。验证步骤:

• github.com/Team-ACE/ToolACE — 404
• github.com/HuaweiLin-CN/ToolACE — 404
• GitHub search q=ToolACE 返回的全部是社区 fork / 衍生品(zuoyifan132/ToolAce 6 ⭐ / aimedvedevq/toolaceqwen 1 ⭐ 等)

这是 ToolACE 开源完整度上的一个重要短板: 数据 + 模型 weights 公开了,但 合成 pipeline 代码、prompt 模板、TSS 的 context tree 构造、SDG 的 multi-agent prompt、DLV 的 rule + model checker 实现 全部没开源。#22 TOUCAN / #23 EnvScaler 都开了 pipeline 代码,这是它们的 differentiator。

§6 与本系列其它工作的连接

6.1 #22 TOUCAN (MIT-IBM + UW, 2025-10) — 规模 5× 但哲学相反

TOUCAN 在它的 abstract / Table 1 反复强调 "5× larger than Nemotron / ToolACE",这里隐含的对比是:

TOUCAN 把 ToolACE 当 "schema-only baseline" 来批判, 但 ToolACE 在它自己的时间点(2024-09,MCP 协议 11 月才发布)真 MCP server 还不存在 —— 所以 schema-only 不是设计缺陷而是历史约束。

6.2 #27 SmallModelMCP landscape — ≤40B 标杆

#27 把 ToolACE 列在学术线 5 篇之一(另 4 篇是 TOUCAN/EnvScaler/SETA/AWM/Agent-World)。它是这条线里最早 8B 触到 GPT-4 的工作,因此后来的 7B-8B 训练方案默认拿 ToolACE-8B 或 ToolACE-2-8B 当起点。#29 EnvTuning 把 ToolACE-2-8B 当 baseline,从 35.74 训到 54.34(BFCL-v3)。

6.3 #28 BFCL — 评测基础设施

ToolACE 是 BFCL 历史上的第一个 8B 学术贡献 —— V1/V2 时代 leaderboard 主要是闭源模型 + 商用 fine-tune (Functionary 等),V3 (2024-09-19) 上线后 ToolACE-8B 在 2024-09-20 截图里达到 Rank 3。但 V4 (2025-07-17) 重排公式后,Multi-Turn 和 Agentic 权重上升到 70% — 原始 ToolACE-8B 在 V4 上排名会大幅下滑(因为它的 multi-turn 只有 14%)。这就是为什么团队后来出 ToolACE-2 / ToolACE-2.5 — 主线就是补 multi-turn。

6.4 #29 EnvTuning — ToolACE-2-8B 是核心 baseline

EnvTuning (蚂蚁 AWorld, ICLR 2026) 拿 ToolACE-2-Llama-3.1-8B 当 baseline, 跑 4-stage curriculum + Actionable Augmentation + Progress Reward 这套 recipe, BFCL V3 上 35.74 → 54.34 (+18.60 pp), 超 GPT-4o 51.x / o3 49.25。同时在 #30 ACEBench OOD 上 8.34 → 15.00 (Multi-Turn) 和 6.67 → 20.00 (Multi-Step)。这说明 ToolACE-2-8B 的 SFT 起点 + EnvTuning 的 RL 课程 = 当前 8B function-calling 最强组合之一。

6.5 #30 ACEBench — 同组的"姐妹工作"

ACEBench 2025-01 上 arXiv, EMNLP 2025 Findings 录用, 团队是 USTC + Huawei Noah's Ark, 作者表与 ToolACE 大幅重合(Weiwen Liu / Xingshan Zeng / Yasheng Wang / Xu Huang / Xinlong Hao 等核心 5 人都在两篇都署名)。这是同一团队"训完 ToolACE-8B 后,意识到 BFCL V1 偏 schema 偏单轮偏英文,无法刻画真正中文工业落地,于是花一年时间另起 ACEBench"的反馈循环结果。

6.6 #31 Prime Intellect Hub §10.1.1 — license 校订点

#31 §10.1.1 表格里把 ToolACE 列进 CC-BY-NC-4.0 风险条 — 这是错的(见 §5)。正确做法是从那条风险条里去掉 "ToolACE 部分",只保留 "xLAM-60K, Hammer-data" — 后者才是真 NC 资产。同时 #31 §10.5 的"训练 datalist 决策树"里 "避免 CC-BY-NC 数据 (xLAM-60K / Hammer-data / ToolACE)" 的 ToolACE 也应当移除。

6.7 #34 ToolMind — 真实"用了 ToolACE 7,327 条"但合规没问题

ToolMind 在 augmented open-source 部分包含 7,327 条 ToolACE 派生样本(精确数字 #34 §3.4 verbatim)。因为 ToolACE 实际是 Apache-2.0,所以 ToolMind 整库自标 Apache-2.0 是合规的,不存在"NC 染色"问题。这一点 #34 §6 + §10 整段关于"license 混染"的论证 需要全部撤回。纠正后的版本: ToolMind 含的 7 个数据源里, 真有 NC 问题的只有 xLAM-60K (101K 条 augmented) — 这一点 #34 应当只标 xLAM 那一条 NC, 其它(Glaive/ToolACE/BUTTON/APIGen-MT/When2Call/τ-bench train)的 license 状态各自独立查证, 但 ToolACE 这条肯定是 clean 的。

§7 一年半回望 — 后继 ToolACE-R/DEV/MT · watt-tool · 局限

7.1 团队后续工作链 (ToolACE 衍生 paper)

从 ToolACE-2.5 model README 里能看到团队后续放出的三篇 follow-up paper, 全是同组接续:

加上 ACEBench (2501.12851, 2025-01), 整个团队的产出轨迹是: 2024-09 ToolACE 造数据 → 2025-01 ACEBench 造尺 → 2025-04 ToolACE-R 自我改进 → 2025-05 ToolACE-DEV 任务分解 → 2025-08 ToolACE-MT 多轮加速。三个 model variants(8B/2-8B/2.5-8B)对应了"初代 SFT → R+DEV 联合 → MT 多轮特化"的三步演进。

7.2 community 衍生 — watt-tool-8B

watt-tool-8B (HF watt-ai/watt-tool-8B, Apache-2.0) 是 ToolACE 系列影响力最大的 community fork。它的 README verbatim 说:

"watt-tool-8B is a fine-tuned language model based on LLaMa-3.1-8B-Instruct, optimized for tool usage and multi-turn dialogue... The training process is inspired by the principles outlined in the paper: 'Direct Multi-Turn Preference Optimization for Language Agents'. We use SFT and DMPO to further enhance the model's performance in multi-turn agent tasks."

watt-tool-8B 的核心 differentiator 是 多加了 DMPO (Direct Multi-Turn Preference Optimization, arXiv:2406.14868) — 把 ToolACE 数据 + DMPO 算法,做 multi-turn 偏好优化。它在 #29 EnvTuning Table 中作为 baseline (BFCL V3 35.74 → 54.34 via EnvTuning recipe)。License 也是 Apache-2.0。

watt-tool-8B 是否真在 ToolACE 数据上训 — 未在公开来源 verbatim 确认 — README 没明说底层数据来源,只说"specialized dataset for tool usage and multi-turn dialogue",但社区普遍认为它 fine-tune 自 ToolACE-8B 类似数据(论文 inspiration 也是 multi-turn preference)。

7.3 局限性 — ToolACE 的"三大根本约束"

(1) Tool response 全是 LLM 模拟,不是真 server

这是 §2.2.2 提到的,也是 #22 TOUCAN 整篇论文的对照面。后果: ToolACE-8B 在真 MCP server 上(如 MCP-Universe / MCPMark)表现可能脱节 —— 因为它训练时从没见过 rate-limit / auth-fail / timeout 等真实错误。#22 TOUCAN Section 3 实验显示, schema-only 数据训的模型遇到真 server error 会持续重试或编造结果。但这一点对 BFCL 评测无害, 因为 BFCL 本身也是 schema-based。

(2) Multi-turn 弱(初代 14.37)

BFCL-v3 加入 1000 条 multi-turn 后, ToolACE-8B Multi-turn 只有 14.37 — 远低于它 single-turn 89.27 的 spotlight。这是 SFT-only 模型的普遍弱点, 团队 ToolACE-2 + ToolACE-2.5 已经针对性补强。但 V4 (2025-07) Agentic 权重又上升, 又把这个问题放大了一次 — V4 leaderboard 上, ≤40B 模型领先的是 Qwen3-32B / GLM-4.5 那种 base 自带 agentic 能力的, ToolACE 系列优势不再显著。

(3) Pipeline 代码全闭源 — 无法复现合成过程

论文细描了 TSS / SDG / DLV 三件套, 但 没有任何公开 GitHub repo 包含实现。其它 contemporary 工作中:

• #22 TOUCAN 完全开 pipeline (MIT 代码)
• #23 EnvScaler 完全开
• #34 ToolMind 数据开但 pipeline / judge LM 闭源
• ToolACE 数据 + 模型开,pipeline 全闭

这是 ToolACE 在"复现性"这个维度上的最大短板 — 你能用它的数据,但你想自己跑 ToolACE pipeline 造新数据 是不可能的。

7.4 ToolACE 是否被后继工作超越 — 一年半时间表

结论: ToolACE 在 规模 上被 TOUCAN 超越,在 真实度 上被 TOUCAN/EnvScaler 超越,在 方法论 上被 ToolMind 的 turn-level filter 补丁,在 多轮 上被它自己的 2.5 代和后继 RL 工作覆盖。但作为 SFT 数据 starting point, ToolACE-2/2.5-8B 仍然是 ≤40B 函数调用社区的事实标准之一,在 2026-05 的当下,它和 watt-tool-8B 仍然被 #29 EnvTuning 当 baseline. 它的 历史地位 是: 第一个证明 8B SFT 在 BFCL 上能追上 GPT-4 系列的工作, 这点的 first-mover 价值不会因后继规模化而抹掉。

7.5 笔者个人 take

• 方法论看点: TSS 的 speciation-adaptation-evolution 生物隐喻是好的, 但实际效果取决于 frontier LLM 抽 API 文档的质量 — 没开 prompt 模板,我们无法判断这个抽取过程到底有多 robust。
• self-guided complexity 这个点是真新意 —— 让待训 LLM 当 evaluator,然后用它的 loss 当 complexity 信号 — 后来的 SETA, CoEvolve, ToolMind turn-level 都各自做了这个 idea 的变体。在没有 reward model 的 SFT 设置下,这是用 LLM 自身能力做难度匹配的最自然实现。
• License 校订: 这是本笔记最重要的产出。Apache-2.0 = 可商用 = 后继工作引用 ToolACE 时不必背 NC 包袱 = ToolMind 全 Apache 化无 license 冲突。
• pipeline 不开源: 仍是 ToolACE 影响力上的最大短板 —— 你想"我也要造 50K function-call 数据" 时, ToolACE 没法直接给你 pipeline,只能去看 TOUCAN/EnvScaler 那种全开源工作。
• 未来方向预测: 团队下一篇可能是 ToolACE-3 或 ToolACE-Agent — 接 MCP 真 server 的版本,以应对 BFCL V4 的 agentic 权重 + 真实 server 评测如 MCP-Universe。推测,未在公开来源确认

关键事实速查 (cheatsheet)

附录 A — TSS context tree 的实际样貌(论文 Appendix A Figure 9)

论文 Appendix A 给了 entertainment domain 的 context tree 子树示意。可以从那一图反推 TSS 的实际形态:

附录 B — ToolACE-8B 推理用法(README 附 code snippet)

HF model card 给的 prompt 模板很重要,因为 ToolACE 系列的输出格式不是 OpenAI JSON, 而是 函数调用列表:

system_prompt = """You are an expert in composing functions. You are given a question
and a set of possible functions. Based on the question, you will need to make one or
more function/tool calls to achieve the purpose.
...
If you decide to invoke any of the function(s), you MUST put it in the format of
[func_name1(params_name1=params_value1, params_name2=params_value2...),
 func_name2(params)]
You SHOULD NOT include any other text in the response.
Here is a list of functions in JSON format that you can invoke.\n{functions}\n
"""

对比 OpenAI 标准 {"name":"...", "arguments":"..."},ToolACE 用的是 Python-call 字面量字符串 [func_name(arg=val)]。这是 BFCL AST 解析的原生格式 —— BFCL 评测时直接 parse 这种字符串成 AST 然后比对 —— 所以 ToolACE 训练时刻意走这个 schema,在 BFCL 上拿分自然容易。但: 如果你想直接接 OpenAI Tool Calling API / MCP server 协议,你需要写一层 format adapter 把 ToolACE 输出转成 JSON。这是工程接入的实际 gotcha。

"未在公开来源确认"清单 (透明度)

1. ToolACE 完整训练集 N 条 — paper 没给。HF 公开的 11,300 是 subset,完整规模根据 ToolACE-easy/medium/hard 各 60K 暗示 ≥180K, 但 paper 未明确数字。
2. 390+ domain 这个具体数字 — paper Table 1 应该有但 HTML 抽取里没拿到 verbatim,沿用社区引用。
3. BFCL-v3 Top-3 表里 GPT-4-turbo / GPT-4o 具体 Overall 数 — HTML 表格未完整截到,只给了"ToolACE-8B 89.27"等本行。社区印象 GPT-4-turbo ~60.4 / GPT-4o ~59.5。
4. watt-tool-8B 是否真用 ToolACE 数据 — README 没 verbatim 说底层数据来源,只说"specialized dataset for tool usage and multi-turn dialogue" + DMPO。社区默认是 ToolACE 派生,但没 commit-level 证据。
5. ToolACE pipeline 代码是否会开源 — 团队没承诺,4 篇衍生 paper 也没开。这是推测而非已知。