Whisper.cpp API Webserver in Docker

Whisper.cpp HTTP-сервер для автоматического распознавания речи (ASR), предоставляющий API, совместимое с OpenAI-клиентами, и обеспечивающий гибкую настройку распределённой обработки аудиофайлов. Система оптимизирована для эффективного развертывания и маршрутизации запросов между несколькими Docker-контейнерами, основанными на whisper.cpp server.

Русский | 中文 | English

Содержание

• Требования
• Установка
• Whisper.cpp API-сервер
  • Swagger документация Whisper.cpp
  • Эндпоинты
  • Переменные окружения
  • Квантизация
• OpenAI-like API-сервер
  • Пример config.yml
  • Swagger документация сервера
  • Эндпоинты
• Ссылки

Требования

Docker-контейнер для Whisper.cpp собирается в две стадии, сначала берётся базовый образ nvidia/cuda:12.5.1-devel-ubuntu22.04, в нём происходит компиляция бинарников server и quantize, далее на второй стадии используется контейнер nvidia/cuda:12.5.1-runtime-ubuntu22.04, в него доустанавливаются нужные пакеты и копируются бинарные файлы собранные на предыдущем этапе.

По идее если вы понизите версию контейнера nvidia/cuda вплоть до 12.1 проблем не возникнет, но я не проверял.

Поэтому, прежде чем начать убедитесь, что в вашей системе установлена карточка с GPU, который поддерживает современную CUDA и установлен свежий CUDA драйвер.

И так, для работы проекта понадобится:

• Видеокарта от Nvidia >= GTX 10xx (или аналог)
• CUDA >= 12.5 (хотя скорее всего и на 12.1 всё будет ок)
• Docker
• Docker Compose
• Nvidia Docker Runtime

Подробную инструкцию по подготовке Linux-машины к запуску нейросетей, включая установку CUDA, Docker и Nvidia Docker Runtime вы сможете найти в моей публикации “Как подготовить Linux к запуску и обучению нейросетей? (+ Docker)”.

Установка

1. Склонируем репозиторий, после чего перейдём в корень с исходниками:

   git clone https://github.com/EvilFreelancer/docker-whisper-server.git
   cd docker-whisper-server
   
   

2. Скопируем конфигурацию Docker Compose из шаблона:

   cp docker-compose.dist.yml docker-compose.yml
   

3. Скопируем конфигурацию OpenAI-like API сервера:

   cp config.dist.yml config.yml
   

4. Соберём Docker-образы:

   docker-compose build
   

5. Запустим Docker-контейнеры:

   docker-compose up -d
   

Whisper.cpp API-сервер

В конфигурации docker-compose.yml вы можете настроить переменные окружения, версию whisper.cpp, порты, подключаемы тома и так далее.

Например, вот так можно собрать сервер из ветки master и при работе использовать модель base, которая будет квантизирована до q4_0 и запущена на 1 ядре процессора в 4 потока.

  whisper:
    restart: "unless-stopped"
    build:
      context: ./whisper
      args:
        # В качестве версии можно указать: тег, ветку или коммит
        # https://github.com/ggerganov/whisper.cpp
        - WHISPER_VERSION=master
    volumes:
      - ./models:/app/models
    ports:
      - "127.0.0.1:9000:9000"
    environment:
      WHISPER_MODEL: base
      WHISPER_MODEL_QUANTIZATION: q4_0
      WHISPER_PROCESSORS: 1
      WHISPER_THREADS: 4

Swagger документация Whisper.cpp

Сервис whisper-swagger предоставляет визуализацию и документацию всех доступных эндпоинтов.

  whisper-swagger:
    restart: "unless-stopped"
    image: swaggerapi/swagger-ui:v5.17.14
    ports:
      - "127.0.0.1:9010:8080"
    volumes:
      - ./whisper/openapi.yaml:/openapi.yaml
    environment:
      SWAGGER_JSON: /openapi.yaml

После включения по адресу http://localhost:9010 будет доступен следующего вида интерфейс:

Эндпоинты

/inference

Транскрибируем аудиофайл:

curl http://localhost:9000/inference \
  -H "Content-Type: multipart/form-data" \
  -F file="@./assets/audio.mp3" \
  -F language="auto" \
  -F response_format="json"

Вместо language="auto" (автоопределение языка аудио) вы можете явно передать нужный, например language="ru".

Вместо response_format="json" можно попросить систему вернуть субтитры response_format="srt" или просто текст response_format="text".

/load

Сменить модель Whisper:

curl http://localhost:9000/load \
  -H "Content-Type: multipart/form-data" \
  -F model="<path-to-model-file-in-docker-container>"

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

Базовая конфигурация

Квантизация

Доступные уровни квантования которые можно указать через переменную WHISPER_MODEL_QUANTIZATION:

q2_k или 10
q3_k или 11
q4_0 или 2
q4_1 или 3
q4_k или 12
q5_0 или 8
q5_1 или 9
q5_k или 13
q6_k или 14
q8_0 или 7

