Local Large Language Models Benchmark - LLaMBa

Гибкая система для быстрого тестирования локальных LLM-моделей с возможностью экспериментирования с различными параметрами и оценки их влияния на качество ответов.

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

1. Простое конфигурирование экспериментов — все параметры эксперимента (модель, промт, параметры генерации) задаются в YAML-файле.

2. Гибкая система пайплайнов — можно легко создавать различные способы формирования промтов (базовые запросы, RAG, структурированный вывод и т.д.) без изменения ядра системы.

3. Автоматическая оценка качества — система автоматически оценивает качество ответов модели, сравнивая их с эталонными ответами, что позволяет количественно измерять влияние изменений параметров.

4. Воспроизводимость — каждый эксперимент сохраняет свою конфигурацию и результаты, что позволяет легко сравнивать различные подходы и отслеживать прогресс.

5. Минимальные зависимости — проект использует только необходимые библиотеки и работает с локальными моделями через Ollama.

Требования

• Python >= 3.13
• Ollama (установленный и запущенный)
• uv (менеджер пакетов)

Установка

1. Клонируйте репозиторий:

2. Установите зависимости с помощью
   uv
   :

3. Убедитесь, что Ollama запущен:

Если Ollama не установлен, следуйте инструкциям на ollama.ai.

Важно: Программа автоматически проверяет доступность Ollama при запуске. Если Ollama не запущен, программа выведет сообщение об ошибке и завершит работу. В этом случае запустите Ollama командой

и повторите запуск программы.

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

1. Создайте конфигурационный файл в директории

   configs/
   (см. пример ниже).

2. Подготовьте файл с вопросами в формате Excel. Файл должен содержать следующие столбцы:

   • №
     — номер вопроса (число)
   • Вопрос для модели
     — текст вопроса, который будет отправлен модели (обязательное поле)
   • Текст из источника
     — контекст из исходного источника (опциональное поле, может быть пустым)
   • Правильный ответ
     — эталонный ответ для сравнения (опциональное поле, может быть пустым)

3. Запустите эксперимент:

Примечание: Программа автоматически проверяет доступность Ollama на

при запуске. Если Ollama не запущен, вы увидите сообщение:

❌ Ollama не запущен. Пожалуйста, запустите ollama перед запуском эксперимента.
   Команда для запуска: ollama serve

В этом случае запустите Ollama в отдельном терминале и повторите запуск программы.

4. Результаты будут сохранены в директории, указанной в

   output_dir
   конфигурации:
   • answers.xlsx
     — таблица с вопросами, контекстом (заполняется только если используется в pipeline), системным промтом (первые 100 символов), промтами, ответами модели, оценками качества и временем ответа. В конце таблицы добавляется строка с медианным баллом качества ответов (после пустой строки)
   • config.yaml
     — копия конфигурации эксперимента для воспроизводимости

5. После каждого запуска автоматически обновляется файл сводной статистики:

   • data/experiments/statistics.html
     — HTML файл с красивой таблицей со статистикой по всем экспериментам из папки
     data/experiments/
     . Файл содержит две вкладки:
     • Детальная статистика — таблица со всеми экспериментами, содержащая основные параметры каждого эксперимента (модель, пайплайн, системный промпт, temperature, top_p, top_k), медианный балл качества, дату и время эксперимента, среднее время ответа. Таблица сортируется по медианному баллу (по убыванию).
     • Сводная статистика — таблица, в которой эксперименты с одинаковыми параметрами конфигурации (модель, пайплайн, системный промпт, temperature, top_p, top_k) объединены в группы. Для каждой группы отображаются:
       • Разброс значений медианного балла качества (от минимального до максимального)
       • Медианное значение медианного балла качества по группе
       • Среднее время ответов на один вопрос по группе
       • Количество экспериментов в группе Сводная статистика позволяет упростить аналитику экспериментов, в которых входные параметры одинаковые, а выходные варьируются в некотором диапазоне. Файл автоматически обновляется после каждого запуска
         main.py
         и имеет встроенные CSS стили для читаемости. После успешной генерации файл автоматически открывается в браузере по умолчанию

