Spaces:
Sleeping
Sleeping
| # System Architecture | |
| ## Overview | |
| Whisper German ASR is a modular, production-ready speech recognition system with multiple deployment options. | |
| --- | |
| ## High-Level Architecture | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────┐ | |
| │ User Interfaces │ | |
| ├─────────────────────────────────────────────────────────────┤ | |
| │ Web Browser │ Mobile App │ CLI │ API Clients │ | |
| └────────┬──────┴──────┬───────┴───┬───┴──────┬───────────────┘ | |
| │ │ │ │ | |
| ▼ ▼ ▼ ▼ | |
| ┌─────────────┐ ┌──────────┐ ┌─────┐ ┌──────────┐ | |
| │ Gradio │ │ Custom │ │ CLI │ │ REST API │ | |
| │ Demo │ │ UI │ │ │ │ Client │ | |
| └──────┬──────┘ └─────┬────┘ └──┬──┘ └────┬─────┘ | |
| │ │ │ │ | |
| └───────────────┴───────────┴──────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────────────────┐ | |
| │ FastAPI Application │ | |
| │ ┌───────────────────────┐ │ | |
| │ │ /transcribe endpoint │ │ | |
| │ │ /health endpoint │ │ | |
| │ │ /docs endpoint │ │ | |
| │ └───────────────────────┘ │ | |
| └──────────────┬──────────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────────────────┐ | |
| │ Whisper Model Pipeline │ | |
| │ ┌───────────────────────┐ │ | |
| │ │ 1. Audio Processing │ │ | |
| │ │ - Load audio │ │ | |
| │ │ - Resample 16kHz │ │ | |
| │ │ - Convert to mono │ │ | |
| │ ├───────────────────────┤ │ | |
| │ │ 2. Feature Extraction │ │ | |
| │ │ - Mel spectrogram │ │ | |
| │ │ - Normalization │ │ | |
| │ ├───────────────────────┤ │ | |
| │ │ 3. Model Inference │ │ | |
| │ │ - Encoder │ │ | |
| │ │ - Decoder │ │ | |
| │ │ - Beam search │ │ | |
| │ ├───────────────────────┤ │ | |
| │ │ 4. Post-processing │ │ | |
| │ │ - Token decoding │ │ | |
| │ │ - Text formatting │ │ | |
| │ └───────────────────────┘ │ | |
| └──────────────┬──────────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────────────────┐ | |
| │ Response/Output │ | |
| │ German Transcription │ | |
| └─────────────────────────────┘ | |
| ``` | |
| --- | |
| ## Component Details | |
| ### 1. User Interfaces | |
| #### Gradio Demo (`demo/app.py`) | |
| ``` | |
| ┌─────────────────────────────────┐ | |
| │ Gradio Interface │ | |
| ├─────────────────────────────────┤ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ Audio Input │ │ | |
| │ │ - Microphone │ │ | |
| │ │ - File Upload │ │ | |
| │ └──────────────────────────┘ │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ Transcribe Button │ │ | |
| │ └──────────────────────────┘ │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ Output Display │ │ | |
| │ │ - Transcription │ │ | |
| │ │ - Duration │ │ | |
| │ └──────────────────────────┘ │ | |
| └─────────────────────────────────┘ | |
| ``` | |
| #### REST API (`api/main.py`) | |
| ``` | |
| ┌─────────────────────────────────┐ | |
| │ FastAPI Server │ | |
| ├─────────────────────────────────┤ | |
| │ Endpoints: │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ POST /transcribe │ │ | |
| │ │ - Upload audio file │ │ | |
| │ │ - Returns JSON │ │ | |
| │ └──────────────────────────┘ │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ GET /health │ │ | |
| │ │ - Model status │ │ | |
| │ │ - Device info │ │ | |
| │ └──────────────────────────┘ │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ GET /docs │ │ | |
| │ │ - Swagger UI │ │ | |
| │ │ - API documentation │ │ | |
| │ └──────────────────────────┘ │ | |
| └─────────────────────────────────┘ | |
| ``` | |
| ### 2. Processing Pipeline | |
| ``` | |
| Audio Input | |
| │ | |
| ▼ | |
| ┌─────────────────┐ | |
| │ Audio Loading │ librosa.load() | |
| │ - Load file │ sr=16000, mono=True | |
| │ - Resample │ | |
| └────────┬────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────┐ | |
| │ Preprocessing │ WhisperProcessor | |
| │ - Mel spectro │ 80 channels | |
| │ - Normalization │ 3000 frames (30s) | |
| └────────┬────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────┐ | |
| │ Model Inference │ WhisperForConditionalGeneration | |
| │ - Encoder │ 6 layers | |
| │ - Decoder │ 6 layers | |
| │ - Generation │ Beam search (size=5) | |
| └────────┬────────┘ | |
| │ | |
| ▼ | |
| ┌─────────────────┐ | |
| │ Decoding │ processor.batch_decode() | |
| │ - Token→Text │ skip_special_tokens=True | |
| │ - Formatting │ | |
| └────────┬────────┘ | |
| │ | |
| ▼ | |
| German Transcription | |
| ``` | |
| ### 3. Model Architecture | |
| ``` | |
| ┌─────────────────────────────────────────────────┐ | |
| │ Whisper-small Architecture │ | |
| ├─────────────────────────────────────────────────┤ | |
| │ │ | |
| │ Input: 80-channel Mel Spectrogram │ | |
| │ (80 x 3000 = 30 seconds) │ | |
| │ │ | |
| │ ┌───────────────────────────────────────┐ │ | |
| │ │ Encoder (6 layers) │ │ | |
| │ │ ┌─────────────────────────────────┐ │ │ | |
| │ │ │ Conv1D → Conv1D → Positional │ │ │ | |
| │ │ │ Embedding → Transformer Blocks │ │ │ | |
| │ │ └─────────────────────────────────┘ │ │ | |
| │ │ Output: 384-dim embeddings │ │ | |
| │ └──────────────────┬────────────────────┘ │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ ┌───────────────────────────────────────┐ │ | |
| │ │ Decoder (6 layers) │ │ | |
| │ │ ┌─────────────────────────────────┐ │ │ | |
| │ │ │ Token Embedding → Positional │ │ │ | |
| │ │ │ Embedding → Transformer Blocks │ │ │ | |
| │ │ │ → Cross-Attention → Output │ │ │ | |
| │ │ └─────────────────────────────────┘ │ │ | |
| │ │ Output: Token probabilities │ │ | |
| │ └───────────────────────────────────────┘ │ | |
| │ │ | |
| │ Parameters: 242M │ | |
| │ Language: German (de) │ | |
| │ Task: Transcribe │ | |
| └─────────────────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## Deployment Architectures | |
| ### Local Development | |
| ``` | |
| ┌──────────────────────────────┐ | |
| │ Developer Machine │ | |
| │ ┌────────────────────────┐ │ | |
| │ │ Python Environment │ │ | |
| │ │ - FastAPI/Gradio │ │ | |
| │ │ - Whisper Model │ │ | |
| │ │ - Dependencies │ │ | |
| │ └────────────────────────┘ │ | |
| │ Ports: 8000 (API) │ | |
| │ 7860 (Demo) │ | |
| └──────────────────────────────┘ | |
| ``` | |
| ### Docker Deployment | |
| ``` | |
| ┌─────────────────────────────────────┐ | |
| │ Docker Host │ | |
| │ ┌───────────────────────────────┐ │ | |
| │ │ Container: whisper-api │ │ | |
| │ │ - FastAPI │ │ | |
| │ │ - Port 8000 │ │ | |
| │ └───────────────────────────────┘ │ | |
| │ ┌───────────────────────────────┐ │ | |
| │ │ Container: whisper-demo │ │ | |
| │ │ - Gradio │ │ | |
| │ │ - Port 7860 │ │ | |
| │ └───────────────────────────────┘ │ | |
| │ ┌───────────────────────────────┐ │ | |
| │ │ Volume: whisper_test_tuned │ │ | |
| │ │ - Shared model files │ │ | |
| │ └───────────────────────────────┘ │ | |
| └─────────────────────────────────────┘ | |
| ``` | |
| ### Cloud Deployment (AWS) | |
| ``` | |
| ┌─────────────────────────────────────────────────┐ | |
| │ AWS Cloud │ | |
| │ ┌───────────────────────────────────────────┐ │ | |
| │ │ Application Load Balancer │ │ | |
| │ │ - HTTPS (443) │ │ | |
| │ │ - Health checks │ │ | |
| │ └──────────────┬────────────────────────────┘ │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ ┌───────────────────────────────────────────┐ │ | |
| │ │ ECS Fargate Service │ │ | |
| │ │ ┌─────────────────────────────────────┐ │ │ | |
| │ │ │ Task 1: whisper-asr │ │ │ | |
| │ │ │ - 1 vCPU, 2GB RAM │ │ │ | |
| │ │ │ - Container: API │ │ │ | |
| │ │ └─────────────────────────────────────┘ │ │ | |
| │ │ ┌─────────────────────────────────────┐ │ │ | |
| │ │ │ Task 2: whisper-asr │ │ │ | |
| │ │ │ - Auto-scaling (2-10 tasks) │ │ │ | |
| │ │ └─────────────────────────────────────┘ │ │ | |
| │ └───────────────────────────────────────────┘ │ | |
| │ ┌───────────────────────────────────────────┐ │ | |
| │ │ S3 Bucket │ │ | |
| │ │ - Model files │ │ | |
| │ │ - Static assets │ │ | |
| │ └───────────────────────────────────────────┘ │ | |
| │ ┌───────────────────────────────────────────┐ │ | |
| │ │ CloudWatch │ │ | |
| │ │ - Logs │ │ | |
| │ │ - Metrics │ │ | |
| │ │ - Alarms │ │ | |
| │ └───────────────────────────────────────────┘ │ | |
| └─────────────────────────────────────────────────┘ | |
| ``` | |
| ### HuggingFace Spaces | |
| ``` | |
| ┌─────────────────────────────────────┐ | |
| │ HuggingFace Spaces │ | |
| │ ┌───────────────────────────────┐ │ | |
| │ │ Gradio Space │ │ | |
| │ │ - app.py │ │ | |
| │ │ - requirements.txt │ │ | |
| │ │ - README.md │ │ | |
| │ └───────────────────────────────┘ │ | |
| │ ┌───────────────────────────────┐ │ | |
| │ │ Model from HF Hub │ │ | |
| │ │ - YOUR_USER/whisper-de │ │ | |
| │ │ - Auto-loaded │ │ | |
| │ └───────────────────────────────┘ │ | |
| │ ┌───────────────────────────────┐ │ | |
| │ │ Hardware │ │ | |
| │ │ - CPU Basic (free) │ │ | |
| │ │ - GPU T4 (paid) │ │ | |
| │ └───────────────────────────────┘ │ | |
| │ Public URL: https://hf.co/spaces/ │ | |
| │ YOUR_USER/whisper-de │ | |
| └─────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## Data Flow | |
| ### Transcription Request Flow | |
| ``` | |
| 1. User uploads audio | |
| │ | |
| ▼ | |
| 2. API receives file | |
| │ | |
| ▼ | |
| 3. Load audio with librosa | |
| - Decode format (mp3/wav/etc) | |
| - Resample to 16kHz | |
| - Convert to mono | |
| │ | |
| ▼ | |
| 4. WhisperProcessor | |
| - Compute mel spectrogram | |
| - Normalize features | |
| - Pad/truncate to 30s | |
| │ | |
| ▼ | |
| 5. Model.generate() | |
| - Encoder: audio → embeddings | |
| - Decoder: embeddings → tokens | |
| - Beam search for best sequence | |
| │ | |
| ▼ | |
| 6. Processor.decode() | |
| - Tokens → text | |
| - Remove special tokens | |
| - Format output | |
| │ | |
| ▼ | |
| 7. Return JSON response | |
| { | |
| "transcription": "...", | |
| "duration": 2.5, | |
| "language": "de" | |
| } | |
| ``` | |
| --- | |
| ## Technology Stack | |
| ``` | |
| ┌─────────────────────────────────────┐ | |
| │ Frontend/Interface │ | |
| ├─────────────────────────────────────┤ | |
| │ - Gradio 4.0+ │ | |
| │ - HTML/CSS/JavaScript │ | |
| │ - Swagger UI (FastAPI) │ | |
| └─────────────────────────────────────┘ | |
| ┌─────────────────────────────────────┐ | |
| │ Backend/API │ | |
| ├─────────────────────────────────────┤ | |
| │ - FastAPI 0.104+ │ | |
| │ - Uvicorn (ASGI server) │ | |
| │ - Pydantic (validation) │ | |
| └─────────────────────────────────────┘ | |
| ┌─────────────────────────────────────┐ | |
| │ ML Framework │ | |
| ├─────────────────────────────────────┤ | |
| │ - PyTorch 2.2+ │ | |
| │ - Transformers 4.42+ │ | |
| │ - Datasets 2.19+ │ | |
| └─────────────────────────────────────┘ | |
| ┌─────────────────────────────────────┐ | |
| │ Audio Processing │ | |
| ├─────────────────────────────────────┤ | |
| │ - Librosa 0.10+ │ | |
| │ - SoundFile 0.12+ │ | |
| │ - FFmpeg (system) │ | |
| └─────────────────────────────────────┘ | |
| ┌─────────────────────────────────────┐ | |
| │ Evaluation │ | |
| ├─────────────────────────────────────┤ | |
| │ - jiwer 4.0+ (WER/CER) │ | |
| │ - NumPy 1.24+ │ | |
| └─────────────────────────────────────┘ | |
| ┌─────────────────────────────────────┐ | |
| │ Deployment/DevOps │ | |
| ├─────────────────────────────────────┤ | |
| │ - Docker │ | |
| │ - Docker Compose │ | |
| │ - GitHub Actions │ | |
| └─────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## Performance Characteristics | |
| ### Latency | |
| ``` | |
| Component Time | |
| ───────────────────────────────── | |
| Audio Loading 50-100ms | |
| Feature Extraction 100-200ms | |
| Model Inference (CPU) 1-3s | |
| Model Inference (GPU) 200-500ms | |
| Post-processing 10-50ms | |
| ───────────────────────────────── | |
| Total (CPU) 1.2-3.4s | |
| Total (GPU) 360-850ms | |
| ``` | |
| ### Throughput | |
| ``` | |
| Hardware Samples/sec | |
| ──────────────────────────── | |
| CPU (4 cores) 0.3-0.5 | |
| GPU (T4) 2-5 | |
| GPU (A100) 10-20 | |
| ``` | |
| ### Resource Usage | |
| ``` | |
| Component CPU Memory GPU Memory | |
| ───────────────────────────────────────── | |
| Model Loading - 1.5GB 1GB | |
| Inference 100% 2GB 1.5GB | |
| API Server 10% 200MB - | |
| Gradio Demo 5% 100MB - | |
| ``` | |
| --- | |
| ## Security Architecture | |
| ``` | |
| ┌─────────────────────────────────────┐ | |
| │ Security Layers │ | |
| ├─────────────────────────────────────┤ | |
| │ 1. Network Layer │ | |
| │ - HTTPS/TLS │ | |
| │ - CORS policies │ | |
| │ - Rate limiting │ | |
| │ │ | |
| │ 2. Application Layer │ | |
| │ - Input validation │ | |
| │ - File type checking │ | |
| │ - Size limits │ | |
| │ - Error handling │ | |
| │ │ | |
| │ 3. Authentication (optional) │ | |
| │ - API keys │ | |
| │ - OAuth2 │ | |
| │ - JWT tokens │ | |
| │ │ | |
| │ 4. Infrastructure │ | |
| │ - Container isolation │ | |
| │ - Resource limits │ | |
| │ - Secrets management │ | |
| └─────────────────────────────────────┘ | |
| ``` | |
| --- | |
| ## Monitoring & Observability | |
| ``` | |
| ┌─────────────────────────────────────┐ | |
| │ Monitoring Stack │ | |
| ├─────────────────────────────────────┤ | |
| │ Logs │ | |
| │ - Application logs (Python) │ | |
| │ - Access logs (Uvicorn) │ | |
| │ - Error logs │ | |
| │ │ | |
| │ Metrics │ | |
| │ - Request count │ | |
| │ - Latency (p50, p95, p99) │ | |
| │ - Error rate │ | |
| │ - Model inference time │ | |
| │ - Resource usage (CPU/RAM/GPU) │ | |
| │ │ | |
| │ Health Checks │ | |
| │ - /health endpoint │ | |
| │ - Model loaded status │ | |
| │ - Device availability │ | |
| │ │ | |
| │ Tools │ | |
| │ - TensorBoard (training) │ | |
| │ - CloudWatch/Stackdriver (cloud) │ | |
| │ - Prometheus + Grafana (optional) │ | |
| └─────────────────────────────────────┘ | |
| ``` | |
| --- | |
| This architecture provides: | |
| - ✅ Modularity and separation of concerns | |
| - ✅ Scalability (horizontal and vertical) | |
| - ✅ Multiple deployment options | |
| - ✅ Production-ready monitoring | |
| - ✅ Security best practices | |
| - ✅ High availability potential | |