ddadminandClaude Opus 4.6
b7e6ab634a
- Зачем: - тестирование на реальных записях показало, что 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>
11 KiB
local-transcriber
Локальный CLI для транскрипции аудио и видео через faster-whisper. Принимает файл, распознаёт речь на машине (без внешних API) и создаёт markdown с таймкодами. Результат удобен для последующей обработки ИИ — суммаризация, action items и т.д. Работает с GPU (NVIDIA CUDA, быстро) и CPU (медленнее).
transcribe meeting.mp4
# → meeting-transcript.md
Требования
- Python ≥ 3.10
- uv — менеджер пакетов
- ffmpeg в PATH
- (Опционально) NVIDIA GPU + установленный драйвер (проверка:
nvidia-smi)
Установка
git clone <repo>
cd local-transcriber
uv tool install .
После этого команда transcribe доступна глобально в PATH.
Обновление после git pull:
uv tool install --force .
Модели скачиваются автоматически при первом запуске (~1.5 GB для medium, ~3 GB для large-v3), нужен доступ в интернет (Hugging Face Hub).
Если
transcribe: command not found— убедитесь, что директория инструментов uv добавлена в PATH. Выполнитеuv tool dir --binчтобы узнать путь, и добавьте его в PATH вашего shell.
Использование
# Простой запуск (medium, русский, автодетект устройства)
transcribe meeting.mp4
# Указать язык
transcribe lecture.mp3 --language en
# Максимальное качество на GPU
transcribe podcast.wav --model large-v3 --compute-type float16
# Сохранить в конкретный файл
transcribe interview.m4a --output result.md
Батч-режим
Обработка нескольких файлов за один вызов — модель загружается один раз:
# Все mp4 в директории
transcribe ./recordings/*.mp4
# Несколько файлов
transcribe meeting1.mp3 meeting2.mp3
# Перезаписать существующие транскрипты
transcribe *.mp4 --force
- Файлы с существующим транскриптом (
*-transcript.md) автоматически пропускаются --force/-f— перезаписать существующие транскрипты- В конце выводится итоговая статистика: обработано, пропущено, ошибок
- При ошибке в одном файле остальные продолжают обрабатываться
--outputнесовместим с несколькими файлами
Конфигурационный файл
Дефолтные параметры можно задать в .transcriber.toml:
language = "ru"
model = "large-v3"
compute_type = "float16"
Порядок поиска:
.transcriber.tomlв текущей директории (проектный конфиг)~/.config/transcriber/config.toml(глобальный конфиг пользователя)
Приоритет: CLI-аргумент > конфиг > device-aware дефолт > встроенный дефолт.
Дефолты зависят от устройства (если не заданы явно):
| Параметр | GPU (CUDA) | CPU |
|---|---|---|
| model | medium | medium |
| compute_type | float16 | float32 |
| language | ru | ru |
Опции CLI
| Опция | Сокращение | По умолчанию | Описание |
|---|---|---|---|
--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) | Тип вычислений |
--force |
-f |
— | Перезаписать существующие транскрипты |
--verbose |
-v |
— | Подробный вывод |
Модели
| Модель | Размер на диске | 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 | ★ | ★★★★★ |
Типы квантизации (--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 |
float32 |
CPU | Среднее | Отлично | По умолчанию для CPU |
Важно: int8 на длинных записях может давать галлюцинации (повтор фраз, потеря контента).
float16 и float32 значительно стабильнее на записях >20 минут с техническими терминами.
Установка ffmpeg
- Linux / WSL2:
sudo apt install ffmpeg - macOS:
brew install ffmpeg - Windows:
winget install ffmpeg
GPU и CUDA
Для работы с GPU необходим установленный NVIDIA драйвер
(проверка: nvidia-smi в терминале). Драйвер предоставляет libcuda.so.1,
без которого CUDA не работает — его нельзя поставить через pip.
По платформам
- Linux / WSL2 (x86_64): библиотека cuBLAS ставится автоматически
(зависимость
nvidia-cublas-cu12подтягивается при установке). Дополнительных шагов не требуется. На ARM (aarch64) cuBLAS через pip недоступен — нужен системный CUDA toolkit. - Windows: нужен системный CUDA toolkit
(
choco install cudaилиwinget install -e --id Nvidia.CUDA)
Режимы --device
auto(по умолчанию) — выберет GPU еслиnvidia-smiдоступен, иначе CPUcuda— строго GPU, ошибка если недоступен (без silent fallback)cpu— строго CPU
Совместимость 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 | Хорошо | Без галлюцинаций (на коротких файлах) |
Ключевые выводы:
- Указание языка (
--language ru) критично — auto-detect может ошибиться и выдать мусор - float16/float32 стабильнее int8 — особенно на записях >20 минут
- medium + float16 на GPU — лучший баланс скорости и качества для повседневного использования
- large-v3 + float16 на GPU — для максимального качества важных записей
Формат выходного файла
# Транскрипт: 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] Добрый день, коллеги. Сегодня мы обсудим результаты
квартала. Первый вопрос — по метрикам продукта. Как вы видите на слайде, MAU вырос
на двадцать три процента по сравнению с предыдущим кварталом.
[00:00:18.10 - 00:00:25.73] Теперь перейдём к финансовым показателям.
...
Близкие по времени сегменты автоматически объединяются в абзацы (пауза > 2 сек или длительность > 60 сек разделяет абзацы).
Таймкоды: MM:SS.ss, для записей длиннее 1 часа — HH:MM:SS.ss.
Поддерживаемые форматы
- Аудио: mp3, wav, flac, ogg, m4a, wma, aac
- Видео: mp4, mkv, avi, mov, webm, ts
Формат определяется по расширению, декодирование выполняет ffmpeg.