BFCLベンチマーク完全ガイド2025：Tool Calling性能評価、リーダーボード分析、モデル比較

AIエージェント能力スタック：

┌─────────────────────┐
│  Multi-Agent 協業    │  ← Tool Callingなしで不可能
├─────────────────────┤
│  多段階計画実行      │  ← 各ステップでツール呼出
├─────────────────────┤
│  ★ Tool Calling ★   │  ← コア能力
├─────────────────────┤
│  推論（CoT）        │  ← どのツールを使うか決定
├─────────────────────┤
│  テキスト生成       │  ← 基礎能力
└─────────────────────┘

改善サイクル：

  ┌──────────┐
  │ベンチマーク│
  │  で評価   │
  └────┬─────┘
       │
  ┌────▼─────┐    ┌─────────────┐    ┌─────────────┐
  │ 弱点発見  │───►│ 改善措置     │───►│ 再評価      │
  │          │    │(プロンプト、 │    │(ベンチマーク)│
  │          │    │ ファインチューン)│  │             │
  └──────────┘    └─────────────┘    └──────┬──────┘
                                            │
                          ┌─────────────────┘
                          ▼
                    改善確認 → 繰り返し

BFCL核心情報：
─────────────────────────────────────────
テストケース：    2,000+（v3基準）
カテゴリ：       7つの主要カテゴリ
サポート言語：   Python、Java、JavaScript
評価方式：       AST + Executable
リーダーボード： gorilla.cs.berkeley.edu
最新バージョン： BFCL v3（2025）
更新周期：       四半期ごと
参加モデル：     60+（商用 + オープンソース）
─────────────────────────────────────────

# ユーザー入力
"What is the weather in San Francisco today?"

# 使用可能な関数
def get_weather(location: str, date: str = "today") -> dict:
    """Get weather information for a specific location and date."""
    pass

# 期待出力
get_weather(location="San Francisco", date="today")

# 入力: "Find me flights from NYC to LA next Friday under $500"
# 使用可能な関数:
def search_flights(
    origin: str,        # 空港コードか都市名か？
    destination: str,
    date: str,          # "next Friday" → 実際の日付変換？
    max_price: float,   # "$500" → 500.0
    currency: str = "USD"
) -> list:
    pass

# 期待: search_flights(origin="NYC", destination="LA",
#        date="2025-03-28", max_price=500.0, currency="USD")

# 使用可能な関数群（類似だが異なる）
def get_current_weather(location: str, unit: str = "celsius") -> dict:
    """Get CURRENT weather conditions for a location."""
    pass

def get_weather_forecast(location: str, days: int = 7) -> dict:
    """Get weather FORECAST for upcoming days."""
    pass

def get_historical_weather(location: str, date: str) -> dict:
    """Get HISTORICAL weather data for a past date."""
    pass

def check_severe_weather_alerts(region: str) -> list:
    """Check for severe weather ALERTS in a region."""
    pass

# テスト1: "What will the weather be like in Tokyo next week?"
# 正解: get_weather_forecast(location="Tokyo", days=7)

# テスト2: "Were there any storms in Florida last month?"
# 正解: get_historical_weather(location="Florida", date="2025-02")

# テスト3: "Is it raining in Seoul right now?"
# 正解: get_current_weather(location="Seoul")

# 入力: "What's the weather in Seoul, Tokyo, and New York?"

# 期待: 3つの独立した並列呼出し
[
    get_weather(location="Seoul"),
    get_weather(location="Tokyo"),
    get_weather(location="New York")
]

# より複雑なケース:
# "AliceとBobに挨拶メールを送り、明日のカレンダーも確認して"
[
    send_email(to="alice@example.com", subject="Greeting", body="Hello Alice!"),
    send_email(to="bob@example.com", subject="Greeting", body="Hello Bob!"),
    get_calendar(date="2025-03-26")  # 異なる関数だが並列可能
]

# 入力: "リストから最も安い目的地へのフライトを予約して"

# ステップ1: 目的地の価格を照会
destinations = get_destination_prices(origin="Seoul")
# 結果: [{"city": "Tokyo", "price": 300}, {"city": "Osaka", "price": 250}]

# ステップ2: 最安値の目的地に予約
cheapest = min(destinations, key=lambda x: x["price"])
book_flight(origin="Seoul", destination=cheapest["city"])

# シナリオ1: 関連のない関数のみ存在
# ユーザー: "人生の意味とは？"
# 使用可能: get_weather(), search_products(), book_flight()
# 期待: どの関数も呼び出さず直接回答

