feat(config): добавлены device-aware дефолты и результаты тестов

- Зачем:
  - тестирование на реальных записях показало, что int8 даёт галлюцинации на длинных файлах, auto-detect языка ошибается — нужны оптимальные дефолты по устройству.
- Что:
  - дефолты: medium float16 (GPU), medium float32 (CPU), language=ru.
  - добавлены DEVICE_DEFAULTS и apply_device_defaults() в config.py.
  - убран preprocessor_config.json из обязательных файлов модели (отсутствует у medium).
  - README обновлён: таблицы скоростей, качества, результаты тестирования compute_type.
- Проверка:
  - uv run pytest — 98 passed, 1 skipped.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-18 21:43:06 +03:00
co-authored by Claude Opus 4.6
parent e28232ef50
commit b7e6ab634a
6 changed files with 163 additions and 70 deletions
+62 -29
View File
@@ -33,7 +33,7 @@ uv tool install .
uv tool install --force .
```
Модели скачиваются автоматически при первом запуске (~3 GB для large-v3),
Модели скачиваются автоматически при первом запуске (~1.5 GB для medium, ~3 GB для large-v3),
нужен доступ в интернет (Hugging Face Hub).
> **Если `transcribe: command not found`** — убедитесь, что директория
@@ -43,14 +43,14 @@ uv tool install --force .
## Использование
```bash
# Простой запуск (large-v3, автодетект языка и устройства)
# Простой запуск (medium, русский, автодетект устройства)
transcribe meeting.mp4
# Указать язык
transcribe lecture.mp3 --language ru
transcribe lecture.mp3 --language en
# Быстрая модель на CPU
transcribe podcast.wav --model small --device cpu
# Максимальное качество на GPU
transcribe podcast.wav --model large-v3 --compute-type float16
# Сохранить в конкретный файл
transcribe interview.m4a --output result.md
@@ -82,27 +82,34 @@ transcribe *.mp4 --force
Дефолтные параметры можно задать в `.transcriber.toml`:
```toml
model = "small"
language = "ru"
device = "cpu"
compute_type = "int8"
model = "large-v3"
compute_type = "float16"
```
Порядок поиска:
1. `.transcriber.toml` в текущей директории (проектный конфиг)
2. `~/.config/transcriber/config.toml` (глобальный конфиг пользователя)
Приоритет: **CLI-аргумент > конфиг > встроенный дефолт**.
Приоритет: **CLI-аргумент > конфиг > device-aware дефолт > встроенный дефолт**.
Дефолты зависят от устройства (если не заданы явно):
| Параметр | GPU (CUDA) | CPU |
|----------|-----------|-----|
| model | medium | medium |
| compute_type | float16 | float32 |
| language | ru | ru |
### Опции CLI
| Опция | Сокращение | По умолчанию | Описание |
|-------|-----------|-------------|----------|
| `--model` | `-m` | `large-v3` | Модель Whisper |
| `--language` | `-l` | `auto` | Язык (ru, en, auto) |
| `--model` | `-m` | `medium` | Модель Whisper |
| `--language` | `-l` | `ru` | Язык (ru, en, auto и др.) |
| `--output` | `-o` | `<файл>-transcript.md` | Путь к выходному файлу |
| `--device` | `-d` | `auto` | Устройство (auto, cpu, cuda) |
| `--compute-type` | — | `int8` | Тип вычислений |
| `--compute-type` | — | float16 (GPU) / float32 (CPU) | Тип вычислений |
| `--force` | `-f` | — | Перезаписать существующие транскрипты |
| `--verbose` | `-v` | — | Подробный вывод |
@@ -118,14 +125,15 @@ compute_type = "int8"
### Типы квантизации (`--compute-type`)
| Тип | VRAM | Скорость | Качество | Когда использовать |
|-----|------|----------|----------|--------------------|
| `int8` | Низкое | Быстро | Почти без потерь | По умолчанию, GPU от 4 GB и CPU |
| `int8_float16` | Низкое | Быстро | Почти без потерь | GPU, чуть точнее int8 |
| `float16` | Среднее | Быстро | Без потерь | GPU от 6 GB |
| `float32` | Высокое | Медленно | Эталон | CPU (если int8 недоступен) |
| Тип | Устройство | 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 |
| `float32` | CPU | Среднее | Отлично | **По умолчанию для CPU** |
По умолчанию `int8` — универсален для GPU от 4 GB и CPU.
**Важно:** `int8` на длинных записях может давать галлюцинации (повтор фраз, потеря контента).
`float16` и `float32` значительно стабильнее на записях >20 минут с техническими терминами.
## Установка ffmpeg
@@ -156,19 +164,44 @@ compute_type = "int8"
### Совместимость GPU
| GPU | VRAM | large-v3 int8 | Рекомендация |
|-----|------|--------------|--------------|
| RTX 3060 | 6 GB | ✅ | int8 |
| RTX 4050 | 6 GB | ✅ | int8 |
| Quadro M3000M | 4 GB | ✅ | int8 обязательно |
| 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 |
### Ожидаемая скорость
| Конфигурация | 1 час аудио ≈ |
|-------------|---------------|
| RTX 3060 + large-v3 | 46 мин |
| CPU + large-v3 | 60120 мин |
| CPU + small | 1220 мин |
Замеры на 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** — для максимального качества важных записей
## Формат выходного файла