.. _citeck-stt-sidecar:

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

.. contents::
    :depth: 3

**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, сервис продолжает работу в режиме только транскрипции.

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

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

.. code-block:: text

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


API
---

.. list-table::
   :header-rows: 1
   :widths: 30 10 60
   :class: tight-table

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


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

.. list-table::
   :header-rows: 1
   :widths: 30 20 50
   :class: tight-table

   * - Переменная
     - По умолчанию
     - Назначение
   * - ``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


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

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Файл
     - Назначение
   * - ``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