> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-ru/audio-i-golos/whisperx.md).

# WhisperX с диаризацией

WhisperX расширяет Whisper от OpenAI тремя важными улучшениями: **временные метки на уровне слов** через принудительное фонемное выравнивание, **диаризация говорящих** с использованием pyannote.audio, и **скорость до 70× в реальном времени** за счёт пакетного вывода с faster-whisper. Это основной инструмент для производственных пайплайнов транскрибации, которым нужны точное время и определение говорящих.

**GitHub:** [m-bain/whisperX](https://github.com/m-bain/whisperX) **PyPI:** [whisperx](https://pypi.org/project/whisperx/) **Лицензия:** BSD-4-Clause **Статья:** [arxiv.org/abs/2303.00747](https://arxiv.org/abs/2303.00747)

## Ключевые особенности

* **Временные метки на уровне слов** — точность ±50 мс благодаря принудительному выравниванию wav2vec2 (против ±500 мс в обычном Whisper)
* **Диаризация говорящих** — определение, кто что сказал, с помощью pyannote.audio 3.1
* **Пакетный вывод** — скорость до 70× в реальном времени на RTX 4090
* **Предфильтрация VAD** — Silero VAD удаляет тишину перед транскрибацией
* **Все модели Whisper** — от tiny до large-v3-turbo
* **Несколько форматов вывода** — JSON, SRT, VTT, TXT, TSV
* **Автоматическое определение языка** — или принудительно задайте конкретный язык для более быстрой обработки

## Требования

| Компонент | Минимум                 | Рекомендуется           |
| --------- | ----------------------- | ----------------------- |
| GPU       | RTX 3060 12 ГБ          | RTX 4090 24 GB          |
| VRAM      | 4 ГБ (маленькая модель) | 10 ГБ+ (large-v3-turbo) |
| ОЗУ       | 8 ГБ                    | 16 ГБ+                  |
| Диск      | 5 ГБ                    | 20 ГБ (кэш модели)      |
| Python    | 3.9+                    | 3.11                    |
| CUDA      | 12.8+                   | 12.8+                   |

**Требуется токен HuggingFace** для диаризации говорящих — примите лицензию на [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1).

**Рекомендация Clore.ai:** RTX 3090 ($0.07–0.21/час) для модели large-v3-turbo с размером пакета 16. RTX 4090 ($0.14–0.42/час) для максимальной пропускной способности при размере пакета 32.

## Установка

```bash
# Установка WhisperX
pip install whisperx

# Проверить GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

Если возникнут конфликты версий CUDA:

```bash
pip install torch==2.5.1+cu124 torchaudio==2.5.1+cu124 --index-url https://download.pytorch.org/whl/cu128
pip install whisperx
```

## Быстрый старт

```python
import whisperx
import json

device = "cuda"
compute_type = "float16"  # "int8" для меньшего расхода VRAM
batch_size = 16            # уменьшите до 4–8, если VRAM в дефиците

# 1. Загрузить модель
model = whisperx.load_model("large-v3-turbo", device, compute_type=compute_type)

# 2. Загрузить и транскрибировать аудио
audio = whisperx.load_audio("interview.mp3")
result = model.transcribe(audio, batch_size=batch_size)
print(f"Language: {result['language']}")

# 3. Выполнить выравнивание для временных меток на уровне слов
model_a, metadata = whisperx.load_align_model(
    language_code=result["language"], device=device
)
result = whisperx.align(
    result["segments"], model_a, metadata, audio, device,
    return_char_alignments=False,
)

# 4. Вывести результаты
for seg in result["segments"]:
    print(f"[{seg['start']:.2f}s → {seg['end']:.2f}s] {seg['text']}")
    for w in seg.get("words", []):
        print(f"  '{w['word']}' @ {w.get('start', 0):.2f}s")

# 5. Сохранение
with open("transcript.json", "w") as f:
    json.dump(result, f, indent=2, ensure_ascii=False)
```

## Примеры использования

### Транскрибация с диаризацией говорящих

```python
import whisperx
import gc
import torch

device = "cuda"
HF_TOKEN = "hf_your_token_here"  # из huggingface.co/settings/tokens

# Шаг 1: Транскрибировать
model = whisperx.load_model("large-v3-turbo", device, compute_type="float16")
audio = whisperx.load_audio("meeting.mp3")
result = model.transcribe(audio, batch_size=16)

# Освободить память GPU перед загрузкой модели выравнивания
del model; gc.collect(); torch.cuda.empty_cache()

# Шаг 2: Выполнить выравнивание
model_a, metadata = whisperx.load_align_model(
    language_code=result["language"], device=device
)
result = whisperx.align(result["segments"], model_a, metadata, audio, device)
del model_a; gc.collect(); torch.cuda.empty_cache()

# Шаг 3: Выполнить диаризацию
diarize_model = whisperx.DiarizationPipeline(
    use_auth_token=HF_TOKEN, device=device
)
diarize_segments = diarize_model(audio, min_speakers=2, max_speakers=6)

# Шаг 4: Назначить говорящих словам
result = whisperx.assign_word_speakers(diarize_segments, result)

for seg in result["segments"]:
    speaker = seg.get("speaker", "UNKNOWN")
    print(f"[{speaker}] [{seg['start']:.1f}s → {seg['end']:.1f}s] {seg['text']}")
```

### Использование из командной строки

```bash
# Базовая транскрибация
whisperx audio.mp3 --model large-v3-turbo --device cuda

# Принудительно задать язык (быстрее, пропускает определение)
whisperx audio.mp3 --model large-v3-turbo --language en --device cuda

# С диаризацией говорящих
whisperx audio.mp3 --model large-v3-turbo --diarize --hf_token hf_your_token

# Вывод субтитров SRT
whisperx audio.mp3 --model large-v3-turbo --output_format srt --output_dir ./subs/

# Режим с низким расходом VRAM
whisperx audio.mp3 --model medium --compute_type int8 --batch_size 4 --device cuda

# Пакетная обработка каталога
for f in /data/audio/*.mp3; do
  whisperx "$f" --model large-v3-turbo --output_dir /data/transcripts/
done
```

### Скрипт генерации SRT

```python
import whisperx

def transcribe_to_srt(audio_path, output_path, model_name="large-v3-turbo"):
    device = "cuda"
    model = whisperx.load_model(model_name, device, compute_type="float16")
    audio = whisperx.load_audio(audio_path)
    result = model.transcribe(audio, batch_size=16)

    model_a, metadata = whisperx.load_align_model(
        language_code=result["language"], device=device
    )
    result = whisperx.align(result["segments"], model_a, metadata, audio, device)

    with open(output_path, "w") as f:
        for i, seg in enumerate(result["segments"], 1):
            start = format_ts(seg["start"])
            end = format_ts(seg["end"])
            f.write(f"{i}\n{start} --> {end}\n{seg['text'].strip()}\n\n")

    print(f"SRT сохранён в {output_path}")

def format_ts(seconds):
    h = int(seconds // 3600)
    m = int((seconds % 3600) // 60)
    s = int(seconds % 60)
    ms = int((seconds % 1) * 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

transcribe_to_srt("podcast.mp3", "podcast.srt")
```

## Тесты производительности

| Метод           | Модель             | 1 ч аудио    | GPU          | Примерная скорость |
| --------------- | ------------------ | ------------ | ------------ | ------------------ |
| Обычный Whisper | large-v3           | \~60 мин     | RTX 3090     | 1×                 |
| faster-whisper  | large-v3           | \~5 мин      | RTX 3090     | \~12×              |
| **WhisperX**    | **large-v3-turbo** | **\~1 мин**  | **RTX 3090** | **\~60×**          |
| **WhisperX**    | **large-v3-turbo** | **\~50 сек** | **RTX 4090** | **\~70×**          |

| Размер батча | Скорость (RTX 4090)      | VRAM  |
| ------------ | ------------------------ | ----- |
| 4            | \~30× в реальном времени | 6 ГБ  |
| 8            | \~45× в реальном времени | 8 ГБ  |
| 16           | \~60× в реальном времени | 10 ГБ |
| 32           | \~70× в реальном времени | 14 ГБ |

## Советы для пользователей Clore.ai

* **Освобождайте VRAM между шагами** — удаляйте модели и вызывайте `torch.cuda.empty_cache()` между транскрибацией, выравниванием и диаризацией
* **Токен HuggingFace** — перед тем как диаризация заработает, нужно принять лицензию pyannote; установите `HF_TOKEN` как переменную окружения
* **Настройка размера пакета** — начните с `batch_size=16`, уменьшите до 4–8 на картах с 12 ГБ, увеличьте до 32 на картах с 24 ГБ
* **`int8` вычисления** — используйте `compute_type="int8"` чтобы вдвое сократить использование VRAM с минимальной потерей качества
* **Docker-образ** — `pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime`
* **Постоянный кэш модели** — подключите `/root/.cache/huggingface` чтобы не загружать модели заново при каждом перезапуске контейнера

## Устранение неполадок

| Проблема                         | Решение                                                                                                               |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory`             | Уменьшите `batch_size`, используйте `compute_type="int8"`, или используйте меньшую модель (medium, small)             |
| Диаризация возвращает `UNKNOWN`  | Убедитесь, что токен HuggingFace действителен и вы приняли лицензию pyannote                                          |
| `Нет модуля с именем 'whisperx'` | `pip install whisperx` — убедитесь, что нет опечатки (это `whisperx`, а не `whisper-x`)                               |
| Плохие временные метки слов      | Проверьте, что `whisperx.align()` вызывается после `transcribe()` — сырой вывод Whisper не содержит точных меток слов |
| Неверное определение языка       | Принудительно задайте язык с помощью `--language en` или `language="en"` в Python API                                 |
| Медленная обработка              | Увеличьте `batch_size`, используйте `large-v3-turbo` вместо `large-v3`, убедитесь, что GPU не используется совместно  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/audio-i-golos/whisperx.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.