gpu-transcription-mcp

A faster-whisper-Transkriptionsdienst mit einer integrierten Job-Warteschlange, sodass mehrere Agenten sich eine einzelne GPU teilen können, ohne zu kollidieren. Der Queue/Worker/Engine-Kern ist transportunabhängig und wird über zwei austauschbare Server bereitgestellt – wählen Sie den, der zu Ihren Clients passt:

Beide verwenden denselben QueueManager, sodass Jobs weiterhin einzeln verarbeitet werden und die Antwort-Payloads identisch sind (gemeinsames app/service.py).

So funktioniert es

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

Ein Job wird in die Warteschlange eingereht and gibt sofort eine job_id zurück; anschließend fragen Sie seinen Status ab, bis er done ist (oder error). Der einzelne Worker arbeitet die Warteschlange einen Job nach dem anderen ab, sodass eine gemeinsam genutzte GPU nie zwei Transkriptionen gleichzeitig ausführt.

Related MCP server: faster-whisper-mcp

Installation

pip install -e .        # or: uv sync

Dadurch werden fastmcp (MCP-Transport), flask + waitress (HTTP-Transport) und faster-whisper (die Engine) installiert.

Server starten

Wählen Sie einen Server (die sind unabhängig – keiner importiert den anderen):

# 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

Führen Sie nur einen einzigen Prozess aus – Die Warteschlange und die Job-Registrierung leben im Arbeitsspeicher. Mehrere Threads sind in Ordnung (Waitress verwendet einen Thread-Pool); mehrere Worker-Prozesses dagegen nicht, da jeder eine eigene, nicht gemeinsame Warteschlange hätte.

Der Flask-Server (einschließlich des Produktionspfads über waitress) gibt ein Start-Banner aus und protokolliert pro Anfrage eine Zeile auf stdout, z. B. GET /queue ->200 (1.2ms).

Engine-Konfiguration (beide Server)

Wird aus Umgebungsvariablen gelesen:

• WHISPER_MODEL (Standard: distil-large-v3.5)

• WHISPER_DEVICE (Standard: auto)

• WHISPER_COMPUTE_TYPE (Standard: auto)

• WHISPER_MODEL_DIR

HTTP-API (Flask-Transport)

Beipiel für eine Sitzung

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-Transport)

Stellt dieselben Oprationen als fünf FastMCP-Tools bereit:

Schnelle Checks gegen einen laufenden MCP-Server (nutzt den fastmcp-Client):

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

args-Argumente (beide Transporte)

Der args-String akzeptiert auf beitedn Transporten dieselben faster-whisper-CLI-Flaags, z. B. --format --, --model large-v3, --languine en, --diarize, --word-timestamps, --beam-size 5. Die vollständige Liste finden Sie in _APP_MAP in app/queue_manager.py.

📖 Vollständige HTTP-Referenz: siehe docs/HTTP_API.md für Anfrage-/Antwort-Schemeta, Statuscodes, den Job-Lebenszyklus und die args-Argumente.

Projektstruktivität

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

Das mitgelieferite Dockerfile / docker-compose.yml führt den MCP- Server aus (CMD ["python", "server.py"], Port 8000) mit einer NVIDIA-GPU-Reservierung. Um den Flask-Transport statdessen in einem CContainer zu bedienenen, überschreiben Sie den Befehl, z. B.:

command: python flask_server.py --port 8000

Tests

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 – Warteschlange / Worker-/Anbrech-Logik

• tests/test_service.py – Gemeinsame Payload-Aufbereitung

• tests/test_tools.py – MCP-Transport End-to-End (gemockte Engine)

• tests/test_flask_app.py – Flask-Outen End-to-Ende über den Test-Clients