ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Написать runbook для retrieval degradation

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

Разработать структурированный runbook (инструкцию действий) для дежурного инженера, позволяющий быстро выявить и устранить деградацию качества retrieval в RAG-системе. Документ должен содержать пошаговые сценарии проверки эмбеддингов, параметров chunking и пороговых значений (threshold), а также указания по автоматизированной диагностике. Ключевой результат runbook, выполнение которого гарантирует MTTD (Mean Time To Detect) менее 10 минут при типовых инцидентах деградации retrieval.

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

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

1. Разверните простую RAG-систему на Qdrant и sentence-transformers (например, на основе датасета с документами).
2. Настройте сбор метрик: каждые 30 секунд логируйте hit rate по фиксированному набору тестовых запросов.
3. Поочерёдно внесите три типа намеренных деградаций:
   • замените embedding модель на более слабую (например, all-MiniLM-L6-v2 → paraphrase-MiniLM-L3-v2),
   • измените параметры chunking (увеличьте размер чанка в 2 раза, уберите overlap),
   • увеличьте threshold cosine similarity до 0.95 (или уменьшите top-k до 1).
4. Зафиксируйте логи и метрики для каждого сценария.

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

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

Этап 1: Определение структуры runbook (30 минут)

Действия

1. Изучите типовые сценарии деградации retrieval:
   • Ухудшение качества эмбеддингов (модель изменена, эмбеддинги «сползли»).
   • Неоптимальный chunking (слишком крупные/мелкие фрагменты, нет overlap).
   • Жёсткий threshold (слишком высокий порог отсекает релевантные документы).
2. Составьте каркас runbook с разделами:
   • Обнаружение — как увидеть, что проблема возникла (метрики, алерты).
   • Диагностика — пошаговая проверка трёх компонентов.
   • Устранение — конкретные действия (откат конфига, переиндексация, изменение threshold).
   • Верификация — проверка, что метрики вернулись к baseline.
3. Определите критерий успеха: время от получения алерта до определения корневой причины (MTTD) должно быть менее 10 минут.

Ожидаемый результат этапа
Готовая структура runbook (набор заголовков с краткими описаниями).

Этап 2: Сбор метрик и конфигураций baseline (1 час)

Действия

1. Запишите baseline значения метрик для нормальной работы: hit rate, MRR, recall@5, recall@10.
   • Для симуляции — прогоните 20-50 тестовых запросов в «здоровом» состоянии.
2. Создайте дашборд в Grafana (или таблицу в Markdown) с текущими значениями порогов:
   • top-k, threshold cosine similarity, параметры HNSW (M, ef_construct).
3. Экспортируйте логи за последний час (до инцидента) — сохраните в ./baseline_logs/.
4. Подготовьте скрипт быстрой сверки check_baseline.py, который сравнивает текущие метрики с baseline и выдаёт расхождение.

Ожидаемый результат этапа
Скрипт check_baseline.py и файл baseline_metrics.json.

Этап 3: Написание сценариев проверки эмбеддингов, chunking и threshold (2 часа)

Действия

1. Проверка эмбеддингов

   • Опишите шаги: загрузка пары запросов, вычисление эмбеддингов текущей моделью и референсной моделью (sentence-transformers/all-MiniLM-L6-v2), вычисление cosine similarity между ними. Если средняя схожесть < 0.85 — вероятна смена модели или дрейф.
   • Реализуйте в виде функции diagnose_embeddings(query_text, current_model_name, ref_model_name) → status.
   • Пример кода

     from sentence_transformers import SentenceTransformer
     from sklearn.metrics.pairwise import cosine_similarity
     
     def diagnose_embeddings(queries, current_model, ref_model="all-MiniLM-L6-v2"):
         cur = SentenceTransformer(current_model).encode(queries)
         ref = SentenceTransformer(ref_model).encode(queries)
         sim = cosine_similarity(cur, ref).diagonal().mean()
         return "OK" if sim >= 0.85 else f"ISSUE: similarity={sim:.2f}"
     

2. Проверка chunking

   • Извлеките конфигурацию chunking (размер, overlap) из последнего pipeline-лога или конфига.
   • Сравните с задокументированным baseline (например, chunk_size=512, overlap=128).
   • Если параметры изменились — верните предупреждение и рекомендуемые значения.
   • Дополнительно проверьте, что документы не потеряли контекст — для нескольких примеров сравните результаты retrieval до и после (используя baseline запросы).
   • Пример проверки

     def check_chunking_config(expected, actual):
         changes = {k: (expected[k], actual[k]) for k in expected if expected[k] != actual[k]}
         return changes if changes else "No changes"
     