# シナリオ2: 部分的に関連あるが不十分
# ユーザー: "ビッグマックのカロリーは？"
# 使用可能: search_restaurants(cuisine, location)
# 期待: 関数呼出なし（レストラン検索であり、カロリー情報ではない）

# シナリオ3: 誘惑的だが誤用
# ユーザー: "プログラミングのジョークを教えて"
# 使用可能: search_web(query)
# 期待: 関数呼出なし（LLMが直接ジョーク生成可能）

Relevance Detection失敗の結果：
─────────────────────────────────────
1. 不要なAPIコスト発生
2. ユーザー体験の低下（遅い応答）
3. 誤った結果によるハルシネーション
4. セキュリティリスク（不要なデータアクセス）
─────────────────────────────────────

# 評価対象
generated_call = 'get_weather(location="Seoul", unit="celsius")'

# ASTパース
import ast
tree = ast.parse(generated_call)

# 検証項目:
# 1. 関数名が正しいか？
# 2. パラメータ名が正しいか？
# 3. パラメータタイプが正しいか？
# 4. 必須パラメータが全て含まれているか？
# 5. 存在しないパラメータが含まれていないか？

def evaluate_executable(generated_call, expected_result):
    try:
        actual_result = eval(generated_call)
        return compare_results(actual_result, expected_result)
    except TypeError as e:
        return {"status": "fail", "reason": f"Type error: {e}"}
    except Exception as e:
        return {"status": "fail", "reason": f"Execution error: {e}"}

BFCLメトリック構造：
─────────────────────────────────────────────────────

Overall Accuracy（総合正確度）
├── AST Accuracy（構文的正確度）
│   ├── Simple AST
│   ├── Multiple AST
│   ├── Parallel AST
│   └── Nested AST
├── Exec Accuracy（実行正確度）
│   ├── Simple Exec
│   ├── Multiple Exec
│   ├── Parallel Exec
│   └── Nested Exec
├── Relevance Accuracy（関連性正確度）
│   └── 不要呼出し拒否率
└── Live Test Accuracy（リアルタイムテスト）
    └── 実際のAPIに対する正確度

─────────────────────────────────────────────────────

# AST正確度計算
def calculate_ast_accuracy(predictions, ground_truth):
    correct = 0
    total = len(predictions)

    for pred, truth in zip(predictions, ground_truth):
        pred_ast = parse_function_call(pred)
        truth_ast = parse_function_call(truth)

        if (pred_ast.function_name == truth_ast.function_name and
            match_parameters(pred_ast.params, truth_ast.params)):
            correct += 1

    return correct / total

# パラメータマッチング（順序不問、タイプ一致）
def match_parameters(pred_params, truth_params):
    for key in truth_params:
        if key not in pred_params:
            return False
        if not type_match(pred_params[key], truth_params[key]):
            return False
    return True

# Relevance正確度計算
def calculate_relevance_accuracy(predictions, labels):
    tp = sum(1 for p, l in zip(predictions, labels)
             if p == "no_call" and l == "irrelevant")
    fp = sum(1 for p, l in zip(predictions, labels)
             if p != "no_call" and l == "irrelevant")

    precision = tp / (tp + fp) if (tp + fp) > 0 else 0
    return precision

強み：
  + Relevance Detection最高性能（94.5%）
  + 複雑なパラメータ抽出の正確度が高い
  + ネスト呼出チェーンで安定的

弱み：
  - 一部の並列呼出しで順次呼出しに変換
  - 非常に多いツール（20+）提供時に選択正確度低下

強み：
  + Parallel呼出しで最高性能（91.2%）
  + JSONスキーマ準拠率が非常に高い
  + ストリーミングツール呼出しの安定性

弱み：
  - RelevanceでClaudeより低い
  - 時折不要なツール呼出し発生

強み：
  + 高速な応答速度
  + コスト効率的
  + マルチモーダル入力と結合したツール呼出し

弱み：
  - 複雑なネスト呼出しで正確度低下
  - 一部エッジケースでパラメータタイプエラー

コスト効率性（正確度 / コスト）：
─────────────────────────────────────────
モデル                    | 正確度 | コスト(/1M tok) | 効率性
GPT-4o-mini               | 80.8%  | ~$0.30          | *****
Claude 3.5 Haiku          | 88.5%  | ~$2.40          | ****
Gemini 2.0 Flash          | 90.1%  | ~$0.40          | *****
Claude 3.5 Sonnet         | 92.4%  | ~$9.00          | ***
GPT-4o                    | 91.8%  | ~$7.50          | ***
Llama 3.1 70B (self)      | 81.5%  | ~$0.10*         | *****
─────────────────────────────────────────
* セルフホスティング基準推定

