docs: уточнены ограничения авто-профиля и профиль turbo

- Зачем: - документация обещала large-v3-turbo на NVIDIA, где он недоступен, и умалчивала, что модель по умолчанию без CUDA понимает только русскую речь. - Что: - large-v3-turbo перенесён из таблицы faster-whisper в раздел OpenVINO с измеренными размерами моделей. - языковое ограничение авто-профиля и предупреждение CLI описаны в README, gpu.md и ADR-006. - в backlog добавлен пункт про turbo для faster-whisper, в gpu.md снято расхождение по скорости openvino-cpu. - Проверка: - вычитка diff, проверка якорной ссылки на docs/gpu.md.
2026-08-12 11:53:09 +03:00
parent 9f11c32979
commit dae9d107c9
5 changed files with 73 additions and 10 deletions
@@ -36,7 +36,11 @@ uv tool install git+https://github.com/dementev-dev/local-transcriber
 - **NVIDIA CUDA** (GPU): если есть GPU — транскрипция в 5-10× быстрее
  - **Windows**: `winget install -e --id Nvidia.CUDA --version 12.9` (от администратора), перезапустить терминал
  - **Linux / WSL2**: работает из коробки (нужен только драйвер: `nvidia-smi`)
- **Без NVIDIA GPU**: автоматически используется ONNX с GigaAM RNN-T на CPU
+- **Без NVIDIA GPU**: автоматически используется ONNX с GigaAM RNN-T на CPU.
+  Эта модель понимает только русскую речь
+- **Другие языки без NVIDIA**: выбирайте Whisper явно —
+  `--device openvino-cpu --model medium` на x86 или `--device cpu --model medium`
+  на любой платформе
 - **OpenVINO** для Intel GPU или x86 CPU остаётся доступен через явный
  `--device openvino`, `--device openvino-gpu` или `--device openvino-cpu`

@@ -183,7 +187,7 @@ transcribe --uninstall-menu
 | Опция | Сокращение | По умолчанию | Описание |
 |-------|-----------|-------------|----------|
 | `--model` | `-m` | medium (CUDA) / gigaam-v3-e2e-rnnt (ONNX) | Модель распознавания |
-| `--language` | `-l` | `ru` | Язык (ru, en, auto и др.) |
+| `--language` | `-l` | `ru` | Язык (ru, en, auto и др.); автоматический профиль без NVIDIA понимает только русский |
 | `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу |
 | `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu, onnx) |
 | `--compute-type` | — | float16 (CUDA) / int8 (ONNX/OpenVINO) / float32 (CPU) | Тип вычислений |
@@ -200,6 +204,9 @@ transcribe --uninstall-menu
 | OpenVINO (Intel GPU) | ✅ явно | — | ✅ явно |
 | GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) |

+Данные по macOS основаны на доступности пакетов onnxruntime: прогонов на этой
+платформе не было.
+
 <details>
 <summary>Linux / WSL2</summary>

@@ -253,7 +260,9 @@ language = "ru"
 При `device = "auto"` выбирается CUDA, если доступен `nvidia-smi`, иначе ONNX.
 Явный `device` из CLI или конфига отключает этот автоматический выбор.
 Каталоги моделей различаются между бэкендами, поэтому при закреплении `model`
-в конфиге рекомендуется явно закрепить и совместимый `device`.
+в конфиге рекомендуется явно закрепить и совместимый `device`. То же с языком:
+автоматический ONNX-профиль рассчитан на русскую речь, а для остальных языков
+нужен Whisper — например, `device = "openvino-cpu"` и `model = "medium"`.

 Дефолты зависят от устройства:

@@ -278,6 +287,8 @@ language = "ru"
 <details>
 <summary>Таблица моделей</summary>

+#### Whisper через faster-whisper (`--device cuda`, `--device cpu`)
+
 | Модель | Размер на диске | VRAM (int8) | Скорость (GPU) | Качество |
 |--------|----------------|-------------|----------------|----------|
 | `tiny` | ~75 MB | ~1 GB | ★★★★★ | ★ |