3. Проверка threshold / top-k

   • Получите текущие значения top-k и score threshold (cosine / distance).
   • Проверьте по логам retrieval, сколько запросов вернули пустой результат из-за высокого threshold.
   • Вычислите среднее количество возвращённых документов на запрос; если оно меньше ожидаемого (например, <3 при top-k=10), вероятна проблема с threshold.
   • Скрипт

     def check_threshold(logs_path, expected_min_docs=3):
         # загрузить логи, извлечь количество документов на запрос
         # вернуть "OK" если среднее >= expected_min_docs, иначе "THRESHOLD ISSUE"
     

4. Все сценарии объедините в единый CLI-инструмент run_retrieval_diagnostics.py с опциями --mode all или отдельно --mode embeddings.

Ожидаемый результат этапа
CLI-скрипт run_retrieval_diagnostics.py с тремя функциями диагностики.

Этап 4: Написание runbook (1.5 часа)

Действия

1. Оформите пошаговые инструкции в Markdown-документ RUNBOOK_RETRIEVAL_DEGRADATION.md.

2. Следуйте структуре:

   • Общая информация (кто использует, когда применять, определение деградации).
   • Шаг 1 – Запуск автоматической диагностики (запустить скрипт, проанализировать вывод).
   • Шаг 2 – Ручная проверка (если скрипт не дал однозначного ответа):
     2.1. Эмбеддинги: сравнить распределение эмбеддингов тестовых запросов за последние 10 мин vs baseline (использовать t-SNE или cosine distance).
     2.2. Chunking: проверить файлы конфигурации и логи последнего развёртывания.
     2.3. Threshold: выполнить SELECT запрос к векторной БД с разными порогами.
   • Шаг 3 – Принятие решения (таблица с вариантами: замена эмбеддинг-модели, переиндексация, корректировка threshold).
   • Шаг 4 – Верификация (перезапустить скрипт диагностики, сравнить метрики с baseline).
   • Шаг 5 – Завершение (залогировать действие в Postmortem).

3. Добавьте таблицы с порогами и временными метками:

   Параметр	Нормальное значение	Тревожное значение
   Средняя cosine similarity эмбеддингов к референсу	≥0.85	<0.85
   Chunk size	512	≠512
   Среднее количество документов на запрос	≥5	<3
   Top-k	10	≤2

4. Укажите, что после выполнения любого исправления необходимо подождать 2-3 минуты и проверить hit rate в Grafana.

Ожидаемый результат этапа
Файл RUNBOOK_RETRIEVAL_DEGRADATION.md (не менее 100 строк) с готовыми инструкциями.

Этап 5: Тестирование runbook на симуляции (1 час)

Действия

1. Создайте три тестовых сценария (по одному на каждый тип деградации), внедрите их в RAG-систему.
2. Переведите систему в режим симуляции (ограниченный набор пользователей).
3. Попросите коллегу (или засеките время самостоятельно) выполнить runbook с нуля. Зафиксируйте MTTD – время от начала выполнения до обнаружения коренной причины.
4. Если MTTD > 10 минут – доработайте runbook: сократите шаги, добавьте more specific checks.
5. Повторите тест для всех трёх типов деградации.

Ожидаемый результат этапа
Протокол тестирования (test_report.md) с тремя замерами MTTD и выводами. Финальная версия runbook с исправлениями.

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

• Runbook содержит чёткое описание индикаторов деградации retrieval (hit rate, recall@k, пустые ответы).
• Включены три независимых сценария проверки: эмбеддинги, chunking, threshold.
• Каждый сценарий имеет выполняемый скрипт или точные шаги для ручного выполнения.
• Скрипт run_retrieval_diagnostics.py выводит структурированный JSON-отчёт о состоянии.
• Runbook имеет тайм-боксы на каждый шаг (не более 2 минут на автоматическую диагностику).
• Документ протестирован на трёх смоделированных инцидентах; MTTD в каждом случае <10 минут.
• Runbook опубликован в корпоративной wiki / Git-репозитории с тегом retrieval.
• К runbook приложен readme с инструкцией по развёртыванию скрипта.

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

• Основной артефакт RUNBOOK_RETRIEVAL_DEGRADATION.md.
• Сопутствующие файлы
  • run_retrieval_diagnostics.py (CLI-скрипт диагностики).
  • baseline_metrics.json (эталонные метрики и конфигурация).
  • test_report.md (результаты трёх симуляций с MTTD).
• Содержание runbook описание триггеров, пошаговая процедура быстрой диагностики с указанием команд и ожидаемых выводов, таблица пороговых значений, действия по устранению для каждого типа деградации, инструкция по верификации.

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

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

Примечание: при первом выполнении задачи может потребоваться дополнительно 1–2 часа на настройку векторной БД и дашбордов.

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

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

• Я проверил, что runbook начинается с краткой схемы инцидента и триггеров.
• В каждом сценарии указаны конкретные команды и их ожидаемые результаты.
• Все скрипты корректно работают на моём тестовом окружении.
• Я смоделировал деградацию и прошёл runbook за время менее 10 минут.
• Я убедился, что runbook содержит раздел «Верификация» после исправления.