390 lines
16 KiB
Markdown
390 lines
16 KiB
Markdown
# Плагин Transcriber — транскрибация аудио в текст
|
||
|
||
## Обзор
|
||
|
||
VidConf использует **Strategy pattern** для подключаемых реализаций транскрибации речи. Это позволяет менять провайдеров (faster-whisper на CPU, OpenAI Whisper, Vosk и т.д.) через конфигурацию без изменения ядра.
|
||
|
||
## Контракт Transcriber
|
||
|
||
### Интерфейс
|
||
|
||
Все реализации наследуют абстрактный класс `Transcriber` из `backend/core/plugins/transcriber.py`:
|
||
|
||
```python
|
||
from abc import ABC, abstractmethod
|
||
from dataclasses import dataclass
|
||
from typing import ClassVar
|
||
|
||
@dataclass(frozen=True, slots=True)
|
||
class Segment:
|
||
"""Один транскрибированный сегмент трека."""
|
||
start: float # Начало в секундах от старта файла
|
||
end: float # Конец в секундах от старта файла
|
||
text: str # Распознанный текст
|
||
|
||
class Transcriber(ABC):
|
||
"""Интерфейс Strategy для реализаций преобразования речи в текст."""
|
||
|
||
provider: ClassVar[str] # Уникальный идентификатор провайдера
|
||
|
||
@abstractmethod
|
||
def transcribe(self, audio_path: str, language: str = "ru") -> list[Segment]:
|
||
"""Транскрибировать аудиофайл в список сегментов."""
|
||
...
|
||
```
|
||
|
||
### Сигнатура метода transcribe
|
||
|
||
| Параметр | Тип | Описание |
|
||
|----------|-----|---------|
|
||
| `audio_path` | `str` | Абсолютный путь к аудиофайлу на диске |
|
||
| `language` | `str` | Код языка (ISO 639-1), дефолт `"ru"` |
|
||
| **Возврат** | `list[Segment]` | Упорядоченный список сегментов, отсортированный по `start` |
|
||
|
||
**Требования:**
|
||
- Если файл не найден → исключение `FileNotFoundError`
|
||
- Сегменты должны быть отсортированы по `start` в возрастающем порядке
|
||
- Дублирующиеся/перекрывающиеся сегменты допустимы (алгоритм фраз их обработает)
|
||
|
||
## Реализация по умолчанию: FasterWhisperCPU
|
||
|
||
### Описание
|
||
|
||
`FasterWhisperCPU` — оптимизированная реализация faster-whisper (CTranslate2-бэкэнд) для транскрибации на CPU с int8-квантизацией. Она встроена в проект как реализация по умолчанию.
|
||
|
||
**Файл:** `backend/core/plugins/faster_whisper.py`
|
||
|
||
### Параметры конструктора
|
||
|
||
```python
|
||
@register_transcriber
|
||
class FasterWhisperCPU(Transcriber):
|
||
provider: ClassVar[str] = "faster_whisper_cpu"
|
||
|
||
def __init__(
|
||
self,
|
||
model: str | None = None,
|
||
language: str = "ru",
|
||
download_root: str | None = None,
|
||
) -> None:
|
||
"""Инициализировать транскрибер.
|
||
|
||
Args:
|
||
model: Имя модели Whisper (small/base/medium/etc);
|
||
дефолт 'small' (оптимум для CPU).
|
||
language: Код языка (ISO 639-1), дефолт 'ru'.
|
||
download_root: Папка для кэша загруженных моделей;
|
||
дефолт ~/.cache/huggingface/hub.
|
||
"""
|
||
```
|
||
|
||
| Параметр | Тип | Дефолт | Описание |
|
||
|----------|-----|--------|---------|
|
||
| `model` | `str` | `"small"` | Модель Whisper: `tiny`, `base`, `small`, `medium`, `large` |
|
||
| `language` | `str` | `"ru"` | Язык распознавания (ISO 639-1) |
|
||
| `download_root` | `str` | `~/.cache/` | Папка для кэша моделей |
|
||
|
||
### Особенности
|
||
|
||
#### VAD (Voice Activity Detection)
|
||
|
||
FasterWhisperCPU включает встроенный **Silero VAD** для автоматического разбиения аудио на речевые сегменты и подавления молчания. Это улучшает качество транскрибации и снижает галлюцинации Whisper на тишине/шуме.
|
||
|
||
- **Параметр:** `vad_filter=True`
|
||
- **Порог молчания:** `vad_min_silence_duration_ms=500` (0.5 сек)
|
||
|
||
#### Отбрасывание коротких сегментов
|
||
|
||
Whisper часто халлюцинирует на очень коротких сегментах (шум, клики, тишина). FasterWhisperCPU автоматически отбрасывает сегменты, короче **0.3 секунды**:
|
||
|
||
```python
|
||
MIN_SEGMENT_DURATION_S = 0.3
|
||
|
||
# Фильтрация в transcribe()
|
||
return [
|
||
Segment(start=segment.start, end=segment.end, text=segment.text)
|
||
for segment in raw_segments
|
||
if (segment.end - segment.start) >= MIN_SEGMENT_DURATION_S
|
||
]
|
||
```
|
||
|
||
#### Ленивый импорт
|
||
|
||
Зависимость `faster-whisper` импортируется лениво — только при первом вызове `transcribe()`. Это позволяет API-процессу, который не использует транскрибацию, избежать загрузки тяжёлой библиотеки в память.
|
||
|
||
```python
|
||
def _get_model(self) -> "WhisperModel":
|
||
if FasterWhisperCPU._model is None:
|
||
from faster_whisper import WhisperModel # Импорт здесь, не в начале файла
|
||
FasterWhisperCPU._model = WhisperModel(...)
|
||
return FasterWhisperCPU._model
|
||
```
|
||
|
||
#### Синглтон модели на процесс
|
||
|
||
Модель Whisper создаётся один раз при первом вызове `transcribe()` и переиспользуется всеми последующими вызовами в пределах одного процесса воркера. Это снижает нагрузку на память и CPU (загрузка модели — дорогая операция).
|
||
|
||
> **Примечание:** Celery-воркер транскрибации запускается с флагом `--pool=solo --concurrency=1`, поэтому гонок за синглтоном не бывает.
|
||
|
||
### Конфигурация
|
||
|
||
В `config/plugins.yaml`:
|
||
|
||
```yaml
|
||
transcriber:
|
||
enabled: true
|
||
provider: "faster_whisper_cpu"
|
||
model: "small"
|
||
language: "ru"
|
||
options:
|
||
download_root: "/models/whisper"
|
||
```
|
||
|
||
Переменные окружения (если нужны):
|
||
|
||
```bash
|
||
# Опционально: переопределить папку кэша моделей
|
||
export HF_HOME=/models
|
||
```
|
||
|
||
### Производительность
|
||
|
||
- **Модель small:** ~8 минут аудио за 1 минуту на современном CPU (зависит от CPU)
|
||
- **Память:** ~1.5 ГБ на процесс (с моделью и бэкэндом)
|
||
- **Формат входа:** WAV, MP3, OGG, FLAC, M4A и др. (поддерживает ffmpeg-compatible форматы)
|
||
|
||
## Добавление нового Transcriber
|
||
|
||
### Пошаговая инструкция
|
||
|
||
#### Шаг 1: Создать файл реализации
|
||
|
||
Создайте новый файл в `backend/core/plugins/`, например `my_transcriber.py`:
|
||
|
||
```python
|
||
"""Плагин Transcriber на основе MyService."""
|
||
|
||
from typing import ClassVar
|
||
from core.plugins.factory import register_transcriber
|
||
from core.plugins.transcriber import Segment, Transcriber
|
||
|
||
@register_transcriber
|
||
class MyTranscriber(Transcriber):
|
||
"""Транскрибер, использующий MyService API."""
|
||
|
||
provider: ClassVar[str] = "my_service"
|
||
|
||
def __init__(
|
||
self,
|
||
model: str | None = None,
|
||
language: str = "ru",
|
||
api_key: str | None = None,
|
||
**options,
|
||
) -> None:
|
||
"""Инициализировать транскрибер.
|
||
|
||
Args:
|
||
model: Имя модели (опционально).
|
||
language: Язык распознавания.
|
||
api_key: API-ключ для сервиса.
|
||
**options: Дополнительные параметры из config/plugins.yaml.
|
||
"""
|
||
self.model = model or "default-model"
|
||
self.language = language
|
||
self.api_key = api_key or os.getenv("MY_SERVICE_API_KEY")
|
||
self.options = options
|
||
|
||
def transcribe(self, audio_path: str, language: str = "ru") -> list[Segment]:
|
||
"""Транскрибировать аудиофайл через MyService API.
|
||
|
||
Args:
|
||
audio_path: Путь к аудиофайлу на диске.
|
||
language: Язык распознавания (может переопределить конструктор).
|
||
|
||
Returns:
|
||
Упорядоченный список сегментов, отсортированный по start.
|
||
"""
|
||
# 1. Прочитать аудиофайл
|
||
with open(audio_path, "rb") as f:
|
||
audio_data = f.read()
|
||
|
||
# 2. Отправить на API (пример)
|
||
response = requests.post(
|
||
"https://api.myservice.com/transcribe",
|
||
files={"audio": audio_data},
|
||
json={"language": language, "model": self.model},
|
||
headers={"Authorization": f"Bearer {self.api_key}"},
|
||
)
|
||
response.raise_for_status()
|
||
|
||
# 3. Распарсить ответ в list[Segment]
|
||
result = response.json()
|
||
segments = [
|
||
Segment(
|
||
start=float(item["start"]),
|
||
end=float(item["end"]),
|
||
text=item["text"],
|
||
)
|
||
for item in result.get("segments", [])
|
||
]
|
||
|
||
# 4. Отсортировать по start (важно!)
|
||
segments.sort(key=lambda s: s.start)
|
||
|
||
return segments
|
||
```
|
||
|
||
**Важные правила:**
|
||
- Класс **должен** наследовать `Transcriber`
|
||
- Класс **должен** иметь декоратор `@register_transcriber` (регистрирует в реестре)
|
||
- Класс-переменная `provider: ClassVar[str]` **должна быть** уникальным идентификатором
|
||
- Конструктор **должен** принимать `model`, `language` и `**options`
|
||
- Метод `transcribe()` **должен** возвращать сегменты, отсортированные по `start`
|
||
|
||
#### Шаг 2: Импортировать в `__init__.py`
|
||
|
||
Добавьте импорт в `backend/core/plugins/__init__.py`:
|
||
|
||
```python
|
||
"""Пакет плагинов Transcriber/Summarizer."""
|
||
|
||
from core.plugins import faster_whisper as faster_whisper # noqa: F401
|
||
from core.plugins import my_transcriber as my_transcriber # noqa: F401 # ДОБАВИТЬ
|
||
from core.plugins import null as null # noqa: F401
|
||
```
|
||
|
||
> **Примечание:** `noqa: F401` подавляет предупреждение о неиспользуемом импорте — он нужен для побочного эффекта (регистрация). Используйте `as` для явности.
|
||
|
||
#### Шаг 3: Обновить конфигурацию
|
||
|
||
Отредактируйте `config/plugins.yaml`:
|
||
|
||
```yaml
|
||
transcriber:
|
||
enabled: true
|
||
provider: "my_service" # Совпадает с MyTranscriber.provider
|
||
model: "default-model"
|
||
language: "ru"
|
||
options:
|
||
api_key: "${MY_SERVICE_API_KEY}" # Переменная окружения
|
||
# Дополнительные параметры, специфичные для вашего сервиса
|
||
timeout_seconds: 300
|
||
retry_count: 3
|
||
```
|
||
|
||
#### Шаг 4: Добавить переменные окружения
|
||
|
||
Отредактируйте `.env` (или `.env.example`):
|
||
|
||
```bash
|
||
# MyService API
|
||
MY_SERVICE_API_KEY=sk-...
|
||
```
|
||
|
||
#### Шаг 5: Написать тесты
|
||
|
||
Добавьте тесты в `backend/tests/test_plugins_factory.py` или новый `test_my_transcriber.py`:
|
||
|
||
```python
|
||
import pytest
|
||
from core.plugins.factory import create_transcriber
|
||
from core.plugins.config import TranscriberConfig
|
||
|
||
def test_my_transcriber_registered():
|
||
"""Проверить регистрацию плагина."""
|
||
cfg = TranscriberConfig(provider="my_service", model="test")
|
||
transcriber = create_transcriber(cfg)
|
||
assert transcriber.provider == "my_service"
|
||
assert transcriber.model == "test"
|
||
|
||
def test_my_transcriber_transcribe(tmp_path):
|
||
"""Тест транскрибации с моком API."""
|
||
# Создать тестовый WAV-файл
|
||
audio_file = tmp_path / "test.wav"
|
||
# ... создать корректный WAV-файл ...
|
||
|
||
cfg = TranscriberConfig(provider="my_service", model="test")
|
||
transcriber = create_transcriber(cfg)
|
||
|
||
# Вызвать transcribe
|
||
segments = transcriber.transcribe(str(audio_file), language="ru")
|
||
|
||
# Проверить результат
|
||
assert len(segments) > 0
|
||
assert all(s.start < s.end for s in segments)
|
||
assert segments == sorted(segments, key=lambda s: s.start)
|
||
```
|
||
|
||
#### Шаг 6: Протестировать локально
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# Убедиться, что конфиг загружается
|
||
uv run python -c "
|
||
from core.plugins.factory import _TRANSCRIBERS
|
||
print('Зарегистрированные транскрибаторы:', list(_TRANSCRIBERS.keys()))
|
||
"
|
||
|
||
# Запустить тесты
|
||
uv run pytest tests/test_my_transcriber.py -v
|
||
|
||
# Запустить пайплайн с новым провайдером (интеграционный тест)
|
||
CELERY_ALWAYS_EAGER=True uv run pytest tests/test_build_phrases.py -v
|
||
```
|
||
|
||
### Отключение транскрибации
|
||
|
||
Если нужно полностью отключить модуль транскрибации, установите в `config/plugins.yaml`:
|
||
|
||
```yaml
|
||
transcriber:
|
||
enabled: false
|
||
provider: "null"
|
||
model: null
|
||
```
|
||
|
||
Поведение:
|
||
- Запись аудиотреков продолжает работать (egress в активном состоянии)
|
||
- При `room_finished` `run_pipeline()` завершится до инстанцирования плагина
|
||
- `pipeline_status` сеанса останется `"recording"` (не перейдёт в `"transcribing"`)
|
||
- Лог-сообщение: "transcriber отключён (enabled=false) — сеанс ... пропущен"
|
||
|
||
## Архитектурные решения
|
||
|
||
### Идемпотентный пайплайн пост-обработки
|
||
|
||
Пайплайн пост-обработки — идемпотентная машина состояний (см. `backend/models/session.py`):
|
||
|
||
```
|
||
recording → transcribing → summarizing → notified / failed
|
||
```
|
||
|
||
**run_pipeline()** диспетчер:
|
||
1. Проверяет текущий `pipeline_status` сеанса
|
||
2. Продолжает работу с последнего успешного шага
|
||
3. Отслеживает статус каждого трека (`session_audio_tracks.status`)
|
||
4. Коммитит результаты транскрибации в `session_audio_tracks.segments` (JSONB) после каждого трека
|
||
|
||
Это позволяет восстановиться после сбоя воркера без потери данных или дублирования.
|
||
|
||
### Атрибуция к участнику сеанса (ADR-002)
|
||
|
||
Фразы и аудиотреки атрибутированы не к `users`, а к `conference_participants` (участник сеанса). Это позволяет работать с гостями без `user_id`:
|
||
|
||
```python
|
||
# Получить спикера фразы
|
||
participant = session.query(ConferenceParticipant).get(phrase.participant_id)
|
||
user = participant.user # Может быть None для гостей
|
||
guest = participant.guest # Может быть None для пользователей
|
||
```
|
||
|
||
## Ссылки
|
||
|
||
- **ADR-002:** `docs/architecture/adr/002-phrase-attribution-session-participant.md`
|
||
- **Контракты плагинов:** `docs/plugins/contracts.md`
|
||
- **Модели:** `backend/models/audio_track.py`, `backend/models/phrase.py`
|
||
- **Пайплайн:** `workers/tasks/pipeline.py`
|
||
- **Реконструкция фраз:** `workers/transcription/phrases.py`
|
||
- **Тесты:** `backend/tests/test_plugins_factory.py`, `backend/tests/test_build_phrases.py`
|