Eval AI Library¶

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

Быстрый пример¶

Ниже приведён минимальный пример, демонстрирующий основной рабочий процесс Eval AI Library: создание тест-кейса, выбор метрик и запуск оценки. Всего несколько строк кода позволяют получить количественную оценку качества ответов вашей AI-системы.

import asyncio
from eval_lib import evaluate, EvalTestCase, AnswerRelevancyMetric, FaithfulnessMetric

test_case = EvalTestCase(
    input="What is machine learning?",
    actual_output="Machine learning is a subset of AI that enables systems to learn from data.",
    expected_output="Machine learning is a branch of artificial intelligence focused on building systems that learn from data.",
    retrieval_context=[
        "Machine learning is a subset of artificial intelligence (AI) that provides systems the ability to automatically learn and improve from experience without being explicitly programmed."
    ]
)

metrics = [
    AnswerRelevancyMetric(model="gpt-4o", threshold=0.7),
    FaithfulnessMetric(model="gpt-4o", threshold=0.7),
]

results = asyncio.run(evaluate([test_case], metrics))

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

============================================================
                EVALUATION RESULTS
============================================================
Test Case 1/1: What is machine learning?

  Answer Relevancy
    Score: 0.92 | Threshold: 0.70 | PASSED

  Faithfulness
    Score: 0.95 | Threshold: 0.70 | PASSED

============================================================
Overall: 1/1 test cases passed (100.0%)
Total evaluation cost: $0.0034
============================================================

Каждая метрика возвращает числовой score от 0.0 до 1.0, где 1.0 означает идеальный результат. Порог (threshold) определяет минимальное значение score, при котором тест-кейс считается пройденным. Стоимость оценки (evaluation cost) рассчитывается автоматически на основе количества токенов, отправленных модели-судье.

Обзор архитектуры¶

Eval AI Library построена по модульному принципу. Библиотека состоит из пяти основных слоёв: ядро с API оценки и агрегацией, слой метрик с 30+ реализациями, абстрактный интерфейс провайдеров для подключения любых LLM, модуль генерации тестовых данных и модуль вывода результатов.

graph TB
    subgraph Core["🔧 Ядро"]
        direction LR
        TC[EvalTestCase]
        DS[EvalDataset]
        API["evaluate()"]
        AGG[Агрегация оценок]
    end

    subgraph Metrics["📊 Слой метрик"]
        direction LR
        RAG["RAG\nРелевантность · Верность\nТочность · Полнота"]
        AGENT["Агенты\nИнструменты\nЗадачи · Роль"]
        SEC["Безопасность\nИнъекции · Jailbreak\nPII · Вредоносность"]
        DET["Детерминированные\nRegex · JSON Schema\nТочное совпадение"]
        VEC["Векторные\nСемантическое сходство\nСовпадение с эталоном"]
        CUST["Кастомные\nG-Eval\nCustom Metric"]
    end

    subgraph Providers["☁️ Интерфейс провайдеров"]
        direction LR
        BASE["BaseLLMProvider"]
        IMPL["OpenAI · Azure · Gemini · Claude\nDeepSeek · Qwen · Mistral · Groq\nGrok · Zhipu · Ollama · Custom"]
    end

    subgraph Data["📁 Генерация данных"]
        direction LR
        DG[DataGenerator]
        FMT["PDF · DOCX · CSV\nJSON · HTML · Изображения"]
    end

    subgraph Output["📈 Вывод"]
        direction LR
        RES[EvalResult]
        DASH[Дашборд]
    end

    Core --- Metrics
    Metrics --- Providers
    Core --- Data
    Core --- Output
    BASE --- IMPL

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

Категории метрик¶

В таблице ниже перечислены все категории метрик, доступные в Eval AI Library. Каждая категория предназначена для оценки определённого аспекта вашей AI-системы.

Агрегация оценок¶

Eval AI Library использует Temperature-Controlled Verdict Aggregation via Generalized Power Mean -- новаторский подход, обеспечивающий гибкий скоринг через настраиваемые уровни строгости. Этот метод позволяет контролировать, насколько сильно единичные низкие вердикты влияют на итоговый score.

В отличие от простого среднего арифметического, обобщённое степенное среднее с параметром температуры позволяет настроить поведение агрегации от практически минимума (строгая оценка) до практически максимума (мягкая оценка). Это особенно важно для сценариев, где критически важна безопасность или, наоборот, допускается определённая степень вариативности.

Подробнее об агрегации оценок

Установка¶

Установите Eval AI Library с помощью pip:

pip install eval-ai-library

Требуется Python 3.9 и выше. Библиотека поддерживает все основные операционные системы: Linux, macOS и Windows. Подробные инструкции по установке, настройке окружения и установке дополнительных зависимостей смотрите в руководстве по установке.