# Eval-API

Сервис для расчёта различных метрик качества текста.

## Содержание
- [Обзор](#обзор)
- [Функционал](#функционал)
- [Установка](#установка)
- [Использование](#использование)
- [API Endpoints](#api-endpoints)

## Обзор

Eval-API предоставляет инструменты для оценки качества генерируемого текста путем сравнения с эталонным текстом. \
Сервис вычисляет ряд метрик, таких как ROUGE, BERT-Score, METEOR и ряд метрик на основе распознавания именнованных сущностей(NER), а также метрики [Ragas](https://github.com/explodinggradients/ragas) для оценки качества ответов.

Проект реализован как REST API с использованием фреймворка FastAPI, что обеспечивает высокую производительность и удобство использования.

## Функционал

- **Расчёт метрик ROUGE (Rouge-L, Rouge-2)** - оценка текстового перекрытия между сгенерированным и эталонным текстом
- **BERTScore** - семантическая оценка сходства текстов с использованием контекстуальных эмбеддингов
- **METEOR** - метрика, учитывающая синонимы и морфологические варианты слов
- **NER-метрики** - оценка точности извлечения именованных сущностей:
  - F1-мера
  - Точность (Precision)
  - Полнота (Recall)
  - IoU (Intersection over Union)
  - **Ragas-метрики** - комплексная оценка качества ответов:
  - Response Relevancy - релевантность ответа
  - Context Utilization - эффективность использования контекста
  - Answer Accuracy - точность ответа
  - Non-LLM String Similarity - текстовое сходство без использования LLM
- **Автоматическая валидация** - проверка результатов на соответствие допустимым значениям метрик

## Установка

### Ручная установка

#### Сборка образа

```bash
make build
```

#### Запуск контейнера

```bash
make run
```

После выполнения сервис будет доступен по адресу http://localhost:8099.

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

После запуска сервиса доступна автоматическая документация по адресу:
- **Swagger UI**: http://localhost:8099/docs

### Пример запроса

```json
{
    "reference": "Это эталонный текст с упоминанием Python, FastAPI и NLP.",
    "hypothesis": "Текст содержит упоминания Python и обработки естественного языка.",
    "user_input": "Расскажи про инструменты для NLP",
    "context": ["Python - популярный язык программирования для NLP", "FastAPI - современный фреймворк для создания API"]
}
```

### Пример ответа

```json
{
  "ner": {
    "f1": 0.6666666666666666,
    "precision": 1.0,
    "recall": 0.5,
    "iou": 0.5
  },
  "ragas": {
    "response_relevancy": 0.85,
    "context_utilization": 0.76,
    "answer_accuracy": 0.92,
    "non_llm_string_similarity": 0.63
  },
  "rouge": {
    "rouge_l": 0.5714285714285714,
    "rouge_2": 0.3333333333333333
  },
  "bert_score": 0.8945612311363220,
  "meteor": 0.7123456835746765
}
```

## API Endpoints

### Расчёт метрик

**URL**: `/compute_metrics`
**Метод**: POST

**Запрос**:
- `reference` (обязательный) - Эталонный текст
- `hypothesis` (обязательный) - Сгенерированный или проверяемый текст
- `user_input` (необязательный) - Запрос пользователя, на основе которого был сгенерирован ответ
- `context` (необязательный) - Список контекстов, использованных для генерации ответа

**Ответ**:
- `ner` - Объект с метриками для именованных сущностей (f1, precision, recall, iou)
- `rouge` - Объект с метриками ROUGE (rouge_l, rouge_2)
- `ragas` - Объект с метриками Ragas (response_relevancy, context_utilization, answer_accuracy, non_llm_string_similarity)
- `bert_score` - Значение BERTScore
- `meteor` - Значение METEOR

---

Если у вас возникнут вопросы или потребуется помощь, не стесняйтесь обращаться!