local-transcriber/docs/specs/2026-09-21-transcription-execution.md

# Владение выполнением транскрипции

**Статус:** реализовано. Правила выбора исполнения и optional CUDA — в #2,
владение выполнением (`Transcriber`), бюджет потоков ONNX и диагностика —
в #56. Windows GPU-прогон без Toolkit остаётся невыполненным (см. ADR-001).

## Зачем

Основное направление развития — поддерживаемые модели и движки распознавания,
прежде всего ONNX. В перспективе нужны аппаратные варианты исполнения на Mac
и через Windows ML, но их внедрение не входит в этот рефакторинг.

Сейчас CLI хранит модель, backend, путь к модели и фактическое устройство,
передаёт их в `_transcribe_file` и обновляет после fallback. Для ONNX часть
согласованного состояния находится в adapter, а загруженная модель передаётся
отдельно. Это увеличивает interface: caller должен знать порядок вызовов
и поддерживать согласованность значений.

`device` одновременно обозначает движок и аппаратное исполнение. До #2 значение
`onnx` выбирало adapter, но не закрепляло CPU: `onnx-asr` по умолчанию использует
доступные execution providers, хотя CLI писал `ONNX (CPU)`. В #2 для ASR и VAD
закреплён CPU provider. Параметр `cpu_threads` всё ещё принимается ONNX adapter,
но не используется при загрузке ASR и VAD.

## Согласованные ограничения

- Сохраняются ONNX-ASR, OpenVINO и FasterWhisper. Удаление CUDA-библиотек из
  обязательной установки не означает удаление FasterWhisper или его CPU-пути.
- Приоритет — подключение моделей и вариантов исполнения. Промежуточное
  сохранение и возобновление обработки совещаний не нужны для этой работы.
- Автоматически выбираются только проверенные сочетания модели и исполнения.
  Новое аппаратное исполнение сначала подключается явно и проверяется отдельно.
- CUDA-зависимости устанавливаются по желанию пользователя. Способ установки
  и включения должен быть описан в документации.
- Наличие драйвера NVIDIA не доказывает совместимость железа с runtime.
  Ноутбук владельца с установленным драйвером и несовместимым старым GPU —
  обязательный сценарий для проверки нового поведения.
- Диаризация остаётся необязательным последующим проходом. Сбой «два
  собеседника на чёткой записи, найден один говорящий» требует отдельного
  исследования качества; этот рефакторинг его не исправляет.

## Форма module

External seam проходит между caller и выполнением распознавания. Caller
создаёт один module для согласованных настроек запуска и последовательно
передаёт ему файлы. Module владеет загруженной моделью, связанным adapter,
фактическими настройками и допустимыми переходами исполнения. Caller получает
результат распознавания и сведения о выполнении, а не внутреннее состояние,
которое нужно передать обратно при следующем файле.

Module создаётся после prescan, когда есть работа. Загрузка и проверка
возможностей завершаются до распознавания первого файла: это сохраняет
проверку пословного контракта перед включённой диаризацией. Один и тот же
interface используется для одного файла и для батча. События прогресса остаются
доступны CLI. Публичная функция `transcribe` сохраняется как путь одного файла
через тот же module; конкретные имена новых типов здесь не закрепляются.

Внутри различаются поддерживаемая модель, движок распознавания и способ
исполнения. Существующие значения CLI и TOML преобразуются в этот выбор при
подготовке запуска. Backend остаётся internal seam с реальными adapters;
каталог ONNX, VAD, квантизация и перевод результата библиотеки в сегменты
распознавания и слова с временной привязкой остаются в ONNX adapter.
Отдельная иерархия adapters для каждого execution provider пока не нужна.

CLI сохраняет выбор файлов, prescan, пользовательский вывод и итоговый статус.
Форматирование, запись Markdown и правила диаризации не поглощаются новым
module. Это ограничивает первый шаг владением ASR и его настройками.

Depth оценивается по обязанностям caller: ему больше не нужно согласовывать
model/backend/path/device. Locality — изменения загрузки и исполнения
сосредоточены в module и соответствующем adapter. Leverage — один interface
покрывает одиночный запуск, батч и их тесты.

## Выбор исполнения и ошибки

Ручное включение CUDA состоит из двух явных действий: установки зависимостей
и выбора CUDA через CLI либо TOML. Extra `cuda` поддерживает Linux/WSL x86_64
и Windows x64 без обязательного системного Toolkit; совместимый драйвер
устанавливается отдельно. CUDA не участвует
в `auto`, даже если найден `nvidia-smi` или установлены её библиотеки.
Так установка драйвера не меняет движок и модель по умолчанию.

Начальный автоматический путь — ONNX с CPU и существующей моделью по умолчанию.
Для ONNX список providers задаётся явно; наличие CoreML в macOS wheel не
включает его автоматически. Это делает политику проекта определённой, но
не заменяет проверку работы на настоящем Mac.

