docs(execution): описаны владение выполнением и диагностика
ADR-002 и ADR-003 отражают Transcriber как единственного владельца загрузки и fallback; README получил раздел «Диагностика исполнения» и уточнение --threads для ONNX; AGENTS.md — новые тестовые паттерны. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dmitry DementievandClaude Opus 5 committed
1 parent
0f8ecb5bd3
commit
a8241b1d6b
5 files changed
+82
-38
No files matched your search
@@ -2,6 +2,7 @@
|
||||
|
||||
**Статус**: Принято
|
||||
**Дата**: 2026-03-18
|
||||
**Обновлено**: 2026-09-21 — решения 2 и 4 пересмотрены (см. пометки)
|
||||
|
||||
## Контекст
|
||||
|
||||
@@ -17,19 +18,23 @@
|
||||
|
||||
**Почему**: загрузка модели (large-v3) занимает ~10 секунд и ~3 GB RAM/VRAM. Повторный запуск по уже обработанным файлам должен быть дешёвым no-op.
|
||||
|
||||
### 2. TranscribeFileResult: возврат обновлённого состояния модели
|
||||
### 2. Состояние модели между файлами
|
||||
|
||||
При mid-stream CUDA fallback `_transcribe_file()` перезагружает модель на CPU внутри себя. Чтобы следующие файлы в батче не грузили модель повторно, результат включает обновлённые `model` и `actual_device`.
|
||||
**Пересмотрено 2026-09-21.** Исходное решение: `_transcribe_file()` возвращал
|
||||
`TranscribeFileResult` с обновлёнными `model`, `backend`, `model_path`
|
||||
и `actual_device`, а CLI переносил их в следующий файл после mid-stream
|
||||
fallback. Это делало caller владельцем согласованности четырёх полей.
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class TranscribeFileResult:
|
||||
result: TranscribeResult
|
||||
model: WhisperModel # может измениться при fallback
|
||||
actual_device: str # может измениться при fallback
|
||||
```
|
||||
Теперь состояние не покидает module выполнения: `Transcriber` создаётся один
|
||||
раз на запуск после prescan, загружает модель при первом файле и сам держит
|
||||
загруженную модель, adapter и фактическое исполнение. Fallback меняет
|
||||
состояние внутри module, и следующий файл батча идёт уже по нему. Caller
|
||||
получает `TranscribeResult` и `ExecutionInfo` (запрошенное и выбранное
|
||||
исполнение, движок, модель, квантизация, потоки, версии runtime).
|
||||
|
||||
**Альтернатива**: передавать модель по ссылке через mutable контейнер — менее явно и сложнее тестировать.
|
||||
**Альтернатива**: mutable-контейнер с моделью, передаваемый по ссылке, —
|
||||
отклонена тогда же; owner-объект решает ту же задачу явно и тестируется
|
||||
через свой interface.
|
||||
|
||||
### 3. Конфиг: CWD → глобальный, без мержа
|
||||
|
||||
@@ -43,15 +48,18 @@ class TranscribeFileResult:
|
||||
|
||||
**Приоритет значений**: CLI > конфиг > хардкод.
|
||||
|
||||
### 4. `_transcribe_file()` — внутренний helper
|
||||
### 4. Публичный `transcribe()` — путь одного файла
|
||||
|
||||
Публичный API (`transcribe()`) сохранён без изменений. Новая функция `_transcribe_file()` — внутренний helper с префиксом `_`, не часть публичного контракта.
|
||||
|
||||
`transcribe()` стала тонкой обёрткой: `load_model()` + `_transcribe_file()` → `TranscribeResult`.
|
||||
**Пересмотрено 2026-09-21.** Внутренние helpers `load_model()`
|
||||
и `_transcribe_file()` удалены. `transcribe()` сохранён и стал обёрткой над
|
||||
тем же `Transcriber`: `model_name` и `compute_type` без значения берут
|
||||
умолчания выбранного исполнения, `device="auto"` означает ONNX CPU, как в CLI.
|
||||
|
||||
## Последствия
|
||||
|
||||
- Обратная совместимость CLI: `transcribe file.mp4` работает как раньше
|
||||
- Все существующие тесты проходят без изменений сигнатур
|
||||
- Batch mode: модель загружается один раз для всех файлов
|
||||
- Batch mode: модель загружается один раз для всех файлов; CLI не переносит
|
||||
состояние между файлами
|
||||
- Fallback из CLI недостижим: явный device — strict, `auto` — ONNX CPU без
|
||||
переходов. Механизм сохранён для `transcribe(..., strict_device=False)`
|
||||
- `--force` флаг для перезаписи существующих транскриптов в батч-режиме
|
||||
@@ -44,21 +44,38 @@ CUDA bootstrap вызывается только при создании CUDA-м
|
||||
- `onnx` → OnnxAsrBackend
|
||||
- `auto` → ONNX на CPU независимо от `nvidia-smi` и установки extra
|
||||
|
||||
### load_model() — единственный владелец pipeline
|
||||
### Transcriber — единственный владелец загрузки и исполнения
|
||||
|
||||
`load_model()` выполняет ensure_model_available + create_model в одном вызове.
|
||||
CLI не вызывает ensure_model_available отдельно — это убирает двойной resolution
|
||||
и гарантирует, что модель скачивается для правильного бэкенда.
|
||||
Обновлено 2026-09-21. `Transcriber(ExecutionRequest)` в `transcriber.py`
|
||||
разрешает `auto` и device-aware умолчания, выполняет ensure_model_available +
|
||||
create_model в одном месте и держит модель, adapter и фактическое исполнение
|
||||
на весь запуск. CLI не вызывает `get_backend` и не хранит handles.
|
||||
|
||||
Внутри module различаются три вещи: поддерживаемая модель, движок
|
||||
распознавания (`faster-whisper`, `openvino`, `onnx-asr`) и способ исполнения.
|
||||
Значение `device` из CLI/TOML сохраняется как вход: таблица `_ENGINES`
|
||||
сопоставляет ему движок, а аппаратную часть (CPU, CUDA, Intel GPU, список
|
||||
providers) трактует adapter. Новое исполнение — строка таблицы и его
|
||||
понимание в adapter'е, не новая иерархия adapters.
|
||||
|
||||
### Cross-backend fallback
|
||||
|
||||
Fallback живёт в `transcriber.py` (оркестратор), не в бэкендах:
|
||||
Fallback живёт внутри `Transcriber`, не в бэкендах и не в CLI:
|
||||
- CUDA ошибка → CPU (FasterWhisper)
|
||||
- OpenVINO ошибка → CPU (FasterWhisper)
|
||||
- `strict_device=True` (явный device из CLI или TOML) → ошибка без fallback
|
||||
- strict запуск (явный device из CLI или TOML) → ошибка без fallback
|
||||
|
||||
При fallback в батч-режиме обновляются model, backend, model_path и actual_device
|
||||
через TranscribeFileResult — следующий файл использует правильный бэкенд.
|
||||
После перехода module сам держит новое состояние; следующий файл батча
|
||||
использует его без участия caller. `WordTimestampsUnavailableError`
|
||||
и ошибки пользовательских данных переходом не считаются.
|
||||
|
||||
### Диагностика исполнения
|
||||
|
||||
Каждый adapter отдаёт `runtime_info()` — версии runtime и фактическую
|
||||
конфигурацию (для ONNX — доступные providers и те, что заданы сессиям ASR
|
||||
и VAD, квантизация, бюджет потоков). `Transcriber` включает их в
|
||||
`ExecutionInfo`; CLI печатает их в `--verbose`. Наличие provider в wheel не
|
||||
считается доказательством выполнения графа на GPU/NPU.
|
||||
|
||||
### Аудио для OpenVINO
|
||||
|
||||
@@ -83,7 +100,7 @@ macOS; ONNX обеспечивает автоматический CPU-путь
|
||||
|
||||
## Последствия
|
||||
|
||||
- Обратная совместимость: `transcribe()` сохранён; `load_model()` изменил сигнатуру (возвращает 4-tuple вместо 2-tuple, добавлен `compute_type_explicit`)
|
||||
- Обратная совместимость: `transcribe()` сохранён; `load_model()` и `_transcribe_file()` удалены (2026-09-21)
|
||||
- Новый бэкенд добавляется одним файлом в `backends/` + регистрацией в `__init__.py`
|
||||
- Модели скачиваются по запросу — CUDA пользователь не качает OpenVINO модели, и наоборот
|
||||
- ARM и macOS: OpenVINO не ставится (platform markers), auto использует ONNX
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Владение выполнением транскрипции
|
||||
|
||||
**Статус:** согласовано. Правила выбора исполнения и optional CUDA реализованы
|
||||
в #2; рефакторинг владения выполнением не начат. Windows GPU-прогон без Toolkit
|
||||
остаётся невыполненным (см. ADR-001).
|
||||
**Статус:** реализовано. Правила выбора исполнения и optional CUDA — в #2,
|
||||
владение выполнением (`Transcriber`), бюджет потоков ONNX и диагностика —
|
||||
в #56. Windows GPU-прогон без Toolkit остаётся невыполненным (см. ADR-001).
|
||||
|
||||
## Зачем
|
||||
|
||||
|
||||
Reference in new issue
Block a user