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

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

Научиться создавать размеченный «золотой» набор данных (golden dataset), который служит эталоном для тестирования и оценки агентов. Разработать 100 пар «входной запрос → trajectory|ожидаемая траектория агента (последовательность действий, вызовы инструментов, наблюдения)» и обеспечить согласованность разметки между аннотаторами (Inter‑annotator agreement >0.85). Такой датасет позволяет автоматизировать тестирование|регрессионное тестирование и сравнивать разные версии агентов.

Ключевой результат Файл golden_dataset_v1.json со 100 примерами и отчёт о согласованности разметки (Cohen’s κ ≥ 0.85).

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

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

1. Создать простого агента на Python с помощью LangChain / LangGraph, который умеет отвечать на вопросы по документации (например, по pandas). Агент имеет инструменты: search_docs, calculate.
2. Для каждого из 100 запросов запустить агента (любой моделью, качество не важно) и записать его фактические шаги – это сырая запись траектории.
3. Аннотаторы будут не просто копировать сырые шаги, а создавать идеальную, эталонную траекторию – то есть минимально необходимые действия для правильного ответа.

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

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

Этап 1: Определение схемы разметки и подготовка датасета (1–2 часа)

Действия

1. Определить структуру траектории агента
   Каждая траектория – это последовательность шагов. Шаг состоит из:

   • step_id (int),
   • action (строка – название вызванного инструмента или final_answer),
   • input_summary (краткое описание, что передано в инструмент),
   • output_summary (ожидаемый результат вызова).

   Пример:

   {
     "query": "Какая средняя продажа за декабрь 2024?",
     "expected_trajectory": [
       {"step": 1, "action": "search_docs", "input_summary": "поиск отчёта по продажам за декабрь", "output_summary": "данные по продажам"},
       {"step": 2, "action": "calculate", "input_summary": "среднее по столбцу Revenue", "output_summary": "12345.67"},
       {"step": 3, "action": "final_answer", "input_summary": "12345.67", "output_summary": "Средняя продажа: 12345.67"}
     ]
   }
   

2. Подготовить 100 запросов
   Сгенерировать запросы, покрывающие разные сценарии (простые, требующие одного инструмента, сложные с несколькими шагами, граничные случаи).
   Записать в файл queries.csv с колонками: query_id, query_text.

3. Развернуть инструмент разметки
   Создать Google Sheet с колонками:

   • query_id, query_text, annotator_name, trajectory_json, status. Предусмотреть валидацию: ячейка trajectory_json должна содержать валидный JSON по схеме.

Ожидаемый результат этапа
Готовая схема траектории, 100 запросов в файле, настроенная таблица для разметки.

Этап 2: Первый раунд аннотации (3–4 часа)

Действия

1. Разделить 100 запросов на 3 набора (например, по 40 / 30 / 30) для каждого аннотатора, с перекрытием не менее 30% (т.е. минимум 30 общих запросов для всех аннотаторов).
2. Каждый аннотатор для каждого своего запроса заполняет колонку trajectory_json – последовательность действий, которая, по его мнению, должна быть выполнена агентом для правильного ответа.
   Важно: аннотаторы не видят траектории друг друга.
3. Зафиксировать время – не более 2 минут на один пример (180 минут на 90 примеров с учётом повторений).

Ожидаемый результат этапа
Таблица с размеченными траекториями от 2–3 аннотаторов, как минимум 30 запросов размечены всеми.

Этап 3: Измерение согласованности и разрешение конфликтов (1–2 часа)

Действия

1. Экспортировать данные в CSV, написать Python-скрипт compute_agreement.py, который:

   • Для каждого общего запроса вычисляет попарное совпадение последовательностей (например, с помощью расстояния Левенштейна на уровне действий и нормализации к [0,1]).
   • Строит матрицу согласия и вычисляет Cohen’s κ (для 2 аннотаторов) или Fleiss’ κ (для 3+) на основе бинарной метрики «шаг совпадает / не совпадает».
   • Выводит средний κ по всем запросам.

