docs(readme): редизайн README и удаление зависимости от ffmpeg

- Зачем:
  - README перегружен деталями GPU/бенчмарков, нет Quick Start, macOS/Windows — второй класс.
  - системный ffmpeg не нужен — PyAV (зависимость faster-whisper) включает FFmpeg в wheels.
- Что:
  - переписан README: Quick Start в первых строках, установка без клонирования через uv tool install, паритет платформ, progressive disclosure через <details>.
  - удалена функция check_ffmpeg() из utils.py, убраны импорт и вызовы из cli.py.
  - убраны моки check_ffmpeg и тест ffmpeg-ошибки из test_cli.py.
  - GPU-контент вынесен в docs/gpu.md, добавлен CONTRIBUTING.md.
- Проверка:
  - uv run pytest — 97 passed, 1 skipped.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-18 23:07:39 +03:00
co-authored by Claude Opus 4.6
parent b7e6ab634a
commit 87f7dc1723
6 changed files with 265 additions and 185 deletions
+90
View File
@@ -0,0 +1,90 @@
# GPU и CUDA
## Режимы `--device`
- `auto` (по умолчанию) — выберет GPU если `nvidia-smi` доступен, иначе CPU
- `cuda` — строго GPU, ошибка если недоступен (без silent fallback)
- `cpu` — строго CPU
## Настройка по платформам
### Linux / WSL2 (x86_64)
Библиотека cuBLAS ставится автоматически (зависимость `nvidia-cublas-cu12` подтягивается при установке).
Дополнительных шагов не требуется.
> На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit.
### Windows
Нужен системный CUDA toolkit:
```bash
choco install cuda
# или
winget install -e --id Nvidia.CUDA # требует запуска от имени администратора
```
После установки перезапустите терминал.
## Совместимость GPU
| GPU | VRAM | medium float16 | large-v3 float16 | Рекомендация |
|-----|------|---------------|-----------------|--------------|
| RTX 3060 | 6 GB | ✅ | ✅ | medium float16 (дефолт) |
| RTX 4050 | 6 GB | ✅ | ✅ | medium float16 |
| Quadro M3000M | 4 GB | ✅ | ⚠️ tight | medium float16 или int8 |
## Ожидаемая скорость
Замеры на RTX 3060 Laptop (6 GB) и Intel CPU (WSL2):
| Конфигурация | 16 мин файл | 42 мин файл | Отн. скорость |
|-------------|-------------|-------------|---------------|
| GPU + medium float16 | ~35с | ~133с | ~19x реалтайм |
| GPU + large-v3 float16 | ~90с | ~350с | ~7x реалтайм |
| CPU + medium float32 | 613с (10 мин) | ~26 мин* | ~1.5x реалтайм |
| CPU + large-v3 int8 | 839с (14 мин) | ~37 мин* | ~1:1 реалтайм |
*Оценка на основе пропорции.
## Результаты тестирования качества
Тесты проведены на реальных записях рабочих созвонов (русский язык, технические термины:
SQL, PostgreSQL, Greenplum, Airflow, ClickHouse, Docker, CDR, GTP, MAP).
| Конфигурация | Качество (длинная запись, 42 мин) | Проблемы |
|---|---|---|
| large-v3 int8 GPU | Плохо | Галлюцинации (фразы ×25), потеря контента |
| large-v3 float16 GPU | Отлично | — |
| medium float16 GPU | Хорошо | Редкие мелкие ляпы в терминах |
| medium float32 CPU | Хорошо | Сопоставимо с large-v3 int8, без галлюцинаций |
| large-v3 int8 CPU | Хорошо | Без галлюцинаций (на коротких файлах) |
### Ключевые выводы
1. **Указание языка (`--language ru`) критично** — auto-detect может ошибиться и выдать мусор
2. **float16/float32 стабильнее int8** — особенно на записях >20 минут
3. **medium + float16 на GPU — лучший баланс** скорости и качества для повседневного использования
4. **large-v3 + float16 на GPU** — для максимального качества важных записей
## Troubleshooting
### CUDA не обнаружен
Убедитесь, что `nvidia-smi` возвращает информацию о GPU. Драйвер NVIDIA предоставляет `libcuda.so.1`,
без которого CUDA не работает — его нельзя поставить через pip.
### Windows: ошибка при загрузке модели на GPU
GPU на Windows требует CUDA toolkit (включает cuBLAS). Установите:
```bash
choco install cuda
# или
winget install -e --id Nvidia.CUDA
```
После установки перезапустите терминал.
### ARM (aarch64)
cuBLAS через pip недоступен на ARM — нужен системный CUDA toolkit.