# BFCLリポジトリをクローン
git clone https://github.com/ShishirPatil/gorilla.git
cd gorilla/berkeley-function-call-leaderboard

# 依存関係のインストール
pip install -r requirements.txt

# またはpipで直接インストール
pip install bfcl

# 基本評価の実行
from bfcl import evaluate

# OpenAIモデルの評価
results = evaluate(
    model="gpt-4o",
    categories=["simple", "multiple", "parallel", "relevance"],
    api_key="your-openai-api-key"
)

print(f"Overall Accuracy: {results['overall']:.2%}")
print(f"Simple: {results['simple']:.2%}")
print(f"Multiple: {results['multiple']:.2%}")
print(f"Parallel: {results['parallel']:.2%}")
print(f"Relevance: {results['relevance']:.2%}")

# CLIで実行
python eval.py \
    --model gpt-4o \
    --categories simple multiple parallel relevance \
    --output-dir ./results

# Anthropicモデル
python eval.py \
    --model claude-3-5-sonnet \
    --categories all \
    --output-dir ./results

# ローカルモデル（vLLMサーバー）
python eval.py \
    --model local \
    --api-base http://localhost:8000/v1 \
    --categories all

from bfcl import BFCLEvaluator

class MyModelHandler:
    """カスタムモデルハンドラー"""

    def __init__(self, model_path):
        self.model = load_my_model(model_path)

    def generate(self, prompt, tools, **kwargs):
        """
        BFCLが呼び出すインターフェース。
        prompt: ユーザー入力
        tools: 使用可能なツール定義リスト
        戻り値: 関数呼出し文字列または"NO_CALL"
        """
        formatted_prompt = self.format_prompt(prompt, tools)
        response = self.model.generate(formatted_prompt)
        return self.parse_tool_call(response)

    def format_prompt(self, prompt, tools):
        tool_descriptions = "\n".join([
            f"Function: {t['name']}\n"
            f"Description: {t['description']}\n"
            f"Parameters: {json.dumps(t['parameters'])}"
            for t in tools
        ])
        return f"""Available functions:
{tool_descriptions}

User query: {prompt}

Respond with a function call or "NO_CALL" if no function is relevant."""

# 評価実行
evaluator = BFCLEvaluator()
handler = MyModelHandler("/path/to/model")

results = evaluator.evaluate(
    handler=handler,
    categories=["simple", "multiple", "parallel", "relevance"],
    output_dir="./my_model_results"
)

evaluator.generate_report(results, "./report.html")

custom_test = {
    "id": "custom_001",
    "category": "simple",
    "prompt": "チームのSlackチャンネルに「ミーティング開始」と送って",
    "available_functions": [
        {
            "name": "send_slack_message",
            "description": "Send a message to a Slack channel",
            "parameters": {
                "type": "object",
                "properties": {
                    "channel": {
                        "type": "string",
                        "description": "Slack channel name"
                    },
                    "message": {
                        "type": "string",
                        "description": "Message text"
                    }
                },
                "required": ["channel", "message"]
            }
        }
    ],
    "ground_truth": 'send_slack_message(channel="team", message="ミーティング開始")',
}

evaluator.evaluate_custom(
    handler=handler,
    test_cases=[custom_test],
    output_dir="./custom_results"
)

# API-Bank特徴: 3段階評価
# Level 1: API呼出し能力（単一）
# Level 2: API検索 + 呼出し（正しいAPIの発見）
# Level 3: API組み合わせ + 計画（多段階）

# 例（Level 3）:
# "明日の午前中に会議があるか確認し、あれば参加者に通知して"
# -> Step 1: check_calendar(date="tomorrow", time="morning")
# -> Step 2: if meeting exists, get_attendees(meeting_id=...)
# -> Step 3: send_notification(recipients=..., message=...)

# ToolBench特徴: RapidAPIの実際の16,000+ APIベース

# カテゴリ:
# - Single Tool: 単一API使用
# - Intra-Category: 同カテゴリ内の複数API
# - Inter-Category: 異なるカテゴリのAPI組み合わせ

# 評価メトリック:
# - Pass Rate: 実行成功率
# - Win Rate: 他モデルとの比較選好度（GPT-4評価）

