GPU Queue

Сервис транскрибации на базе faster-whisper со встроенной очередью заданий, позволяющий нескольким агентам использовать один GPU без конфликтов. Ядро «очередь/воркер/движок» не привязано к транспорту и доступно через два взаимозаменяемых сервера — выбирайте тот, который поддерживают ваши клиенты:

Оба сервера оборачивают один и тот же QueueManager, поэтому задания по-прежнему выполняются по одному, а тела ответов идентичны (общий app/service.py).

Как это работает

submit  ─►  ┌──────────────┐   one worker, one GPU   ┌───────────────┐
            │  job queue   │ ──────────────────────► │ WhisperEngine │
poll    ◄─  └──────────────┘   processed serially     └───────────────┘

Задание попадает в очередь и немедленно возвращает job_id; затем вы опрашиваете его статус, пока он не станет done (или error). Единственный воркер разбирает очередь по одному заданию за раз, поэтому общий GPU никогда не выполняет две транскрибации одновременно.

Related MCP server: AssemblyAI MCP Server

Установка

pip install -e .        # or: uv sync

Эта команда подтягивает fastmcp (MCP-транспорт), flask + waitress (HTTP-транспорт) и faster-whisper (движок).

Запуск сервера

Выберите один сервер (они независимы — ни один не импортирует другой):

# MCP transport (streamable-http on :8000)
python server.py
python server.py --port 9000
python server.py --transport stdio        # for stdio MCP clients

# Flask transport (HTTP/JSON on :8001)
python flask_server.py
python flask_server.py --port 9001
python flask_server.py --debug            # Flask dev server with auto-reload

Запускайте только один процесс — очередь и реестр заданий хранятся в памяти. Несколько потоков допустимы (waitress использует пул потоков); несколько воркер-процессов — нет, поскольку каждый из них имел бы собственную отдельную неразделяемую очередь.

Flask-сервер (включая продакшн-вариант на waitress) печатает стартовый баннер и логирует в stdout одну строку на каждый запрос, например GET /queue -> 200 (1.2ms).

Конфигурация движка (оба сервера)

Читается из переменных окружения:

• WHISPER_MODEL (по умолчанию distil-large-v3.5)

• WHISPER_DEVICE (по умолчанию auto)

• WHISPER_COMPUTE_TYPE (по умолчанию auto)

• WHISPER_MODEL_DIR

HTTP API (Flask-транспорт)

Пример сессии:

curl localhost:8001/ping

# submit
curl -X POST localhost:8001/transcriptions \
  -H 'Content-Type: application/json' \
  -d '{"audio_path":"/abs/path/audio.mp3","args":"--format text"}'
# → {"job_id":"j_ab12cd34","position":1, ...}

# poll until "status":"done"
curl localhost:8001/transcriptions/j_ab12cd34

# inspect the queue / cancel
curl localhost:8001/queue
curl -X POST localhost:8001/transcriptions/j_ab12cd34/cancel

MCP API (MCP-транспорт)

Предоставляет те же операции в виде пяти инструментов FastMCP:

Быстрые проверки работающего MCP-сервера (с использованием клиента fastmcp):

python test_ping.py                       # ping the server
python test_live.py --audio /path/audio.mp3   # full submit → poll → print transcript

Флаги args (оба транспорта)

Строка args принимает те же CLI-флаги faster-whisper на каждом транспорте, например --format srt, --model large-v3, --language en, --diarize, --word-timestamps, --beam-size 5. Полный список см. в _ARG_MAP в app/queue_manager.py.

📖 Полный HTTP-справочник: см. docs/HTTP_API.md — схемы запросов и ответов, коды статусов, жизненный цикл задания и флаги args.

Структура проекта

app/
  queue_manager.py   queue, worker, engine lifecycle, CLI-arg → kwargs bridge
  whisper/engine.py  faster-whisper wrapper (model stays loaded between jobs)
  models.py          JobRecord dataclass
  service.py         payload-shaping shared by both transports
  main.py / tools.py MCP transport (create_mcp_app + tool definitions)
  flask_app.py       Flask transport (create_flask_app + routes)
server.py            run the MCP server      (:8000)
flask_server.py      run the Flask server    (:8001)

Docker

Входящие в репозиторий Dockerfile / docker-compose.yml запускают MCP-сервер (CMD ["python", "server.py"], порт 8000) с зарезервированным NVIDIA GPU. Чтобы, наоборот, развернуть в контейнере Flask-транспорт, переопределите команду, например:

command: python flask_server.py --port 8000

Тесты

pytest -m "not integration"   # unit tests (engine mocked) — covers core, MCP, and Flask
pytest -m integration         # requires faster-whisper + a real model/audio file

• tests/test_queue_manager.py — логика очереди/воркера/отмены

• tests/test_service.py — общий модуль формирования тел ответов

• tests/test_tools.py — сквозной тест MCP-транспорта (движок замокан)

• tests/test_flask_app.py — сквозной тест Flask-маршрутов через тестовый клиент