내장된 작업 큐가 있는 faster-whisper 전사(transcription) 서비스로, 여러 에이전트가 충돌 없이 단일 GPU를 공유할 수 있습니다. 큐/워커/엔진 코어는 transport-agnostic이며 두 개의 상호 교환 가능한 서버를 통해 노출됩니다 — 클라이언트가 사용하혀는 서버를 선택하세요:
서버 | 엔트리 포인트 | 기본 포트 | 클라이언트 |
MCP |
| 8000 | MCP를 인식하는 에이전트 (FastMCP) |
Flask |
| 8001 | 모든 HTTP/JSON 클라이언트 |
두 서버 모두 동일한 QueueManager를 감싸므로 작업은 여전히 한 번에 하나씩 처리되고 응답 페이로드는 동일합니다 (공유 app/service.py).
submit ─► ┌──────────────┐ one worker, one GPU ┌───────────────┐
│ job queue │ ──────────────────────► │ WhisperEngine │
poll ◄─ └──────────────┘ processed serially └───────────────┘작업이 큐에 넣고 즉시 job_id가 반환됩니다. 그런 다음 상태가 done(또는 error)이 될 때가지 폴링합니다. 단일 워커는 큐에 경우 하나의 작업만 처라하므로 공유 GPU에서 두 개의 전사가 동시에 실행되지 않습니다.
Related MCP server: faster-whisper-mcp
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
메서드 및 경로 | 설멍 |
| 헬스체크 → |
| 작업 제출: |
| 상태 폴링; |
| 큐시/실행 중 작업 취소 |
| 실행 중인 작업, 큐시 작업, 완료된 객체 수 |
예시 세션:
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동일한 작업을 다섯 개의 FastMP 도구로 노출합니다:
도구 | 설명 |
| 활성 상태 확인 |
| 작업을 큐시 |
| 작업 폴링; |
| 큐/실행 중인 작업 취소 |
|
|
실행 중인 MCP 서버에 대한 빠른 점검 (fastmcp 클라이언트 사용):
python test_ping.py # ping the server
python test_live.py --audio /path/audio.mp3 # full submit → poll → print transcriptargs 플래그 (두 전송 모두)args 아래 같은 faster-whisper CLI 플래그를 어느 전송에서든 사용할 수 있습니다 (예: --format srt, --model large-v3, --language en, --diarize, --word-timestamps, --beam-size 5). 전체 목록은 app/queue_manager.py의 _ARG_MAP를 참조하세요.
📖 전체 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)포함된 Dockerfile / docker-compose.yml은 MCP 서버 (CMD ["python", "server.py"], 포트 8000)를 NVIDIA GPU 예약과 실행합니다. 컨이너에서 Flask 전송을 대신 실행하고 명령 <CMD>를 덮이터하 — 예:
command: python flask_server.py --port 8000pytest -m "not integration" # unit tests (engine mocked) — covers core, MCP, and Flask
pytest -m integration # requires faster-whisper + a real model/audio filetests/test_queue_builder.py — 큐/워커/취소 로직 테스트
tests/test_service.py — 공유 페이로드 형성 테스트
tests/test_templates.py — MCP 전송 엔드투엔드 테스트 (모조된 engine)
tests/test_flask_processor.py — Flask 우트 엔드투엔드 테스트 (테스트 클라이언트 사용)
This server cannot be deployed
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.