# T-Eval特徴: ツール使用の各段階を細密に評価
# 6つのサブ能力を測定:

# 1. Instruct Following: 指示理解
# 2. Plan: 作業計画策定
# 3. Reason: 正しいツール推論
# 4. Retrieve: 適切なツール検索
# 5. Understand: ツールドキュメント理解
# 6. Review: 結果検証と修正

どのベンチマークを使うべきか？
─────────────────────────────────────────────────
目的                         | 推奨ベンチマーク
総合Tool Calling評価          | BFCL
大規模実APIテスト             | ToolBench
段階別細密分析                | T-Eval
多段階API計画評価             | API-Bank
クイック基本評価              | BFCL（Simpleのみ）
自社モデル比較                | BFCL + カスタムテスト
─────────────────────────────────────────────────

import json
from openai import OpenAI

def generate_training_data(tools, num_examples=1000):
    """GPT-4oを使用して学習データを生成"""
    client = OpenAI()
    training_data = []

    tool_descriptions = json.dumps(tools, indent=2)

    for i in range(num_examples):
        # 1. 自然言語クエリ生成
        query_response = client.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": f"""Generate a natural language query
requiring one of these tools:
{tool_descriptions}

Generate diverse, realistic queries with edge cases.
Respond with ONLY the query text."""},
                {"role": "user", "content": f"Generate query #{i+1}"}
            ]
        )
        query = query_response.choices[0].message.content

        # 2. 正しい関数呼出し生成
        call_response = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": query}],
            tools=[{"type": "function", "function": t} for t in tools],
            tool_choice="auto"
        )

        if call_response.choices[0].message.tool_calls:
            tc = call_response.choices[0].message.tool_calls[0]
            training_data.append({
                "messages": [
                    {"role": "system", "content": f"Tools: {tool_descriptions}"},
                    {"role": "user", "content": query},
                    {"role": "assistant", "content": None, "tool_calls": [
                        {
                            "type": "function",
                            "function": {
                                "name": tc.function.name,
                                "arguments": tc.function.arguments
                            }
                        }
                    ]}
                ]
            })

    return training_data

# 段階的最適化プロセス

# Step 1: 初期説明
v1 = {
    "name": "search_products",
    "description": "Search for products"  # シンプルすぎ
}

# Step 2: 明確な用途説明を追加
v2 = {
    "name": "search_products",
    "description": "Search for products in the catalog by name, category, or keywords. Returns matching products with price and availability."
}

# Step 3: 使用/非使用条件を追加
v3 = {
    "name": "search_products",
    "description": """Search for products in the e-commerce catalog.

USE WHEN: User wants to find, browse, or compare products.
DO NOT USE: For order status (use get_order), account info, or returns.

Returns: List of products with name, price, rating, availability."""
}

# Step 4: 例を追加（最終版）
v4 = {
    "name": "search_products",
    "description": """Search for products in the e-commerce catalog.

USE WHEN: User wants to find, browse, or compare products.
DO NOT USE: For order status, account info, or returns.

EXAMPLES:
- "wireless headphones" -> query="wireless headphones"
- "cheap laptops under $500" -> query="laptops", max_price=500

Returns: Products with name, price, rating, availability."""
}

def analyze_errors(results):
    """BFCL結果からエラーパターンを分析"""

    error_categories = {
        "wrong_function": [],    # 誤った関数選択
        "missing_params": [],    # 必須パラメータ欠落
        "wrong_param_type": [],  # パラメータタイプエラー
        "extra_params": [],      # 不要パラメータ追加
        "unnecessary_call": [],  # 不要な関数呼出し
        "missing_call": [],      # 必要な関数未呼出し
        "wrong_value": [],       # パラメータ値エラー
    }

    for failure in results["failures"]:
        error_type = classify_error(failure)
        error_categories[error_type].append(failure)

    print("Error Distribution:")
    print("=" * 50)
    total = sum(len(v) for v in error_categories.values())
    for category, errors in sorted(
        error_categories.items(),
        key=lambda x: len(x[1]),
        reverse=True
    ):
        pct = len(errors) / total * 100 if total > 0 else 0
        print(f"  {category}: {len(errors)} ({pct:.1f}%)")

    return error_categories

Tool Calling改善サイクル：
─────────────────────────────────────────────────

ステップ1: 現在の性能測定
  - BFCL全カテゴリ実行
  - カテゴリ別正確度を記録

ステップ2: 弱点特定
  - エラー分析を実行
  - 最頻エラータイプの把握
  - 失敗ケースパターン分析

ステップ3: 改善措置
  ├─ プロンプト改善（即効性あり）
  │   - Tool Description改善
  │   - System Prompt最適化
  │   - Few-shot例の追加
  ├─ ツール設計改善（中期）
  │   - スキーマ簡素化
  │   - 関連ツール統合
  │   - パラメータ名の明確化
  └─ ファインチューニング（長期）
      - 失敗ケースベースの学習データ生成
      - LoRA/QLoRAファインチューニング
      - 評価 + 反復

ステップ4: 再評価
  - 同じベンチマークで再測定
  - 改善率を確認
  - 新しい弱点の特定

→ ステップ2に戻る

ベンチマークの限界：
─────────────────────────────────────────────────
1. 曖昧なユーザー入力
   ベンチマーク: 「ソウルの天気」（明確）
   現実:        「天気どう？」（場所なし、時間不明）

2. 会話コンテキスト依存
   ベンチマーク: シングルターンテスト
   現実:        前の会話で「そこ」がどこか推論

3. エラー回復
   ベンチマーク: 正常応答のみテスト
   現実:        API障害、タイムアウト、不正な応答の処理

4. ツール数の爆発
   ベンチマーク: 5-10個のツール
   現実:        50-100個のツールを同時提供

5. リアルタイム性能
   ベンチマーク: 正確度のみ測定
   現実:        速度、コスト、安定性全てが重要
─────────────────────────────────────────────────

class ProductionEvalSuite:
    def __init__(self, tools, model):
        self.tools = tools
        self.model = model
        self.test_cases = []

    def add_test_case(self, category, prompt, expected, context=None):
        self.test_cases.append({
            "category": category,
            "prompt": prompt,
            "expected": expected,
            "context": context or []
        })

    def build_standard_suite(self):
        # 1. 基本機能テスト
        self.add_test_case(
            "basic", "ソウルの天気を教えて",
            "get_weather(location='Seoul')"
        )

        # 2. 曖昧な入力テスト
        self.add_test_case(
            "ambiguous", "天気どう？",
            "ASK_CLARIFICATION"
        )

        # 3. マルチターンコンテキストテスト
        self.add_test_case(
            "multi_turn",
            "そこの明日の天気は？",
            "get_weather(location='Seoul', date='tomorrow')",
            context=[
                {"role": "user", "content": "ソウルの天気を教えて"},
                {"role": "assistant", "content": "ソウルは現在15度です。"}
            ]
        )

        # 4. 関連性テスト
        self.add_test_case(
            "relevance", "人生の意味って何？",
            "NO_CALL"
        )

    def run(self):
        results = {"total": 0, "correct": 0, "by_category": {}}
        for test in self.test_cases:
            result = self.evaluate_single(test)
            results["total"] += 1
            if result["correct"]:
                results["correct"] += 1
        results["accuracy"] = results["correct"] / results["total"]
        return results

class ToolCallingMonitor:
    def __init__(self):
        self.metrics = {
            "total_calls": 0,
            "successful_calls": 0,
            "failed_calls": 0,
            "unnecessary_calls": 0,
            "latency_sum": 0,
            "cost_sum": 0,
        }

    def record_call(self, tool_name, success, latency, cost,
                    was_necessary=True):
        self.metrics["total_calls"] += 1
        if success:
            self.metrics["successful_calls"] += 1
        else:
            self.metrics["failed_calls"] += 1
        if not was_necessary:
            self.metrics["unnecessary_calls"] += 1
        self.metrics["latency_sum"] += latency
        self.metrics["cost_sum"] += cost

    def get_dashboard_data(self):
        total = self.metrics["total_calls"]
        if total == 0:
            return {}
        return {
            "success_rate": self.metrics["successful_calls"] / total,
            "failure_rate": self.metrics["failed_calls"] / total,
            "unnecessary_rate": self.metrics["unnecessary_calls"] / total,
            "avg_latency": self.metrics["latency_sum"] / total,
            "total_cost": self.metrics["cost_sum"],
        }

    def alert_on_anomaly(self):
        data = self.get_dashboard_data()
        alerts = []
        if data.get("failure_rate", 0) > 0.1:
            alerts.append("HIGH: ツール呼出し失敗率が10%超過")
        if data.get("unnecessary_rate", 0) > 0.2:
            alerts.append("MEDIUM: 不要ツール呼出しが20%超過")
        if data.get("avg_latency", 0) > 5.0:
            alerts.append("MEDIUM: 平均レイテンシが5秒超過")
        return alerts