# Пайплайн экспериментов с диаризацией и транскрипцией на HF Space

## Обзор

HF Space `Niko-NN/store-dialogs-qa` — пайплайн для экспериментов с транскрипцией
и диаризацией русской речи с камер видеонаблюдения. Поддерживает 7 моделей транскрипции,
2 модели диаризации, 2 стратегии, автоматический бенчмарк и grid search по параметрам.

## Текущее состояние

- **Статус**: развёрнут на Nvidia T4 small (Python 3.10), Dev Mode включён
- **Данные**: 76 аудио MP3 загружены в `Niko-NN/gold-store-dialogs/audio/`
- **Gold-разметка**: Label Studio JSON экспорт (33 файла с аннотациями)
- **Метрики**: требуют повторного замера после исправлений (см. «Нерешённые проблемы»)

## Архитектура

```
Входные данные              Диаризация           Транскрипция          Результат
─────────────────          ──────────           ────────────          ─────────
Audio MP3 на Hub  ──┐      pyannote 3.1    ┐    faster-whisper   ┐    Сегменты + текст
                    ├──►   NeMo MSDD (опц.) ├►   transformers    ├►   Метрики DER/WER/CER
Upload через UI   ──┘                      ┘    GigaAM          ┘    Рейтинг моделей
```

### Ключевые механизмы pipeline.py

1. **Word-level speaker alignment** (hybrid режим, faster-whisper):
   - `word_timestamps=True` → каждое слово получает таймстемп
   - Midpoint каждого слова сопоставляется с diarization-сегментом → назначается спикер
   - Последовательные слова одного спикера группируются в сегменты
   - Корректно разделяет реплики разных спикеров внутри длинных Whisper-сегментов

2. **VAD fallback**:
   - Silero VAD (через onnxruntime) плохо работает на зашумлённом аудио с камер на T4
   - Если `vad_filter=True` даёт < 3 слов → автоматический повтор с `vad_filter=False`

3. **Фильтрация галлюцинаций**:
   - Блоклист паттернов ("субтитры сделал", "подписывайтесь" и т.д.)
   - Детект повторяющихся слов
   - **НЕ используются** пороги `no_speech_prob`/`avg_logprob` — они были избыточны
     и фильтровали реальную речь (Whisper сам фильтрует внутренне через AND-логику)

4. **Предзагрузка весов**: `prefetch_model_weights()` до GPU-функции

5. **GPU-декоратор**: `@spaces.GPU` только на ZeroGPU, на T4 — `_noop_gpu`

## Данные

- **76 MP3 файлов**, ~15 мин каждый, записи из магазина (камера 2)
- Датасет: `Niko-NN/gold-store-dialogs` (папка `audio/`)
- Фильтрация по `Barhatnaya.csv` — только файлы с диалогами
- Gold-разметка: Label Studio JSON экспорт (загружается через UI)
  - Спикеры: Продавец, Покупатель
  - Служебные метки: «Начало диалога», «Конец диалога» (фильтруются при расчёте DER)

### Словари домена

Два справочника для повышения качества транскрипции:

- **`dictionary/baza_cvetov_24_domain_dictionary_clean.md`** — терминология цветочного магазина:
  названия цветов, растений, упаковки, инструментов, размеры, цвета и т.д.
- **`dictionary/baza_cvetov_24_sales_phrases_dictionary.md`** — типовые фразы продавца
  и покупателя: приветствия, вопросы, предложения, расчёт, прощание.

**Планируемое использование:**

1. **`initial_prompt` для Whisper** — подсказка модели о домене и лексике.
   faster-whisper и transformers поддерживают параметр `initial_prompt`,
   который задаёт контекст и смещает распознавание к нужной терминологии.
   Пример: *"Разговор в цветочном магазине. Гвоздики, розы, хризантемы, лилии,
   герберы, упаковка, лента, букет."*

