LLM Monitor - Dashboard Ollama

Una dashboard web moderna e intuitiva per monitorare e gestire i modelli LLM caricati in Ollama. Visualizza i modelli disponibili, i dettagli dei caricamenti e accedi ai dati via API Ollama direttamente da una web app elegante.

🎯 Caratteristiche

• ✨ Dashboard intuitiva - Visualizza in tempo reale i modelli caricati in Ollama
• 📊 Monitoraggio modelli - Dettagli completi di ogni modello (nome, dimensione, memoria, stato)
• 🧩 Dettagli avanzati on click - Clic su una card modello per visualizzare i dati Ollama show
• 🔌 API REST documentata - Documentazione interattiva con Swagger/OpenAPI
• 🎨 UI moderna - Interfaccia elegante realizzata con TailwindCSS
• 🐳 Docker ready - Container sempre acceso (until stopped)
• ⚡ Performance - Costruito su FastAPI e uVicorn
• 🔐 Configurazione flessibile - File .env per personalizzazione

📋 Requisiti

• Python 3.10+
• Ollama installato e in esecuzione
• Docker (opzionale, per containerizzazione)
• Docker Compose (opzionale)

🚀 Installazione Rapida

1. Clonare il repository

git clone https://github.com/LucaSacchiNet/llm-monitor.git
cd llm-monitor

2. Configurare l'ambiente

Copia il file di esempio:

cp env.example .env

Modifica .env con i tuoi parametri (vedi Configurazione):

nano .env

3. Installare le dipendenze

Opzione A: Ambiente virtuale (Sviluppo)

python3 -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate
pip install -r requirements.txt

Opzione B: Docker (Produzione)

docker compose up -d

4. Avviare l'applicazione

Modalità sviluppo

python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Modalità produzione

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

⚙️ Configurazione

Crea un file .env nella root del progetto (copia da env.example):

# Ollama Configuration
OLLAMA_HOST=http://localhost:11434
OLLAMA_TIMEOUT=30

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4
ENABLE_MODEL_RW_API=false

# CORS Configuration
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Logging
LOG_LEVEL=INFO

# Environment
ENVIRONMENT=development

Variabili disponibili

Variabile	Default	Descrizione
OLLAMA_HOST	http://localhost:11434	URL della API Ollama
OLLAMA_TIMEOUT	30	Timeout (secondi) per le richieste
API_HOST	0.0.0.0	Host su cui esporre l'API
API_PORT	8000	Porta dell'API
API_WORKERS	4	Worker processes
ENABLE_MODEL_RW_API	false	Abilita endpoint POST/DELETE sui modelli
CORS_ORIGINS	http://localhost:3000	Origini CORS consentite
LOG_LEVEL	INFO	Livello di logging
ENVIRONMENT	development	Ambiente (development/production)

📚 API Swagger

La documentazione interattiva dell'API è disponibile automaticamente:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Endpoint principali

Recuperare modelli caricati

GET /api/v1/models

Risposta:

