Guide Lines

Linee guida di sviluppo e rilascio servizi

1. Scopo

Ogni servizio ML deve essere sviluppato e rilasciato come un normale servizio software containerizzato, mantenendo però separati e tracciabili:

codice applicativo+modello+configurazione\text{codice applicativo} + \text{modello} + \text{configurazione}

Una release deve permettere di identificare senza ambiguità:

Git commit
Docker image + digest
Model name + version + hash
Model format/precision
Runtime
Configuration

Gli ambienti standard sono:

DEV → COLLAUDO → PROD

La stessa immagine Docker e lo stesso model artifact validati in collaudo devono essere promossi in produzione. Non devono essere ricostruiti.

---

2. Architettura standard

Ogni servizio ML espone una propria API FastAPI ed esegue l'inferenza direttamente nel container.

Client
  ↓
FastAPI
  ↓
Preprocessing
  ↓
Inference Runtime
  ↓
Postprocessing
  ↓
Response

Sulle VM NVIDIA il servizio viene eseguito tramite Docker/Compose con accesso alla GPU.

Non viene introdotto un model server centralizzato salvo esigenze future.

Runtime raccomandati:

Caso	Runtime
sviluppo/compatibilità specifica	PyTorch
deployment generico	ONNX Runtime
NVIDIA ottimizzato	ONNX Runtime CUDA / TensorRT
esigenze particolari	motivate e documentate

---

3. Struttura repository

Struttura raccomandata:

project/
├── src/
│   ├── api/
│   ├── inference/
│   │   ├── engine.py
│   │   ├── preprocessing.py
│   │   └── postprocessing.py
│   ├── core/
│   │   └── settings.py
│   └── main.py
│
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── model/
│   └── performance/
│
├── deploy/
│   └── compose.yml
│
├── scripts/
│   ├── fetch_model.py
│   ├── validate_model.py
│   └── benchmark_model.py
│
├── model/
│   └── model-manifest.yaml
│
├── Dockerfile
├── pyproject.toml
├── .gitlab-ci.yml
├── AGENTS.md
└── README.md

I pesi del modello non devono normalmente essere salvati nel repository Git.

---

4. Gestione del modello

Il modello è un artifact indipendente dall'immagine applicativa.

Default:

GitLab Model Registry / Artifact Registry
             ↓
       model version
             ↓
        deploy job
             ↓
      VM model cache
             ↓
mount read-only nel container

Il deploy deve recuperare una versione esatta, mai latest.

Esempio:

MODEL_NAME=ppe-detector
MODEL_VERSION=2.3.1
MODEL_SHA256=...
MODEL_FORMAT=onnx
MODEL_PRECISION=fp16

Il modello viene scaricato prima dell'avvio del nuovo container, verificato tramite hash e montato read-only.

Se la versione è già presente nella cache della VM e l'hash coincide, può essere riutilizzata.

Incorporare il modello nella Docker image è ammesso solo quando modello e codice hanno un ciclo di rilascio necessariamente indivisibile o per servizi molto semplici. Deve essere una scelta esplicita.

---

5. Model manifest

Ogni model artifact deve avere metadata associati almeno equivalenti a:

name: ppe-detector
version: 2.3.1

format: onnx
precision: fp16
sha256: ...

base_model: ...

input:
  shape: ...
  dtype: ...
  color_space: RGB

preprocessing_version: "1"
postprocessing_version: "2"

training:
  dataset_version: ...
  git_commit: ...

metrics:
  primary_metric: ...
  value: ...

runtime:
  recommended: onnxruntime-gpu

Preprocessing e postprocessing fanno parte del contratto del modello.

Una modifica incompatibile dell'input/output deve comportare una nuova versione major del model contract.

---

6. Ottimizzazione del modello

Il modello utilizzato durante il training non è automaticamente il modello da utilizzare in produzione.

Flusso raccomandato:

training artifact
      ↓
baseline benchmark
      ↓
export
      ↓
ONNX
      ↓
equivalence test
      ↓
FP16 / graph optimization
      ↓
benchmark
      ↓
eventuale INT8 / TensorRT
      ↓
quality + performance gate
      ↓
deployment artifact

Ogni ottimizzazione deve essere giustificata da una misura.

Devono essere confrontati almeno:

qualità modello
latenza
throughput
RAM
VRAM
dimensione artifact

FP16 è la prima ottimizzazione da valutare sulle GPU NVIDIA.

INT8 è ammesso solo con calibration dataset rappresentativo e verifica della perdita di qualità.

TensorRT è ammesso quando il miglioramento giustifica la maggiore dipendenza da GPU, CUDA, TensorRT e build environment.

Non è consentito sostituire il deployment artifact senza regression test rispetto al modello di riferimento.

---

7. API obbligatorie

Ogni servizio deve esporre almeno:

GET /health/live
GET /health/ready
GET /info
GET /metrics

/health/live

Verifica esclusivamente che il processo applicativo sia vivo.

Non deve eseguire inferenze complete.

