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

Статус: согласовано. Правила выбора исполнения и 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: обязательная cuBLAS ради готовности CUDA сразу после установки сменяется подключением по желанию пользователя.
ADR-002: состояние модели больше не возвращается caller для переноса между файлами. Prescan-first сохраняется.
ADR-003: движок и аппаратное исполнение различаются внутри module; device больше не считается полным описанием исполнения. Сохраняются adapters, ленивые imports и единый владелец загрузки.
ADR-006: автоматический выбор CUDA по nvidia-smi заменяется явным включением; модель ONNX по умолчанию сохраняется.
ADR-007: правила пословного результата и диаризации этим решением не пересматриваются.

Основания для будущих аппаратных вариантов уже собраны в исследовании runtime. Актуальные описания механизмов: CoreML EP и Windows ML. Их наличие не является подтверждением выбранных моделей на этих платформах.

Объём задач

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

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

16 KiB Raw Blame History Unescape Escape