2. **Пост-обработка текста** — автозамена частых ошибок распознавания
   на основе словаря (напр. "воздичек" → "гвоздичек").

3. **Нормализация для WER** — приведение gold и predicted текста к единому виду
   перед расчётом метрик (числа, сокращения, регистр).

## Модели

### Транскрипция (7 моделей)

| ID | Модель | Бэкенд | Описание |
|----|--------|--------|----------|
| `whisper-large-v3` | Systran/faster-whisper-large-v3 | faster-whisper | Базовая Whisper v3 |
| `whisper-large-v3-turbo` | Systran/faster-whisper-large-v3-turbo | faster-whisper | Быстрая версия |
| `whisper-podlodka-turbo` | bond005/whisper-podlodka-turbo | transformers | Дообучен на Podlodka/Taiga |
| `whisper-large-v3-russian` | antony66/whisper-large-v3-russian | transformers | Дообучен на Common Voice 17 |
| `whisper-russian-ties-podlodka` | Apel-sin/whisper-large-v3-russian-ties-podlodka-v1.2 | transformers | TIES-merge русских моделей |
| `gigaam-ctc` | GigaAM CTC | gigaam | Сбер, 700K часов русской речи |
| `gigaam-rnnt` | GigaAM RNNT | gigaam | Сбер, RNNT-архитектура |

### Диаризация (2 модели)

| ID | Модель | Описание |
|----|--------|----------|
| `pyannote-3.1` | pyannote/speaker-diarization-3.1 | Основная, стабильная |
| `nemo-msdd` | NeMo MSDD | Экспериментальная (нужен `pip install nemo_toolkit[asr]`) |

### Стратегии транскрипции

- **hybrid** (рекомендуется) — транскрипция всего файла + word-level привязка спикеров
- **per_segment** — транскрипция каждого сегмента диаризации отдельно

## Структура файлов

```
app.py              — Gradio UI с 5 вкладками + утилиты
pipeline.py         — ядро: загрузка моделей, диаризация, транскрипция, process_file()
models_config.py    — реестр моделей с параметрами (7 транскрипция + 2 диаризация)
evaluation.py       — оценка: DER, WER, CER, run_benchmark(), run_grid_search()
requirements.txt    — зависимости
README.md           — конфигурация Space
INSTRUCTIONS.md     — подробная инструкция пользователя
PLAN.md             — этот файл
```

## UI: 5 вкладок Gradio

### Tab 1: Обработка файла
- Выбор файла из датасета или загрузка своего
- Выбор модели диаризации и транскрипции
- Настройка: стратегия, мин/макс спикеров, обрезка по времени
- Результат: таблица сегментов, аудиоплеер, JSON

### Tab 2: Batch-режим
- Список файлов для обработки
- Одна комбинация модель + стратегия
- Прогресс-бар, сводная таблица

### Tab 3: Сравнение с gold
- Загрузка Label Studio JSON
- Автоматическое сравнение с результатом из Tab 1
- Метрики: DER, WER, CER, speaker accuracy, посегментное сравнение

### Tab 4: Бенчмарк
- Загрузка gold-разметки
- Выбор нескольких моделей × стратегий (чекбоксы)
- Автоматический прогон всех комбинаций
- **Сводная таблица рейтинга**, отсортированная по WER

### Tab 5: Grid Search
- Выбор лучшей модели из бенчмарка
- Автоматический подбор параметров (один-за-раз):
  - Whisper: beam_size, no_speech_threshold, temperature, condition_on_previous_text, repetition_penalty
  - Diarization: min_speakers, merge_gap, merge_min_dur
- Результат: лучшие параметры + таблица всех конфигураций

## Зависимости (requirements.txt)

```
numpy<2
gradio>=6.9.0
huggingface_hub>=0.30.0
transformers>=4.40
accelerate>=0.26
pytorch-lightning>=2.0
speechbrain>=1.0
pyannote.audio>=3.1
faster-whisper>=1.0.0
gigaam
librosa>=0.10
soundfile>=0.12
jiwer>=3.0
onnxruntime>=1.17
```