2. Проверить порог 0.85. Если κ < 0.85:

   • Проанализировать запросы с наибольшими расхождениями.
   • Провести совместную сессию: обсудить неоднозначные случаи и уточнить правила разметки (например, считать ли порядок шагов жёстким или допускать перестановки).
   • Внести изменения в схему, если необходимо (добавить новые действия, уточнить описания).

3. Повторить разметку только для запросов с расхождениями (не более 10–15 штук).

Ожидаемый результат этапа
Отчёт с вычисленным κ, список уточнённых правил, исправленные траектории в таблице.

Этап 4: Финальная консолидация и формирование golden dataset (1 час)

Действия

1. Для каждого запроса выбрать эталонную траекторию:

   • Если все аннотаторы согласны – берём любую.
   • Если есть разногласия после обсуждения – берём траекторию, одобренную большинством или лидом.

2. Собрать финальный датасет в формате JSON:

   [
     {
       "query_id": "001",
       "query": "Какая средняя продажа за декабрь 2024?",
       "expected_trajectory": [
         {"step": 1, "action": "search_docs", "input": "продажи декабрь 2024", "expected_output": "DataFrame с продажами"},
         {"step": 2, "action": "calculate", "input": "среднее по Revenue", "expected_output": "12345.67"}
       ]
     },
     ...
   ]
   

3. Выложить датасет в Git (например, data/golden_dataset_v1.json) и добавить краткое описание в README.md.

4. Приложить скрипт compute_agreement.py и финальный отчёт с метриками.

Ожидаемый результат этапа
Готовый golden dataset и инструменты для его воспроизведения.

Этап 5: Автоматизация проверки (опционально, 1 час)

Действия

1. Написать тест, который скармливает каждый запрос агенту и сравнивает полученную траекторию с ожидаемой.
2. Использовать семантическое сравнение (например, через эмбеддинги шагов) для допуска небольших вариаций.
3. Сохранить отчёт о прохождении тестов – golden_test_report.html.

Ожидаемый результат этапа
CI-пайплайн (или локальный скрипт), который запускает агента на golden dataset и выдаёт метрику точности траекторий.

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

• Создан файл golden_dataset_v1.json со 100 примерами.
• Каждый пример содержит query_id, query, expected_trajectory как массив шагов.
• Inter‑annotator agreement (Cohen’s κ / Fleiss’ κ) ≥ 0.85 по общей выборке.
• Исходные сырые разметки сохранены (CSV/JSON) для аудита.
• Написан скрипт compute_agreement.py, воспроизводимый и документированный.
• В репозитории есть README.md с описанием структуры датасета и правил разметки.
• Минимум 2 аннотатора участвовали в разметке каждого из 30 общих запросов.
• Все расхождения разрешены и зафиксированы в разделе notes к датасету (или в отдельном файле discrepancies.md).

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

• Основной артефакт файл golden_dataset_v1.json – 100 записей с ожидаемыми траекториями.
• Сопутствующие файлы
  • raw_annotations.csv – сырые данные от аннотаторов.
  • agreement_report.txt / .html – метрики согласованности.
  • compute_agreement.py – скрипт для воспроизведения расчётов.
  • README.md – описание датасета, правила, примеры.
• Опционально скрипт test_agent_on_golden.py для автоматической валидации агента.

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

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

Примечание: Для первого раза рекомендуется выделить 2 дня по 6–7 часов, включая синхронизацию аннотаторов.

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

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

• Я выбрал агента с чётко определёнными инструментами и действиями.
• Я подготовил 100 запросов, которые покрывают разнообразные сценарии.
• Я создал Google Sheet / Airtable с колонками, включая JSON для траектории.
• Я привлёк минимум двух коллег для аннотации и организовал перекрытие.
• Я написал и запустил скрипт для вычисления Cohen’s κ / Fleiss’ κ.
• Я разрешил все расхождения и записал окончательные траектории.
• Я экспортировал финальный датасет в golden_dataset_v1.json согласно схеме.
• В README описаны правила разметки и формат данных.
• Я проверил, что датасет можно использовать для регрессионного тестирования агента.