Явный аппаратный выбор не подменяется молча другим исполнением. При отсутствии
CUDA-библиотек выводится инструкция подключения; при несовместимости железа
объясняется отказ выбранного пути. Установка библиотек не предлагается как
универсальное исправление аппаратной несовместимости. Остальные существующие
правила ошибок и разрешённых fallback сохраняются внутри module; состояние
после перехода остаётся согласованным для следующего файла.

Сведения о выполнении различают запрошенное и выбранное исполнение, модель,
квантизацию и настройки потоков. Они не раскрывают model handle. Для ONNX
наличие или регистрация provider не выдаётся за доказательство выполнения
всего графа на GPU/NPU. Отладочный вывод должен помогать выяснить конфигурацию
на чужой машине, включая версии runtime и providers, без доступа к записи.

## Проверка результата

Основные сценарии проверяются через external interface с подменой внешних
движков, при работающей оркестрации проекта:

- Пустой prescan не загружает модели; два файла переиспользуют одну модель.
- Добавление каталожной ONNX-модели не требует изменений в CLI.
- Выбранная квантизация и бюджет потоков действительно передаются ASR и VAD;
  нулевой бюджет сохраняет настройки потоков библиотек.
- Наличие `nvidia-smi` при обычной установке не запускает CUDA и не ведёт
  через ошибку GPU к FasterWhisper CPU.
- Явная CUDA с отсутствующими библиотеками и с несовместимым GPU даёт разные
  содержательные ошибки. Автоматическая смена модели не маскирует отказ.
- Случайно доступный непроверенный ONNX provider не меняет автоматический путь.
- Разрешённый fallback не требует переноса состояния в CLI; обычная ошибка
  файла не повреждает состояние для последующих файлов батча.
- Сохраняются явные CPU/OpenVINO-пути, порядок слов, пословный контракт,
  прогресс, прерывание и существующее поведение необязательной диаризации.

Тесты ручного переноса внутренних полей заменяются проверками этих сценариев.
Тесты преобразования результатов adapters сохраняются на их internal seams.
Mock-тесты не подтверждают ускорение или совместимость на Mac/Windows ML;
для признания сочетания проверенным нужен реальный прогон с оценкой результата.

## Документация и прежние решения

README должен различать обычную установку и подключение CUDA: дополнительные
зависимости через один extra на Linux/WSL x86_64 и Windows x64, внешние
требования драйвера и Visual C++ Runtime, явный запуск, настройку TOML
и диагностику отсутствующих библиотек или несовместимого железа. Команды
установки из клона и через `uv tool` проверяются при реализации. CUDA extra
оформляется отдельным изменением, чтобы поставку можно было проверить
независимо от рефакторинга выполнения.

При реализации нужно отразить пересмотр прежних решений:

- [ADR-001](../adr/001-cuda-bootstrap.md): обязательная cuBLAS ради готовности
  CUDA сразу после установки сменяется подключением по желанию пользователя.
- [ADR-002](../adr/002-batch-and-config.md): состояние модели больше не
  возвращается caller для переноса между файлами. Prescan-first сохраняется.
- [ADR-003](../adr/003-pluggable-backends.md): движок и аппаратное исполнение
  различаются внутри module; device больше не считается полным описанием
  исполнения. Сохраняются adapters, ленивые imports и единый владелец загрузки.
- [ADR-006](../adr/006-onnx-asr-backend.md): автоматический выбор CUDA по
  `nvidia-smi` заменяется явным включением; модель ONNX по умолчанию сохраняется.
- [ADR-007](../adr/007-word-level-speaker-diarization.md): правила пословного
  результата и диаризации этим решением не пересматриваются.

Основания для будущих аппаратных вариантов уже собраны в
[исследовании runtime](../research/2026-08-12-onnx-runtime-openvino-lifecycle.md).
Актуальные описания механизмов: [CoreML EP](https://onnxruntime.ai/docs/execution-providers/CoreML-ExecutionProvider.html)
и [Windows ML](https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/overview).
Их наличие не является подтверждением выбранных моделей на этих платформах.

## Объём задач

Для основного рефакторинга достаточно одной задачи с несколькими коммитами:
владение моделью, перевод callers, настройки ONNX и проверка поведения входят
в один принимаемый результат. Отдельных задач на каждый файл или коммит нет.

Существующая [задача #2](https://git.dementev.space/ddmitry/local-transcriber/issues/2)
получает принятое решение об optional CUDA вместо дальнейшего исследования:
зависимости, ручное включение, автоматический ONNX CPU, диагностика CUDA
и документация. Она выполняется первой и даёт основному рефакторингу
определённые правила выбора. Фиксация CPU providers ASR/VAD относится к #2;
бюджет потоков, владение состоянием и общая диагностика исполнения — к основной
задаче. Работа над CoreML, Windows ML и качеством диаризации сюда не входит.