docs(architecture): согласовано владение выполнением транскрипции
This commit is contained in:
Dmitry Dementiev committed
1 parent
671ac8e5c9
commit
2b54f5bc9e
1 file changed
+162
@@ -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 и качеством диаризации сюда не входит.
|
||||||
Reference in new issue
Block a user