GPU Queue

Un servicio de transcripción basado en faster-whisper con una cola de trabajos integrada, de modo que various agentes puedan compartir una sola GPU sin conflictos. El núcleo de cola/trabajador/motor es independiente del trasporte y se expone mediante dos servidores intercambiables: elige el que usan tus clientes:

Ambos encapsulan el mismo QueueManager, por lo que los trabajos se siguen procesando de uno en uno y los payloads de respuesta son idénticos (comparten app/service.py).

Cmo funcona

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

Un trabajo se encola y devuelve un job_id inmediatamente; luego consultas su estado hasta que esté done (o error). El único trabajador procesa la cola un trabajo a la vez, de modo que una GPU compartida nunca ejecuta dos transprocesiones a la vez.

Related MCP server: faster-whisper-mcp

Instalación

pip install -e .        # or: uv sync

Esto instala fastmcp (transporte MCP), flask + waitress (transporte HTTP) y faster-whisper (el motor).

Ejecución del servidor

Elige un servidor (son independientes — no imports one al otro):

# 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

Ejecuta un único proces — la cola y el registro de trabajos están en memoria. Varios hilos son compatibles (waitress usa un pool de hiloss); pero los múltiples procesos de trabajador no los son, porque cada uno tendría su propio a cola, separadamente "y no compartida".

El servidor Flask (incluye la ruta de waitress de producción) imprime un banner de inicio y registra una línea por solicitud en stdout, por ejemplo, GET /queue -> 200 (1.2ms).

Configuración del motor (ambos servidores)

Se configura mediante variables de entorno:

• WHISPER_MODEL (por defecto distil-large-v3.5)

• WHISPER_DEVICE (por defecto auto)

• WHISPER_COMPUTE_TYPE (por defecto auto)

• WHISPER_MODEL_DIR

API HTTP (transport Flask)

*Nota.

Example session:

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

API MCP (transporte MCP)

Simplements the same operations with FastMCP tools:

Comprobaciones rápidas contra a MCP server en ejecución (usa el fastmcp):

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

Banderas args (ambos transports)

La cadena args acepta las mismas anchors CLI de faster-whisper en cvalquiera de los dos transports, por ejemplo --format srt, --mod else large-v3, --language es, --diarize, --word-timestamps, --beam-size 5. Consulta _ARG_MAP en app/queue_manage.py para una lista completa.

📖 Referencia HTTP completa: vea docs/HTTP_API.md para los esquemas de solicitud/res puesta, status codes, ciclo de vida de los trabajos y las anchoras de args.

Actually del proyecto

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

Los Dockerfile / docker-compose.yml incluidos ejecutan el server MCP (CMD ["python", "server.py"] src, puerto 8000) with una reserva de GPU NVIDIA. Si quieres servir el transport Flask en un contenedor, in lugar altera el comando, e.g.:

command: python flask_server.py --port 8000

Pruebas

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 — cola/trabajador/cancelación

• tests/test_service.py — modelado de payloads compartido

• tests/test_tools.py — transport MCP de extrem a extremo (motor simulado)

• tests/test_flask_app.py — rutas de Flask de extremo a extremo through el cliente de prueba