🛠️ LLM Tool Calling Benchmark

Комплексный бенчмарк для оценки способностей больших языковых моделей (LLM) вызывать инструменты (function calling). Проект объединяет оригинальные сценарии тестирования с официальным набором Berkeley Function Calling Leaderboard (BFCL V4), адаптированным для локального запуска.

🎯 Назначение

Фреймворк предназначен для глубокого анализа того, как модели справляются с реальными задачами автоматизации:

1. Точность выбора: Выбор правильного инструмента из десятков доступных (включая "шумовые" функции).
2. Работа с параметрами: Извлечение сложных структур, списков и вложенных объектов.
3. Multi-turn диалоги: Поддержание контекста на протяжении 2-3 шагов (State Persistence).
4. Следование инструкциям: Обработка негативных сценариев (Refusal) и уточнений (Clarification).
5. Форматирование: Сравнение форматов OpenAI, Anthropic, Mistral и Raw JSON.

✨ Ключевые возможности

• 53 Тестовых сценария:
  • 🧩 28 Custom тестов: Оригинальные кейсы, от прогноза погоды до сложных многошаговых цепочек.
  • 🏆 25 BFCL-V4 тестов: Официальная выборка из Berkeley Function Calling Leaderboard.
• Двуязычная поддержка: Плотная интеграция Russian (RU) и English (EN) языков на уровне промптов и ожидаемых значений.
• Multi-Turn Engine: Полноценная симуляция диалога (User → Model → Tool → Output → User...) для 16 сложных сценариев (10 Custom + 6 BFCL).
• Гибкий CLI: Фильтрация по наборам (--suite), языкам (--lang), уровням сложности (--levels) и температурам.
• Детальная аналитика: Progress bars, JSONL-логи, сводные Markdown-отчёты и инструменты анализа.

📊 Структура тестов

В бенчмарк включено 53 уникальных теста, разделенных по сложности и происхождению:

Уровни сложности (Levels)

• L1 (Basic): 13 тестов. Одиночные вызовы с явными параметрами.
• L2 (Selection): 14 тестов. Выбор инструмента среди похожих, игнорирование шума.
• L3 (Multi-turn): 10 тестов. Зависимые цепочки (Sequential calls). Все тесты L3 являются multi-turn.
• L4 (Expert): 11 тестов. Параллельные вызовы и сложные ограничения. Включает 1 сложный multi-turn (BFCL-4.3).
• L5 (Complex): 5 тестов. Комбинированные сценарии (Parallel + Sequential). Все тесты L5 являются multi-turn.

🚀 Быстрый старт

1. Установка

# Клонирование репозитория
git clone https://github.com/MKreGGo/ru_tool_calling_tests.git
cd ru_tool_calling_tests

# Создание виртуального окружения
python -m venv venv

# Активация (Windows)
.\venv\Scripts\activate
# Активация (Linux/macOS)
# source venv/bin/activate

# Установка зависимостей
pip install -r requirements.txt

2. Запуск бенчмарка

Убедитесь, что ваша модель доступна через API (например, LM Studio, vLLM, Ollama) по адресу http://localhost:8000/v1 (или укажите свой URL).

Базовый запуск (все тесты, En):

python main.py --model "qwen2.5-7b"

Русская версия BFCL тестов:

python main.py --model "mistral-nemo" --suite bfcl --lang ru

Полный прогон (3 попытки, разные температуры):

python main.py --model "llama-3.1-8b" --runs 3 --temperatures 0.1,0.5,0.8

🏗️ Структура проекта

• main.py — Точка входа CLI.
• core/ — Конфигурация и API-клиент (OpenAI-compatible).
• benchmark/ — Движки для Single-turn и Multi-turn тестов.
• parsers/ — Парсеры форматов ответов (OpenAI, Anthropic, Hermes, Mistral, Raw JSON).
• tools/ — Реестр и схемы инструментов (с поддержкой RU/EN описаний) + утилиты анализа.
• tests/ — Определения тестовых сценариев и генераторы (Custom & BFCL).
• benchmark_logging/ — Логгеры и генератор финальных отчётов.

⚙️ Аргументы CLI

📝 Описание тестовых наборов

🧩 Custom Suite (28 тестов)

Разработан для проверки прикладных сценариев использования агентов.

• Single-Turn (18): Операции с файловой системой, математика, погода, управление встречами.
• Multi-Turn (10):
  • L3 Sequential: Найти файл → Прочитать → Отправить коллеге.
  • L5 Complex: Получить данные из 3 источников → Свести в отчет → Сохранить.

🏆 BFCL Suite (25 тестов)

Адаптация Berkeley Function Calling Leaderboard V4.

• L1 Basic (6): Простая геометрия, валидация строк, арифметика.
• L2 Intermediate (8): Параллельные вызовы (Parallel call), выбор из множества API.
• L3 Multi-Turn (5):
  • Ticket System: Создать тикет → Назначить → Изменить статус.
  • Robustness: Работа с "отвлекающими" инструментами и отсутствующими документациями.