{
  "models": [
    {
      "name": "llama2",
      "digest": "abc123...",
      "size": 3825922048,
      "modified_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Dettagli di un modello specifico

GET /api/v1/models/{model_name}

Dettagli estesi da Ollama show

GET /api/v1/models/{model_name}/show

Health check API Ollama

GET /api/v1/health

Endpoint R/W modelli (opzionali)

Per impostazione predefinita gli endpoint di scrittura sono disabilitati e non disponibili.

POST /api/v1/models/{model_name}/pull
DELETE /api/v1/models/{model_name}

Per abilitarli, imposta nel file .env:

ENABLE_MODEL_RW_API=true

Risposta:

{
  "status": "healthy",
  "ollama_version": "0.1.0",
  "uptime_seconds": 3600
}

Test API con cURL

# Ottenere i modelli
curl http://localhost:8000/api/v1/models

# Ottenere info su un modello
curl http://localhost:8000/api/v1/models/llama2

# Ottenere dettagli estesi show
curl http://localhost:8000/api/v1/models/llama2/show

# Health check
curl http://localhost:8000/api/v1/health

Comportamento dashboard

• Al refresh della lista modelli, per ogni modello viene recuperato anche il dettaglio show.
• I dati vengono salvati in localStorage nella chiave llm_monitor_models (campo showByModel).
• Cliccando su una card modello, la dashboard mostra i dettagli show senza ricaricare la pagina.

🐳 Docker

Build dell'immagine

docker build -t llm-monitor:latest .

Eseguire il container

docker run -d \
  --name llm-monitor \
  -p 8000:8000 \
  --env-file .env \
  --network host \
  llm-monitor:latest

⚠️ Nota: --network host consente al container di accedere a Ollama su localhost

Docker Compose

Usa il file docker-compose.yml fornito:

# Avviare i servizi
docker compose up -d

# Rebuild completo senza cache (consigliato dopo modifiche UI/Tailwind)
docker compose build --no-cache

# Verificare che il CSS compilato non sia vuoto
docker exec llm-monitor-app wc -l /app/app/web/static/css/output.css

# Visualizzare i log
docker compose logs -f llm-monitor

# Fermare i servizi
docker compose down

# Riavviare
docker compose restart llm-monitor

Deploy consigliato (Tailwind-safe)

Se l'interfaccia appare senza stili o una modale non si posiziona correttamente, usa il deploy con rebuild no-cache e verifica CSS:

cd /opt/llm-monitor
docker compose down
docker compose build --no-cache
docker compose up -d
sleep 5
docker exec llm-monitor-app wc -l /app/app/web/static/css/output.css

In alternativa dal repository:

make deploy-no-cache

Tailwind Build Process

• Lo stage css-builder del Dockerfile installa dipendenze Node con npm ci.
• Prima della build Tailwind vengono copiati template HTML e JS usati dal content scan.
• Dopo npm run tailwind:build una verifica bloccante controlla che output.css esista e abbia almeno 100 linee.
• Lo stage runtime copia output.css compilato da css-builder con COPY --from=css-builder.

Troubleshooting UI

Se la modale non appare o i componenti sembrano "unstyled":

1. Esegui docker compose build --no-cache.
2. Riavvia con docker compose up -d.
3. Verifica CSS compilato: docker exec llm-monitor-app wc -l /app/app/web/static/css/output.css.
4. Se il numero linee e < 100, la build Tailwind non e riuscita correttamente.

Container sempre acceso

Il container llm-monitor rimarrà in esecuzione fino al suo arresto manuale:

# Fermare
docker compose stop llm-monitor
# oppure
docker stop llm-monitor

# Riavviare
docker compose start llm-monitor
# oppure
docker start llm-monitor

📁 Struttura del Progetto

llm-monitor/
├── main.py                 # Entry point dell'applicazione
├── requirements.txt        # Dipendenze Python
├── env.example            # Esempio di configurazione
├── Dockerfile             # Configurazione Docker
├── docker-compose.yml     # Composizione servizi
├── README.md              # Questo file
├── .gitignore
│
├── app/
│   ├── __init__.py
│   ├── config.py          # Configurazione (variabili ambiente)
│   ├── main.py            # Inizializzazione FastAPI
│   │
│   ├── api/
│   │   ├── __init__.py
│   │   ├── models.py      # Endpoint modelli
│   │   ├── health.py      # Endpoint health
│   │   └── v1/
│   │       └── __init__.py
│   │
│   ├── services/
│   │   ├── __init__.py
│   │   ├── ollama.py      # Client Ollama
│   │   └── cache.py       # Cache in-memory (opzionale)
│   │
│   └── web/
│       ├── __init__.py
│       ├── static/        # Assets statici (CSS compilato TailwindCSS)
│       └── templates/     # Template HTML
│
└── tests/
    ├── __init__.py
    ├── test_api.py
    └── test_ollama.py

🛠️ Sviluppo

Setup locale

# Clonare il repo
git clone https://github.com/LucaSacchiNet/llm-monitor.git
cd llm-monitor

# Ambiente virtuale
python3 -m venv venv
source venv/bin/activate

# Installare dipendenze + dev
pip install -r requirements.txt
pip install -r requirements-dev.txt  # black, pytest, flake8, etc.

Comandi utili

# Formattare codice
black app/ tests/ main.py

# Linting
flake8 app/ tests/ main.py

# Test
pytest tests/ -v

# Test con coverage
pytest tests/ --cov=app

# Hot reload durante sviluppo
uvicorn main:app --reload

Compilare TailwindCSS

# Installare dipendenze Node (opzionale)
npm install

# Generare CSS in modalità développement
npm run tailwind:dev

# Build per produzione
npm run tailwind:build

🐛 Troubleshooting

Errore: "Cannot connect to Ollama"

• Verificare che Ollama sia in esecuzione: curl http://localhost:11434/api/tags
• Controllare che l'indirizzo in .env sia corretto (OLLAMA_HOST)
• Se usi Docker, assicurati che il container abbia accesso a Ollama (vedi Docker)

Errore: "Port 8000 already in use"

# Cambiare la porta in .env
API_PORT=8001

# Oppure liberare la porta
lsof -ti :8000 | xargs kill -9

Dashboard lenta

• Verificare lo stato di Ollama
• Aumentare OLLAMA_TIMEOUT in .env
• Controllare i log: docker compose logs -f llm-monitor

📄 Dipendenze Principali

• FastAPI - Framework web moderno
• uVicorn - Server ASGI ad alte prestazioni
• Pydantic - Validazione dati
• Requests - Client HTTP
• Jinja2 - Template HTML
• TailwindCSS - Utility-first CSS

📜 Licenza

Questo progetto è distribuito sotto licenza MIT. Vedi il file LICENSE per dettagli.

🤝 Contribuire

Le pull request sono benvenute! Per cambiamenti importanti, apri prima un issue per discutere i cambiamenti proposti.

Processo di contribuzione

1. Fork il repository
2. Crea un branch (git checkout -b feature/amazing-feature)
3. Commit i cambiamenti (git commit -m 'Add amazing feature')
4. Push al branch (git push origin feature/amazing-feature)
5. Apri una Pull Request

📞 Supporto

Per domande o segnalazioni di bug, apri un Issue nel repository.

---

Fatto con ❤️ da LucaSacchi.Net

Versione: 1.0.0
Ultima modifica: Aprile 2026
Status: 🟢 In Development