# ai_benchmark

Эксперименты и тестирование LLM, VLM и прочих тулов

## Установка

```bash
pip install -r requirements.txt
```

## Использование

### Через скрипт run.sh

```bash
./run.sh run --model llama3 --ollama-url http://localhost:11434
```

### Генерация тестов через Ollama

```bash
# Генерировать 1 тест для каждой категории через Ollama
./run.sh gen

# Или через Python напрямую
python scripts/generate_tests.py --count 1 --category all --model llama3 --ollama-url http://localhost:11434
```

### Через Python

```bash
python src/main.py --model llama3 --ollama-url http://localhost:11434
```

### Аргументы для generate_tests.py

- `--count`: Количество тестов для генерации (по умолчанию: 1)
- `--category`: Категория тестов (translation, summarization, codegen, или all) (по умолчанию: all)
- `--model`: Название модели для генерации тестов (обязательный)
- `--ollama-url`: URL подключения к Ollama серверу (обязательный)
- `--validate`: Валидировать тесты в указанной директории

### Аргументы для main.py

- `--model`: Название модели для тестирования (обязательный)
- `--ollama-url`: URL подключения к Ollama серверу (обязательный)
- `--benchmarks`: Список бенчмарков для выполнения (translation, summarization, codegen). По умолчанию все.
- `--output`: Директория для сохранения результатов. По умолчанию: `results`
- `--verbose`: Подробный режим вывода

### Примеры

Запуск всех бенчмарков через скрипт:
```bash
./run.sh run --model llama3 --ollama-url http://localhost:11434
```

Генерация тестов через Ollama:
```bash
./run.sh gen
```

Запуск только тестов переводов:
```bash
./run.sh run --model llama3 --ollama-url http://localhost:11434 --benchmarks translation
```

Очистка отчетов:
```bash
./run.sh clean
```

Запуск с подробным выводом:
```bash
./run.sh run --model llama3 --ollama-url http://localhost:11434 --verbose
```

## Структура проекта

```
ai-benchmark/
├── src/
│   ├── benchmarks/          # Модули с тестовыми наборами
│   │   ├── translation.py   # Тесты переводов
│   │   ├── summarization.py # Тесты пересказов
│   │   ├── codegen.py       # Тесты генерации кода
│   │   └── base.py          # Базовый класс для тестов
│   ├── models/              # Модули для работы с моделями
│   │   └── ollama_client.py # Клиент для Ollama
│   ├── utils/               # Утилиты
│   │   ├── report.py        # Генерация отчетов
│   │   └── scoring.py      # Вычисление метрик оценки качества
│   └── main.py              # Основной скрипт запуска
├── tests/                   # Тестовые данные
│   ├── translation/         # Данные для тестов переводов
│   ├── summarization/       # Данные для тестов пересказов
│   └── codegen/             # Данные для тестов генерации кода
├── results/                 # Результаты выполнения
├── scripts/                 # Скрипты для работы с проектом
│   ├── generate_tests.py    # Скрипт для генерации тестов
│   └── README.md            # Документация по скриптам
├── prompts/                 # Промпты для генерации тестов
│   ├── translation.txt      # Промпты для тестов перевода
│   ├── summarization.txt    # Промпты для тестов пересказа
│   └── codegen.txt          # Промпты для тестов генерации кода
├── requirements.txt         # Зависимости проекта
└── README.md                # Документация
```

## Добавление новых тестов

1. Создайте новый файл в `src/benchmarks/` наследуя от `Benchmark`
2. Реализуйте методы `load_test_data()` и `evaluate()`
3. Добавьте тестовые данные в соответствующую директорию в `tests/`
4. Обновите список бенчмарков в `src/main.py`

## Формат тестовых данных

Тестовые данные должны быть в формате TXT с разделителем:

```
Текст промпта для модели
=== разделитель ===
Ожидаемый ответ
```

Файл должен содержать два разделенных строкой `=== разделитель ===` поля:
- Первая строка - промпт для модели
- Вторая строка - ожидаемый ответ

## Результаты

После выполнения бенчмарков в директории `results/` будут сгенерированы файлы в формате Markdown с таблицами результатов. Каждый бенчмарк будет иметь свой отчет, а также будет создан сводный отчет со статистикой по всем тестам.

## Методика расчета Score (Скор)

### Основная метрика: F1-score

Каждый тест оценивается по метрике F1-score, которая вычисляется на основе сходства между ответом модели и ожидаемым ответом:

1. **Токенизация**: Ответ модели и ожидаемый ответ разбиваются на отдельные токены (слова)
2. **Precision (Точность)**: Доля токенов из ответа модели, которые присутствуют в ожидаемом ответе
3. **Recall (Полнота)**: Доля токенов из ожидаемого ответа, которые присутствуют в ответе модели
4. **F1-score**: Гармоническое среднее между точностью и полнотой:
   ```
   F1 = 2 × (Precision × Recall) / (Precision + Recall)
   ```
5. **Диапазон**: 0.0 - 1.0, где 1.0 означает идеальное совпадение

### Альтернативные метрики

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

- **Levenshtein Distance / Edit Distance**: Количество редактирований (вставок, удалений, замен) для преобразования ответа модели в ожидаемый ответ. Полезно для оценки структурных различий.
- **BLEU Score**: Популярная метрика для оценки качества машинного перевода, основанная на n-граммах. Подходит для задач переводов.
- **ROUGE Score**: Метрика для оценки качества суммаризации, основанная на перекрытии n-грамм, слов и последовательностей. Подходит для задач пересказов.
- **Code Similarity Metrics**: Для генерации кода можно использовать процент совпадения структуры кода (функции, классы, синтаксис), а также метрики типа AST (Abstract Syntax Tree) similarity.

### Средний Score

В отчетах вычисляется средний Score по всем успешно выполненным тестам в каждом бенчмарке. Этот показатель позволяет сравнить общую производительность модели по разным задачам.

### Пример расчета F1-score

Если модель ответила "hello world" на промпт, а ожидаемый ответ "hello there", расчет будет следующим:

- Токены модели: {"hello", "world"}
- Токены ожидаемого: {"hello", "there"}
- Пересечение: {"hello"}
- Precision = 1/2 = 0.5
- Recall = 1/2 = 0.5
- F1-score = 2 × (0.5 × 0.5) / (0.5 + 0.5) = 0.5

## Дополнительные возможности

### Генерация тестов

Скрипт `scripts/generate_tests.py` позволяет автоматически генерировать тесты для всех категорий:
- **Переводы** (translation): генерирует английские предложения и их переводы на русский
- **Пересказы** (summarization): генерирует тексты и их пересказы
- **Генерация кода** (codegen): генерирует задачи и соответствующий код

Тесты генерируются с использованием LLM и сохраняются в формате TXT с разделителем `=== разделитель ===`.

### Валидация тестов

Скрипт поддерживает валидацию тестов:
```bash
python scripts/generate_tests.py --validate tests/translation
```

Валидация проверяет:
- Соответствие формату (наличие разделителя)
- Наличие обязательных полей
- Корректность содержания

### Промпты

В директории `prompts/` хранятся промпты, используемые для генерации тестов. Каждый файл содержит специфические инструкции для каждой категории задач.

### Результаты отчетов

Отчеты генерируются в формате Markdown и содержат:
- Таблицы с результатами каждого теста
- Статистику по каждой метрике
- Сводные данные по всем тестам
- Сравнение результатов между разными моделями