## Важные нюансы

- **Nvidia T4**: 16GB VRAM, $0.40/час, без квоты на GPU-время
- **Python 3.10**: зафиксирован в README.md для совместимости с gigaam/torchaudio
- **numpy<2**: зафиксирован для совместимости onnxruntime
- **pyannote** требует accept на HF Hub + HF_TOKEN
- **NeMo MSDD** не в requirements.txt (тяжёлая зависимость), ставить вручную
- **onnxruntime**: stub в app.py для обхода несовместимости — если onnxruntime не ставится,
  подставляется заглушка (Silero VAD не работает → hybrid fallback на vad_filter=False)
- Модели кэшируются в памяти, выгружать кнопкой перед сменой модели
- **Dev Mode**: код обновляется через git push, но может требовать ручного рестарта Space

## Рекомендованный workflow

```
1. Factory Reboot Space (подхватить весь новый код)
2. Загрузить словари домена в датасет (dictionary/)
3. Экспорт gold из Label Studio (JSON)
4. Tab 4 (Бенчмарк) — грубый отбор (3-5 моделей × 2 стратегии × 2-3 файла)
5. Tab 4 (Бенчмарк) — уточнение (топ-2 модели × все файлы)
6. Добавить initial_prompt из словаря → повторить бенчмарк
7. Tab 5 (Grid Search) — тонкая настройка параметров лучшей модели
8. Добавить пост-обработку ошибок из словаря → финальный замер
9. Tab 1 + Tab 3 — финальная проверка на отдельных файлах
```

## Нерешённые проблемы / TODO

1. **Factory Reboot Space** — Dev Mode не подхватывает git push автоматически.
   Нужен ручной Factory Reboot для применения накопленных изменений.

2. **Бенчмарк и Grid Search** не тестировались после исправлений:
   - Удаление двойных пост-фильтров
   - VAD fallback
   - Word-level alignment (faster-whisper + transformers-whisper)
   - Корректная фильтрация служебных меток в evaluation.py

3. **Pyannote diarization** на тестовом файле присваивает всю речь
   одному спикеру (SPEAKER_01), второй (SPEAKER_00) — только шумовые сегменты.
   Возможные причины: плохое аудио, параметры `min_speakers`.

4. **Интеграция словарей домена** (приоритет — высокий):
   - [ ] Загрузить словари в `Niko-NN/gold-store-dialogs/dictionary/`
   - [ ] Сформировать `initial_prompt` из ключевых терминов словаря
   - [ ] Передавать `initial_prompt` в faster-whisper (`model.transcribe(initial_prompt=...)`)
     и transformers (`generate_kwargs={"prompt_ids": ...}`)
   - [ ] Добавить `initial_prompt` как параметр Grid Search
   - [ ] Реализовать пост-обработку с автозаменой частых ошибок
   - [ ] Добавить нормализацию текста перед расчётом WER/CER

## История изменений

1. Базовый пайплайн: pyannote 3.1 + Whisper large-v3 (faster-whisper) + GigaAM
2. Фильтрация галлюцинаций, мерж сегментов, min/max спикеров
3. Гибридная стратегия транскрипции
4. Автоматическая оценка vs Label Studio gold (DER, WER, CER)
5. 3 новые русские Whisper модели (transformers бэкенд), бенчмарк, grid search
6. Переход с ZeroGPU на Nvidia T4 small, фикс Python 3.10, numpy<2
7. Удаление избыточных пост-фильтров no_speech_prob/avg_logprob
8. VAD fallback (vad_filter=False при < 3 слов)
9. Word-level speaker alignment (word_timestamps=True + midpoint matching)
10. Word-level alignment для transformers-whisper (return_timestamps="word")
11. **Текущий**: Планирование интеграции словарей домена (initial_prompt, пост-обработка)