168 lines
16 KiB
Markdown
168 lines
16 KiB
Markdown
# Владение выполнением транскрипции
|
||
|
||
**Статус:** согласовано. Правила выбора исполнения и 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 и качеством диаризации сюда не входит.
|