Микросервис для транскрипции аудио и диаризации 

Citeck stt sidecar — микросервис для транскрипции аудио и диаризации (определения говорящих), интегрированный как sidecar в платформу Citeck. Обрабатывает записи конференций из pipeline citeck-meeting-recorder / citeck-ai.

Принцип работы 

Сервис принимает аудиофайл, преобразует его в нужный формат, разбивает на чанки для транскрипции и при необходимости определяет, кто из участников говорит в каждом фрагменте.

Конвертация аудио 

Любой входящий формат (WebM, Opus и др.) преобразуется в WAV 16 кГц / mono / PCM16 через ffmpeg. Временные файлы, созданные в процессе конвертации, гарантированно удаляются в finally-блоках.

Чанковая транскрипция 

Аудио нарезается на 25-секундные чанки с перекрытием 1 секунду. Это позволяет обрабатывать длинные записи без переполнения памяти и не терять слова на границах фрагментов. Каждый чанк транскрибируется моделью GigaAM-v3 (Сбер) — основной моделью распознавания русской речи. Результат — список сегментов с временными метками.

Диаризация 

Диаризация выполняется библиотекой pyannote.audio и загружается лениво — только при первом запросе к /transcribe-diarize. Если переменная HF_TOKEN не задана, диаризация отключается gracefully, сервис продолжает работу в режиме только транскрипции.

После получения результатов транскрипции и диаризации сервис сопоставляет сегменты: для каждого текстового отрезка определяется говорящий по максимальному перекрытию с сегментами диаризации.

Поток обработки 

citeck-ai (WebSocket handler)
    ↓
citeck-stt-sidecar (FastAPI :8090)
    ├── Принять аудиофайл (multipart, WebM или WAV)
    ├── Конвертировать в WAV 16kHz/mono/PCM16 (ffmpeg)
    ├── Транскрибировать чанками по 25с (GigaAM)
    ├── [опционально] Диаризация (pyannote)
    ├── Слить сегменты транскрипции и говорящих
    └── Вернуть JSON: текст, сегменты, кол-во говорящих, длительность

API 

Эндпоинт	Метод	Описание
`/health`	`GET`	Состояние сервиса и доступность моделей
`/transcribe`	`POST`	Транскрипция аудиофайла (только текст, без диаризации)
`/transcribe-diarize`	`POST`	Транскрипция + определение говорящих

Переменные окружения 

Переменная	По умолчанию	Назначение
`HF_TOKEN`	—	Токен HuggingFace (необходим для диаризации через pyannote)
`GIGAAM_MODELS_PATH`	`../citeck-ai/models`	Путь к кэшу модели GigaAM (монтируется как volume из citeck-ai)
`PORT` / `STT_PORT`	`8090`	Порт сервиса

Технологический стек 

FastAPI + Uvicorn — асинхронный REST API (порт 8090)
GigaAM-v3 (Сбер) — распознавание русской речи
pyannote.audio — диаризация
pydub + ffmpeg — конвертация аудио (WebM/Opus → WAV)
Python 3.11, деплой в Docker

Ключевые файлы 

Файл	Назначение
`app/main.py`	Точка входа FastAPI, управление жизненным циклом моделей, слияние результатов транскрипции и диаризации
`app/transcriber.py`	`GigaAmTranscriber`: чанковая обработка аудио (25с с перекрытием 1с), возвращает сегменты с временными метками
`app/diarizer.py`	`SpeakerDiarizer`: ленивая загрузка pyannote-пайплайна при первом запросе (требует `HF_TOKEN`)
`app/audio_utils.py`	Конвертация любого формата в WAV 16 кГц/mono через ffmpeg, очистка временных файлов
`Dockerfile` / `docker-compose.yml`	Python 3.11-slim, лимит памяти 2 ГБ, модели монтируются как volume из citeck-ai