====== Whisper ASR: сервер распознавания речи (GPU) ======

===== Введение =====

Инструкция описывает развёртывание сервера распознавания речи **openai-whisper-asr-webservice** (образ ''onerahmet/openai-whisper-asr-webservice'') на GPU через Docker Compose и его подключение к [[:truenas:application:ai_anki|AI Anki]], где он используется для голосовых ответов на карточки, в AI-собеседованиях и на экзаменах.

Сервис принимает аудиофайл (webm, ogg, mp3, wav и др.) и возвращает распознанный текст через HTTP API ''/asr''. Публичный адрес в нашей инфраструктуре — ''https://asr.webmastermsk.ru'' (за обратным прокси), внутри сети — порт **9890**.

**Важное замечание:** изначально сервер работал на модели ''base''. Она маленькая и плохо понимает русскую речь: технические термины превращались в обычные слова («SQL» → «Эсквель», «база данных» → «база донных»). Рекомендуемая конфигурация ниже — движок **faster_whisper** с моделью **large-v3-turbo**.

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

  * Видеокарта NVIDIA и Docker с поддержкой GPU (NVIDIA Container Toolkit).
  * Свободно ~2–3 ГБ видеопамяти для ''large-v3-turbo'' (около 1,5 ГБ в режиме int8).
  * Свободный порт **9890** (или любой другой).
  * Доступ в интернет при первом запуске — модель (~1,6 ГБ) скачивается автоматически.

===== Шаг 1: Docker Compose конфигурация =====

Итоговый вариант ''docker-compose.yml'':

<code yaml>
services:
  whisper-server:
    container_name: whisper-server
    deploy:
      resources:
        reservations:
          devices:
            - capabilities:
                - gpu
              count: 1
              driver: nvidia
    environment:
      - ASR_ENGINE=faster_whisper
      - ASR_MODEL=large-v3-turbo
      - ASR_DEVICE=cuda
      - ASR_QUANTIZATION=float16
      - ASR_MODEL_PATH=/data/whisper
      - MODEL_IDLE_TIMEOUT=300
    volumes:
      - whisper-models:/data/whisper
    image: onerahmet/openai-whisper-asr-webservice:latest-gpu
    ports:
      - '9890:9000'
    restart: unless-stopped

volumes:
  whisper-models:
</code>

^ Параметр ^ Значение и зачем ^
| ''ASR_ENGINE'' | ''faster_whisper'' — тот же Whisper, но быстрее в несколько раз и экономнее по видеопамяти. Также есть ''openai_whisper'' и ''whisperx'' |
| ''ASR_MODEL'' | ''large-v3-turbo'' — качество близко к ''large-v3'' при гораздо большей скорости, хорошо понимает русский |
| ''ASR_DEVICE'' | ''cuda'' — распознавание на GPU |
| ''ASR_QUANTIZATION'' | ''float16'' — стандарт для GPU. При нехватке видеопамяти — ''int8'' (проверить ''int8_float16'' в вашей версии образа) |
| ''ASR_MODEL_PATH'' + том | модель скачивается один раз и не перекачивается при пересоздании контейнера |
| ''MODEL_IDLE_TIMEOUT'' | выгрузка модели из видеопамяти после N секунд простоя — полезно, если GPU общий с Ollama **(проверить: есть только в новых версиях образа, в старых игнорируется)** |

==== 1.1. Выбор модели ====

^ Модель ^ Видеопамять (float16, примерно) ^ Русская речь ^ Когда выбирать ^
| ''base'' | ~1 ГБ | плохо, путает термины | не рекомендуется |
| ''small'' | ~1,5 ГБ | средне | очень слабая видеокарта |
| ''medium'' | ~3 ГБ | хорошо | если turbo недоступна |
| ''large-v3-turbo'' | ~2–3 ГБ | очень хорошо | **рекомендуется** |
| ''large-v3'' | ~4–5 ГБ | лучше всего, но медленнее | много свободной видеопамяти |

===== Шаг 2: Развёртывание =====

==== 2.1. Через веб-интерфейс TrueNAS ====

  - **Apps** → **Discover Apps** → **Custom App** (или **Install via YAML**).
  - Вставьте конфигурацию из Шага 1.
  - **Save** → **Deploy**.