/health/ready

Restituisce 200 solamente se:

modello caricato
hash verificato
runtime inizializzato
GPU disponibile se obbligatoria
warmup completato
dipendenze indispensabili disponibili

Se il servizio richiede GPU, il fallback silenzioso su CPU non è consentito salvo configurazione esplicita.

/info

Deve rendere disponibili almeno:

{
  "app_version": "...",
  "git_sha": "...",
  "model_name": "...",
  "model_version": "...",
  "model_format": "...",
  "precision": "...",
  "runtime": "..."
}

Non deve esporre secret.

/metrics

Deve essere compatibile con il sistema di monitoring adottato e separare almeno tempi HTTP e tempi effettivi di inferenza.

---

8. Warmup

Il modello deve essere caricato prima che il servizio risulti ready.

Quando necessario deve essere effettuato un warmup:

process start
    ↓
load model
    ↓
initialize CUDA/runtime
    ↓
warmup inference
    ↓
READY

Il traffico non deve raggiungere una nuova istanza prima del completamento.

---

9. Logging

Il logging applicativo deve essere strutturato, preferibilmente JSON, e scritto su stdout/stderr.

Ogni inference deve poter essere correlata tramite un request_id.

Campi raccomandati:

timestamp
level
service
request_id
git_sha
model_name
model_version
latency_ms
preprocess_ms
inference_ms
postprocess_ms
status
error_type

Immagini, video o payload sensibili non vengono loggati automaticamente.

Eventuali log degli output ML devono essere campionati o aggregati per evitare volumi ingestibili.

Non utilizzare request_id, user id o valori ad alta cardinalità come label Prometheus.

---

10. Monitoring

Ogni servizio deve permettere di monitorare quattro livelli.

Livello	Metriche
Container/VM	CPU, RAM, restart, disk
GPU	utilization, VRAM, temperatura
API	request rate, error rate, P50/P95/P99
ML	preprocess, inference, postprocess, confidence/output distribution

Quando significativo devono essere aggiunte metriche di dominio.

Esempio CV:

FPS
frames dropped
detections/frame
confidence distribution
invalid frames
blur/brightness
queue length

Lo stato HTTP 200 non è sufficiente per considerare sano un sistema ML.

---

11. Docker

Le immagini devono essere costruite esclusivamente dalla CI.

In collaudo e produzione il Compose deve utilizzare:

image: registry/...@sha256:...

o una versione immutabile equivalente.

Sulle VM remote non deve essere presente:

build:

La stessa image digest deve attraversare:

COLLAUDO → PROD

Il container deve essere il più possibile minimale, eseguito come utente non root e privo delle dipendenze di training quando non necessarie all'inference.

---

12. Configurazione

La configurazione varia tra ambienti, gli artifact no.

image = immutabile
model = immutabile
configuration = environment-specific

Secret, token di registry e credenziali devono provenire da GitLab CI/CD Variables o dal sistema di secret adottato.

Non devono essere versionati file .env contenenti credenziali.

---

13. Pipeline GitLab

Pipeline minima:

quality
   ↓
tests
   ↓
model validation
   ↓
build image
   ↓
push registry
   ↓
deploy COLLAUDO [manual]
   ↓
smoke/integration/performance test
   ↓
deploy PROD [manual]

La CI deve almeno verificare:

lint/type checks
unit tests
API tests
model loading
model contract
representative inference
model equivalence se esportato/ottimizzato
Docker build

Il deployment in collaudo e produzione deve utilizzare la stessa Docker image già costruita.

GitLab raccomanda anch'esso tag immutabili basati sul commit invece di costruire direttamente su latest.

---

14. Collaudo

Il collaudo deve riprodurre quanto più possibile la configurazione di produzione.

Prima della promozione devono essere verificati:

container health
GPU/runtime
model version
API contract
representative inference
logging
metrics
latency
VRAM
assenza di regressioni note

Il deploy PROD è consentito solamente dopo il superamento del collaudo.

---

15. Release manifest

Ogni rilascio deve produrre un manifest equivalente a:

service: ppe-service
release: 3.4.0

git_sha: 7e91ac2

image:
  digest: sha256:...

model:
  name: ppe-detector
  version: 2.3.1
  sha256: ...
  format: onnx
  precision: fp16

Questo è il riferimento per deploy, incident analysis e rollback.

---

16. Rollback

Il rollback non deve richiedere una nuova build.

Deve essere sufficiente ripristinare:

previous IMAGE_DIGEST
previous MODEL_VERSION

Le VM devono mantenere almeno le versioni recenti necessarie a effettuare un rollback rapido.

---

17. Definition of Done

Un servizio ML non è pronto al rilascio se manca uno di questi elementi:

container riproducibile
modello versionato
model manifest
health/live
health/ready
info endpoint
metrics
structured logging
test inferenza
CI
compose
collaudo
release manifest
rollback definito

La performance ML, la performance software e l'operabilità in produzione sono tutte parte della qualità del servizio.