Dmitry DementievandClaude Opus 5
a8241b1d6b
ADR-002 и ADR-003 отражают Transcriber как единственного владельца загрузки и fallback; README получил раздел «Диагностика исполнения» и уточнение --threads для ONNX; AGENTS.md — новые тестовые паттерны. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
66 lines
4.5 KiB
Markdown
66 lines
4.5 KiB
Markdown
# ADR-002: Batch mode и config
|
||
|
||
**Статус**: Принято
|
||
**Дата**: 2026-03-18
|
||
**Обновлено**: 2026-09-21 — решения 2 и 4 пересмотрены (см. пометки)
|
||
|
||
## Контекст
|
||
|
||
После завершения MVP (шаги 1–7) пользователям не хватает:
|
||
- Обработки нескольких файлов за один вызов (batch mode)
|
||
- Конфигурационного файла для хранения дефолтов (модель, язык, устройство)
|
||
|
||
## Решения
|
||
|
||
### 1. Prescan-first: валидация до загрузки модели
|
||
|
||
Модель загружается **только если есть файлы для обработки**. Перед загрузкой модели выполняется полный prescan: валидация всех файлов и проверка существующих транскриптов.
|
||
|
||
**Почему**: загрузка модели (large-v3) занимает ~10 секунд и ~3 GB RAM/VRAM. Повторный запуск по уже обработанным файлам должен быть дешёвым no-op.
|
||
|
||
### 2. Состояние модели между файлами
|
||
|
||
**Пересмотрено 2026-09-21.** Исходное решение: `_transcribe_file()` возвращал
|
||
`TranscribeFileResult` с обновлёнными `model`, `backend`, `model_path`
|
||
и `actual_device`, а CLI переносил их в следующий файл после mid-stream
|
||
fallback. Это делало caller владельцем согласованности четырёх полей.
|
||
|
||
Теперь состояние не покидает module выполнения: `Transcriber` создаётся один
|
||
раз на запуск после prescan, загружает модель при первом файле и сам держит
|
||
загруженную модель, adapter и фактическое исполнение. Fallback меняет
|
||
состояние внутри module, и следующий файл батча идёт уже по нему. Caller
|
||
получает `TranscribeResult` и `ExecutionInfo` (запрошенное и выбранное
|
||
исполнение, движок, модель, квантизация, потоки, версии runtime).
|
||
|
||
**Альтернатива**: mutable-контейнер с моделью, передаваемый по ссылке, —
|
||
отклонена тогда же; owner-объект решает ту же задачу явно и тестируется
|
||
через свой interface.
|
||
|
||
### 3. Конфиг: CWD → глобальный, без мержа
|
||
|
||
Порядок поиска:
|
||
1. `.transcriber.toml` в текущей директории (проектный конфиг)
|
||
2. `~/.config/transcriber/config.toml` (глобальный конфиг)
|
||
|
||
Первый найденный побеждает, мержа между файлами нет.
|
||
|
||
**Почему**: CWD-конфиг удобен для per-project дефолтов (`language = "ru"` для русскоязычного проекта), глобальный — для машинных дефолтов (`device = "cpu"` на ноутбуке без GPU). Мерж усложняет предсказуемость.
|
||
|
||
**Приоритет значений**: CLI > конфиг > хардкод.
|
||
|
||
### 4. Публичный `transcribe()` — путь одного файла
|
||
|
||
**Пересмотрено 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: модель загружается один раз для всех файлов; CLI не переносит
|
||
состояние между файлами
|
||
- Fallback из CLI недостижим: явный device — strict, `auto` — ONNX CPU без
|
||
переходов. Механизм сохранён для `transcribe(..., strict_device=False)`
|
||
- `--force` флаг для перезаписи существующих транскриптов в батч-режиме
|