diff --git a/docs/specs/2026-09-21-transcription-execution.md b/docs/specs/2026-09-21-transcription-execution.md new file mode 100644 index 0000000..2779daa --- /dev/null +++ b/docs/specs/2026-09-21-transcription-execution.md @@ -0,0 +1,162 @@ +# Владение выполнением транскрипции + +**Статус:** согласовано для постановки задач. Реализация не начата. + +## Зачем + +Основное направление развития — поддерживаемые модели и движки распознавания, +прежде всего ONNX. В перспективе нужны аппаратные варианты исполнения на Mac +и через Windows ML, но их внедрение не входит в этот рефакторинг. + +Сейчас CLI хранит модель, backend, путь к модели и фактическое устройство, +передаёт их в `_transcribe_file` и обновляет после fallback. Для ONNX часть +согласованного состояния находится в adapter, а загруженная модель передаётся +отдельно. Это увеличивает interface: caller должен знать порядок вызовов +и поддерживать согласованность значений. + +`device` одновременно обозначает движок и аппаратное исполнение. Значение +`onnx` выбирает adapter, но не закрепляет CPU: установленный `onnx-asr 0.12.0` +по умолчанию использует доступные execution providers. При этом CLI безусловно +пишет `ONNX (CPU)`. Параметр `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. 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: дополнительные +зависимости Linux/WSL, требования Windows, явный запуск, настройку 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 и качеством диаризации сюда не входит.