From 854bf55145a6241c3a50a6cd5b9668f61ff97716 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sat, 25 Apr 2026 23:13:41 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B7=D0=B0=D0=B4=D0=BE=D0=BA=D1=83?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82?= =?UTF-8?q?=D1=8C=20onnx-=D0=B1=D1=8D=D0=BA=D0=B5=D0=BD=D0=B4=20=D0=B2=20R?= =?UTF-8?q?EADME,=20CLI-help=20=D0=B8=20ADR-005?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - пользователь должен знать о --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. --- README.md | 23 +++++++++++++++-------- docs/adr/005-onnx-asr-backend.md | 30 ++++++++++++++++-------------- src/local_transcriber/cli.py | 2 +- 3 files changed, 32 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d792660..17cdcd6 100644 --- a/README.md +++ b/README.md @@ -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 с таймкодами** — удобен для суммаризации ИИ - **Аудио и видео** — mp3, wav, mp4, mkv и [другие форматы](#поддерживаемые-форматы) @@ -114,6 +114,12 @@ transcribe podcast.wav --model large-v3 --compute-type float16 # Максимальное качество на Intel 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 ``` @@ -145,8 +151,8 @@ transcribe *.mp4 --force | `--model` | `-m` | `medium` | Модель Whisper | | `--language` | `-l` | `ru` | Язык (ru, en, auto и др.) | | `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу | -| `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu) | -| `--compute-type` | — | float16 (CUDA) / int8 (OpenVINO GPU/CPU) / float32 (CPU) | Тип вычислений | +| `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino, openvino-gpu, openvino-cpu, onnx) | +| `--compute-type` | — | float16 (CUDA) / int8 (OpenVINO/ONNX) / float32 (CPU) | Тип вычислений | | `--threads` | `-t` | 0 (авто) | Потоки CPU (рекомендуется = число физ. ядер) | | `--force` | `-f` | — | Перезаписать существующие транскрипты | | `--verbose` | `-v` | — | Подробный вывод | @@ -158,6 +164,7 @@ transcribe *.mp4 --force | CPU | ✅ | ✅ | ✅ | | OpenVINO (x86 CPU) | ✅ авто | — | ✅ авто | | OpenVINO (Intel GPU) | ✅ авто | — | ✅ авто | +| ONNX (CPU) | ✅ явно | ✅ явно | ✅ явно | | GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) |
@@ -210,11 +217,11 @@ language = "en" Дефолты зависят от устройства: -| Параметр | CUDA | OpenVINO (GPU) | OpenVINO (CPU) | CPU | -|----------|------|----------------|----------------|-----| -| model | medium | medium | medium | medium | -| compute_type | float16 | int8 | int8 | float32 | -| language | ru | ru | ru | ru | +| Параметр | CUDA | OpenVINO (GPU) | OpenVINO (CPU) | ONNX | CPU | +|----------|------|----------------|----------------|------|-----| +| model | medium | medium | medium | gigaam-v3 | medium | +| compute_type | float16 | int8 | int8 | int8 | float32 | +| language | ru | ru | ru | ru | ru | ## Модели и GPU diff --git a/docs/adr/005-onnx-asr-backend.md b/docs/adr/005-onnx-asr-backend.md index e036051..cb68bcb 100644 --- a/docs/adr/005-onnx-asr-backend.md +++ b/docs/adr/005-onnx-asr-backend.md @@ -18,19 +18,20 @@ ### Результаты -| Файл | Длит. | gigaam-v3 (CPU) | OpenVINO medium (CPU) | Ускорение | -|------|-------|-----------------|----------------------|-----------| -| 10-59-59 | 22:26 | 81с (16.6×) | 265с (5.1×) | **3.3×** | -| Vasya | 45:51 | 95с (29×) | 455с (6×) | **4.8×** | -| 12-02-37 | 1:20:44 | 170с (28.5×) | 779с (6.2×) | **4.6×** | +| Файл | Длит. | gigaam-v3 (CPU) | parakeet-v3 --ru (CPU) | OpenVINO medium (CPU) | +|------|-------|-----------------|----------------------|----------------------| +| 10-59-59 | 22:26 | 81с (16.6×) | 116с (11.6×) | 265с (5.1×) | +| Vasya | 45:51 | 95с (29×) | 138с (20×) | 455с (6×) | +| 12-02-37 | 1:20:44 | 170с (28.5×) | 251с (19.3×) | 779с (6.2×) | ### Качество (русская речь, файл 12-02-37) -| Модель | Пунктуация | Читаемость | Контекст | -|--------|-----------|-----------|----------| -| GPU f-whisper large-v3 | ✅ | Отлично | ✅ | -| **GigaAM v3 CTC (CPU)** | ❌ | Хорошо | ✅ | -| OpenVINO medium (CPU) | ✅ | Хорошо | ✅ | +| Модель | Пунктуация | Читаемость | Контекст | Особенности | +|--------|-----------|-----------|----------|-------------| +| GPU f-whisper large-v3 | ✅ | Отлично | ✅ | — | +| **GigaAM v3 CTC (CPU)** | ❌ | Хорошо | ✅ | Самый быстрый, без пунктуации | +| **Parakeet v3 --ru (CPU)** | ✅ | Хорошо | ✅ | Пунктуация, `` токены, ловит англ. вкрапления | +| OpenVINO medium (CPU) | ✅ | Хорошо | ✅ | Самый медленный | GigaAM v3 не расставляет знаки препинания, но контекст разговора полностью сохраняется — пригоден для конспектирования и дальнейшей LLM-обработки. VAD даёт более дробные сегменты (удобнее для навигации). Английскую речь не понимает (модель обучена только на русском). @@ -39,18 +40,19 @@ GigaAM v3 не расставляет знаки препинания, но ко **Оставить onnx-asr как экспериментальный бэкенд.** Доступен через `--device onnx`, не в цепочке авто-детекта. Модели: -- `gigaam-v3` — по умолчанию для `--device onnx`. Русский, 4.7% WER, 17-29x RTF на CPU. -- `parakeet-v3` — мультиязычный fallback (25 языков, включая русский). 11% WER, 34x RTF. +- `gigaam-v3` — по умолчанию для `--device onnx`. Русский, 4.7% WER, 17-29x RTF на CPU. Без пунктуации. +- `parakeet-v3` — мультиязычный (25 языков). 11% WER, 12-20x RTF. Для русского рекомендуется `--language ru`. С пунктуацией, но возможны `` токены. Обе модели в int8-квантизации (~300 MB, минимальная потеря качества). ## Последствия - Пользователи CPU получают 3-5x ускорение для русской речи по сравнению с OpenVINO -- Пунктуация отсутствует (GigaAM не обучен её ставить) — приемлемо для конспектирования +- gigaam-v3: максимальная скорость, без пунктуации — пригоден для конспектирования +- parakeet-v3: с пунктуацией, медленнее gigaam на 40%, для русского нужен явный `--language ru` - Мультиязычные записи требуют `--model parakeet-v3` - Бэкенд не в авто-детекте — пользователь должен явно указать `--device onnx` -- В будущем: добавить parakeet-v3 в авто-детект для мультиязыка, рассмотреть Canary для лучшего качества +- В будущем: добавить onnx в авто-детект, рассмотреть Canary для лучшего качества ## Отклонённые альтернативы diff --git a/src/local_transcriber/cli.py b/src/local_transcriber/cli.py index 497cc84..4c543d4 100644 --- a/src/local_transcriber/cli.py +++ b/src/local_transcriber/cli.py @@ -55,7 +55,7 @@ def main( output: Path | None = typer.Option(None, "--output", "-o", help="Путь к выходному файлу"), device: str | None = typer.Option( 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( None, "--compute-type", show_default=False,