Конфигурация

Система поддерживает два формата конфигурационных файлов:

Формат 1: Один эксперимент

Каждый эксперимент описывается YAML-файлом конфигурации. Пример:

Формат 2: Серия экспериментов

Позволяет описать несколько экспериментов с общими параметрами. Все эксперименты сохраняются в один Excel файл, но каждый эксперимент — на отдельном листе. Пример:

При использовании формата серии экспериментов:

• Поля из секции
  common
  применяются ко всем экспериментам
• Поля из секции
  experiments
  перезаписывают соответствующие поля из
  common
• Каждый эксперимент запускается отдельно и выводится в консоль с разделителями
• Все результаты сохраняются в один файл
  answers.xlsx
  с несколькими листами (имя листа =
  name
  из эксперимента, если
  num_repetitions == 1
  , или "<имя> - N" при повторениях)

Параметр

num_repetitions

Параметр

позволяет запускать один и тот же эксперимент несколько раз подряд с сохранением результатов каждого запуска на отдельном листе Excel файла. Это полезно для оценки вариативности результатов модели при одинаковых параметрах.

Для формата одного эксперимента:

• Если
  num_repetitions
  не указан или равен 1, эксперимент запускается один раз, как обычно
• Если
  num_repetitions > 1
  , эксперимент запускается указанное количество раз
• Результаты каждого повторения сохраняются на отдельном листе с именами "Повтор 1", "Повтор 2", "Повтор 3" и т.д.
• Медианный балл вычисляется для каждого повторения отдельно
• В консоль выводится информация о каждом повторении
• После завершения всех повторений выводится агрегированная статистика: медианный балл по всем повторениям и разброс значений (от минимального до максимального)

Для формата серии экспериментов:

• Параметр
  num_repetitions
  может быть указан в секции
  common
  (применяется ко всем экспериментам) или в конкретном эксперименте (перезаписывает значение из
  common
  )
• Если
  num_repetitions == 1
  или не указан, эксперимент запускается один раз, как обычно
• Если
  num_repetitions > 1
  , эксперимент запускается указанное количество раз
• Результаты каждого повторения сохраняются на отдельном листе с именами "<имя_эксперимента> - 1", "<имя_эксперимента> - 2" и т.д.
• Медианный балл вычисляется для каждого повторения отдельно
• В консоль выводится информация о каждом повторении
• После завершения всех повторений каждого эксперимента выводится агрегированная статистика: медианный балл по всем повторениям и разброс значений (от минимального до максимального)

Пример для формата одного эксперимента:

Пример для формата серии экспериментов:

Примечание: Каждое повторение отображается как отдельный эксперимент в статистике (файл

), что позволяет видеть вариативность результатов модели при одинаковых параметрах.

Поля конфигурации

Для формата одного эксперимента:

• name
  — имя эксперимента
• model
  — идентификатор модели Ollama (например,
  qwen3:0.6b
  ,
  llama3.2:3b
  )
• pipeline
  — название пайплайна (должен быть зарегистрирован в
  src/pipelines/__init__.py
  ). Доступные пайплайны:
  • baseline
    — простой запрос к модели, использует только вопрос (контекст игнорируется)
  • rag
    — RAG-pipeline, передаёт модели контекст из источника вместе с вопросом
  • cheat
    — "читерский" pipeline для проверки способности модели выдать 100%-й результат. Передаёт модели правильный ответ и просит его повторить. Используется для верификации того, что модель способна при идеальных условиях выдать корректный ответ. В шаблоне промта доступен плейсхолдер
    {ground_truth}
    для правильного ответа
• system_prompt
  (опционально) — системный промпт, который передаётся в Ollama API как отдельный параметр
  system
  (не конкатенируется с пользовательским промтом). Позволяет задать роль модели (например, "Ты - опытный председатель ТСЖ, который очень хорошо знает законодательство Российской Федерации"). В Excel сохраняются первые 100 символов системного промта в колонке "Системный промт". По умолчанию пустая строка