Для замены модели у существующего приложения: **Apps** → ''whisper-server'' → **Edit** → поменять ''environment'' → **Save**. Контейнер пересоздастся.

==== 2.2. Через SSH ====

<code bash>
cd /путь/к/compose
docker compose up -d
docker logs -f whisper-server
</code>

При первом запросе модель скачивается в том ''whisper-models''. Распознавание станет доступно через 1–2 минуты (зависит от скорости интернета).

===== Шаг 3: Проверка =====

Документация API (Swagger) открывается в браузере:

<code>
http://<IP-сервера>:9890/docs
</code>

Тестовое распознавание с консоли:

<code bash>
curl -s -X POST \
  -F "audio_file=@test.webm" \
  "http://<IP-сервера>:9890/asr?task=transcribe&language=ru&output=json&encode=true"
</code>

Ответ содержит поле ''text'' с распознанной фразой. Загрузку GPU и использование памяти можно посмотреть так:

<code bash>
nvidia-smi
</code>

==== 3.1. Параметры запроса /asr ====

^ Параметр ^ Пример ^ Назначение ^
| ''task'' | ''transcribe'' | распознать (''translate'' — перевести на английский) |
| ''language'' | ''ru'' | язык речи; без него Whisper определяет язык сам и чаще ошибается |
| ''output'' | ''json'' | формат ответа (''txt'', ''vtt'', ''srt'', ''tsv'', ''json'') |
| ''encode'' | ''true'' | перекодировать вход через ffmpeg (нужно для webm/ogg из браузера) |
| ''initial_prompt'' | ''Термины: SQL, JOIN, PHP'' | подсказка: контекст и правильное написание терминов |
| ''vad_filter'' | ''true'' | вырезать тишину (faster_whisper) |

**Примечание:** параметр ''initial_prompt'' сильно улучшает распознавание терминов. AI Anki автоматически передаёт в нём текст текущего вопроса и английские термины из него.

===== Шаг 4: Подключение к AI Anki =====

  - Войдите в AI Anki под **администратором**.
  - **Настройки** → раздел **«Сервер»**:
    * **ASR URL (Whisper)** — ''https://asr.webmastermsk.ru'' (или ''%%http://<IP>:9890%%'' внутри сети);
    * **ASR логин / пароль** — если прокси требует Basic-авторизацию, иначе оставить пустыми.
  - **Сохранить**.
  - В разделе **«Обучение»** каждый пользователь может включить или выключить **«Исправлять распознанную речь с помощью ИИ»**. Модель поправит неверно услышанные термины, не меняя смысл ответа.

Кнопка **«Голосом»** появится в учебной сессии (текстовые карточки), в AI-собеседовании и на экзамене.

===== Проблемы и решения =====

^ Проблема ^ Причина ^ Решение ^
| Термины распознаются как обычные слова («Эсквель», «база донных») | слабая модель ''base'', нет контекста | ''large-v3-turbo'' + ''initial_prompt'' (AI Anki передаёт его сам) |
| ''HTTP 500'' на записи из браузера | формат webm/opus без перекодирования | передавать ''encode=true'' |
| Первый запрос очень долгий | модель скачивается | дождаться загрузки, смотреть ''docker logs whisper-server'' |
| Ollama стал медленным после смены модели | Whisper и Ollama делят видеопамять одной видеокарты, LLM уходит на CPU | ''ASR_QUANTIZATION=int8'', ''MODEL_IDLE_TIMEOUT'', проверить ''nvidia-smi'' |
| ''401'' из AI Anki | прокси требует авторизацию | указать ASR логин и пароль в настройках AI Anki |
| ''CUDA out of memory'' в логах | не хватает видеопамяти | модель меньше (''medium'', ''small'') или ''int8'' |

===== Шпаргалка =====

<code bash>
# логи сервиса
docker logs -f whisper-server

# перезапуск
docker restart whisper-server

# занятость видеопамяти
nvidia-smi

# тест распознавания
curl -s -X POST -F "audio_file=@test.webm" \
  "http://<IP>:9890/asr?task=transcribe&language=ru&output=json&encode=true"
</code>