Обновить README.md

README.md

@@ -1,2 +1,115 @@
-# benchmark_llm_plantwild
+# Бенчмаркинг LLM для классификации болезней растений
 
+Этот проект представляет собой комплексное решение для тестирования мультимодальных больших языковых моделей (LLM) на задаче классификации болезней растений по изображениям. Он состоит из двух основных этапов:
+
+1.  **ETL (Extract, Transform, Load)**: Подготовка и стандартизация компактного датасета из большого исходного набора данных.
+2.  **Бенчмаркинг**: Систематическое тестирование моделей на подготовленном датасете с записью и логированием результатов.
+
+## Этап 1: Подготовка датасета (`etl.py`)
+
+### Задача
+
+Основная цель этого этапа — подготовить компактную и стандартизированную версию большого датасета изображений **PlantWild** для дальнейших исследований. Оригинальный датасет содержит более 18 000 изображений, что делает его обработку и проведение быстрых экспериментов ресурсозатратными.
+
+### Описание скрипта `etl.py`
+
+Скрипт `src/etl.py` выполняет процесс извлечения, преобразования и загрузки (ETL) данных. Его главная задача — создать новый, легковесный датасет на основе оригинального `PlantWild`.
+
+**Ключевые шаги работы скрипта:**
+
+1.  **Создание целевой директории:** Скрипт создает новую папку для обработанных данных, сохраняя исходный датасет нетронутым.
+2.  **Итерация по классам:** Он проходит по каждой папке-классу (например, `apple black rot`, `apple leaf` и т.д.) в исходном датасете.
+3.  **Отбор изображений:** Из каждого класса отбирается небольшое, заранее заданное количество изображений (например, первые 4). Это количество легко настраивается в коде.
+4.  **Обработка и стандартизация:** Каждое отобранное изображение обрабатывается:
+    *   Если его ширина превышает заданный максимум (например, 640 пикселей), изображение пропорционально уменьшается до этой ширины.
+    *   Если изображение уже меньше или равно максимальной ширине, оно копируется без изменений.
+5.  **Сохранение результата:** Обработанные изображения сохраняются в целевую директорию с сохранением исходной структуры папок (классов).
+
+В результате мы получаем небольшой, готовый к экспериментам датасет, где все изображения имеют одинаковую максимальную ширину, а количество примеров в каждом классе сбалансировано.
+
+### Как использовать `etl.py`
+
+#### 1. Установка зависимостей
+
+```bash
+pip install Pillow tqdm
+```
+
+#### 2. Настройка
+
+Перед запуском откройте файл `src/etl.py` и убедитесь, что переменные в секции `НАСТРОЙКИ` соответствуют вашим путям и требованиям:
+
+```python
+dataset_plantwild: Path = Path(r'E:\Project\OLIMP\PlantWild\plantwild')
+dataset_processed: Path = Path(r'E:\Project\OLIMP\Benchmark_LLM_PlantWild\dataset')
+num_images_per_class: int = 4
+max_width: int = 640
+```
+
+#### 3. Запуск скрипта
+
+```bash
+python src/etl.py
+```
+После выполнения в указанной папке `dataset_processed` появится готовый датасет.
+
+---
+
+## Этап 2: Тестирование моделей (`main.py`)
+
+### Задача
+
+Скрипт `src/main.py` является ядром проекта. Он использует подготовленный на первом этапе датасет для систематического тестирования vision-моделей. Скрипт отправляет каждое изображение в LLM и надежно фиксирует результат в структурированном виде.
+
+### Описание скрипта `main.py`
+
+**Ключевые особенности:**
+
+1.  **Модульная архитектура провайдеров**: Легко переключаться между различными API-провайдерами (например, OpenAI, OpenRouter) и моделями, изменяя всего пару переменных.
+2.  **Надежный JSON Mode**: Скрипт использует `response_format={"type": "json_object"}` — самый надежный способ заставить модель вернуть строго структурированный JSON. Это исключает ошибки парсинга и необходимость в сложных промптах.
+3.  **Раздельное логирование**:
+    *   **Чистые результаты**: В файл `results_{...}.csv` записываются только ключевые данные: имя файла, правильный класс и предсказание модели. Этот файл идеально подходит для последующего анализа.
+    *   **Логи ошибок**: В файл `error_log_{...}.txt` автоматически попадают только те запросы, которые завершились ошибкой (ошибка API, парсинга и т.д.), включая полный сырой ответ от сервера для легкой отладки.
+
+### Как использовать `main.py`
+
+#### 1. Установка зависимостей
+
+```bash
+pip install openai pydantic python-dotenv tqdm
+```
+
+#### 2. Настройка API ключей
+
+Создайте в корневой папке проекта файл `.env` и добавьте в него ваши API-ключи. Скрипт автоматически их подгрузит.
+
+**Пример файла `.env`:**
+```
+OPENAI_API_KEY="sk-..."
+OPENROUTER_API_KEY="sk-or-..."
+```
+
+#### 3. Настройка
+
+Откройте файл `src/main.py` и настройте следующие переменные:
+
+```python
+PROVIDER = "openai"  # или "openrouter"
+MODEL_NAME = "gpt-4o" # Укажите нужную модель
+processed_dataset_path = Path(r'E:\Project\OLIMP\Benchmark_LLM_PlantWild\dataset')
+```
+
+#### 4. Запуск тестирования
+
+```bash
+python src/main.py
+```
+Скрипт начнет обработку и будет выводить прогресс. По завершении в корне проекта появятся файлы с результатами и логами ошибок (если они были).
+
+---
+
+## Исходный датасет
+
+Этот проект использует обработанную версию датасета **PlantWild**. Вся информация об оригинальном датасете, его структуре и методах сбора доступна на официальной странице проекта:
+
+-   **[Benchmarking In-the-Wild Multimodal Plant Disease Recognition and A Versatile Baseline](https://tqwei05.github.io/PlantWild/)**