• system_prompt_file
  (опционально) — путь к файлу с системным промтом (относительно директории конфига). Позволяет выносить большие системные промты в отдельные файлы. Нельзя указывать одновременно с
  system_prompt
  (если оба параметра заданы непустыми, программа выдаст ошибку)
• prompt_template
  — шаблон промта с плейсхолдерами
  {question}
  и
  {context}
• parameters
  — дополнительные параметры модели:
  • temperature
    (float, опционально) — температура сэмплирования. Чем выше значение, тем более разнообразные ответы генерирует модель
  • top_p
    (float, опционально) — nucleus sampling параметр. Ограничивает выборку токенов с кумулятивной вероятностью
  • top_k
    (int, опционально) — top-k sampling параметр. Ограничивает количество токенов с наибольшей вероятностью, из которых модель выбирает следующий токен
  • enable_thinking
    (bool, опционально) — управляет thinking-режимом для моделей типа Qwen3. При
    false
    в промт добавляется
    /no_think
    , что отключает генерацию блоков
    <think>...</think>
    . По умолчанию
    true
    (thinking включен)
• input_path
  — путь к Excel-файлу с вопросами
• output_dir
  — директория для сохранения результатов
• num_repetitions
  (опционально) — количество повторений эксперимента. Если указано значение > 1, эксперимент запускается указанное количество раз, и результаты каждого повторения сохраняются на отдельном листе Excel файла с именами "Повтор 1", "Повтор 2" и т.д. По умолчанию 1 (один эксперимент, один лист)

Для формата серии экспериментов:

• common
  — общие параметры для всех экспериментов (те же поля, что и для одного эксперимента, кроме
  name
  ). Параметр
  num_repetitions
  может быть указан в
  common
  и будет применяться ко всем экспериментам, если не переопределён в конкретном эксперименте
• experiments
  — список экспериментов, каждый из которых содержит:
  • name
    — имя эксперимента (используется как имя листа в Excel, если
    num_repetitions == 1
    , или как префикс для имён листов при повторениях)
  • system_prompt
    (опционально) — перезаписывает
    system_prompt
    из
    common
  • system_prompt_file
    (опционально) — путь к файлу с системным промтом (относительно директории конфига). Нельзя указывать одновременно с
    system_prompt
  • parameters
    (опционально) — перезаписывает
    parameters
    из
    common
  • num_repetitions
    (опционально) — перезаписывает
    num_repetitions
    из
    common
    . Если указано значение > 1, эксперимент запускается указанное количество раз, и результаты каждого повторения сохраняются на отдельном листе с именами "<имя> - 1", "<имя> - 2" и т.д.
  • Любые другие поля из формата одного эксперимента (перезаписывают соответствующие поля из
    common
    )

Архитектура

Система состоит из четырёх основных компонентов: конфигурация экспериментов, пайплайны формирования промтов, компонент запуска экспериментов и вспомогательные модули для работы с LLM, Excel и оценкой качества.

Сценарий работы

1. Создайте или модифицируйте .yaml-файл конфигурации в
   ./configs/
   .
2. Запустите Ollama командой
   ollama serve
   (если ещё не запущено).
3. Запустите эксперимент:
   uv run main.py --config configs/<experiment>.yaml
   .
4. Изучите результаты в папке
   ./data/experiments/<experiment>/
   :
   • answers.xlsx
     — таблица с результатами эксперимента
   • config.yaml
     — копия конфигурации для воспроизводимости
5. Просмотрите сводную статистику по всем экспериментам в файле
   ./data/experiments/statistics.html
   (автоматически открывается в браузере). На странице доступны две вкладки: "Детальная статистика" (все эксперименты) и "Сводная статистика" (группировка экспериментов с одинаковыми параметрами).

Целевая аудитория

• Исследователи, изучающие возможности локальных LLM
• Разработчики, которым нужно найти оптимальные настройки модели для конкретной задачи
• Энтузиасты, экспериментирующие с различными моделями и параметрами

Лицензия

MIT