ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Реализовать quality gates для агента

1. Цель задачи

Разработать и внедрить систему автоматических quality gates для CI/CD агента, которые фиксируют метрику faithfulness (точность следования фактам) на тестовых сценариях. При падении faithfulness ниже заданного порога (деградация более 5% от baseline) пайплайн должен завершаться с ошибкой (красный статус), блокируя деплой новой версии агента.

Ключевой результат Каждый коммит, ухудшающий faithfulness агента более чем на 5%, автоматически блокируется на этапе CI/CD, предотвращая регресс в production.

2. Исходные данные

Если нет реального агента или тестовых данных — симулируем:

1. Создать простого агента на LangGraph или LangChain с двумя-тремя вызовами LLM (например, retrieval + generate).
2. Собрать 20 тестовых запросов с эталонными ответами (факты из документов или выдуманные контексты).
3. Вычислить faithfulness вручную или через библиотеку RAGAS на одном прогоне — это будет baseline (например, 0.95).
4. Создать fork репозитория с простым CI-пайплайном (например, GitHub Actions с одним job).

3. Технологический стек

4. Этапы выполнения

Этап 1: Подготовка тестового набора и вычисление baseline (1 час)

Действия

1. Собрать или сгенерировать тестовые сценарии
   • Создать JSON-файл eval_data.json с полями: id, question, expected_answer, context (текст, из которого агент должен извлекать факты).
   • Пример (50 записей):

     [
       {
         "id": "1",
         "question": "Какой бюджет проекта на 2024 год?",
         "expected_answer": "10 млн рублей",
         "context": "Бюджет проекта на 2024 год утверждён в размере 10 млн рублей."
       },
       ...
     ]
     

2. Прогнать агента на этих сценариях — сохранить ответы агента.
3. Вычислить faithfulness для каждого ответа (например, через langchain.evaluation.load_evaluator("faithfulness") или RAGAS FaithfulnessMetric).
4. Усреднить метрику — получить baseline (назовём BASELINE_FAITHFULNESS).
5. Сохранить baseline в файл baseline.json (репозиторий) и MLflow (если доступен):

   {
     "baseline_faithfulness": 0.92,
     "date": "2025-04-01",
     "eval_count": 50,
     "std": 0.03
   }
   

Ожидаемый результат этапа Файл baseline.json в репозитории; MLflow run с baseline метрикой; eval dataset готов.

Этап 2: Разработка скрипта quality gate (1.5 часа)

Действия

1. Создать Python-скрипт quality_gate.py, который:
   • Загружает baseline из baseline.json (или из переменной окружения BASELINE_FAITHFULNESS).
   • Запускает агента на eval dataset.
   • Вычисляет faithfulness для каждого ответа.
   • Агрегирует среднюю faithfulness.
   • Сравнивает с baseline: если падение >5% (т.е. new_faithfulness < baseline * (1 - threshold)), завершается с кодом 1 (ошибка), иначе 0.
2. Добавить порог как параметр (например, --threshold 0.05).
3. Интегрировать логирование — записывать результат в metrics_output.json для последующего анализа.
4. Пример кода (упрощённый):

   import json, sys, os
   from agent import run_agent
   from evaluate import faithfulness_score
   
   def main(threshold=0.05):
       with open("baseline.json") as f:
           baseline = json.load(f)["baseline_faithfulness"]
       with open("eval_data.json") as f:
           eval_data = json.load(f)
   
       scores = []
       for item in eval_data:
           response = run_agent(item["question"])
           score = faithfulness_score(item["context"], response, item["expected_answer"])
           scores.append(score)
   
       new_faith = sum(scores) / len(scores)
       print(f"New faithfulness: {new_faith:.4f} (baseline: {baseline:.4f})")
   
       if new_faith < baseline * (1 - threshold):
           print("FAIL: Faithfulness degraded more than {:.0%}".format(threshold))
           sys.exit(1)
       else:
           print("PASS: Faithfulness within acceptable range")
           sys.exit(0)
   
   if __name__ == "__main__":
       main()
   

Ожидаемый результат этапа Скрипт quality_gate.py, который можно запустить в CI и который корректно определяет прохождение/непрохождение.

Этап 3: Интеграция в CI/CD (1 час)

Действия

