local-transcriber/docs/superpowers/specs/2026-04-18-parakeet-backend-design.md

# Parakeet backend — design spec

**Дата:** 2026-04-18
**Статус:** Готов к планированию реализации
**Ветка реализации:** `feature/parakeet-backend` (в отдельном git worktree)

## Контекст и гипотеза

`local-transcriber` — CLI для локальной транскрипции аудио/видео (Whisper). Архитектура pluggable backends (ADR-003): `FasterWhisperBackend` (CTranslate2, CPU/CUDA), `OpenVINOBackend` (Intel CPU/iGPU/NPU). Дефолтный язык — `ru`. Целевая аудитория — ноутбуки с Intel и AMD встройками; NVIDIA — меньшинство.

**Гипотеза.** NVIDIA Parakeet TDT 0.6B v3 (через ONNX Runtime на CPU) быстрее и/или качественнее Whisper-бэкендов на Intel/AMD встройках. Проверяется прогоном на реальных русских файлах с сравнением wall-clock и качества против OpenVINO-Whisper medium и faster-whisper CPU medium.

## Выбор технологии (зафиксирован)

- **Модель:** `nvidia/parakeet-tdt-0.6b-v3` — multilingual, 25 языков включая русский.
- **Runtime:** ONNX Runtime через Python-пакет `onnx-asr` ([`istupakov/onnx-asr`](https://github.com/istupakov/onnx-asr)). Отклонены: NeMo toolkit (~1-2GB зависимостей), OpenVINO Parakeet (AMD iGPU не поддерживается, Intel — экспериментальный порт без сообщества).
- **Execution Provider в MVP:** CPU. DirectML (Windows AMD/Intel iGPU), ORT-OpenVINO EP, `onnxruntime-gpu` (CUDA) — отдельные фазы после валидации гипотезы.
- **VAD:** Silero VAD через `asr.with_vad()` — обязательно (без VAD лимит 20-30 сек на файл; все реальные файлы длиннее).
- **Quantization:** `int8` по умолчанию (~670MB диск, ~2GB RAM при inference), `fp32` — опциональное значение `--compute-type float32`.

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

### Инвариант

`TranscribeFileResult`, `TranscribeResult`, `Segment`, `format_transcript()` — **не меняем**. Регрессионный риск для существующих Whisper/OpenVINO-путей минимизирован.

Parakeet интегрируется через две минимальные точки:
1. `result.language = "multi"` внутри `ParakeetBackend.transcribe` — соответствует поведению Parakeet v3.
2. Атрибут backend-инстанса `effective_model_name` — аналог существующих `actual_compute_type`, `actual_ov_device`.

CLI после `_transcribe_file` читает `getattr(tfr.backend, "effective_model_name", defaults["model"])` для rich-вывода и `format_transcript(..., model_name=...)`. Rich-строка `Модель: ...` **переносится** после `_transcribe_file` (точка, где уже доступен `tfr.backend`). До транскрипции выводится только `Файл: ...` и сообщения `on_status` от загрузки модели.

**Шапка транскрипта для Parakeet:** `result.language = "multi"` + `language_mode = "detected"` (CLI форсит `"detected"` при `--device parakeet*`). Формат — `**Язык**: multi (detected)`.

### Контракт `--language`

- `result.language = "multi"` всегда.
- CLI при `--device parakeet*` форсит `language_mode = "detected"` (независимо от того, задавал ли пользователь `--language`).
- **Warning только при явном CLI-флаге `--language`.** Если `language` пришёл из `.transcriber.toml` или `HARDCODED_DEFAULTS` (без явного CLI) — warning подавлен. Источник явности: `cli_values["language"] is not None` (не `"language" in config`).
- Текст warning: `Parakeet игнорирует --language; язык определяется автоматически`.

### Контракт `--compute-type`

| CLI `--compute-type` | `onnx_asr.load_model(quantization=...)` | Примечание |
|----------------------|------------------------------------------|------------|
| `int8`               | `"int8"`                                 | Дефолт |
| `float32`            | `None`                                   | Без quantization |
| другое               | —                                        | `ValueError("Parakeet поддерживает только int8 или float32")` |

### Контракт VAD — runtime-зависимость, без prefetch

`ensure_model_available` отвечает только за Parakeet-модель. `create_model` вызывает `onnx_asr.load_vad(model="silero")`, который при первом запуске скачивает Silero VAD (~15MB).

Одна точка правды — `onnx_asr.load_vad`. Двойной prefetch (наш `snapshot_download` + внутренний `onnx-asr`) без точного знания repo/layout создавал несостыковку: `ensure_model_available` рапортует «готово», но `create_model` всё равно тянет из сети.

Документировано в ADR-005 и README: **первый запуск `--device parakeet` требует интернет для Silero VAD; повторные — оффлайн** (проверяется в long-audio gate).

### Контракт fallback — **НЕ fallback'ить Parakeet на Whisper CPU**

В `load_model` и `_transcribe_file` при `actual_device.startswith("parakeet")` — пропускаем fallback-ветку, исключение пробрасывается наружу.

Обоснование: Parakeet — другое семейство моделей с другим качеством и семантикой языка (`multi` vs `ru`). Молчаливая подмена на Whisper medium ломает интерпретацию транскрипта. Пользователь видит понятную ошибку (`Ошибка загрузки Silero VAD — проверьте интернет` / `Parakeet inference crashed — см. --verbose`) и делает осознанный выбор.

### `detect_device` (utils.py)

`--device auto` **не переключается на Parakeet.** Порядок остаётся: CUDA → OpenVINO GPU → OpenVINO CPU → CPU. Parakeet — только через явный `--device parakeet` / `--device parakeet-cpu`.

### `config.py`

```python
_VALID_DEVICES = {
    "auto", "cpu", "cuda",
    "openvino", "openvino-gpu", "openvino-cpu",
    "parakeet", "parakeet-cpu",
}

DEVICE_DEFAULTS["parakeet"] = {"model": "parakeet-tdt-0.6b-v3", "compute_type": "int8"}
DEVICE_DEFAULTS["parakeet-cpu"] = {"model": "parakeet-tdt-0.6b-v3", "compute_type": "int8"}
```

**Config-conflict на `model`.** Если в глобальном `.transcriber.toml` стоит `model = "medium"` и пользователь запускает `--device parakeet` без `--model`, `apply_device_defaults` возьмёт `"medium"` из конфига → `ParakeetBackend.ensure_model_available` кидает **понятный `ValueError`**:

> `Parakeet поддерживает только 'parakeet-tdt-0.6b-v3' или алиас 'parakeet'. Получено: 'medium'. Передайте --model parakeet или уберите 'model' из .transcriber.toml.`

Принципиально **не делаем** скрытого override в `apply_device_defaults` — это ломает инвариант «CLI > config > defaults». Пользователь получает ясную ошибку и делает явный фикс.

Алиас `"parakeet"` → `"parakeet-tdt-0.6b-v3"` допустим в `ensure_model_available` (UX-удобство).

### Новый бэкенд — `backends/parakeet.py`

```python
class ParakeetBackend:
    SUPPORTED_MODEL_NAMES = {"parakeet-tdt-0.6b-v3", "parakeet"}
    SUPPORTED_COMPUTE_TYPES = {"int8", "float32"}

    def __init__(self, compute_type_explicit: bool = True):
        self._compute_type_explicit = compute_type_explicit
        self.actual_compute_type: str | None = None
        self.effective_model_name: str = "parakeet-tdt-0.6b-v3"

    def ensure_model_available(self, model_name, compute_type, on_status) -> str:
        # 1. model_name ∈ SUPPORTED_MODEL_NAMES иначе ValueError (текст выше)
        # 2. compute_type ∈ SUPPORTED_COMPUTE_TYPES иначе ValueError
        # 3. snapshot_download("nvidia/parakeet-tdt-0.6b-v3") → локальный путь
        # 4. Silero VAD здесь НЕ трогаем (runtime-зависимость)
        # 5. self.actual_compute_type = compute_type
        # 6. Возвращаем путь к каталогу

    def create_model(self, model_path, device, compute_type, cpu_threads=0) -> Any:
        # 1. quantization = "int8" if compute_type == "int8" else None
        # 2. asr = onnx_asr.load_model("nemo-parakeet-tdt-0.6b-v3", path=model_path, quantization=quantization)
        # 3. vad = onnx_asr.load_vad(model="silero")   # может качать VAD при первом запуске
        # 4. asr_with_vad = asr.with_vad(vad=vad)
        # 5. cpu_threads → sess_options через providers_options
        # 6. Возвращаем asr_with_vad

    def transcribe(self, model, file_path, language, on_segment, on_status) -> TranscribeResult:
        # 1. Если language задан явно (см. «Контракт --language») — warnings.warn
        # 2. result = model.recognize(str(file_path))
        # 3. Поддержка iterator И list (детектим на лету)
        # 4. Для каждого SegmentResult → Segment(start, end, text); on_segment; on_status c heartbeat
        # 5. Возвращаем TranscribeResult(segments, language="multi", language_probability=0.0, duration, device_used="")
```

### Регистрация в `backends/__init__.py`

```python
if device in ("parakeet", "parakeet-cpu"):
    try:
        from .parakeet import ParakeetBackend
    except ImportError:
        raise ValueError(
            "Parakeet бэкенд недоступен. Установите: pip install onnx-asr[cpu,hub]"
        ) from None
    return ParakeetBackend(compute_type_explicit=compute_type_explicit)
```

### `transcriber.py` — no-fallback для Parakeet

```python
def _is_parakeet_error(exc: BaseException) -> bool:
    if isinstance(exc, RuntimeError):
        return True
    mod = type(exc).__module__ or ""
    return "onnxruntime" in mod or "onnx_asr" in mod

def _is_backend_error(exc, device):
    if device.startswith("parakeet"):
        return _is_parakeet_error(exc)
    # ... existing branches
```

В `load_model` и `_transcribe_file` добавляется ранний выход из fallback-ветки при `actual_device.startswith("parakeet")` — исключение пробрасывается (как будто `strict_device=True`).

### `cli.py` — точечные изменения

1. **Rich-строка `Модель: ...` переносится после `_transcribe_file`.** Использует `getattr(tfr.backend, "effective_model_name", defaults["model"])`.
2. **`format_transcript(..., model_name=...)`** получает `getattr(tfr.backend, "effective_model_name", defaults["model"])`.
3. **`language_mode`** при Parakeet: `if actual_device.startswith("parakeet"): language_mode = "detected"`. Иначе — существующая логика.
4. **Warning на явный `--language`** при Parakeet: проверка `cli_values["language"] is not None` (не `"language" in config`). Срабатывает в `_run_single` / `_run_batch` до `_transcribe_file` — пользователь видит сразу.
5. **`_format_device_info`**: `if device_used == "parakeet-cpu": return "Parakeet (CPU via ONNX Runtime)"`.

Для Whisper-бэкендов код не меняется.

### Progress UX — heartbeat если блокирующий вызов

Если `asr_with_vad.recognize()` возвращает iterator — итерируем с вызовами `on_status` per segment. Если блокирующий — обёртка в поток с heartbeat-таймером (паттерн `openvino.py::_generate_with_progress`). Тип возврата проверяется в long-audio gate (см. ниже); при блокирующем вызове heartbeat — **обязателен до merge**.

## Зависимости

```toml
# pyproject.toml
dependencies = [
    # ... existing
    "onnx-asr[cpu,hub]>=0.7",  # минимальная версия уточнить после uv lock
]
```

`uv lock` обязателен до любой имплементации — проверить, что `onnxruntime` не конфликтует с тем, что тянут `faster-whisper` / `openvino-genai`. Platform markers не нужны: `onnx-asr` — pure Python; `onnxruntime` CPU-wheels покрывают Linux/macOS/Windows × x86_64/arm64.

## Тесты

### `tests/test_parakeet_backend.py` — юнит с mock `onnx_asr`

1. `test_ensure_model_available_accepts_alias` — `model_name="parakeet"` → скачивает `nvidia/parakeet-tdt-0.6b-v3`.
2. `test_ensure_model_available_rejects_unknown_model` — `model_name="medium"` → `ValueError` с текстом-подсказкой.
3. `test_ensure_model_available_rejects_unknown_compute_type` — `compute_type="float16"` → `ValueError`.
4. `test_create_model_maps_compute_type` — `int8` → `quantization="int8"`; `float32` → `quantization=None`.
5. `test_transcribe_produces_segments` — mock `recognize` возвращает 3 `SegmentResult` → 3 `Segment`.
6. `test_transcribe_warns_on_explicit_cli_language` — явный `--language` → `warnings.warn`.
7. `test_transcribe_does_not_warn_on_config_language` — `language` из конфига → warning НЕ срабатывает.
8. `test_transcribe_calls_on_segment` — callback на каждый сегмент.
9. `test_transcribe_returns_multi_language` — `result.language == "multi"`, `language_probability == 0.0`.
10. `test_backend_sets_effective_model_name` — атрибут проставлен.
11. `test_transcribe_accepts_list_and_iterator_results` — оба типа возврата обрабатываются.

### `tests/test_transcriber.py`

12. `test_load_model_parakeet_no_fallback` — при ошибке Parakeet исключение пробрасывается (без fallback на CPU Whisper).

### `tests/test_cli.py` — regression + новые

13. `test_cli_whisper_transcript_header_unchanged` — `--device cpu --language ru` → шапка содержит `**Язык**: ru (forced)` (регрессия отсутствует).
14. `test_cli_whisper_auto_language_header_unchanged` — `--device cpu --language auto` → шапка отражает detected-режим.
15. `test_cli_parakeet_transcript_header` — `--device parakeet` → шапка `**Язык**: multi (detected)` и `**Модель**: parakeet-tdt-0.6b-v3`.
16. `test_cli_parakeet_model_row_shows_effective` — config `model="medium"` + `--device parakeet --model parakeet` → rich-вывод и `format_transcript` получают `parakeet-tdt-0.6b-v3`.
17. `test_cli_errors_on_config_model_mismatch_without_override` — config `model="medium"` + `--device parakeet` без `--model` → ясная ошибка (не traceback).
18. `test_cli_parakeet_warns_explicit_language` — config без `language`, явный `--language en --device parakeet` → warning.

Все юнит-тесты — чистые mocks, без реального скачивания.

## Long-audio verification gate — exit criteria, blocker для merge

**Метрики и нормы (единственный источник истины):**

| Метрика | Норма |
|---------|-------|
| Длина тестового файла | ≥30 минут, русский |
| Peak RSS | ≤4 GB |
| Первый `on_status` update | ≤10 сек от старта `_transcribe_file` |
| Максимальный интервал между `on_status` update'ами | ≤30 сек |
| Повторный прогон с `HF_HUB_OFFLINE=1` | без сетевых запросов |

**Методика измерения:**
- Peak RSS: `/usr/bin/time -v ...` (поле "Maximum resident set size") или `psutil.Process().memory_info().rss` из внешнего процесса раз в секунду.
- Интервалы `on_status`: специальный тестовый callback в CLI логирует `time.monotonic()` каждого вызова в файл; пост-анализ считает max interval.
- Offline: `HF_HUB_OFFLINE=1` через `env`; либо `strace -e trace=connect`, либо проверка отсутствия задержек на сетевых операциях в начале прогона.

**Blocker-правила (план заморожен до устранения):**
- Peak RSS > 4 GB → нужен ручной chunking; MVP не готов.
- Первый update > 10 сек ИЛИ любой интервал > 30 сек → нужен heartbeat-thread (паттерн `openvino.py::_generate_with_progress`).
- Offline-прогон делает сетевые обращения → VAD-кэш не работает, разбираться до merge.

Результаты (числа всех метрик) фиксируются в `docs/gpu.md`.

## Документация

1. **ADR-005** (`docs/adr/005-parakeet-backend.md`) — контекст, решение (ONNX Runtime + onnx-asr + Silero VAD), отклонённые альтернативы (NeMo toolkit, OpenVINO Parakeet, DirectML в MVP, VAD prefetch, скрытый override в `apply_device_defaults`, cross-backend fallback на Whisper), последствия (язык игнорируется, no fallback, `effective_model_name` через backend-атрибут, VAD runtime-зависимость с требованием интернета на первый запуск).
2. **README.md** — секция «Parakeet (экспериментально)»: установка, `--device parakeet`, ограничения (int8/fp32, язык auto, первый запуск — интернет для VAD ~15MB, память ~2GB, конфликт с `model` в конфиге).
3. **docs/gpu.md** — секция «Parakeet»: результаты long-audio gate + сравнение с OpenVINO medium / faster-whisper medium CPU на одном и том же RU-файле.

## Порядок шагов (для writing-plans)

Вся работа — в git worktree на ветке `feature/parakeet-backend` (через `superpowers:using-git-worktrees`).

1. **Scaffold + зависимости:** worktree, ветка, `uv add "onnx-asr[cpu,hub]>=0.7"`, `uv lock` → нет конфликтов `onnxruntime` с существующими deps (**блокер**). `uv sync`. Существующие `uv run pytest` зелёные.
2. **config.py:** `_VALID_DEVICES` + `DEVICE_DEFAULTS` для parakeet/parakeet-cpu. Тест на валидацию `device = "parakeet"` в конфиге.
3. **ParakeetBackend (заглушка):** файл `backends/parakeet.py` со stub'ами (`raise NotImplementedError`). Регистрация в `backends/__init__.py`. Импорт работает без ошибок.
4. **`ensure_model_available`:** валидация model_name / compute_type, `snapshot_download`, валидация каталога. Тесты 1-3.
5. **`create_model`:** `onnx_asr.load_model + load_vad + with_vad`, маппинг compute_type, cpu_threads. Тест 4.
6. **`transcribe`:** итерация `SegmentResult`, warning на язык, `language="multi"`, duration. Тесты 5-11.
7. **`transcriber.py` — no-fallback:** `_is_parakeet_error`, ветка в `_is_backend_error`, пропуск fallback при `actual_device.startswith("parakeet")`. Тест 12.
8. **cli.py:** перенос строки `Модель:` после `_transcribe_file`, чтение `effective_model_name` через `getattr`, force `language_mode="detected"` для Parakeet, warning на явный CLI `--language`, `_format_device_info` для `parakeet-cpu`. Regression-тесты 13-14, Parakeet-тесты 15-18.
9. **Long-audio verification gate:** прогон ≥30-мин RU-файла, замеры всех метрик, оффлайн-повтор. Фиксация в `docs/gpu.md`. **Blocker для merge.**
10. **ADR-005 + README** с финальными числами из шага 9.
11. **Финал:** `uv run pytest -v` зелёное, `uv run transcribe sample.mp3 --device parakeet` работает end-to-end, PR.

## Что НЕ делаем в MVP (отложено)

- DirectML EP для AMD iGPU / Intel iGPU (Windows).
- ORT-OpenVINO EP для Intel iGPU/NPU.
- Parakeet на CUDA (`onnxruntime-gpu`).
- Ручной chunking длинных файлов (доверяем `with_vad` + gate).
- `--device auto` включает Parakeet.
- Alias `parakeet-tdt-0.6b-v3` для моделей других бэкендов.
- Canary (ещё одна NeMo-модель, поддерживается `onnx-asr`).
- Prefetch Silero VAD в `ensure_model_available`.
- Изменение сигнатур `TranscribeFileResult` / `TranscribeResult` / `format_transcript`.

## Открытые риски и митигации

1. **Память на длинных файлах** — gate шага 9; провал → блокер MVP до ручного chunking.
2. **Progress UX (блокирующий `recognize`)** — gate шага 9; провал → heartbeat-thread обязателен.
3. **Качество на русском** — основная гипотеза; результат фиксируется в `docs/gpu.md`; при ухудшении по сравнению с Whisper — бэкенд остаётся с пометкой «EN лучше, чем RU».
4. **Конфликт версий `onnxruntime`** — блокер шага 1; решается через `uv lock` до любой имплементации.
5. **VAD offline** — gate шага 9 (`HF_HUB_OFFLINE=1`); провал → разбираться, при необходимости возвращаться к prefetch с реальной проверкой repo/layout.
6. **Config-conflict на `model`** — ясная ошибка, не скрытый override.