В случае если передать целое число скрипт entrypoint.sh автоматически преобразует его в соответствующую комбинацию символов вида qX_X.

Подробнее о квантизации в документации проекта whisper.cpp.

OpenAI-like API-сервер

Этот сервис представляет собой обёртку вокруг нескольких Whisper.cpp серверов, запущенных по сети. Он маршрутизирует запросы на сервер соответствующей модели.

  server:
    restart: "unless-stopped"
    build:
      context: ./server
    volumes:
      - ./config.yml/app/config.yaml
    ports:
      - "127.0.0.1:5000:5000"

Пример config.yml

Конфигурация сервера и список доступных моделей настраивается в файле config.yml, по умолчанию имеет следующий вид:

models:
  base:
    owned_by: organization-owner
    endpoints:
      - base_url: http://whisper:9000/inference
  #tiny:
  #  owned_by: organization-tiny-owner
  #  endpoints:
  #    - base_url: http://whisper01:9000/inference
  #    - base_url: https://user:pass@remote-server:9000/inference

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

Swagger документация сервера

Сервис server-swagger предоставляет визуализацию и документацию всех доступных эндпоинтов.

  server-swagger:
    restart: "unless-stopped"
    image: swaggerapi/swagger-ui:v5.17.14
    ports:
      - "127.0.0.1:5010:8080"
    volumes:
      - ./server/openapi.yaml:/openapi.yaml
    environment:
      SWAGGER_JSON: /openapi.yaml

После включения по адресу http://localhost:5010 будет доступен следующего вида интерфейс:

Эндпоинты

/audio/transcriptions

Этот эндпоинт используется для создания транскрипции аудиофайла в исходном языке.

Метод: POST

Параметры запроса:

• file (обязательный): Аудиофайл для транскрипции. Поддерживаются форматы: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, или webm.
• model (обязательный): ID модели, которая будет использоваться для транскрипции.
• language (опционально): Язык аудиофайла в формате ISO-639-1. Передача этого параметра может улучшить точность и скорость распознавания.
• prompt (опционально): Дополнительный текст, который может помочь модели в транскрипции или продолжить предыдущий сегмент аудио.
• response_format (опционально): Формат вывода транскрипции. Возможные значения: json, text, srt, verbose_json и vtt. По умолчанию: json.
• temperature (опционально): Температура выборки, значение от 0 до 1. Более высокие значения, такие как 0.8, сделают результат более случайным, а более низкие значения, такие как 0.2, сделают его более фокусированным и детерминированным. Если установлено значение 0, модель будет автоматически увеличивать температуру до достижения определённых порогов.

Пример запроса:

curl http://localhost:5000/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F file="@./assets/audio.mp3" \
  -F model="base" \
  -F language="auto" \
  -F response_format="json"

Пример ответа:

{
  "text": "This is the transcription of the audio."
}

/audio/translations

Этот эндпоинт используется для перевода аудиофайла на английский язык.

Работает один в один как /audio/transcriptions только language=en и его нельзя менять.

Пример запроса:

curl http://localhost:5000/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F file="@./assets/audio.mp3" \
  -F model="base" \
  -F response_format="json"

Пример ответа:

{
  "text": "This is the translated transcription of the audio."
}

/models

Этот эндпоинт используется для получения списка всех доступных моделей.

Метод: GET

Пример запроса:

curl http://localhost:5000/models

Пример ответа:

{
  "object": "list",
  "data": [
    {
      "id": "base",
      "object": "model",
      "created": 1686935002,
      "owned_by": "organization-owner"
    }
  ]
}

/models/

Этот эндпоинт используется для получения информации о конкретной модели.

Метод: GET

Параметры пути:

• model (обязательный): ID модели, о которой нужно получить информацию.

Пример запроса:

curl http://localhost:5000/models/base

Пример ответа:

{
  "id": "base",
  "object": "model",
  "created": 1686935002,
  "owned_by": "organization-owner"
}

Ссылки

Whisper.cpp

• https://github.com/ggerganov/whisper.cpp
• https://github.com/ggerganov/whisper.cpp/tree/master/examples/server

OpenAI-like API

• https://platform.openai.com/docs/api-reference/audio/createTranscription
• https://platform.openai.com/docs/api-reference/audio/createTranslation
• https://platform.openai.com/docs/api-reference/models/list
• https://platform.openai.com/docs/api-reference/models/retrieve

Лицензия

Этот проект лицензирован на условиях лицензии MIT. Подробности в файле LICENSE.

Цитирование

Если вы используете этот проект в своих исследованиях или работе, пожалуйста, укажите ссылку на него следующим образом:

[Pavel Rykov]. (2024). Whisper.cpp API Webserver in Docker. GitHub. https://github.com/EvilFreelancer/docker-whisper-server

Альтернатива в формате BibTeX:

@misc{pavelrykov2024whisperapi,
  author = {Pavel Rykov},
  title  = {Whisper.cpp API Webserver in Docker},
  year   = {2024},
  url    = {https://github.com/EvilFreelancer/docker-whisper-server}
}