@@ -285,7 +296,15 @@ language = "ru"
 | `small` | ~460 MB | ~1.5 GB | ★★★ | ★★★ |
 | `medium` | ~1.5 GB | ~2.5 GB | ★★ | ★★★★ |
 | `large-v3` | ~3 GB | ~2.5 GB | ★ | ★★★★★ |
-| `large-v3-turbo` | ~1 GB | — | ★★★★ | ★★★★ |
+
+#### Whisper через OpenVINO (`--device openvino-cpu`, `--device openvino-gpu`)
+
+Здесь те же модели Whisper, но предквантизированные, поэтому на диске они
+занимают меньше места: `medium` int8 — 748 MB, `large-v3-turbo` int8 — 790 MB,
+`large-v3-turbo` fp16 — 1552 MB. Модель `large-v3-turbo` доступна только здесь:
+faster-whisper её не поддерживает, и запуск с `--device cuda` завершится
+ошибкой. Полный список репозиториев —
+[docs/gpu.md](docs/gpu.md#доступные-openvino-модели).

 #### ONNX-модели (`--device onnx`)

@@ -318,6 +337,9 @@ language = "ru"
 кыргызский и узбекский внутри одной записи. `onnx-asr` не передаёт этим моделям
 подсказку языка, поэтому `--language` не управляет выбором языка.

+Если модель не понимает запрошенный язык, CLI предупреждает об этом до начала
+распознавания и подсказывает совместимый профиль, но работу не прерывает.
+
 Для моделей из таблицы опубликованы `int8` и `float32`. Если неявный
 device-aware дефолт недоступен для выбранной модели, CLI сообщит о подстановке
 доступного варианта. Явное значение из `--compute-type` или
@@ -359,7 +381,7 @@ device-aware дефолт недоступен для выбранной мод

 - **Дата транскрипции**: 2026-03-17 14:30:05
 - **Модель**: large-v3
- **Язык**: ru (detected)
+- **Язык**: ru (задан явно)
 - **Длительность**: 01:23:45
 - **Устройство**: CUDA (NVIDIA GeForce RTX 3060)

@@ -374,6 +396,14 @@ device-aware дефолт недоступен для выбранной мод
 Близкие по времени сегменты автоматически объединяются в абзацы (пауза > 2 сек или длительность > 60 сек разделяет абзацы).
 Таймкоды: `MM:SS.ss`, для записей длиннее 1 часа — `HH:MM:SS.ss`.

+В скобках после языка указан его источник:
+
+- `задан явно` — язык взят из `--language` или конфига;
+- `определён автоматически` — распознан моделью при `--language auto`;
+- `из профиля модели` — у модели всего один язык, как у GigaAM.
+
+Если язык определить не удалось, строка выглядит так: `- **Язык**: не определён`.
+
 </details>

 ## Поддерживаемые форматы
@@ -64,7 +64,7 @@ transcribe <путь_к_файлу> [опции]

 - **Дата транскрипции**: 2026-03-17 14:30:05
 - **Модель**: large-v3
- **Язык**: ru (detected) / ru (forced)
+- **Язык**: ru (задан явно) / ru (определён автоматически)
 - **Длительность**: 01:23:45
 - **Устройство**: CUDA (NVIDIA GeForce RTX 3060)

@@ -107,6 +107,11 @@ GigaAM v3 E2E RNN-T — модель по умолчанию на машинах
 Порядок `--device auto`: CUDA при наличии `nvidia-smi`, иначе ONNX. OpenVINO и
 FasterWhisper CPU остаются доступными через явный CLI-аргумент или конфиг.

+GigaAM понимает только русскую речь, поэтому для остальных языков автоматический
+профиль не годится — нужен явный Whisper. Несовместимый язык работу не
+останавливает: CLI предупреждает о нём до начала распознавания и называет
+подходящий профиль.
+
 Модели:
 - **`gigaam-v3-e2e-rnnt`** — модель по умолчанию: практически равна обычному
  GigaAM по скорости, немного уступает по WER, но выдаёт готовую пунктуацию для
@@ -132,10 +137,11 @@ FasterWhisper CPU остаются доступными через явный CL

 ## Открытые вопросы / следующие шаги

- **Galлюцинации Whisper medium на длинных файлах** — отдельный продуктовый риск, требующий собственного исследования. Возможно, имеет смысл ограничить максимальную длину чанка для openvino-medium, или дать предупреждение пользователю.
+- **Галлюцинации Whisper medium на длинных файлах** — отдельный продуктовый риск, требующий собственного исследования. Возможно, имеет смысл ограничить максимальную длину чанка для openvino-medium, или дать предупреждение пользователю.
 - **Canary** (`nemo-canary-1b-v2`) — тяжелее, но multilingual + пунктуация. Кандидат на «лучшее качество за разумную скорость» для тех, кому важна пунктуация.
- Проверить профиль на других языках и при необходимости добавить явные
-  многоязычные рекомендации; автоматическая политика намеренно не зависит от языка.
+- Проверить качество на других языках и при необходимости дополнить
+  многоязычные рекомендации. Сама автоматическая политика от языка не зависит:
+  она предупреждает о несовместимости, но профиль за пользователя не меняет.

 ## Отклонённые альтернативы

@@ -252,6 +252,22 @@ SQL`), словарь пользовательский в `.transcriber.toml`.

 ---

+### `large-v3-turbo` для faster-whisper
+
+**Что:** Добавить `large-v3-turbo` в каталог faster-whisper, чтобы модель была
+доступна с `--device cuda` и `--device cpu`, а не только через OpenVINO.
+
+**Почему:** На CPU turbo INT8 оказался быстрее `medium` и точнее по WER
+([сравнение от 2026-08-12](benchmarks/2026-08-12-openvino-large-v3-turbo-comparison.md)),
+и владельцам NVIDIA этот профиль сейчас недоступен без ручного указания
+репозитория HuggingFace.
+
+**Почему откладывается:** каталог faster-whisper в проекте собран из
+репозиториев `Systran`, и для turbo нужно сначала выяснить, какая CT2-сборка
+годится, проверить её происхождение и качество, и только потом вносить в код.
+
+---
+
 ## Отклонённые направления

 *(пока пусто — добавлять сюда то, что попробовали и решили не делать, с причиной)*
@@ -6,7 +6,7 @@
 - `cuda` — строго NVIDIA GPU, ошибка если недоступен
 - `openvino` — авто-выбор OpenVINO GPU или CPU
 - `openvino-gpu` — строго Intel GPU через OpenVINO
- `openvino-cpu` — строго CPU через OpenVINO (ускорение 2-4x на x86)
+- `openvino-cpu` — строго CPU через OpenVINO (3-10x на x86, зависит от модели)
 - `cpu` — строго CPU (faster-whisper/CTranslate2)

 ## Какой бэкенд на каком оборудовании
@@ -22,6 +22,10 @@
 \* По результатам контрольных прогонов на Intel и AMD CPU. Реальная скорость
 зависит от CPU, модели и записи.

+Автоматический профиль без NVIDIA рассчитан на русскую речь: GigaAM других
+языков не понимает. Для них берите Whisper — `openvino-cpu` на x86 или `cpu`
+на любой платформе.
+
 ## OpenVINO

 OpenVINO ускоряет inference на x86 процессорах (Intel и AMD) через оптимизированные инструкции
@@ -44,6 +48,13 @@ OpenVINO ускоряет inference на x86 процессорах (Intel и AM
 | large-v3 | OpenVINO/whisper-large-v3-int8-ov | OpenVINO/whisper-large-v3-fp16-ov |
 | large-v3-turbo | OpenVINO/whisper-large-v3-turbo-int8-ov | OpenVINO/whisper-large-v3-turbo-fp16-ov |

+Размер в кеше HuggingFace: `medium` int8 — 748 MB, `large-v3-turbo` int8 —
+790 MB, `large-v3-turbo` fp16 — 1552 MB. Это меньше, чем у тех же моделей для
+faster-whisper, потому что веса уже квантизированы.
+
+Модель `large-v3-turbo` доступна только в OpenVINO: для `--device cuda` и
+`--device cpu` каталог faster-whisper заканчивается на `large-v3`.
+
 ### Результаты тестирования OpenVINO

 Актуальное сравнение OpenVINO 2026.3 на трёх русскоязычных встречах: