🔌 Ollama Bridge Service

Service sidecar FastAPI pour résilience et fiabilité Ollama

Architecture Sidecar Bridge

┌────────────────────────────────────┐
│   COSMIC Orchestrator (Main API)  │
│         Port 8100                  │
└──────────────┬─────────────────────┘
               │
               │ HTTP Request
               │ (internal network)
               ▼
    ┌──────────────────────┐
    │  🔌 Ollama Bridge    │
    │  FastAPI Service     │
    │  Port 8200           │
    │                      │
    │  • Retry Logic       │
    │  • Circuit Breaker   │
    │  • Health Checks     │
    └──────────┬───────────┘
               │
               │ Resilient Connection
               │ (with retries)
               ▼
    ┌──────────────────────┐
    │  🏠 Ollama Host      │
    │  Mac Studio M2       │
    │  Port 11434          │
    │                      │
    │  • deepseek-r1:1.5b  │
    │  • nomic-embed-text  │
    └──────────────────────┘

┌─────────────────────────────────┐
│  Failure Handling               │
│  ────────────────               │
│  1. Request fails → Retry       │
│  2. 3 retries fail → Circuit    │
│  3. Circuit open → Fast fail    │
│  4. After 60s → Half-open test  │
│  5. Success → Circuit closed    │
└─────────────────────────────────┘

4 Étapes du Process

Request Interception

API Gateway intercepte les requêtes Ollama

FastAPI endpoint exposure
Request validation
Authentication check
Rate limiting

Retry Logic

Gestion intelligente des échecs temporaires

Exponential backoff (2s → 4s → 8s)
Max 3 retry attempts
Jitter randomization
Request idempotency

Circuit Breaker

Protection contre les défaillances en cascade

Failure threshold: 5 errors/30s
Half-open state after 60s
Health check endpoints
Automatic recovery

Response Processing

Normalisation et validation des réponses

JSON schema validation
Error handling
Metric collection
Logging & tracing

Spécifications Techniques

Service Port

8200

FastAPI HTTP

Max Retries

with backoff

Circuit Threshold

5/30s

errors per window

Recovery Time

60s

half-open state

Request Timeout

30s

per attempt

Uptime

100%

production validated

💡 Avantages Clés

Résilience: Retry logic élimine les échecs temporaires
Protection: Circuit breaker évite les cascades de pannes
Découplage: API principale indépendante de la stabilité Ollama
Monitoring: Métriques détaillées sur santé et performance
Production-ready: 100% uptime validé en charge réelle

Configuration Docker

cosmic-ollama-bridge:
  image: tiangolo/uvicorn-gunicorn-fastapi:python3.11
  container_name: cosmic-ollama-bridge
  ports:
    - "8200:8200"
  environment:
    OLLAMA_HOST: host.docker.internal:11434
    MAX_RETRIES: 3
    CIRCUIT_THRESHOLD: 5
    CIRCUIT_TIMEOUT: 60
  networks:
    - cosmic-network
  restart: unless-stopped