docs: задокументировать onnx-бэкенд в README, CLI-help и ADR-005

- Зачем:
  - пользователь должен знать о --device onnx и поддерживаемых моделях.
- Что:
  - CLI help: добавлен onnx в список устройств.
  - README: секция примеров, таблица платформ, device-aware дефолты.
  - ADR-005: результаты parakeet-v3 --language ru, уточнённые рекомендации.
- Проверка:
  - uv run pytest -q (172 passed).
  - uv run transcribe --help показывает onnx.
This commit is contained in:
2026-04-25 23:13:41 +03:00
parent 53142fd341
commit 854bf55145
3 changed files with 32 additions and 23 deletions
+15 -8
View File
@@ -8,7 +8,7 @@ transcribe meeting.mp4
``` ```
- **Полностью локально** — данные не покидают машину - **Полностью локально** — данные не покидают машину
- **Авто-ускорение** — NVIDIA CUDA, Intel GPU (OpenVINO), OpenVINO CPU или CPU fallback - **Авто-ускорение** — NVIDIA CUDA, Intel GPU (OpenVINO), ONNX (CPU), OpenVINO CPU или CPU fallback
- **Батч-режим** — обработка нескольких файлов за один вызов - **Батч-режим** — обработка нескольких файлов за один вызов
- **Markdown с таймкодами** — удобен для суммаризации ИИ - **Markdown с таймкодами** — удобен для суммаризации ИИ
- **Аудио и видео** — mp3, wav, mp4, mkv и [другие форматы](#поддерживаемые-форматы) - **Аудио и видео** — mp3, wav, mp4, mkv и [другие форматы](#поддерживаемые-форматы)
@@ -114,6 +114,12 @@ transcribe podcast.wav --model large-v3 --compute-type float16
# Максимальное качество на Intel GPU # Максимальное качество на Intel GPU
transcribe podcast.wav --model large-v3 --device openvino-gpu transcribe podcast.wav --model large-v3 --device openvino-gpu
# Максимальная скорость на CPU (русский)
transcribe meeting.mp4 --device onnx --model gigaam-v3
# Мультиязычный CPU (25 языков, медленнее)
transcribe podcast.wav --device onnx --model parakeet-v3 --language auto
# Сохранить в конкретный файл # Сохранить в конкретный файл
transcribe interview.m4a --output result.md transcribe interview.m4a --output result.md
``` ```
@@ -145,8 +151,8 @@ transcribe *.mp4 --force
| `--model` | `-m` | `medium` | Модель Whisper | | `--model` | `-m` | `medium` | Модель Whisper |
| `--language` | `-l` | `ru` | Язык (ru, en, auto и др.) | | `--language` | `-l` | `ru` | Язык (ru, en, auto и др.) |
| `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу | | `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу |
| `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu) | | `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu, onnx) |
| `--compute-type` | — | float16 (CUDA) / int8 (OpenVINO GPU/CPU) / float32 (CPU) | Тип вычислений | | `--compute-type` | — | float16 (CUDA) / int8 (OpenVINO/ONNX) / float32 (CPU) | Тип вычислений |
| `--threads` | `-t` | 0 (авто) | Потоки CPU (рекомендуется = число физ. ядер) | | `--threads` | `-t` | 0 (авто) | Потоки CPU (рекомендуется = число физ. ядер) |
| `--force` | `-f` | — | Перезаписать существующие транскрипты | | `--force` | `-f` | — | Перезаписать существующие транскрипты |
| `--verbose` | `-v` | — | Подробный вывод | | `--verbose` | `-v` | — | Подробный вывод |
@@ -158,6 +164,7 @@ transcribe *.mp4 --force
| CPU | ✅ | ✅ | ✅ | | CPU | ✅ | ✅ | ✅ |
| OpenVINO (x86 CPU) | ✅ авто | — | ✅ авто | | OpenVINO (x86 CPU) | ✅ авто | — | ✅ авто |
| OpenVINO (Intel GPU) | ✅ авто | — | ✅ авто | | OpenVINO (Intel GPU) | ✅ авто | — | ✅ авто |
| ONNX (CPU) | ✅ явно | ✅ явно | ✅ явно |
| GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) | | GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) |
<details> <details>
@@ -210,11 +217,11 @@ language = "en"
Дефолты зависят от устройства: Дефолты зависят от устройства:
| Параметр | CUDA | OpenVINO (GPU) | OpenVINO (CPU) | CPU | | Параметр | CUDA | OpenVINO (GPU) | OpenVINO (CPU) | ONNX | CPU |
|----------|------|----------------|----------------|-----| |----------|------|----------------|----------------|------|-----|
| model | medium | medium | medium | medium | | model | medium | medium | medium | gigaam-v3 | medium |
| compute_type | float16 | int8 | int8 | float32 | | compute_type | float16 | int8 | int8 | int8 | float32 |
| language | ru | ru | ru | ru | | language | ru | ru | ru | ru | ru |
## Модели и GPU ## Модели и GPU
+16 -14
View File
@@ -18,19 +18,20 @@
### Результаты ### Результаты
| Файл | Длит. | gigaam-v3 (CPU) | OpenVINO medium (CPU) | Ускорение | | Файл | Длит. | gigaam-v3 (CPU) | parakeet-v3 --ru (CPU) | OpenVINO medium (CPU) |
|------|-------|-----------------|----------------------|-----------| |------|-------|-----------------|----------------------|----------------------|
| 10-59-59 | 22:26 | 81с (16.6×) | 265с (5.1×) | **3.3×** | | 10-59-59 | 22:26 | 81с (16.6×) | 116с (11.6×) | 265с (5.1×) |
| Vasya | 45:51 | 95с (29×) | 455с (6×) | **4.8×** | | Vasya | 45:51 | 95с (29×) | 138с (20×) | 455с (6×) |
| 12-02-37 | 1:20:44 | 170с (28.5×) | 779с (6.2×) | **4.6×** | | 12-02-37 | 1:20:44 | 170с (28.5×) | 251с (19.3×) | 779с (6.2×) |
### Качество (русская речь, файл 12-02-37) ### Качество (русская речь, файл 12-02-37)
| Модель | Пунктуация | Читаемость | Контекст | | Модель | Пунктуация | Читаемость | Контекст | Особенности |
|--------|-----------|-----------|----------| |--------|-----------|-----------|----------|-------------|
| GPU f-whisper large-v3 | ✅ | Отлично | ✅ | | GPU f-whisper large-v3 | ✅ | Отлично | ✅ | — |
| **GigaAM v3 CTC (CPU)** | ❌ | Хорошо | ✅ | | **GigaAM v3 CTC (CPU)** | ❌ | Хорошо | ✅ | Самый быстрый, без пунктуации |
| OpenVINO medium (CPU) | ✅ | Хорошо | ✅ | | **Parakeet v3 --ru (CPU)** | ✅ | Хорошо | ✅ | Пунктуация, `<unk>` токены, ловит англ. вкрапления |
| OpenVINO medium (CPU) | ✅ | Хорошо | ✅ | Самый медленный |
GigaAM v3 не расставляет знаки препинания, но контекст разговора полностью сохраняется — пригоден для конспектирования и дальнейшей LLM-обработки. VAD даёт более дробные сегменты (удобнее для навигации). Английскую речь не понимает (модель обучена только на русском). GigaAM v3 не расставляет знаки препинания, но контекст разговора полностью сохраняется — пригоден для конспектирования и дальнейшей LLM-обработки. VAD даёт более дробные сегменты (удобнее для навигации). Английскую речь не понимает (модель обучена только на русском).
@@ -39,18 +40,19 @@ GigaAM v3 не расставляет знаки препинания, но ко
**Оставить onnx-asr как экспериментальный бэкенд.** Доступен через `--device onnx`, не в цепочке авто-детекта. **Оставить onnx-asr как экспериментальный бэкенд.** Доступен через `--device onnx`, не в цепочке авто-детекта.
Модели: Модели:
- `gigaam-v3` — по умолчанию для `--device onnx`. Русский, 4.7% WER, 17-29x RTF на CPU. - `gigaam-v3` — по умолчанию для `--device onnx`. Русский, 4.7% WER, 17-29x RTF на CPU. Без пунктуации.
- `parakeet-v3` — мультиязычный fallback (25 языков, включая русский). 11% WER, 34x RTF. - `parakeet-v3` — мультиязычный (25 языков). 11% WER, 12-20x RTF. Для русского рекомендуется `--language ru`. С пунктуацией, но возможны `<unk>` токены.
Обе модели в int8-квантизации (~300 MB, минимальная потеря качества). Обе модели в int8-квантизации (~300 MB, минимальная потеря качества).
## Последствия ## Последствия
- Пользователи CPU получают 3-5x ускорение для русской речи по сравнению с OpenVINO - Пользователи CPU получают 3-5x ускорение для русской речи по сравнению с OpenVINO
- Пунктуация отсутствует (GigaAM не обучен её ставить) — приемлемо для конспектирования - gigaam-v3: максимальная скорость, без пунктуации — пригоден для конспектирования
- parakeet-v3: с пунктуацией, медленнее gigaam на 40%, для русского нужен явный `--language ru`
- Мультиязычные записи требуют `--model parakeet-v3` - Мультиязычные записи требуют `--model parakeet-v3`
- Бэкенд не в авто-детекте — пользователь должен явно указать `--device onnx` - Бэкенд не в авто-детекте — пользователь должен явно указать `--device onnx`
- В будущем: добавить parakeet-v3 в авто-детект для мультиязыка, рассмотреть Canary для лучшего качества - В будущем: добавить onnx в авто-детект, рассмотреть Canary для лучшего качества
## Отклонённые альтернативы ## Отклонённые альтернативы
+1 -1
View File
@@ -55,7 +55,7 @@ def main(
output: Path | None = typer.Option(None, "--output", "-o", help="Путь к выходному файлу"), output: Path | None = typer.Option(None, "--output", "-o", help="Путь к выходному файлу"),
device: str | None = typer.Option( device: str | None = typer.Option(
None, "--device", "-d", show_default=False, None, "--device", "-d", show_default=False,
help="Устройство (auto|cpu|cuda|openvino|openvino-gpu|openvino-cpu) [по умолч.: auto]" help="Устройство (auto|cpu|cuda|openvino|openvino-gpu|openvino-cpu|onnx) [по умолч.: auto]"
), ),
compute_type: str | None = typer.Option( compute_type: str | None = typer.Option(
None, "--compute-type", show_default=False, None, "--compute-type", show_default=False,