• L4 Expert (6): Работа с долгосрочной памятью, финансовые ограничения, веб-поиск (Multi-turn).

---

🔍 Анализ логов

Для глубокого исследования результатов используйте встроенные инструменты:

1. tools/log_explorer.py: Интерактивный поиск, инспекция конкретных прогонов и сравнение двух разных логов.
2. tools/analyze_logs.py: Сводная аналитика по группе логов.

🛠️ Доступные инструменты (Tools)

Бенчмарк предоставляет более 50 мок-инструментов (Mock Tools), полностью имитирующих реальные API:

• System: read_file, list_directory, archive_files.
• Productivity: send_email, create_ticket, schedule_meeting.
• Data: search_database, analyze_investment, memory_store.
• External: get_weather, web_search, uber_request, stock_price.
• Math/Logic: calculate_geometry, statistics, validation.

📈 Логирование и отчёты

Бенчмарк предоставляет детальную аналитику как в процессе выполнения, так и по завершении:

1. Вывод в консоль

По завершении тестов выводится структурированный отчёт:

• Header Panel: Общая информация (модель, количество тестов, среднее время ответа).
• Token Usage: Суммарное потребление токенов (Prompt, Completion, Reasoning).
• Tables (Custom/BFCL): Подробные таблицы по уровням:
  • Level: Уровень и краткое название.
  • T=X.X: Процент успеха для каждой температуры.
  • Overall: Средний успех по уровню.
  • Tokens: Общее количество затраченных токенов на данный уровень.
• Difficulty Table: Агрегация по категориям Simple, Medium, Hard.
• Errors Panel: Счётчик ошибок парсинга и валидации.

Пример реального вывода:

╭─ 📊 Benchmark Results ───────────────────────────────────────────────────────╮
│ LLM Tool Calling Benchmark Report                                            │
│ Model: qwen2.5-7b-instruct                                                   │
│ Total Tests: 50 | Total Runs: 150 | Avg Time: 1250ms                         │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─ 🔢 Token Usage ─────────────────────────────────────────────────────────────╮
│ Prompt Tokens:     145,200                                                   │
│ Completion Tokens: 12,450                                                    │
│ Reasoning Tokens:  5,100                                                     │
│ Total Tokens:      162,750                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

Custom Tests Results
┏━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ Level      ┃ T=0.2 ┃ T=0.5 ┃ T=0.8 ┃ Overall ┃ Tokens ┃
┡━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
│ L1 Simple  │ 100%  │ 100%  │ 100%  │ 100%    │ 15,200 │
│ L2 Select  │ 100%  │ 90%   │ 80%   │ 90%     │ 24,500 │
│ L3 Seq     │ 80%   │ 70%   │ 60%   │ 70%     │ 42,100 │
│ L4 Par     │ 70%   │ 60%   │ 50%   │ 60%     │ 35,000 │
│ L5 Chain   │ 50%   │ 40%   │ 30%   │ 40%     │ 55,200 │
├────────────┼───────┼───────┼───────┼─────────┼────────┤
│ TOTAL      │ 80%   │ 72%   │ 64%   │ 72%     │ 172K   │
└────────────┴───────┴───────┴───────┴─────────┴────────┘

2. Детальные логи (.jsonl)

Каждый запуск сохраняется в файл logs/benchmark_{model}_{suite}_{lang}_{timestamp}.jsonl. Каждая строка — это полный JSON-объект записи:

• Промпты (System & User), список инструментов.
• Сырой ответ модели и результат автоматического определения формата.
• Результаты парсинга и валидации (ожидаемые vs фактические вызовы).
• Token Usage: Детальная статистика по каждому запросу.
• Timing: Время ответа API в мс.

3. Сводный отчёт (.summary.md)

Автоматически создаётся рядом с основным логом:

• Иерархический Markdown с результатами по всем категориям.
• Удобно для быстрого анализа и сравнения моделей.
• Включает детализацию по температурам и источникам тестов.

4. Инструмент исследования логов (log_explorer.py)

Для удобного анализа результатов, поиска ошибок и сравнения запусков используйте универсальный скрипт:

# Список всех доступных логов
python tools/log_explorer.py ls

# Сводная статистика по конкретному логу (можно использовать часть имени)
python tools/log_explorer.py summary "qwen3-4b"

# Просмотр списка проваленных тестов (с фильтрацией по уровню)
python tools/log_explorer.py failures "qwen3-4b" --level 3

# Детальная инспекция конкретного теста (промпты, ответы, ошибки валидации)
python tools/log_explorer.py inspect "qwen3-4b" BFCL-3.4 --run 0

# Сравнение двух запусков моделей
python tools/log_explorer.py compare "log1.jsonl" "log2.jsonl"

# Полнотекстовый поиск по промптам и ответам в логе
python tools/log_explorer.py search "qwen3-4b" "погода в Москве"

---

Created for deep analysis of LLM Agentic Capabilities.