# Владение выполнением транскрипции **Статус:** согласовано. Правила выбора исполнения и optional CUDA реализованы в #2; рефакторинг владения выполнением не начат. 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 и качеством диаризации сюда не входит.