docs: add comprehensive README and project scaffolding
- README completo con istruzioni di installazione, configurazione e utilizzo - API Swagger/OpenAPI documentata - File env.example con variabili di configurazione - Dockerfile multi-stage ottimizzato - Docker Compose con Ollama e LLM Monitor - Struttura completa dell'app FastAPI (main.py, config, api routes) - Servizio client Ollama reusabile - Dashboard web HTML con TailwindCSS - Test suite con pytest - Makefile per comandi comuni - CONTRIBUTING.md per i contributori - LICENSE MIT - .editorconfig e .dockerignore - requirements.txt e requirements-dev.txt
This commit is contained in:
Luca Sacchi Ricciardi
@@ -0,0 +1,381 @@
|
||||
# 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)
|
||||
- 🔌 **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
|
||||
|
||||
```bash
|
||||
git clone https://github.com/LucaSacchiNet/llm-monitor.git
|
||||
cd llm-monitor
|
||||
```
|
||||
|
||||
### 2. Configurare l'ambiente
|
||||
|
||||
Copia il file di esempio:
|
||||
|
||||
```bash
|
||||
cp env.example .env
|
||||
```
|
||||
|
||||
Modifica `.env` con i tuoi parametri (vedi [Configurazione](#configurazione)):
|
||||
|
||||
```bash
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 3. Installare le dipendenze
|
||||
|
||||
#### Opzione A: Ambiente virtuale (Sviluppo)
|
||||
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Su Windows: venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
#### Opzione B: Docker (Produzione)
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 4. Avviare l'applicazione
|
||||
|
||||
#### Modalità sviluppo
|
||||
|
||||
```bash
|
||||
python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
#### Modalità produzione
|
||||
|
||||
```bash
|
||||
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`):
|
||||
|
||||
```env
|
||||
# Ollama Configuration
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
OLLAMA_TIMEOUT=30
|
||||
|
||||
# API Configuration
|
||||
API_HOST=0.0.0.0
|
||||
API_PORT=8000
|
||||
API_WORKERS=4
|
||||
|
||||
# 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 |
|
||||
| `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
|
||||
|
||||
```bash
|
||||
GET /api/v1/models
|
||||
```
|
||||
|
||||
**Risposta:**
|
||||
|
||||
```json
|
||||
{
|
||||
"models": [
|
||||
{
|
||||
"name": "llama2",
|
||||
"digest": "abc123...",
|
||||
"size": 3825922048,
|
||||
"modified_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Dettagli di un modello specifico
|
||||
|
||||
```bash
|
||||
GET /api/v1/models/{model_name}
|
||||
```
|
||||
|
||||
#### Health check API Ollama
|
||||
|
||||
```bash
|
||||
GET /api/v1/health
|
||||
```
|
||||
|
||||
**Risposta:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"ollama_version": "0.1.0",
|
||||
"uptime_seconds": 3600
|
||||
}
|
||||
```
|
||||
|
||||
### Test API con cURL
|
||||
|
||||
```bash
|
||||
# Ottenere i modelli
|
||||
curl http://localhost:8000/api/v1/models
|
||||
|
||||
# Ottenere info su un modello
|
||||
curl http://localhost:8000/api/v1/models/llama2
|
||||
|
||||
# Health check
|
||||
curl http://localhost:8000/api/v1/health
|
||||
```
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
### Build dell'immagine
|
||||
|
||||
```bash
|
||||
docker build -t llm-monitor:latest .
|
||||
```
|
||||
|
||||
### Eseguire il container
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# Avviare i servizi
|
||||
docker compose up -d
|
||||
|
||||
# Visualizzare i log
|
||||
docker compose logs -f llm-monitor
|
||||
|
||||
# Fermare i servizi
|
||||
docker compose down
|
||||
|
||||
# Riavviare
|
||||
docker compose restart llm-monitor
|
||||
```
|
||||
|
||||
### Container sempre acceso
|
||||
|
||||
Il container Ollama rimarrà in esecuzione fino al suo arresto manuale:
|
||||
|
||||
```bash
|
||||
# Fermare
|
||||
docker compose stop ollama
|
||||
# oppure
|
||||
docker stop llm-monitor
|
||||
|
||||
# Riavviare
|
||||
docker compose start ollama
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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](#docker))
|
||||
|
||||
### Errore: "Port 8000 already in use"
|
||||
|
||||
```bash
|
||||
# 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](https://lucasacchi.net)**
|
||||
|
||||
**Versione**: 1.0.0
|
||||
**Ultima modifica**: Aprile 2026
|
||||
**Status**: 🟢 In Development
|
||||
Reference in New Issue
Block a user