Dmitriy Dementiev
8f85930616
- Зачем: - расширенный benchmark показал устойчивое улучшение multilingual large на трёх реальных записях. - Что: - добавлен alias gigaam-multilingual-large-ctc с квантизациями int8 и float32. - обновлены README, спецификация, backlog и сравнительный benchmark. - Проверка: - uv run pytest -q: 225 passed, 1 skipped. - uvx ruff check src/local_transcriber/backends/onnx_asr.py tests/test_onnx_asr.py.
379 lines
18 KiB
Markdown
379 lines
18 KiB
Markdown
# local-transcriber
|
||
|
||
Локальная транскрипция аудио и видео в markdown — без облака, без API-ключей.
|
||
|
||
```bash
|
||
transcribe meeting.mp4
|
||
# → meeting-transcript.md
|
||
```
|
||
|
||
- **Полностью локально** — данные не покидают машину
|
||
- **Авто-ускорение** — NVIDIA CUDA, Intel GPU (OpenVINO), ONNX (CPU), OpenVINO CPU или CPU fallback
|
||
- **Батч-режим** — обработка нескольких файлов за один вызов
|
||
- **Из проводника Windows** — пункт Transcribe в меню «Отправить» ([установка](#контекстное-меню-проводника-windows))
|
||
- **Markdown с таймкодами** — удобен для суммаризации ИИ
|
||
- **Аудио и видео** — mp3, wav, mp4, mkv и [другие форматы](#поддерживаемые-форматы)
|
||
|
||
## Установка
|
||
|
||
**1. Установить [uv](https://docs.astral.sh/uv/getting-started/installation/)** (если ещё нет):
|
||
|
||
```bash
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh # Linux / macOS
|
||
```
|
||
```powershell
|
||
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
|
||
```
|
||
|
||
**2. Установить transcriber:**
|
||
|
||
```bash
|
||
uv tool install git+https://github.com/dementev-dev/local-transcriber
|
||
```
|
||
|
||
**3. Ускорение (ставится автоматически):**
|
||
|
||
- **Intel GPU** (Arc, встроенная графика): работает через OpenVINO — ускорение в ~2x vs CPU
|
||
- **OpenVINO** (Intel/AMD x86 CPU): ставится автоматически на Linux и Windows — ускорение в 2-4x
|
||
- **NVIDIA CUDA** (GPU): если есть GPU — транскрипция в 5-10× быстрее
|
||
- **Windows**: `winget install -e --id Nvidia.CUDA --version 12.9` (от администратора), перезапустить терминал
|
||
- **Linux / WSL2**: работает из коробки (нужен только драйвер: `nvidia-smi`)
|
||
|
||
**4. Готово:**
|
||
|
||
```bash
|
||
transcribe meeting.mp4
|
||
```
|
||
Модели скачиваются автоматически при первом запуске (~1.5 GB для medium), нужен доступ в интернет.
|
||
|
||
<details>
|
||
<summary><code>transcribe: command not found</code></summary>
|
||
|
||
Выполните `uv tool update-shell` — это добавит нужный путь в PATH автоматически.
|
||
|
||
</details>
|
||
|
||
**Обновление:**
|
||
|
||
```bash
|
||
uv tool install --force git+https://github.com/dementev-dev/local-transcriber
|
||
```
|
||
|
||
**Удаление:**
|
||
|
||
```bash
|
||
uv tool uninstall local-transcriber
|
||
```
|
||
|
||
**Очистка моделей:**
|
||
|
||
Модели кешируются в `~/.cache/huggingface/hub/` и могут занимать несколько гигабайт.
|
||
На Windows без Developer Mode файлы копируются без симлинков — место удваивается.
|
||
|
||
```bash
|
||
# Linux / macOS — посмотреть размер кеша
|
||
du -sh ~/.cache/huggingface/hub/models--*
|
||
|
||
# Удалить все скачанные модели
|
||
rm -rf ~/.cache/huggingface/hub/models--Systran--faster-whisper-*
|
||
rm -rf ~/.cache/huggingface/hub/models--OpenVINO--whisper-*
|
||
```
|
||
|
||
```powershell
|
||
# Windows
|
||
dir "$env:USERPROFILE\.cache\huggingface\hub\models--*"
|
||
|
||
# Удалить все скачанные модели
|
||
Remove-Item -Recurse "$env:USERPROFILE\.cache\huggingface\hub\models--Systran--faster-whisper-*"
|
||
Remove-Item -Recurse "$env:USERPROFILE\.cache\huggingface\hub\models--OpenVINO--whisper-*"
|
||
```
|
||
|
||
При следующем запуске нужная модель скачается заново.
|
||
|
||
<details>
|
||
<summary>Windows: ошибка WinError 1314 при первом запуске</summary>
|
||
|
||
HuggingFace Hub использует симлинки для экономии места. На Windows без Developer Mode первая загрузка модели может упасть с ошибкой `WinError 1314`. Повторный запуск команды обычно помогает — HF Hub переключается на копирование файлов.
|
||
|
||
Чтобы избежать проблемы и сэкономить место, включите Developer Mode:
|
||
[Инструкция Microsoft](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development)
|
||
|
||
</details>
|
||
|
||
## Использование
|
||
|
||
```bash
|
||
# Простой запуск (medium, русский, автодетект устройства)
|
||
transcribe meeting.mp4
|
||
|
||
# Указать язык
|
||
transcribe lecture.mp3 --language en
|
||
|
||
# Максимальное качество на NVIDIA GPU
|
||
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 с пунктуацией и нормализацией русского текста
|
||
transcribe podcast.wav --device onnx --model gigaam-v3-e2e-ctc
|
||
|
||
# Смешанная русско-английская речь
|
||
transcribe meeting.wav --device onnx --model gigaam-multilingual-ctc
|
||
|
||
# Повышенная точность смешанной речи (медленнее, ~590 MB)
|
||
transcribe meeting.wav --device onnx --model gigaam-multilingual-large-ctc
|
||
|
||
# Сохранить в конкретный файл
|
||
transcribe interview.m4a --output result.md
|
||
```
|
||
|
||
### Батч-режим
|
||
|
||
Обработка нескольких файлов за один вызов — модель загружается один раз:
|
||
|
||
```bash
|
||
# Все mp4 в директории
|
||
transcribe ./recordings/*.mp4
|
||
|
||
# Несколько файлов
|
||
transcribe meeting1.mp3 meeting2.mp3
|
||
|
||
# Перезаписать существующие транскрипты
|
||
transcribe *.mp4 --force
|
||
```
|
||
|
||
- Файлы с существующим транскриптом (`*-transcript.md`) автоматически пропускаются
|
||
- `--force` / `-f` — перезаписать существующие транскрипты
|
||
- При ошибке в одном файле остальные продолжают обрабатываться
|
||
- `--output` несовместим с несколькими файлами
|
||
|
||
### Контекстное меню проводника (Windows)
|
||
|
||
Установить пункт `Transcribe` в меню «Отправить»:
|
||
|
||
```bash
|
||
transcribe --install-menu
|
||
```
|
||
|
||
(при запуске из клона репозитория — `uv run transcribe --install-menu`)
|
||
|
||
Использование: выделите один или несколько аудио/видеофайлов в проводнике, откройте контекстное меню правой кнопкой. В Windows 11 выберите «Показать дополнительные параметры» или нажмите Shift+F10, затем «Отправить» → «Transcribe». Несколько выделенных файлов передаются в один процесс и обрабатываются одним батчем.
|
||
|
||
Удалить пункт меню:
|
||
|
||
```bash
|
||
transcribe --uninstall-menu
|
||
```
|
||
|
||
Если что-то пошло не так, пункт можно удалить вручную: Win+R → `shell:sendto` → удалить `Transcribe.cmd`.
|
||
|
||
Известные ограничения:
|
||
|
||
- После переноса или пересоздания проекта/venv выполните `--install-menu` заново: внутри `Transcribe.cmd` хранится абсолютный путь к `transcribe.exe`.
|
||
- Очень большой мультивыбор с суммарной длиной путей ≳8000 символов упирается в лимит командной строки cmd.exe. Обрабатывайте такие файлы частями.
|
||
|
||
### Опции CLI
|
||
|
||
| Опция | Сокращение | По умолчанию | Описание |
|
||
|-------|-----------|-------------|----------|
|
||
| `--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, onnx) |
|
||
| `--compute-type` | — | float16 (CUDA) / int8 (OpenVINO/ONNX) / float32 (CPU) | Тип вычислений |
|
||
| `--threads` | `-t` | 0 (авто) | Потоки CPU (рекомендуется = число физ. ядер) |
|
||
| `--force` | `-f` | — | Перезаписать существующие транскрипты |
|
||
| `--verbose` | `-v` | — | Подробный вывод |
|
||
|
||
## Платформы
|
||
|
||
| | Linux / WSL2 | macOS | Windows |
|
||
|---|---|---|---|
|
||
| CPU | ✅ | ✅ | ✅ |
|
||
| OpenVINO (x86 CPU) | ✅ авто | — | ✅ авто |
|
||
| OpenVINO (Intel GPU) | ✅ авто | — | ✅ авто |
|
||
| ONNX (CPU) | ✅ явно | ✅ явно | ✅ явно |
|
||
| GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) |
|
||
|
||
<details>
|
||
<summary>Linux / WSL2</summary>
|
||
|
||
- **Intel GPU** (Arc, встроенная графика) работает из коробки через OpenVINO
|
||
- **NVIDIA GPU** работает из коробки — cuBLAS ставится автоматически как зависимость
|
||
- Нужен только драйвер NVIDIA (проверка: `nvidia-smi`)
|
||
- На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>macOS</summary>
|
||
|
||
- Работает на CPU (Intel и Apple Silicon)
|
||
- GPU (CUDA) недоступен — NVIDIA не поддерживает macOS
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Windows</summary>
|
||
|
||
- CPU работает из коробки
|
||
- **Intel GPU** (Arc, встроенная графика) работает из коробки через OpenVINO
|
||
- Для **NVIDIA GPU** нужен **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13):
|
||
```
|
||
winget install -e --id Nvidia.CUDA --version 12.9
|
||
```
|
||
> `winget install` требует запуска от имени администратора (elevated terminal).
|
||
> `uv tool install` работает без админа (ставит в пользовательскую директорию).
|
||
- После установки CUDA перезапустите терминал
|
||
|
||
</details>
|
||
|
||
## Конфигурация
|
||
|
||
Дефолтные параметры можно задать в `.transcriber.toml`:
|
||
|
||
```toml
|
||
model = "large-v3"
|
||
language = "en"
|
||
```
|
||
|
||
Порядок поиска:
|
||
1. `.transcriber.toml` в текущей директории
|
||
2. `~/.config/transcriber/config.toml`
|
||
|
||
Приоритет: **CLI-аргумент > конфиг > device-aware дефолт > встроенный дефолт**.
|
||
|
||
Дефолты зависят от устройства:
|
||
|
||
| Параметр | 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
|
||
|
||
Рекомендации:
|
||
- **По умолчанию:** `medium` — хороший баланс скорости и качества
|
||
- **Макс. качество (NVIDIA):** `large-v3` + `--compute-type float16`
|
||
- **Макс. качество (Intel GPU):** `large-v3` + `--device openvino-gpu`
|
||
- **Макс. скорость CPU (русский):** `--device onnx --model gigaam-v3` (17-29× RTF, без пунктуации; рекомендуется LLM-нормализация терминов после)
|
||
- **CPU с пунктуацией (русский):** `--device openvino-cpu --model medium` (5-6× RTF; для встреч ≤30 мин с равномерной громкостью — на длинных файлах с тихими фрагментами возможны галлюцинации)
|
||
- **Быстрый тест:** `tiny` — для проверки пайплайна
|
||
|
||
<details>
|
||
<summary>Таблица моделей</summary>
|
||
|
||
| Модель | Размер на диске | VRAM (int8) | Скорость (GPU) | Качество |
|
||
|--------|----------------|-------------|----------------|----------|
|
||
| `tiny` | ~75 MB | ~1 GB | ★★★★★ | ★ |
|
||
| `base` | ~140 MB | ~1 GB | ★★★★ | ★★ |
|
||
| `small` | ~460 MB | ~1.5 GB | ★★★ | ★★★ |
|
||
| `medium` | ~1.5 GB | ~2.5 GB | ★★ | ★★★★ |
|
||
| `large-v3` | ~3 GB | ~2.5 GB | ★ | ★★★★★ |
|
||
|
||
#### ONNX-модели (`--device onnx`)
|
||
|
||
Другие архитектуры, не Whisper. Работают через onnxruntime на CPU:
|
||
|
||
| Модель | Размер (int8) | RTFx CPU | Языки | Пунктуация |
|
||
|--------|--------------|----------|-------|-----------|
|
||
| `gigaam-v3` | ~300 MB | 17-29× | ru | ❌ |
|
||
| `gigaam-multilingual-ctc` | ~300 MB | 10,0×* | ru, en, kk, ky, uz | ❌ |
|
||
| `gigaam-multilingual-large-ctc` | ~590 MB | 4,8×* | ru, en, kk, ky, uz | ❌ |
|
||
| `gigaam-v3-e2e-ctc` | ~300 MB | 11,9×* | ru | ✅ |
|
||
| `gigaam-v3-e2e-rnnt` | ~300 MB | 11,5×* | ru | ✅ |
|
||
| `parakeet-v3` | ~600 MB | 12-20× | 25 языков | ✅ |
|
||
|
||
\* Наблюдение на AMD Ryzen 7 8845H, Windows, `int8`, три записи общей
|
||
длительностью 43:37. Это не приёмочный замер для целевого Intel Core i5.
|
||
Методика и качественное сравнение:
|
||
[benchmark GigaAM и Whisper](docs/benchmarks/2026-08-11-gigaam-model-comparison.md).
|
||
|
||
> **Рекомендация**: для готового читаемого русского текста
|
||
> используйте `gigaam-v3-e2e-rnnt`, для последующей машинной обработки — более
|
||
> точный по словам `gigaam-v3` без пунктуации. Для смешанной речи с приоритетом
|
||
> качества используйте `gigaam-multilingual-large-ctc`: она примерно вдвое
|
||
> медленнее small-варианта, но приблизилась к monolingual GigaAM по WER.
|
||
> `parakeet-v3` на русском воспроизводит проблемы из
|
||
> [ADR-005](docs/adr/005-parakeet-evaluation.md).
|
||
|
||
Обе GigaAM Multilingual сами распознают русский, английский, казахский,
|
||
кыргызский и узбекский внутри одной записи. `onnx-asr` не передаёт этим моделям
|
||
подсказку языка, поэтому `--language` не управляет выбором языка.
|
||
|
||
Для моделей из таблицы опубликованы `int8` и `float32`. Если неявный
|
||
device-aware дефолт недоступен для выбранной модели, CLI сообщит о подстановке
|
||
доступного варианта. Явное значение из `--compute-type` или
|
||
`.transcriber.toml` вместо подстановки завершится ошибкой.
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Типы квантизации (--compute-type)</summary>
|
||
|
||
| Тип | Бэкенд | VRAM/RAM | Качество | Когда использовать |
|
||
|-----|--------|----------|----------|--------------------|
|
||
| `float16` | CUDA | ~4.5-5 GB | Отлично | **По умолчанию для CUDA** |
|
||
| `int8_float16` | CUDA | ~4.7 GB | Отлично | GPU от 6 GB, альтернатива float16 |
|
||
| `int8_float32` | CPU | Среднее | Отлично | **Рекомендуется для CPU** — 1.5x быстрее float32 при том же качестве |
|
||
| `int8` | CUDA / OpenVINO / ONNX | Низкое | Хорошо, но бывают галлюцинации | **По умолчанию для OpenVINO и ONNX** |
|
||
| `fp16` | OpenVINO | Низкое | Отлично | OpenVINO large-v3 (выбирается автоматически) |
|
||
| `float32` | CPU / ONNX | Среднее | Отлично | **По умолчанию для CPU** |
|
||
|
||
**Важно:** `int8` на длинных записях может давать галлюцинации (повтор фраз, потеря контента).
|
||
`float16`/`fp16` и `float32` значительно стабильнее на записях >20 минут.
|
||
|
||
> Для OpenVINO `--compute-type` выбирает предквантизированную модель (int8 или fp16),
|
||
> а не runtime-параметр. Для `large-v3` по умолчанию выбирается `fp16`.
|
||
|
||
</details>
|
||
|
||
Подробнее: бенчмарки, OpenVINO, совместимость GPU, результаты тестирования — [docs/gpu.md](docs/gpu.md).
|
||
|
||
<details>
|
||
<summary>Формат вывода</summary>
|
||
|
||
```markdown
|
||
# Транскрипт: meeting.mp4
|
||
|
||
- **Дата транскрипции**: 2026-03-17 14:30:05
|
||
- **Модель**: large-v3
|
||
- **Язык**: ru (detected)
|
||
- **Длительность**: 01:23:45
|
||
- **Устройство**: CUDA (NVIDIA GeForce RTX 3060)
|
||
|
||
---
|
||
|
||
[00:00:00.00 - 00:00:15.40] Добрый день, коллеги. Сегодня мы обсудим результаты
|
||
квартала. Первый вопрос — по метрикам продукта.
|
||
|
||
[00:00:18.10 - 00:00:25.73] Теперь перейдём к финансовым показателям.
|
||
```
|
||
|
||
Близкие по времени сегменты автоматически объединяются в абзацы (пауза > 2 сек или длительность > 60 сек разделяет абзацы).
|
||
Таймкоды: `MM:SS.ss`, для записей длиннее 1 часа — `HH:MM:SS.ss`.
|
||
|
||
</details>
|
||
|
||
## Поддерживаемые форматы
|
||
|
||
- **Аудио**: mp3, wav, flac, ogg, m4a, wma, aac
|
||
- **Видео**: mp4, mkv, avi, mov, webm, ts
|
||
|
||
## Для разработчиков
|
||
|
||
```bash
|
||
git clone https://github.com/dementev-dev/local-transcriber
|
||
cd local-transcriber
|
||
uv sync
|
||
uv run transcribe meeting.mp4 # запуск CLI
|
||
uv run pytest # тесты
|
||
```
|
||
|
||
Подробнее — [CONTRIBUTING.md](CONTRIBUTING.md).
|