1. Выбрать CI-систему (GitHub Actions в примере).
2. Создать workflow .github/workflows/quality_gate.yml:

   name: Quality Gate
   
   on: [push, pull_request]
   
   jobs:
     faithfulness:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Set up Python
           uses: actions/setup-python@v5
           with:
             python-version: '3.11'
         - name: Install dependencies
           run: pip install -r requirements.txt
         - name: Run quality gate
           run: python quality_gate.py --threshold 0.05
         - name: Upload metrics
           uses: actions/upload-artifact@v4
           with:
             name: metrics
             path: metrics_output.json
   

3. Добавить шаг уведомления (опционально):

   - if: failure()
     name: Notify Slack
     uses: slackapi/slack-github-action@v1.24.0
     with:
       webhook: ${{ secrets.SLACK_WEBHOOK }}
       payload: '{"text": "❌ Quality gate failed – faithfulness degraded >5%"}'
   

4. Привязать workflow к веткам (main, release/*).

Ожидаемый результат этапа Пайплайн запускается при каждом push и PR, блокирует мерж при падении faithfulness.

Этап 4: Настройка порогов и мониторинг (1 час)

Действия

1. Определить baseline threshold: 5% от baseline (0.05). Если baseline = 0.92, допустимый минимум = 0.874.
2. Добавить механизм обновления baseline:
   • Создать отдельный workflow (например, update_baseline.yml), который раз в месяц (или после каждого успешного релиза) заново прогоняет eval dataset на production-версии агента и перезаписывает baseline.json.
   • Использовать скрипт compute_baseline.py.
3. Настроить дашборд (опционально): Grafana + Prometheus для визуализации faithfulness во времени, используя экспортируемые метрики metrics_output.json.

Ожидаемый результат этапа Пороги согласованы с командой; baseline автоматически обновляется; есть алерты при регрессе.

Этап 5: Тестирование пайплайна (0.5 часа)

Действия

1. Создать тестовый коммит, который искусственно ухудшает faithfulness (например, уменьшить top-k retrieval или изменить prompt на менее точный).
2. Запушить в новую ветку — проверить, что CI падает с ошибкой FAIL: Faithfulness degraded more than 5%.
3. Откатить изменения — убедиться, что пайплайн зелёный.
4. Проверить, что уведомление пришло в канал.

Ожидаемый результат этапа Quality gate работает корректно, блокирует деградацию, уведомляет команду.

5. Критерии приемки (Definition of Done)

• Репозиторий содержит файлы: eval_data.json, baseline.json, quality_gate.py, compute_baseline.py, .github/workflows/quality_gate.yml.
• Скрипт quality_gate.py принимает аргумент --threshold и завершается с кодом 1 при падении faithfulness > порога.
• CI-пайплайн запускается на каждый push/PR и блокирует слияние при деградации >5%.
• Baseline faithfulness вычислен, сохранён и используется как точка отсчёта.
• При успешном прохождении gate создаётся артефакт metrics_output.json с результатами.
• Настроено уведомление о падении метрики (Slack / email).
• Документирован процесс обновления baseline (README или скрипт).
• Интеграция не влияет на время деплоя более чем на 5 минут (eval dataset до 100 сценариев).
• Пайплайн протестирован — зелёный на хорошей версии, красный на ухудшенной.

6. Ожидаемый результат

Основной артефакт

• Код quality gate (quality_gate.py), интегрированный в CI/CD репозитория.
• Файл конфигурации CI (.github/workflows/quality_gate.yml или аналогичный).
• Файлы baseline и eval dataset (baseline.json, eval_data.json).

Дополнительные артефакты

• Документация в README.md с описанием работы gate, порогов, процедуры обновления baseline.
• Интеграция с системой мониторинга (MLflow run, дашборд).

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание: Для первого раза возможен запас в 1-2 дополнительных часа на отладку интеграции CI и доработку eval dataset.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я создал eval dataset с минимум 50 тестовыми сценариями.
• Я вычислил baseline faithfulness и сохранил его в репозитории.
• Скрипт quality_gate.py корректно запускается локально и возвращает 0/1.
• CI-пайплайн запускается на push и pull request, содержит job с этим скриптом.
• Я протестировал искусственную деградацию и пайплайн покраснел.
• Настроены уведомления о падении метрики в командный канал.
• Документация в README описывает процесс обновления baseline и параметры порога.
• Время выполнения gate на CI не превышает 5 минут.