diff --git a/README.md b/README.md index 6efbb00..2f7a7b0 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ transcribe meeting.mp4 ``` - **Полностью локально** — данные не покидают машину -- **Авто-GPU** — автоматически использует NVIDIA CUDA, если доступен +- **Авто-ускорение** — NVIDIA CUDA, OpenVINO (Intel/AMD CPU) или CPU fallback - **Батч-режим** — обработка нескольких файлов за один вызов - **Markdown с таймкодами** — удобен для суммаризации ИИ - **Аудио и видео** — mp3, wav, mp4, mkv и [другие форматы](#поддерживаемые-форматы) @@ -30,12 +30,12 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie uv tool install git+https://github.com/dementev-dev/local-transcriber ``` -**3. (Опционально) GPU-ускорение:** +**3. Ускорение (ставится автоматически):** -Если есть NVIDIA GPU — транскрипция будет в 5–10× быстрее. Требуется **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13). - -- **Windows**: `winget install -e --id Nvidia.CUDA --version 12.9` (от администратора), перезапустить терминал -- **Linux / WSL2**: работает из коробки (нужен только драйвер: `nvidia-smi`) +- **OpenVINO** (Intel/AMD x86 CPU): ставится автоматически на Linux и Windows — ускорение в 2-4 раза +- **NVIDIA CUDA** (GPU): если есть GPU — транскрипция в 5-10× быстрее + - **Windows**: `winget install -e --id Nvidia.CUDA --version 12.9` (от администратора), перезапустить терминал + - **Linux / WSL2**: работает из коробки (нужен только драйвер: `nvidia-smi`) **4. Готово:** @@ -106,8 +106,8 @@ transcribe *.mp4 --force | `--model` | `-m` | `medium` | Модель Whisper | | `--language` | `-l` | `ru` | Язык (ru, en, auto и др.) | | `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу | -| `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda) | -| `--compute-type` | — | float16 (GPU) / float32 (CPU) | Тип вычислений | +| `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda, openvino) | +| `--compute-type` | — | float16 (CUDA) / int8 (OpenVINO) / float32 (CPU) | Тип вычислений | | `--force` | `-f` | — | Перезаписать существующие транскрипты | | `--verbose` | `-v` | — | Подробный вывод | @@ -116,6 +116,7 @@ transcribe *.mp4 --force | | Linux / WSL2 | macOS | Windows | |---|---|---|---| | CPU | ✅ | ✅ | ✅ | +| OpenVINO (x86 CPU) | ✅ авто | — | ✅ авто | | GPU (NVIDIA) | ✅ авто | — | ✅ (нужен CUDA 12) |
@@ -166,11 +167,11 @@ language = "en" Дефолты зависят от устройства: -| Параметр | GPU (CUDA) | CPU | -|----------|-----------|-----| -| model | medium | medium | -| compute_type | float16 | float32 | -| language | ru | ru | +| Параметр | CUDA | OpenVINO | CPU | +|----------|------|----------|-----| +| model | medium | medium | medium | +| compute_type | float16 | int8 | float32 | +| language | ru | ru | ru | ## Модели и GPU @@ -195,19 +196,23 @@ language = "en"
Типы квантизации (--compute-type) -| Тип | Устройство | VRAM/RAM | Качество | Когда использовать | -|-----|-----------|----------|----------|--------------------| -| `float16` | GPU | ~4.5-5 GB | Отлично | **По умолчанию для GPU** | -| `int8_float16` | GPU | ~4.7 GB | Отлично | GPU от 6 GB, альтернатива float16 | -| `int8` | GPU/CPU | Низкое | Хорошо, но бывают галлюцинации | GPU от 4 GB, CPU | +| Тип | Бэкенд | VRAM/RAM | Качество | Когда использовать | +|-----|--------|----------|----------|--------------------| +| `float16` | CUDA | ~4.5-5 GB | Отлично | **По умолчанию для CUDA** | +| `int8_float16` | CUDA | ~4.7 GB | Отлично | GPU от 6 GB, альтернатива float16 | +| `int8` | CUDA / OpenVINO | Низкое | Хорошо, но бывают галлюцинации | **По умолчанию для OpenVINO** | +| `fp16` | OpenVINO | Низкое | Отлично | OpenVINO large-v3 (выбирается автоматически) | | `float32` | CPU | Среднее | Отлично | **По умолчанию для CPU** | **Важно:** `int8` на длинных записях может давать галлюцинации (повтор фраз, потеря контента). -`float16` и `float32` значительно стабильнее на записях >20 минут. +`float16`/`fp16` и `float32` значительно стабильнее на записях >20 минут. + +> Для OpenVINO `--compute-type` выбирает предквантизированную модель (int8 или fp16), +> а не runtime-параметр. Для `large-v3` по умолчанию выбирается `fp16`.
-Подробнее: бенчмарки, совместимость GPU, результаты тестирования — [docs/gpu.md](docs/gpu.md). +Подробнее: бенчмарки, OpenVINO, совместимость GPU, результаты тестирования — [docs/gpu.md](docs/gpu.md).
Формат вывода diff --git a/docs/adr/003-pluggable-backends.md b/docs/adr/003-pluggable-backends.md new file mode 100644 index 0000000..ba812d4 --- /dev/null +++ b/docs/adr/003-pluggable-backends.md @@ -0,0 +1,96 @@ +# ADR-003: Pluggable backends и OpenVINO + +**Статус**: Принято +**Дата**: 2026-03-21 + +## Контекст + +На CPU (faster-whisper/CTranslate2) транскрипция работает медленно (~1.5x реалтайм для medium). +CUDA доступна на малом проценте машин (ноутбуки с NVIDIA GPU), на офисных ПК её нет. + +OpenVINO ускоряет inference на x86 CPU (Intel и AMD) в 2-4 раза. Для его поддержки +нужен второй движок транскрипции, а архитектура должна позволять добавлять новые +бэкенды (CoreML для Mac, AMD XDNA NPU) без переписывания существующего кода. + +## Решение + +### Backend Protocol (structural typing) + +Минимальный интерфейс в `backends/base.py`: + +```python +class Backend(Protocol): + def ensure_model_available(self, model_name, compute_type, on_status) -> str: ... + def create_model(self, model_path, device, compute_type) -> Any: ... + def transcribe(self, model, file_path, language, on_segment, on_status) -> TranscribeResult: ... +``` + +Protocol вместо ABC — бэкенды не наследуются, достаточно реализовать методы. +Соответствует стилю проекта (наследование нигде не используется). + +### Ленивые импорты + +Бэкенды импортируются только при выборе — `get_backend(device)` делает import внутри. +Импорт faster-whisper запускает CUDA bootstrap (~1ms), импорт openvino-genai загружает ~50MB +shared libraries. Ни то, ни другое не должно происходить, если бэкенд не выбран. + +### Device как селектор бэкенда + +Вместо отдельного `--backend` флага устройство само определяет бэкенд: +- `cuda`, `cpu` → FasterWhisperBackend +- `openvino` → OpenVINOBackend +- `auto` → CUDA (nvidia-smi) → OpenVINO (import check + x86) → CPU + +### load_model() — единственный владелец pipeline + +`load_model()` выполняет ensure_model_available + create_model в одном вызове. +CLI не вызывает ensure_model_available отдельно — это убирает двойной resolution +и гарантирует, что модель скачивается для правильного бэкенда. + +### Cross-backend fallback + +Fallback живёт в `transcriber.py` (оркестратор), не в бэкендах: +- CUDA ошибка → CPU (FasterWhisper) +- OpenVINO ошибка → CPU (FasterWhisper) +- `strict_device=True` (явный `--device`) → ошибка без fallback + +При fallback в батч-режиме обновляются model, backend, model_path и actual_device +через TranscribeFileResult — следующий файл использует правильный бэкенд. + +### Аудио для OpenVINO + +OpenVINO GenAI WhisperPipeline принимает raw PCM float массив, не путь к файлу. +Используем `faster_whisper.decode_audio()` (PyAV) → `.tolist()` → `pipe.generate()`. +Системный ffmpeg не требуется — PyAV бандлит FFmpeg внутри wheel. + +### compute_type для OpenVINO + +OpenVINO модели предквантизированы (int8/fp16), compute_type определяет какую модель +скачать. Контракт: +- Явный `--compute-type` или значение из конфига — уважается всегда +- Из дефолтов: для large-v3 автоматически выбирается fp16 (стабильнее по качеству) +- Несуществующая пара (model + compute_type) при явном выборе → ошибка + +### Обе зависимости по умолчанию + +faster-whisper (~37MB) и openvino-genai (~69MB) ставятся вместе — суммарно ~106MB, +приемлемо. Модели скачиваются только для активного бэкенда. CUDA (nvidia-cublas-cu12, +~554MB) остаётся conditional (Linux x86_64). OpenVINO — conditional (x86_64/AMD64, не macOS). + +## Последствия + +- Обратная совместимость: `transcribe()` сохранён; `load_model()` изменил сигнатуру (возвращает 4-tuple вместо 2-tuple, добавлен `compute_type_explicit`) +- Новый бэкенд добавляется одним файлом в `backends/` + регистрацией в `__init__.py` +- Модели скачиваются по запросу — CUDA пользователь не качает OpenVINO модели, и наоборот +- ARM и macOS: OpenVINO не ставится (platform markers), работает CPU через faster-whisper + +## Отклонённые альтернативы + +| Альтернатива | Почему отклонена | +|---|---| +| OpenVINO как optional extra (`pip install .[openvino]`) | Теряется zero-config UX; пользователь должен знать про extras | +| whisper.cpp (pywhispercpp) | Другой движок, больший объём интеграции; OpenVINO GenAI проще | +| Единый бэкенд с OpenVINO для всего | CTranslate2 лучше оптимизирован для CUDA; OpenVINO — для CPU | +| ABC вместо Protocol | Наследование не используется в проекте; Protocol проще | +| librosa для загрузки аудио в OpenVINO | Лишняя зависимость; для видеоконтейнеров ненадёжна без системного ffmpeg | +| `--backend` как отдельный флаг | Усложняет CLI; device уже однозначно определяет бэкенд | diff --git a/docs/gpu.md b/docs/gpu.md index c5a3018..bf35464 100644 --- a/docs/gpu.md +++ b/docs/gpu.md @@ -1,10 +1,46 @@ -# GPU и CUDA +# Ускорение транскрипции ## Режимы `--device` -- `auto` (по умолчанию) — выберет GPU если `nvidia-smi` доступен, иначе CPU -- `cuda` — строго GPU, ошибка если недоступен (без silent fallback) -- `cpu` — строго CPU +- `auto` (по умолчанию) — CUDA → OpenVINO → CPU (первый доступный) +- `cuda` — строго NVIDIA GPU, ошибка если недоступен +- `openvino` — OpenVINO на CPU (ускорение 2-4x на x86) +- `cpu` — строго CPU (faster-whisper/CTranslate2) + +## Какой бэкенд на каком оборудовании + +| Оборудование | Рекомендуемый `--device` | Бэкенд | Ожидаемая скорость | +|---|---|---|---| +| NVIDIA GPU (6+ GB VRAM) | `auto` / `cuda` | faster-whisper (CTranslate2) | 7-19x реалтайм | +| Intel/AMD x86 CPU | `auto` / `openvino` | OpenVINO GenAI | 3-6x реалтайм* | +| Любой CPU (fallback) | `cpu` | faster-whisper (CTranslate2) | ~1.5x реалтайм | +| Apple Silicon (macOS) | `cpu` | faster-whisper (CTranslate2) | ~2x реалтайм | + +\* Ожидаемая оценка на основе бенчмарков OpenVINO. Реальная скорость зависит от CPU и модели. + +## OpenVINO + +OpenVINO ускоряет inference на x86 процессорах (Intel и AMD) через оптимизированные инструкции +(AVX2, AVX-512, VNNI, AMX). Ставится автоматически на Linux и Windows (x86_64/AMD64). + +- **Модели**: предконвертированные из [HuggingFace](https://huggingface.co/OpenVINO) (int8/fp16) +- **Дефолт**: `medium` + `int8` (для `large-v3` автоматически выбирается `fp16`) +- **Аудиодекодирование**: через PyAV (бандлит FFmpeg), системный ffmpeg не нужен + +### Доступные OpenVINO модели + +| Модель | int8 | fp16 | +|--------|------|------| +| tiny | OpenVINO/whisper-tiny-int8-ov | — | +| base | — | OpenVINO/whisper-base-fp16-ov | +| small | OpenVINO/whisper-small-int8-ov | — | +| medium | OpenVINO/whisper-medium-int8-ov | — | +| large-v3 | OpenVINO/whisper-large-v3-int8-ov | OpenVINO/whisper-large-v3-fp16-ov | + +### Качество OpenVINO int8 + +OpenVINO использует NNCF (калиброванная post-training квантизация), отличается от runtime-квантизации +CTranslate2. Качество может быть другим — **тестирование на реальных сэмплах рекомендуется**. ## Настройка по платформам @@ -17,12 +53,10 @@ ### Windows -Нужен системный CUDA toolkit: +Нужен системный **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13): ```bash -choco install cuda -# или -winget install -e --id Nvidia.CUDA # требует запуска от имени администратора +winget install -e --id Nvidia.CUDA --version 12.9 # требует запуска от имени администратора ``` После установки перезапустите терминал. @@ -77,11 +111,9 @@ SQL, PostgreSQL, Greenplum, Airflow, ClickHouse, Docker, CDR, GTP, MAP). ### Windows: ошибка при загрузке модели на GPU -GPU на Windows требует CUDA toolkit (включает cuBLAS). Установите: +GPU на Windows требует **CUDA 12** (ctranslate2 4.7 не совместим с CUDA 11 и 13). Установите: ```bash -choco install cuda -# или -winget install -e --id Nvidia.CUDA +winget install -e --id Nvidia.CUDA --version 12.9 # требует запуска от имени администратора ``` После установки перезапустите терминал.