BFCL (Berkeley Function-Calling Leaderboard) — function-calling 事实标准

§1 BFCL 是什么 — 为什么它是 function-calling 事实标准

BFCL 团队对自己的定位 (README, verbatim):

"We introduce the Berkeley Function Calling Leaderboard (BFCL), the first comprehensive and executable function call evaluation dedicated to assessing Large Language Models' (LLMs) ability to invoke functions. Unlike previous evaluations, BFCL accounts for various forms of function calls, diverse scenarios, and executability."
— repo README

而 ICML 2025 paper("The Berkeley Function Calling Leaderboard (BFCL): From Tool Use to Agentic Evaluation of Large Language Models")abstract 最后一句说得更直接:

"Since its preview, BFCL has become the defacto standard for evaluating function-calls, and can be accessed at gorilla.cs.berkeley.edu/leaderboard.html."
— Patil et al., ICML 2025, abstract verbatim

1.1 "事实标准"具体是什么意思

"function-calling 事实标准"这个说法分几层验证:

• 训练目标: 几乎所有 ≤40B 面向 tool 的模型(xLAM, Hammer, Functionary, NexusRaven, Granite, ToolACE, BitAgent, Llama-xLAM-2, INTELLECT-3 …)都明确地把 BFCL 作为主要 reporting metric(见 #27 ≤40B 小模型 MCP landscape)。
• 论文报数: #22 TOUCAN 在 BFCL V3 报 70.45%, #23 EnvScaler 在 BFCL-MT 报 41.88%, #18 AWM 在 BFCL V3 报 53.83 → 65.94 OOD。 全部以 BFCL 为核心 OOD 测试。
• frontier model card: GPT-5.5 system card 明确把 BFCL 列为 13K-task CoT-Control 训练集源之一(见 §9)。
• HF 下载: 49,556 downloads/月(2026-05, HF)。同期 MCPMark/Atlas/Universe/Toolathlon 加起来都没这个量级。
• Apache-2.0 全套: 数据 + 评测脚本 + AST checker + state checker 全开源,不像 MCP 系列要么 LLM judge 不可复现要么 OAuth 缺失。

1.2 团队 & 学术血统

§2 历史 — V1 → V2 → V3 → V4 演化

四代 BFCL 的演化轨迹非常清晰,每代解决前一代暴露出来的"评测过于简单 → 过拟合 → 该测的没测"的问题。下面 SVG 是时间线 + 每代新增能力的可视化。

2.1 各版本 verbatim 说明

V1 — Simple/Parallel/Multiple Function Call eval with AST (2024-02-26)

HF dataset card 给出"Original Release: 02/26/2024"。V1 引入了核心创新 —— 用 AST(抽象语法树)做参数与类型匹配,而不是把模型输出当字符串去比较或者真的去执行。原始 categories:

• AST 类: Simple Python 400 · Java 100 · JavaScript 50 · Multiple Python 200 · Parallel Python 200 · Parallel Multiple Python 200
• Executable 类: Simple 100 · REST 70 · Multiple 50 · Parallel 50 · Parallel Multiple 40
• Relevance/Irrelevance Detection: 240
• 合计 ~1,700 entries

V2 — Enterprise and OSS-contributed Live Data (2024-08-19)

CHANGELOG verbatim:

"[August 19, 2024] #580: Introduce BFCL V2 Live dataset, featuring user-contributed live prompts and function docs. To read more about the composition and construction of this dataset, please refer to our blog. All CLI commands have been updated to support the new dataset."

V2 Live 分布(verbatim 自 HF dataset card):

• Simple 258 · Multiple 1,053 · Parallel 16 · Parallel Multiple 24 · Irrelevance Detection 882 · Relevance Detection 18
• Total: 2,251 question-function-answer pairs(数字差异: HF dataset card 写 882,blog 早期写 875; 我们取 HF 上的最新数)

V3 — Multi-Turn & Multi-Step Function Call Evaluation (2024-09-19)

CHANGELOG verbatim:

"[Sept 19, 2024] #644: BFCL V3 release: Introduce new multi-turn dataset and state-based evaluation metric."

V3 的 1,000 条 multi-turn(官方 blog):

• Base Multi-Turn 200 — Foundational interactions with all necessary information provided across turns
• Augmented Multi-Turn 800:
  • Missing Parameters 200 — model 必须主动追问
  • Missing Functions 200 — model 必须识别"我没有这个工具"并拒绝
  • Long-Context 200 — 多轮上下文长度 stress
  • Composite 200 — 三种增强组合

V4 — Agentic Web Search + Memory + Format Sensitivity (2025-07-17)

这是现行版本。CHANGELOG #1019 verbatim 给出 V4 的所有改动:

"[Jul 17, 2025] #1019: BFCL V4 release:

1. New agentic domain — Introduces the agentic domain with two categories: Web Search and Memory Management.
2. Revised overall-accuracy formula — As single-turn tasks approach saturation, weighting now favors complex, multi-step agentic tasks."

新权重表(这是 V4 最关键的变化):

除此之外 V4 还做了:

• 退役 Executable categories(rest / exec_simple / exec_parallel / exec_multiple / exec_parallel_multiple)— 2025-04-09 #943
• category 改名: simple → simple_python,java → simple_java,javascript → simple_javascript
• 目录结构改为两级 hierarchy: result/<model>/<general_category>/<category>.json,其中 general_category ∈ {non_live, live, multi_turn, agentic, format_sensitivity}
• 支持的 frontier model 显式列出:claude-opus-4-1-20250805 · gpt-5-2025-08-07 · gpt-5-mini-2025-08-07 · gpt-5-nano-2025-08-07 · Qwen/Qwen3-30B-A3B-Instruct-2507 · Qwen/Qwen3-235B-A22B-Instruct-2507 · Qwen/Qwen3-4B-Instruct-2507

V4 三个 Part 的细节

V4 Part 1 — Agentic Web Search(blog 15): 2025-07-17 发布。引入 multihop QA 任务 —— "100 human-crafted multihop questions spanning various domains"。需要 SerpAPI 才能跑(README 明确说: "For the web_search test category, we use the SerpAPI service to perform web search. You need to sign up for an API key…")。子 category 有 web_search_base 和 web_search_no_snippet(后者强制模型 fetch + read webpage 而不是只用 search snippet)。

V4 Part 2 — Agentic Memory Management(blog 16): 同日发布,150+ 题。覆盖 5 个 domain —— College Student Advising / Customer Support / Personal To-Do List / Healthcare Patient / Finance Managing Director。3 种 memory backend(灵感来自 MemGPT / Mem0):

• memory_kv: key-value store · API: memory_add() · memory_remove() · memory_clear() · memory_search()
• memory_vector: 向量数据库 · 同 API 接口
• memory_rec_sum: recursive summarization · API: memory_append() · memory_update() · memory_replace() · memory_clear() · memory_retrieve()

V4 Part 3 — Agentic Format Sensitivity(blog 17): 这一项不进入总分,只作 diagnostic — 看 prompt 模板小改动会不会让 prompting-mode 模型崩溃。

§3 task 组成详解

BFCL V4 一共 25 个 individual test category(从 TEST_CATEGORIES.md verbatim 抽取)。按 general_category 分组如下:

V4 增强子集还包括: composite (3 种 multi-turn 增强组合), but blog 13 把它划归 augmented multi-turn 类。

- simple_python: Simple Python function calls. Part of the "non-live simple"
  category on the leaderboard.
- multiple: Multiple function calls in sequence.
- parallel: Multiple function calls in parallel.
- parallel_multiple: Multiple function calls in parallel and in sequence.
- irrelevance: Function calls with irrelevant function documentation.
- multi_turn_base: Base entries for multi-turn function calls.
- multi_turn_miss_func: Multi-turn function calls with missing function.
- multi_turn_miss_param: Multi-turn function calls with missing parameter.
- multi_turn_long_context: Multi-turn function calls with long context.
- memory_kv: Tests reading from and writing to a key-value memory backend.
- memory_vector: Tests reading from and writing to a vector-database memory backend.
- memory_rec_sum: Tests reading from and writing to a recursive-summarization memory backend.
- web_search_base: Base entries for web-search calls.
- web_search_no_snippet: Web-search calls where search-engine snippets are withheld,
  forcing the model to fetch and read webpages.
- format_sensitivity: Various system prompt formats to test the format sensitivity
  of the model. (Only works for prompting mode models.)

3.1 几个 prompt template 片段

Simple Python (V1) — 一道典型 simple_python 题的 ground truth(改写自 repo 中的 simple_python_x):

{
  "id": "simple_python_3",
  "question": [[{
    "role":"user",
    "content":"Calculate the area of a triangle with base 10 and height 5."
  }]],
  "function": [{
    "name": "calculate_triangle_area",
    "description": "Calculate the area of a triangle given its base and height.",
    "parameters": {"type":"dict",
      "properties":{
        "base":{"type":"integer","description":"Base length in units"},
        "height":{"type":"integer","description":"Height in units"},
        "unit":{"type":"string","description":"Unit (cm, m, etc.)","default":"units"}
      },
      "required":["base","height"]}
  }],
  "possible_answer": [{
    "calculate_triangle_area":{
      "base":[10], "height":[5], "unit":["units","cm","m"]
    }
  }]
}

注意 possible_answer 中 unit 给了多个允许值 —— BFCL AST 允许 多 ground-truth(set membership),这是它和 string-match eval 的核心区别。

Multi-Turn (V3) — multi_turn_base 题目长这样(改写示意):

{
  "id":"multi_turn_base_15",
  "initial_config":{
    "TravelAPI":{...}, "GorillaFileSystem":{...}
  },
  "involved_classes":["TravelAPI","MessageAPI"],
  "question":[
    [{"role":"user","content":"Book me a flight from SFO to JFK on May 20."}],
    [{"role":"user","content":"Wait, change it to May 22 and message my partner."}]
  ],
  "ground_truth":[
    ["TravelAPI.book_flight(origin='SFO', dest='JFK', date='2026-05-20')"],
    ["TravelAPI.modify_booking(booking_id='...', new_date='2026-05-22')",
     "MessageAPI.send(recipient='partner', body='Flight changed to May 22')"]
  ]
}

3.2 V4 各类任务举例 — verbatim 从 repo 抽取

3.2.1 non-live · simple_python — 单函数 + 多 ground-truth

上面 §3.1 已展示;这里补一个 parallel(同一函数并行调多次)的 verbatim:

// BFCL_v4_parallel.json (第 1 条)
{"id": "parallel_0",
 "question": [[{"role": "user",
   "content": "Play songs from the artists Taylor Swift and Maroon 5,
                with a play time of 20 minutes and 15 minutes respectively, on Spotify."}]],
 "function": [{"name": "spotify.play",
   "description": "Play specific tracks from a given artist for a specific time duration.",
   "parameters": {"type": "dict",
     "properties": {
       "artist": {"type": "string", "description": "..."},
       "duration": {"type": "integer", "description": "..."}},
     "required": ["artist", "duration"]}}]}

难点: 模型必须输出两次 spotify.play 调用而不是一次带 list 的调用 —— AST 检查严格区分 parallel-call vs list-arg。

3.2.2 non-live · irrelevance — 必须不调工具

// BFCL_v4_irrelevance.json (第 1 条)
{"id": "irrelevance_0",
 "question": [[{"role": "user",
   "content": "Calculate the area of a triangle given the base is 10 meters and height is 5 meters."}]],
 "function": [{"name": "determine_body_mass_index",
   "description": "Calculate body mass index given weight and height.",
   "parameters": {"properties": {
     "weight": {"type": "float"}, "height": {"type": "float"}},
     "required": ["weight", "height"]}}]}

难点: 工具名/描述里有 height 这种诱导词。BMI 的 height 是身高,triangle 的 height 是几何高度。模型只要被 keyword 钓中就要 0 分。leaderboard 上 Irrelevance 列就是这种"拒答"准确率。

3.2.3 multi_turn · multi_turn_base — 4 轮文件操作

// BFCL_v4_multi_turn_base.json (第 1 条)
{"id": "multi_turn_base_0",
 "question": [
   [{"role":"user","content":"Move 'final_report.pdf' within document directory
                              to 'temp' directory in document. Make sure to create the directory"}],
   [{"role":"user","content":"Perform a detailed search using grep to identify sections
                              in the file pertaining to 'budget analysis'."}],
   [{"role":"user","content":"Upon identifying the requisite 'budget analysis' content,
                              sort the 'final_report.pdf' by line ..."}],
   [{"role":"user","content":"Move 'previous_report.pdf' in document directory to temp ...
                              proceed to juxtapose it with 'previous_report.pdf' ..."}]],
 "initial_config": {
   "GorillaFileSystem": {"root":{"workspace":{"type":"directory",
     "contents":{"document":{"type":"directory",
       "contents":{"final_report.pdf":{"type":"file",
         "content":"Year2024 This is the final report content including budget analysis ..."},
         "previous_report.pdf":{...}}},
       "archive":{"type":"directory","contents":{}}}}}},
   "TwitterAPI": {"tweet_counter":3, "tweets":{...},
     "username":"analyst_pro", "password":"Kj8#mP9$vL2"}},
 "path": ["GorillaFileSystem.find","GorillaFileSystem.mv","GorillaFileSystem.grep",
          "GorillaFileSystem.sort","GorillaFileSystem.diff","TwitterAPI.post_tweet"],
 "involved_classes": ["TwitterAPI","GorillaFileSystem"],
 "excluded_function": ["cp"]}

注意要点:

• initial_config 是 Python class 的初始状态(包括明文 password!),由 GorillaFileSystem / TwitterAPI 等 14+ 个仿真后端类承载。
• path 是必经函数列表(state-based eval 验证);excluded_function 是禁用清单(如 cp 不能用,只能 mv)。
• 评测时每轮调用结束后,checker 把仿真器的真实 state 和 ground-truth state 用 state_diff 比较 —— 详见 §4.3。

3.2.4 multi_turn · multi_turn_miss_func — 空轮 = 工具被故意拿掉

// BFCL_v4_multi_turn_miss_func.json (第 1 条)
{"id": "multi_turn_miss_func_0",
 "question": [
   [{"role":"user","content":"Move 'final_report.pdf' ..."}],
   [{"role":"user","content":"Perform a detailed search using grep ..."}],
   [{"role":"user","content":"... sort the 'final_report.pdf' by line ..."}],
   [],   // ← 空轮! 上一轮的 sort 函数被 "missed_function" 表抽掉了
   [{"role":"user","content":"Move 'previous_report.pdf' ... juxtapose ..."}]],
 ...,
 "missed_function": {"3": ["sort"]},  // ← 第 3 轮 sort 不可见
 "excluded_function": ["cp"]}

难点: 第 3 轮(0-indexed)给模型的可用工具列表里少了 sort,所以模型应当回答"对不起,我没有 sort 工具"而不是 hallucinate 一个调用。question 数组里出现 [] 空轮 = "本轮模型不应该有用户输入,系统让模型自由发挥"。

3.2.5 multi_turn · multi_turn_miss_param — 必须追问

// BFCL_v4_multi_turn_miss_param.json (第 1 条 — 注意倒数第二轮)
{"id": "multi_turn_miss_param_0",
 "question": [
   ...,
   [{"role":"user","content":"Move one of the file in document directory to temp ...
                              proceed to juxtapose it with 'previous_report.pdf' ..."}],
   //  ↑ 用户说 "one of the file" 但没指明哪一个
   [{"role":"user","content":"The specific file is previous_report.pdf."}]],
   //  ↑ 模型本应该追问,然后用户在下一轮给出答案
 ...}

难点: 模型如果"猜"了一个文件名直接 mv,会失败;正确行为是 asking-for-clarification(回 user 消息,不发函数调用)。这是 V3 加进来检测 "agreeable hallucination" 的核心 category。

3.2.6 agentic · web_search(V4 新)— multi-hop QA + SerpAPI

// BFCL_v4_web_search.json (第 1 条)
{"id": "web_search_0",
 "question": [[{"role":"user","content":
   "Some countries are known for producing luxury goods, including the world's most
    expensive tea. In April 2025, who is the richest billionaire (according to Forbes)
    from the country that produces the most expensive tea?"}]],
 "involved_classes": ["WebSearchAPI"]}

// possible_answer/BFCL_v4_web_search.json (第 1 条 — 注意 source 是 3-hop 推理)
{"id": "web_search_0",
 "ground_truth": ["Zhang Yiming"],   // ← 但 wikipedia 2025 第一名其实是 Zhong Shanshan
 "source": [
   {"subquestion":"Most expensive tea in the world",
    "answer":"DaHong Pao", "source":"https://camellios.com/..."},
   {"subquestion":"Country that produces DaHong Pao",
    "answer":"China", "source":"https://en.wikipedia.org/wiki/Da_Hong_Pao"},
   {"subquestion":"Who is the richest billionaire in China",
    "answer":"Zhong Shanshan", "source":"https://www.forbes.com/..."}],
 "num_hops": 3}

暴露的工具签名(multi_turn_func_doc/web_search.json):

• search_engine_query(keywords, max_results=10, region="wt-wt") — 走 SerpAPI
• fetch_url_content(url, mode="raw"|"markdown"|"truncate") — fetch + 解析网页

难点 & 数据观察:

• 本题 ground_truth 是 "Zhang Yiming",但 source 链条最终答案写的是 "Zhong Shanshan" —— 这是 leaderboard 数据库里实际不一致的样例,说明这类题答案随时间会漂(2024 是 Zhong Shanshan,2025 Forbes 又一变)。所以 BFCL 把 web_search 限定在 "April 2025" 这种时间锚提问,但人工标的 ground_truth 仍可能滞后。
• web_search_no_snippet 子 category 把 SerpAPI 返回的 snippet 字段抠掉,强制模型 fetch_url_content 实际打开网页 —— 不能"看摘要凑答案"。
• 跑这个 category 需要付费 SerpAPI key,这是 BFCL 第一次把"非免费基础设施"引入 leaderboard。

3.2.7 agentic · memory(V4 最大新增)— 全面拆解

Memory 任务的 2-stage 架构(关键!):

1. Stage 1 — prereq 阶段(模型不可见,由 evaluator 预跑): 同 scenario 的 memory_prereq_conversation/memory_<domain>.json 是一段长达 6-30 轮的用户独白(顾客/学生/病人/财务/记事 5 种 domain)。evaluator 把这段独白送进模型,让模型用 memory API 自行把信息存进 memory。这一阶段的 memory dump 会被持久化到 snapshot_folder/<test_id>.json。
2. Stage 2 — 实际计分(打榜看的就是这一阶段): 把 Stage 1 持久化的 memory 重新加载,然后给模型一个单轮问题(BFCL_v4_memory.json 里的 question),问 "What is my first name?" / "How old am I?" / "What kind of latte do I occasionally like?"。模型必须用 memory_search / memory_retrieve 把答案从 memory 中查出来,并以最终自然语言答复。Ground truth 是字符串 set,如 ["35","thirty five"] 都接受。

5 个 domain(verbatim from data folder):

样例 verbatim — Stage 2 问题(BFCL_v4_memory.json 前 5 条):

{"id":"memory_0-customer-0","question":[[{"role":"user","content":"What is my first name?"}]],
 "involved_classes":["MemoryAPI"],"scenario":"customer"}
{"id":"memory_1-customer-1","question":[[{"role":"user","content":"How old am I?"}]],
 "involved_classes":["MemoryAPI"],"scenario":"customer"}
{"id":"memory_2-customer-2","question":[[{"role":"user","content":"Where do I live?"}]],
 "involved_classes":["MemoryAPI"],"scenario":"customer"}
{"id":"memory_3-customer-3","question":[[{"role":"user","content":"What kind of latte do I occasionally like?"}]],
 "involved_classes":["MemoryAPI"],"scenario":"customer"}
{"id":"memory_4-customer-4","question":[[{"role":"user","content":"How many square feet is my kitchen counter?"}]],
 "involved_classes":["MemoryAPI"],"scenario":"customer"}

对应的 ground truth + source 出处(possible_answer/BFCL_v4_memory.json):

{"id":"memory_0-customer-0","ground_truth":["Michael"],
 "source":"My name is Michael, and this is my first time interacting with your company..."}
{"id":"memory_1-customer-1","ground_truth":["35","thirty five"],
 "source":"I'm 35 years old, live in Seattle..."}
{"id":"memory_2-customer-2","ground_truth":["Seattle"],
 "source":"I'm 35 years old, live in Seattle..."}
{"id":"memory_3-customer-3","ground_truth":["strawberry matcha"],
 "source":"...I occasionally like a strawberry matcha latte..."}
{"id":"memory_4-customer-4","ground_truth":["38","thirty eight"],
 "source":"...my counter is only 38 square feet."}

Stage 1 的 prereq 独白长这样(memory_prereq_conversation/memory_customer.json 节选):

{"id":"memory_prereq_0-customer-0","topic":"First-Time Inquiry About a Product",
 "question": [
   [{"role":"user","content":"Hey there! Thanks for getting back to me ...
                              My name is Michael, and this is my first time
                              interacting with your company in any way..."}],
   [{"role":"user","content":"I'm 35 years old, live in Seattle, and am
                              pretty serious about both my work and my hobbies.
                              I work as a freelance graphic designer..."}],
   ... // 30+ 轮长独白
 ]}

注意:Stage 1 的每一轮都是 user → assistant,assistant 边读边决定要不要调 core_memory_add / archival_memory_add 来记下"Michael / 35 / Seattle / strawberry matcha / 38 sqft"等关键事实。Stage 1 模型的记什么 / 不记什么会直接决定 Stage 2 能不能查出来。

3.2.7.A memory_kv 子类 — key-value 后端

来源: eval_checker/multi_turn_eval/func_source_code/memory_kv.py 类 MemoryAPI_kv。设计灵感来自 MemGPT —— core memory(短期,容量 7 条,每条 ≤300 字符)+ archival memory(长期,容量 50 条,每条 ≤2000 字符)双层结构。

# memory_kv.py verbatim
MAX_CORE_MEMORY_SIZE = 7
MAX_CORE_MEMORY_ENTRY_LENGTH = 300
MAX_ARCHIVAL_MEMORY_SIZE = 50
MAX_ARCHIVAL_MEMORY_ENTRY_LENGTH = 2000

class MemoryAPI_kv(MemoryAPI):
    """A class that provides APIs to manage short-term and long-term
       memory data in a key-value format."""

    def core_memory_add(self, key: str, value: str) -> Dict[str, str]:
        """Add a key-value pair to the short-term memory.
           Keys must be snake_case and cannot contain spaces."""
        # 检查容量 / 长度 / key 格式 / 重复
        ...

    def core_memory_remove(self, key: str) -> Dict[str, str]: ...
    def core_memory_replace(self, key: str, value: str) -> ...
    def core_memory_clear(self) -> ...
    # 同名一组 archival_memory_* 方法
    def archival_memory_key_search(self, query: str, k: int = 5):
        """Search for key names ... using BM25+ algorithm."""

暴露给模型的 16 个工具签名(multi_turn_func_doc/memory_kv.json): core_memory_add / remove / replace / clear / retrieve / key_search / list_keys + 同名一组 archival_memory_*。注意 key 必须 snake_case,这是 V4 故意加的 format 约束,逼模型规范命名。

难点: core memory 只能放 7 条 → 模型必须做 importance ranking(决定 "Michael 名字" 进 core 还是 archival),否则容易溢出。检索是 BM25+ 词袋,所以同义词检索能力差(写入是 customer_first_name,查 "name" 能命中,查 "user" 就不一定)。

3.2.7.B memory_vector 子类 — 向量库后端

来源: memory_vector.py 类 MemoryAPI_vector,内部用 sentence-transformers all-MiniLM-L6-v2 + FAISS(verbatim 见下)。

# memory_vector.py verbatim
ENCODER = SentenceTransformer("all-MiniLM-L6-v2", device="cpu")
ENCODER_DIM = ENCODER.get_sentence_embedding_dimension()

class MemoryAPI_vector(MemoryAPI):
    def __init__(self):
        self.core_memory = VectorStore(max_size=7, max_entry_length=300)
        self.archival_memory = VectorStore(max_size=50, max_entry_length=2000)

    def core_memory_add(self, text: str) -> dict[str, str]:
        """Add a new entry to the core memory.
           Returns: id (int): The ID of the added entry."""
        return self.core_memory.add(text)

    def core_memory_retrieve(self, query: str, top_k: int = 5) -> list[dict]:
        """Retrieve the most similar entries from the core memory."""
        # FAISS L2 nearest-neighbor search

区别 vs kv: 不需要 key —— core_memory_add(text) 只传文本,系统自动 encode 并返回数字 id;检索靠 cosine/L2 similarity 不是关键词。

难点: 模型不能用"key 提示"自己,完全依赖 embedding 召回。Stage 1 写入时如果 batch 多条信息进一条 entry(如 "name=Michael, age=35, city=Seattle"),Stage 2 任何相关 query 都能拉回但 top-k 噪声大;反之每条只存一个事实,Stage 2 又可能 top-5 召不到。这就是经典 RAG chunk-size tradeoff。

3.2.7.C memory_rec_sum 子类 — recursive summarization 后端

来源: memory_rec_sum.py 类 MemoryAPI_rec_sum。这一个最特殊:memory 就是一个 plain string,容量 10000 字符,只有 5 个工具。

# memory_rec_sum.py verbatim
MAX_MEMORY_ENTRY_LENGTH = 10000  # 10k characters

class MemoryAPI_rec_sum(MemoryAPI):
    def __init__(self):
        self.memory = ""   # ← 单一字符串,不是 dict / 不是 list

    def memory_append(self, text: str) -> Dict[str, str]:
        """Append a new text to the end of the memory."""
        # 长度溢出就报错,逼模型 summarize

    def memory_update(self, text: str) -> Dict[str, str]:
        """Update the memory with new text.
           This will replace the existing memory content."""

    def memory_replace(self, old_text, new_text) -> ...
    def memory_clear(self) -> ...
    def memory_retrieve(self) -> ...  # 拿回整段字符串

核心 design intent: 这就是 Claude 风格的 "rolling summary" memory。模型必须每隔 N 轮把现有 memory 取出来、压成更短的 summary,再 memory_update 写回 —— "递归"二字就在于反复 retrieve → summarize → overwrite。memory_replace(old, new) 是细粒度修订,等价于 sed。

难点: 没有索引,Stage 2 查询时只能拿回 整段 10k 字符串 然后塞进 context 让 LLM 自己 grep —— 这也是为什么这个子类的 token cost 通常最高(每次 retrieve 都把全部 memory 灌回 prompt)。但反之"召回率"理论 100%(整段都给你),所以 leaderboard 上 rec_sum 经常分数偏高但 latency / cost 最差。这对应 #29 EnvTuning paper 中提到的 RecSum / KV / Vector 三分,与该 paper 的 "RL-based memory management" 直接对照。

3.2.7.D Memory 评测的判分

memory 任务和 multi-turn 用同一个 state-based checker(multi_turn_checker.py),但额外多两步:

• Stage 1 snapshot 必须能成功生成 —— 如果 Stage 1 模型从头到尾不调 *_add,Stage 2 拿到空 memory,几乎必 0。
• Stage 2 最终回复包含 ground_truth 子串 —— 这是少数用 string-contains 而不是 AST 的 category(因为最终答案是 NL 回答),但 ground_truth 是 set,如 ["35","thirty five"] 任一命中即可。

3.2.8 diag · format_sensitivity(V4 新,不进总分)

同一个 multi_turn_base 任务,但 system prompt 用多种格式扰动模板包装(JSON vs YAML vs XML vs Markdown,有无 emoji,大小写等),看模型在不同模板下答案稳定性如何。结果体现在 leaderboard 的 FmtΔ 列(format gap)—— Claude Opus 4.5 prompt-mode 在这一列跌 44 pp(见 §6.2),说明 prompting-mode 模型对 system prompt 模板极度敏感,而 FC handler 几乎不受影响。

§4 评测方法

BFCL 同时支持两种核心评测,V3 起又增加 state-based + response-based 双重 multi-turn 评测。

4.1 AST evaluation(V1 起,所有 single-turn 用)

AST checker 的核心 dispatch(verbatim 自 bfcl_eval/eval_checker/ast_eval/ast_checker.py):

def ast_checker(
    func_description,
    model_output,
    possible_answer,
    language: Language,
    test_category: str,
    model_name: str,
):
    if "parallel" in test_category:
        return parallel_function_checker_no_order(
            func_description, model_output, possible_answer, language, model_name
        )
    elif "multiple" in test_category:
        return multiple_function_checker(
            func_description, model_output, possible_answer, language, model_name
        )
    else:
        return simple_function_checker(
            func_description[0], model_output[0], possible_answer[0], language, model_name
        )

三个 sub-checker 都基于真正解析模型输出为 AST(Python: ast.parse;Java/JS: 各自的 tree-sitter 风格 parser),然后逐层匹配:

1. 函数名匹配 —— 调对函数没?
2. 参数名匹配 —— 必填参数都给了没?
3. 类型匹配 —— int 不能给成 str(strict on typing)。但有个例外: int → float Python 自动转,允许放宽(CHANGELOG 2024-06-07 #407 加入)。
4. 值匹配 —— 落在 possible_answer 的合法值集合里就算对(允许 multi-ground-truth)。
5. String standardization(2024-04-03 #309 引入)—— 去白空格 + 去 ,./-_*^ 子集标点,让 AST 匹配更鲁棒。

对 parallel 类用 no-order matching(可以乱序,数量必须对);multiple 用 all-or-nothing("strict all-or-nothing for multiple/parallel scenarios" — blog 8 verbatim)。

4.2 Executable evaluation(V1 引入,V4 在 2025-04-09 #943 整体退役)

原来的 exec_simple / exec_parallel / exec_multiple / exec_parallel_multiple / rest 真的会去 import 一个函数包并执行,然后用四种 criteria 之一:

• exact_match — 严格相等
• structural_match (type match) — list 比长度,dict 比 key
• real_time_match — 数值结果允许 20% 误差(用来兼容 API 实时数据微变化)
• API sanity check — 每次跑 eval 先 ping 一遍 API 健不健康

4.3 State-based evaluation(V3 起,所有 multi-turn 用)

这是 V3 最大的方法学创新。整套 multi-turn 包含一个 backend simulator(GorillaFileSystem / TravelAPI / MessageAPI / VehicleControlAPI / TicketAPI / TradingBot / MathAPI)。模型每发一个工具调用,backend 实际执行并改变 state。评测时(blog 13 verbatim):

"State-based evaluation: Compares backend system attributes after all function calls complete each turn, capturing correctness of write/delete operations.

Response-based evaluation (subset-matched): Validates execution paths against minimal viable ground truth trajectories, ensuring read-only requests succeed while allowing reasonable alternative paths rather than requiring exact trajectory matching.

Human-labeled ground truth trajectories underpin all evaluation."

关键设计点:

• State diff 而非 trajectory match — 只要最终 state 对了,中间走多远的路都行。这样允许 exploration / error recovery。
• Read-only 操作单独 subset-match — read-only 不修改 state,所以只检查"是否调对了"。
• Human-labeled GT — 不用 LLM judge,因此可复现。这是它和 MCP-Atlas / MCP-Universe 的分水岭(后两者要么 Gemini judge 要么真 GCP env,都不便宜)。

4.4 Hallucination detection(贯穿所有版本)

irrelevance / live_irrelevance / multi_turn_miss_func 三类都是测拒答能力 —— function doc 里没有合适工具时,模型应该用自然语言回答而不是硬编一个 function name。Hallucination = 在没有合适工具的时候编出一个。

§5 开源现状 — repo / dataset / 评测脚本 / 自托管

5.1 三步自托管完整流程(README verbatim)

# 1. 装环境
conda create -n BFCL python=3.10
conda activate BFCL
git clone https://github.com/ShishirPatil/gorilla.git
cd gorilla/berkeley-function-call-leaderboard
pip install -e .

# 2. 生成 model 响应(以 OSS Qwen3-8B 为例)
bfcl generate \
  --model Qwen/Qwen3-8B-FC \
  --test-category multi_turn \
  --backend vllm \
  --num-gpus 1 \
  --gpu-memory-utilization 0.9

# 3. 评测
bfcl evaluate --model Qwen/Qwen3-8B-FC --test-category multi_turn

# 输出: score/Qwen/Qwen3-8B-FC/multi_turn/*.json
#       score/data_overall.csv
#       score/data_multi_turn.csv

关键 flag:

• --backend {sglang|vllm}: sglang 在 multi-turn 用例下"much faster",但只支持 SM80+(Ampere 起);老 GPU 用 vllm
• --local-model-path: 离线推理 — 指向预下载好的 ckpt 目录
• --enable-lora --lora-modules name="path": 直接评测 LoRA adapter 微调模型
• --run-ids + test_case_ids_to_generate.json: 只跑指定 ID,迭代时省时间
• --partial-eval: 评测部分 entry(注意不能和官方 leaderboard 数字直接对比)
• --skip-server-setup + LOCAL_SERVER_ENDPOINT/LOCAL_SERVER_PORT: 接 SLURM 上已经在跑的 vllm 服务
• REMOTE_OPENAI_BASE_URL / REMOTE_OPENAI_API_KEY: 接 RunPod / ngrok / 企业网关

§6 完整 leaderboard — V4 全量(2026-05 quote)

6.1 表头解读 — V4 列含义

官方 CSV 共 36 列,本文聚焦下面 8 个语义维度(其它如 cost / latency 在 §7 提交流程那块用):

6.2 (a) Proprietary frontier 模型 — V4 全量

来自 data_overall.csv 2026-05-13 截图,所有 Anthropic / OpenAI / Google / xAI / Cohere / Mistral / Amazon proprietary 模型(已剔除小数;FormatΔ N/A 表示官方未跑此 diagnostic):

6.3 (b) Open-weight ≥40B 模型

6.4 (c) Open-weight ≤40B 模型 — 训 ≤40B 最关心的子榜

Top 3 ≤40B open-weight on V4 (verbatim from official CSV):

1. Nanbeige4-3B-Thinking-2511 (FC) — 51.40% · 3B Apache-2.0 · 这是 2026-05 最大惊喜:3B 模型上 51.40%, multi-turn 51.12% 超过 Qwen3-32B 的 47.87%。
2. Qwen3-32B (FC) — 48.71% · 32B Apache-2.0
3. Nanbeige3.5-Pro-Thinking (FC) — 47.68% · Apache-2.0

6.5 (d) Specialized fine-tuned tool models

6.6 ≤40B open-weight 子榜历史比对(沿用上一版)

对 #27 小模型 MCP landscape 那群读者,把上面 V4 数据接到我们已有的 V3 / 自报数字上,得到这张跨版本子榜:

V4 数字大面积比 V3 低 10-30 pp,这是 V4 把 multi-turn+agentic 加权 70% 的直接结果(V3 是 33%)。注意 Nanbeige4-3B 在 V4 上爆冷拿 ≤40B 第一;Qwen3-32B 不再是 ≤40B 顶点 — 是 V4 改公式后最大的"洗牌"。

§7 提交流程

BFCL 的提交流程 不像 MCPMark / Atlas 那样有 web submission portal — 它是 纯 PR-based。README "Contributing" verbatim:

"We welcome contributions! To add a new model:

1. Review bfcl_eval/model_handler/base_handler.py and/or bfcl_eval/model_handler/local_inference/base_oss_handler.py (if your model is hosted locally).
2. Implement a new handler class for your model.
3. Update bfcl_eval/constants/model_config.py.
4. Submit a Pull Request.

For detailed steps, please see the Contributing Guide."

实操步骤:

1. fork ShishirPatil/gorilla
2. 在 bfcl_eval/model_handler/{api,local_inference}/ 实现一个 handler 类(参考 OpenAIHandler / AnthropicHandler / QwenHandler)
3. 把 model name + handler 类注册到 bfcl_eval/constants/model_config.py
4. 本地跑 bfcl generate + bfcl evaluate 出 score/data_overall.csv
5. 提 PR,附 data_overall.csv + data_live.csv + data_multi_turn.csv
6. Berkeley 团队 review 后合并 + 更新 live leaderboard

§8 局限 + 与 MCP benchmark 的本质区别

8.1 BFCL 本身的几个局限

1. Schema-based, not stateful real-MCP — BFCL multi-turn 用的是 7 个简化的 Python class backend(GorillaFileSystem / TravelAPI / MessageAPI / VehicleControlAPI / TicketAPI / TradingBot / MathAPI),不是真实的 OAuth-authenticated MCP server。所以"BFCL 高分"不能保证模型在真实 Notion / GitHub / Stripe API 上工作。
2. Web Search 强绑 SerpAPI — 你想跑 V4 的 web_search category,必须有 SerpAPI key,且数字会随互联网内容漂移。这是 V4 唯一的"非确定性"评测部分。
3. Live category 受用户贡献质量影响 — V2 Live 数据来自社区 PR,质量不均(CHANGELOG 里反复在修单条 ground truth bug:#600 #1185 #1175 #1086 …)。
4. Format Sensitivity 暴露了"分数易碎" — V4 引入这一类的本意是承认:很多模型在 BFCL 上跑 60% 跑 70% 完全取决于 system prompt 怎么写。
5. 没有真长 horizon — V3 multi-turn 主要 1-3 轮,V4 web/memory 也少有 >10 轮。对比 Toolathlon(#21)的 50+ tool 多 hop 任务,BFCL agentic 更像"短 vignette"。
6. 评测语言/生态局限 — Java 100 + JavaScript 50 数量太少,REST 70 已被 V4 退役。BFCL 实际上是 Python-only 的 function-calling benchmark。

8.2 为什么 "BFCL 高分 ≠ MCP benchmark 高分"

这是 #21 和 #26 反复验证的命题。把核心差异提炼成一张表:

所以 GPT-5 在 BFCL V4 只有 59.2 但在 MCP-Atlas 上其它数字更分散(GPT-5.4 在 MCP-Atlas 68.1%),而 Claude Opus 4 在 BFCL V3 25.3 但在 MCP-Atlas Live 是 77.3 —— 评的根本就是不同维度。从 #26 的结论上看:

"不能一个 ckpt SOTA 全部 benchmark,但可以打到各 80%。 联合训配方: TOUCAN 冷启(BFCL) + MCPMark/Universe RLVR(schema 严格 verify) + Toolathlon long-horizon SFT + Atlas LoRA 隔离。"
— #26 结论 verbatim

§9 frontier model 官方引用情况

这是 #19 和 #21 已经形成的考察套路 —— 一个 benchmark 是不是"事实标准",看 frontier model card 直接引不引。

结论: GPT-5.5 是唯一一个把 BFCL 写进 system card 的西方 frontier model(还是作为训练数据源而非 eval target)。Anthropic 和 Google 更倾向于 MCP-Atlas / 自家 agentic benchmark。但中国厂(Qwen / GLM / Kimi)+ 训练向小模型(xLAM / Hammer / TOUCAN / EnvScaler / AWM)几乎 100% 引用 BFCL。所以 BFCL 在"open-weight + ≤40B function-calling"领域几乎是法定 KPI,在frontier proprietary 领域是次选。

§10 我的 take + 实用建议

10.1 我的 take

1. BFCL 是 schema-level standard,不是 production agent standard。 它评的是"给定一个 function spec, 模型能不能调对"。它不评"在真 OAuth Notion 上完成 task"。两者在能力树上是父子节点关系: BFCL 是 prerequisite,MCP-bench 才是 production-ready。 任何 ≤40B 模型想做 function-call,先在 BFCL 拿到 ≥70%,再去碰 MCP-Atlas / Toolathlon。
2. V4 的权重重排很激进 — Agentic 直接 40%。 V4 把 single-turn(Live+Non-Live)总占比从 66% 砍到 20%,这意味着过去刷 V3 高分的策略(TOUCAN 1.5M SFT)在 V4 上效用打折。 V4 高分需要 (a) 良好的 multi-turn state 保持, (b) 调用 search/memory API 的连续决策, (c) 拒答 / 追问能力。这正好是 EnvScaler + SETA + AWM 类合成 env 训练的甜点。
3. ≤40B 当前 ceiling: Qwen3-32B (V3 75.7%)。 但 V4 SOTA 已经被 GLM-4.5 (70.9%) 拿走 — 注意这不是真 open-weight。下一年(2026 H2)的开源 race 大概率是 Qwen3.5 / GLM-4.7-Air / DeepSeek-V4-FC 在 V4 上的争夺。
4. Claude 在 BFCL 上吃亏 ≠ Claude 不会 tool use。 V3 BFCL 25.3 vs MCP-Atlas 77.3 这种巨大反差,本质是 Anthropic Tool Use API schema 与 BFCL prompt-mode 默认 schema 不兼容。这是 V4 加 format_sensitivity diag 的真正原因。如果你用 Claude 做 tool agent,记得用 claude-opus-4-1-20250805 这个 FC native handler(CHANGELOG #1019)。
5. BFCL 缺什么 = MCP bench 在补什么。 BFCL 没有的: OAuth / 真 API 限流 / 副作用 / 长 horizon (>10 turn) / 跨 server 调度 / 自然语言 query 含糊度。这恰恰是 MCP-Universe (#25) / MCPMark / Toolathlon / Atlas 各自切的赛道。 BFCL 的留白 = MCP bench 的机会。

10.2 训 ≤40B 模型时 BFCL 该怎么用、不该怎么用

✅ 该怎么用

• SFT 冷启验证: 训完 1 个 epoch tool SFT(用 TOUCAN / xLAM 数据), 跑 BFCL V3 simple_python + multiple + parallel 三个 — 如果 ≥85%,schema 基础 OK,可以进入 multi-turn 阶段
• Hallucination 早筛: irrelevance + live_irrelevance + multi_turn_miss_func 三个 category 是"拒答"专用测,任何 <50% 都说明模型乱编 function
• Multi-turn 状态保持作为 gating signal: 训 RL 时把 multi_turn_base + multi_turn_miss_param 当 dev set,curriculum 推进的依据
• 用 V4 agentic 子集做 MCP bench 的 dry-run: 真要去测 MCPMark / Atlas 太贵,先在 BFCL V4 memory_kv + web_search_base 上跑,通过了再上真 MCP
• Format sensitivity 必跑: V4 加的 format_sensitivity 不进总分但极有诊断价值 — 你的模型对 system prompt 的 5 种格式有没有 ±10% 的 variance? 有 → 还在过拟合 schema

❌ 不该怎么用

• 不要把 BFCL V3 Overall 当成"我的 function-call 能力总体水平"。 V4 已经把 V3 Multi-Turn 权重从 33% 砍到 30% 并加了 40% Agentic。 V3 跑 70% 在 V4 上可能跑 50%
• 不要为了 BFCL 而 BFCL — 不要用 BFCL train data 训测一致。 BFCL HF dataset 是 Apache-2.0 可商用,但把它当训练数据等于数据污染。 用 TOUCAN / xLAM / Hammer / EnvScaler 训,BFCL 仅做 OOD eval
• 不要忽略 prompt-mode vs FC-mode 的差异。 BFCL leaderboard 有两个并行列(后缀 -FC = native function-calling),分数能差 5-15 pp。 你部署用哪种就报哪种
• 不要把 web_search category 数字当严肃 eval。 SerpAPI 结果随时间漂,且模型分数和 SerpAPI key tier 强相关
• 不要把 BFCL 替代 MCP-Atlas / Universe。 见 §8.2 表格 —— 评的根本就不是一个东西

10.3 一句话推荐

训 ≤40B function-call 模型的标准流程: TOUCAN 1.5M SFT 冷启 → BFCL V3 Overall ≥70% gate → EnvScaler/SETA 合成 env RLVR → BFCL V4 Agentic ≥50% gate → MCP-Atlas / MCPMark 真测。 BFCL 是第二关,不是终点,但跨不过它就没法继续。

§11 BFCL-targeted RL / post-train infra

这一章是 2026-05 新加的:既然 BFCL 是 ≤40B function-call 的事实标准 KPI(§9),那"什么框架/数据集/recipe 是直接以 BFCL 为优化目标训出来的?"就成了能直接落地的问题。下面把当前 stack 里所有可考的工件列出来,带 repo URL / license / 验证依据。

11.1 Gorilla 团队本身的训练代码 — 缺席

这是研究里的一个负面发现。Berkeley Gorilla 团队没有发布"训 BFCL"的公开 RL 代码。具体观察:

• gorilla/openfunctions/ 只有 inference_hosted.py + inference_local.py + 一份 openfunctions_utils.py — 全是 inference / serving 代码。没有训练 loop, 没有 dataset 构建, 没有 RL reward。
• gorilla/gorilla/ 只有 eval/ + inference/。和上面同样的 SFT/RL 空缺。
• 原始 Gorilla paper(2023, API Bench)使用 self-instruct + LLaMA-7B SFT,但训练 pipeline 未开源。 OpenFunctions v0/v1/v2 ckpt 上 HuggingFace 但不带训练脚本。
• BFCL 仓库本身只有 berkeley-function-call-leaderboard/bfcl_eval/(pip install bfcl-eval),evaluation only。

结论: 想"train against BFCL",必须用第三方框架。下面是当前实际可用的 stack。

11.2 NVIDIA Tool-N1 — 唯一明确"以 BFCL 为目标"的开源 RL 训练 codebase

核心 claim(paper verbatim): "RL offers a more effective paradigm for enhancing the tool-calling capabilities of LLMs compared to standard supervised fine-tuning", 并在 BFCL 上展示 RL beats SFT。这是第一个 BFCL native 的端到端 RL 实证 codebase。

11.3 Salesforce xLAM + APIGen + ActionStudio — SFT-heavy, 数据规模最大

用 xLAM 训 BFCL 的最佳路径: (a) 取 xlam-function-calling-60k 做冷启 SFT, (b) 取 APIGen-MT-5k 做 multi-turn SFT, (c) 用 Tool-N1 (§11.2) 做 GRPO RL — 三段式。 这是当前 BFCL multi-turn 类别最佳实证(xLAM-2 在 multi-turn 单维拿到 77.38%,§6.5)。

11.4 MadeAgents Hammer — function-masking SFT, on-device 取向

11.5 verl / SkyRL / NeMo-RL — 通用 RL 框架(可承载 BFCL reward)

11.6 BFCL-targeted RL papers(2025-2026)

GPT-5.5 system card verbatim: "CoT-Control includes over 13,000 tasks built from established benchmarks: GPQA, MMLU-Pro, HLE, BFCL and SWE-Bench Verified. Each task is created by pairing a benchmark problem with one CoT instruction such as avoiding certain problem-relevant keywords in CoT, using only lowercase letters, or appending a given word to each sentence." — 这把 BFCL 从"eval"提升到"训练数据源"位置,是 frontier lab 引用 BFCL 的最严肃方式。

11.7 比较矩阵 — Stage × Tool × License × BFCL-specific?

11.8 我的 take — 实战 BFCL 训练 stack 建议

1. 纯 SFT 起步: Qwen3-8B(Apache-2.0 base)+ TOUCAN-1.5M(冷启 4 epoch)+ APIGen-MT-5k(multi-turn 2 epoch)。 目标:V3 ≥70% → V4 NonLive ≥85% / Live ≥75%。 整套用 HF trainer + LoRA 在 4×A100 一周搞定。
2. RL 提升: 接 Tool-N1 的 verl+GRPO,reward 用 BFCL bfcl_eval/eval_checker/ast_eval/ 的 AST checker(直接 import,这是 §11 最关键的实操点)+ multi_turn state diff。 注意训 train split 和 eval split 严格隔离 — BFCL 没有官方 train/val split, 所以要自己做 hold-out。
3. 避坑:
   • 不要用 BFCL 原 ground truth 训 — 那是 eval 集合,等于污染
   • 不要用 xLAM ckpt 商用(cc-by-nc),要商用必须从 base model + dataset 重训
   • 不要只追 BFCL Overall — 拆分看 multi_turn vs irrelevance,常常一升一降(xLAM 案例就是典型)
4. 下一步(把 BFCL 当 prerequisite): BFCL V4 Agentic ≥50% 后,接 MCP-Atlas / MCPMark(#21),BFCL 不能替代真 MCP eval(§8.2)。

相关阅读

• #19 MCP-Atlas (Scale AI) — 真 MCP server + Live leaderboard + Claude card 引用
• #21 4-bench MCP 横评 — BFCL vs Universe vs Atlas vs Toolathlon vs MCPMark
• #22 TOUCAN — 32B SFT 在 BFCL V3 拿 70.45
• #23 EnvScaler — Qwen3-8B 在 BFCL-MT 拿 41.88 超 GPT-4.1
• #25 MCP-Universe (Salesforce) — framework + GRPO+verl RL stack
• #26 MCP bench 代码级深潜 — 4 verifier 风味互斥 + 联合训 recipe
• #27 ≤40B 小模型 MCP landscape — BFCL 在 ≤40B 训练栈中的位置
• #18 AWM — 合成 env / BFCL V3 53.83 → 65.94 OOD
• NVlabs/Tool-N1 — §11.2 当前唯一 BFCL-targeted open RL codebase(Apache-2.0)
• SalesforceAIResearch/xLAM — §11.3 BFCL multi-turn SOTA 训练 pipeline(ActionStudio + APIGen-MT)
• arXiv:2505.00024 — Tool-N1 paper (verl+GRPO+R1-style reward)