Alibi Detect Logo

Alibi Detect è una libreria Python con sorgente disponibile, focalizzata sulla rilevazione di outlier, adversarial e drift. Il pacchetto mira a coprire rilevatori sia online che offline per dati tabellari, testo, immagini e serie temporali. Sia i backend TensorFlow che PyTorch sono supportati per la rilevazione del drift.

Documentazione

Per maggiori informazioni sull'importanza del monitoraggio di outlier e distribuzioni in un contesto di produzione, dai un'occhiata a questo talk del workshop Challenges in Deploying and Monitoring Machine Learning Systems ICML 2020, basato sull'articolo Monitoring and explainability of models in production e che fa riferimento ad Alibi Detect.

Per un'introduzione approfondita alla rilevazione del drift, guarda Protecting Your Machine Learning Against Drift: An Introduction. Il talk spiega cos'è il drift, perché conviene rilevarlo, i diversi tipi di drift, come può essere rilevato in modo rigoroso e descrive anche l'anatomia di un rilevatore di drift.

Installazione e Utilizzo

Il pacchetto alibi-detect può essere installato da:

PyPI o sorgente GitHub (con pip)
Anaconda (con conda/mamba)

Con pip

alibi-detect può essere installato da PyPI: ```bash pip install alibi-detect
In alternativa, è possibile installare la versione di sviluppo: ```bash pip install git+https://github.com/SeldonIO/alibi-detect.git
Per installare con il backend TensorFlow: ```bash pip install alibi-detect[tensorflow]
Per installare con il backend PyTorch: ```bash pip install alibi-detect[torch]
Per installare con il backend KeOps: ```bash pip install alibi-detect[keops]
Per utilizzare il rilevatore di outlier per serie temporali Prophet: ```bash pip install alibi-detect[prophet]

Con conda

Per installare da conda-forge è consigliato usare mamba, che può essere installato nell'ambiente conda base con:```bash conda install mamba -n base -c conda-forge

Per installare alibi-detect:```bash
mamba install -c conda-forge alibi-detect

Usage

Useremo il rilevatore di anomalie VAE per illustrare l'API.```python from alibi_detect.od import OutlierVAE from alibi_detect.saving import save_detector, load_detector

initialize and fit detector

od = OutlierVAE(threshold=0.1, encoder_net=encoder_net, decoder_net=decoder_net, latent_dim=1024) od.fit(x_train)

make predictions

preds = od.predict(x_test)

save and load detectors

filepath = './my_detector/' save_detector(od, filepath) od = load_detector(filepath)

Le previsioni vengono restituite in un dizionario con come chiavi `meta` e `data`. `meta` contiene i metadati del rilevatore mentre `data` è a sua volta un dizionario con le previsioni effettive. Include i punteggi e le soglie per outlier, adversarial o drift, nonché le previsioni relative a se le istanze sono, ad esempio, outlier o meno. I dettagli esatti possono variare leggermente da un metodo all'altro, per cui invitiamo il lettore a familiarizzare con i [tipi di algoritmi supportati](https://docs.seldon.io/projects/alibi-detect/en/stable/overview/algorithms.html).

## Algoritmi supportati

Le seguenti tabelle mostrano i casi d'uso consigliati per ciascun algoritmo. La colonna *Livello della feature* indica se il rilevamento può essere effettuato a livello di feature, ad esempio per pixel per un'immagine. Consulta l'[elenco di riferimento degli algoritmi](#reference-list) per ulteriori informazioni con collegamenti alla documentazione e agli articoli originali, nonché esempi per ciascuno dei rilevatori.

### Rilevamento di outlier

| Rilevatore             | Tabellare | Immagine | Serie temporali | Testo | Feature categoriche | Online | Livello della feature |
|:---------------------|:-------:|:-----:|:-----------:|:----:|:--------------------:|:------:|:-------------:|
| Isolation Forest     |    ✔    |       |             |      |          ✔           |        |               |
| Mahalanobis Distance |    ✔    |       |             |      |          ✔           |   ✔    |               |
| AE                   |    ✔    |   ✔   |             |      |                      |        |       ✔       |
| VAE                  |    ✔    |   ✔   |             |      |                      |        |       ✔       |
| AEGMM                |    ✔    |   ✔   |             |      |                      |        |               |
| VAEGMM               |    ✔    |   ✔   |             |      |                      |        |               |
| Likelihood Ratios    |    ✔    |   ✔   |      ✔      |      |          ✔           |        |       ✔       |
| Prophet              |         |       |      ✔      |      |                      |        |               |
| Spectral Residual    |         |       |      ✔      |      |                      |   ✔    |       ✔       |
| Seq2Seq              |         |       |      ✔      |      |                      |        |       ✔       |

### Rilevamento adversarial

| Rilevatore           | Tabellare | Immagine | Serie temporali | Testo | Feature categoriche | Online | Livello della feature |
| :---               |  :---:  | :---: |:-----------:|:----:|:--------------------:|:------:|:-------------:|
| Adversarial AE     | ✔       | ✔     |             |      |                      |        |               |
| Model distillation | ✔       | ✔     |      ✔      |  ✔   |          ✔           |        |               |

### Rilevamento del drift

| Rilevatore                         | Tabellare | Immagine | Serie temporali | Testo  | Feature categoriche | Online | Livello della feature |
|:---------------------------------|  :---:  | :---: |   :---:     | :---: |   :---:              | :---:  | :---:         |
| Kolmogorov-Smirnov               | ✔       | ✔     |             | ✔     | ✔                    |        | ✔             |
| Cramér-von Mises                 | ✔       | ✔     |             |       |                      | ✔      | ✔             |
| Fisher's Exact Test              | ✔       |       |             |       | ✔                    | ✔      | ✔             |
| Maximum Mean Discrepancy (MMD)   | ✔       | ✔     |             | ✔     | ✔                    | ✔      |               |
| Learned Kernel MMD               | ✔       | ✔     |             | ✔     | ✔                    |        |               |
| Context-aware MMD                | ✔       | ✔     |  ✔          | ✔     | ✔                    |        |               |
| Least-Squares Density Difference | ✔       | ✔     |             | ✔     | ✔                    | ✔      |               |
| Chi-Squared                      | ✔       |       |             |       | ✔                    |        | ✔             |
| Mixed-type tabular data          | ✔       |       |             |       | ✔                    |        | ✔             |
| Classifier                       | ✔       | ✔     |  ✔          | ✔     | ✔                    |        |               |
| Spot-the-diff                    | ✔       | ✔     |  ✔          | ✔     | ✔                    |        | ✔             |
| Classifier Uncertainty           | ✔       | ✔     |  ✔          | ✔     | ✔                    |        |               |
| Regressor Uncertainty            | ✔       | ✔     |  ✔          | ✔     | ✔                    |        |               |

#### Supporto per TensorFlow e PyTorch

I rilevatori di drift supportano i backend TensorFlow, PyTorch e (dove applicabile) [KeOps](https://www.kernel-operations.io/keops/index.html). 
Tuttavia, Alibi Detect non li installa di default. Vedi le [opzioni di installazione](#installation-and-usage) per maggiori dettagli.```python
from alibi_detect.cd import MMDDrift

cd = MMDDrift(x_ref, backend='tensorflow', p_val=.05)
preds = cd.predict(x)

Lo stesso detector in PyTorch:```python cd = MMDDrift(x_ref, backend='pytorch', p_val=.05) preds = cd.predict(x)

Oppure in KeOps:```python
cd = MMDDrift(x_ref, backend='keops', p_val=.05)
preds = cd.predict(x)

Passaggi di pre-elaborazione integrati

Alibi Detect include anche vari passaggi di pre-elaborazione come encoder inizializzati casualmente, embedding di testo pre-addestrati per rilevare il drift usando la libreria transformers e l'estrazione di livelli nascosti da modelli di machine learning. Questo consente di rilevare diversi tipi di drift come spostamento della distribuzione covariata e prevista. I passaggi di pre-elaborazione sono supportati anche in TensorFlow e PyTorch.```python from alibi_detect.cd.tensorflow import HiddenOutput, preprocess_drift

model = # TensorFlow model; tf.keras.Model or tf.keras.Sequential preprocess_fn = partial(preprocess_drift, model=HiddenOutput(model, layer=-1), batch_size=128) cd = MMDDrift(x_ref, backend='tensorflow', p_val=.05, preprocess_fn=preprocess_fn) preds = cd.predict(x)

Consulta i notebook di esempio (ad es. [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_mmd_cifar10.html), [recensioni di film](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_text_imdb.html)) per ulteriori dettagli.

### Elenco dei riferimenti

#### Rilevamento anomalie

- [Isolation Forest](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/iforest.html) ([FT Liu et al., 2008](https://cs.nju.edu.cn/zhouzh/zhouzh.files/publication/icdm08b.pdf))
   - Esempio: [Intrusione di rete](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_if_kddcup.html)

- [Mahalanobis Distance](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/mahalanobis.html) ([Mahalanobis, 1936](https://insa.nic.in/writereaddata/UpLoadedFiles/PINSA/Vol02_1936_1_Art05.pdf))
   - Esempio: [Intrusione di rete](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_mahalanobis_kddcup.html)

- [Auto-Encoder (AE)](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/ae.html)
   - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_ae_cifar10.html)

- [Variational Auto-Encoder (VAE)](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/vae.html) ([Kingma et al., 2013](https://arxiv.org/abs/1312.6114))
   - Esempi: [Intrusione di rete](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_vae_kddcup.html), [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_vae_cifar10.html)

- [Auto-Encoding Gaussian Mixture Model (AEGMM)](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/aegmm.html) ([Zong et al., 2018](https://openreview.net/forum?id=BJJLHbb0-))
   - Esempio: [Intrusione di rete](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_aegmm_kddcup.html)

- [Variational Auto-Encoding Gaussian Mixture Model (VAEGMM)](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/vaegmm.html)
   - Esempio: [Intrusione di rete](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_aegmm_kddcup.html)
     
- [Likelihood Ratios](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/llr.html) ([Ren et al., 2019](https://arxiv.org/abs/1906.02845))
   - Esempi: [Genoma](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_llr_genome.html), [Fashion-MNIST vs. MNIST](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_llr_mnist.html)

- [Prophet Time Series Outlier Detector](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/prophet.html) ([Taylor et al., 2018](https://peerj.com/preprints/3190/))
   - Esempio: [Previsioni meteo](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_prophet_weather.html)
  
- [Spectral Residual Time Series Outlier Detector](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/sr.html) ([Ren et al., 2019](https://arxiv.org/abs/1906.03821))
   - Esempio: [Dataset sintetico](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_sr_synth.html)

- [Sequence-to-Sequence (Seq2Seq) Outlier Detector](https://docs.seldon.io/projects/alibi-detect/en/stable/od/methods/seq2seq.html) ([Sutskever et al., 2014](https://papers.nips.cc/paper/5346-sequence-to-sequence-learning-with-neural-networks.pdf); [Park et al., 2017](https://arxiv.org/pdf/1711.00614.pdf))
   - Esempi: [ECG](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_seq2seq_ecg.html), [Dataset sintetico](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/od_seq2seq_synth.html)
  
#### Rilevamento avversariale

- [Adversarial Auto-Encoder](https://docs.seldon.io/projects/alibi-detect/en/stable/ad/methods/adversarialae.html) ([Vacanti and Van Looveren, 2020](https://arxiv.org/abs/2002.09364))
   - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/ad_ae_cifar10.html)

- [Model distillation](https://docs.seldon.io/projects/alibi-detect/en/stable/ad/methods/modeldistillation.html) 
   - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_distillation_cifar10.html)
     
#### Rilevamento del drift

- [Kolmogorov-Smirnov](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/ksdrift.html)
   - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_ks_cifar10.html), [grafi molecolari](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_mol.html), [recensioni di film](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_text_imdb.html)

- [Cramér-von Mises](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/cvmdrift.html)
  - Esempio: [Pinguini](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_supervised_penguins.html)

- [Fisher's Exact Test](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/fetdrift.html)
  - Esempio: [Pinguini](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_supervised_penguins.html)

- [Least-Squares Density Difference](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/lsdddrift.html) ([Bu et al, 2016](https://alippi.faculty.polimi.it/articoli/A%20Pdf%20free%20Change%20Detection%20Test%20Based%20on%20Density%20Difference%20Estimation.pdf))

- [Maximum Mean Discrepancy](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/mmddrift.html) ([Gretton et al, 2012](http://jmlr.csail.mit.edu/papers/v13/gretton12a.html))
   - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_mmd_cifar10.html), [grafi molecolari](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_mol.html), [recensioni di film](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_text_imdb.html), [recensioni Amazon](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_text_amazon.html)

- [Learned Kernel MMD](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/learnedkerneldrift.html) ([Liu et al, 2020](https://arxiv.org/abs/2002.09116))
  - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_clf_cifar10.html)

- [Context-aware MMD](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/contextmmddrift.html) ([Cobb and Van Looveren, 2022](https://arxiv.org/abs/2203.08644))
  - Esempio: [ECG](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_context_ecg.html), [argomenti di notizie](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_context_20newsgroup.html)

- [Chi-Squared](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/chisquaredrift.html)
   - Esempio: [Previsione del reddito](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_chi2ks_adult.html)

- [Mixed-type tabular data](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/tabulardrift.html)
   - Esempio: [Previsione del reddito](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_chi2ks_adult.html)

- [Classifier](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/classifierdrift.html) ([Lopez-Paz and Oquab, 2017](https://openreview.net/forum?id=SJkXfE5xx))
   - Esempio: [CIFAR10](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_clf_cifar10.html), [recensioni Amazon](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_text_amazon.html)

- [Spot-the-diff](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/spotthediffdrift.html) (adattamento di [Jitkrittum et al, 2016](https://arxiv.org/abs/1605.06796))
  - Esempio [MNIST e qualità del vino](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/spot_the_diff_mnist_win.html)

- [Classifier and Regressor Uncertainty](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/modeluncdrift.html)
   - Esempio: [CIFAR10 e vino](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_model_unc_cifar10_wine.html), [grafi molecolari](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_mol.html)

- [Online Maximum Mean Discrepancy](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/onlinemmddrift.html)
  - Esempio: [Qualità del vino](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_online_wine.html), [imaging medico Camelyon](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_online_camelyon.html)
  
- [Online Least-Squares Density Difference](https://docs.seldon.io/projects/alibi-detect/en/stable/cd/methods/onlinemmddrift.html) ([Bu et al, 2017](https://ieeexplore.ieee.org/abstract/document/7890493))
  - Esempio: [Qualità del vino](https://docs.seldon.io/projects/alibi-detect/en/stable/examples/cd_online_wine.html)


## Dataset

Il pacchetto contiene anche funzionalità in `alibi_detect.datasets` per recuperare facilmente una serie di dataset per diverse modalità. Per ogni dataset vengono restituiti i dati e le etichette, oppure un oggetto *Bunch* con dati, etichette e metadati opzionali. Esempio:```python
from alibi_detect.datasets import fetch_ecg

(X_train, y_train), (X_test, y_test) = fetch_ecg(return_X_y=True)

Dati Sequenziali e Serie Temporali

Genome Dataset: fetch_genome
- Dataset di genomica batterica per il rilevamento out-of-distribution, rilasciato come parte di Likelihood Ratios for Out-of-Distribution Detection. Dal TL;DR originale: Il dataset contiene sequenze genomiche di 250 coppie di basi provenienti da 10 classi di batteri in-distribution per l'addestramento, 60 classi di batteri OOD per la validazione e altre 60 classi di batteri OOD diverse per il test. Ci sono rispettivamente 1, 7 e di nuovo 7 milioni di sequenze nei set di training, validazione e test. Per informazioni dettagliate sul dataset, consulta il README. ```python from alibi_detect.datasets import fetch_genome
(X_train, y_train), (X_val, y_val), (X_test, y_test) = fetch_genome(return_X_y=True)
ECG 5000: fetch_ecg
- 5000 ECG, originariamente ottenuti da Physionet.
NAB: fetch_nab
- Qualsiasi serie temporale univariata in un DataFrame del Numenta Anomaly Benchmark. È possibile ottenere un elenco delle serie temporali disponibili utilizzando alibi_detect.datasets.get_list_nab().

Images

CIFAR-10-C: fetch_cifar10c
- CIFAR-10-C (Hendrycks & Dietterich, 2019) contiene il set di test di CIFAR-10, ma corrotto e perturbato da vari tipi di rumore, sfocatura, luminosità, ecc. a diversi livelli di gravità, portando a un progressivo calo delle prestazioni di un modello di classificazione addestrato su CIFAR-10. fetch_cifar10c consente di scegliere qualsiasi livello di gravità o tipo di corruzione. L'elenco dei tipi di corruzione disponibili può essere recuperato con alibi_detect.datasets.corruption_types_cifar10c(). Il dataset può essere utilizzato nella ricerca su robustezza e drift. I dati originali si trovano qui. Esempio: ```python from alibi_detect.datasets import fetch_cifar10c
corruption = ['gaussian_noise', 'motion_blur', 'brightness', 'pixelate'] X, y = fetch_cifar10c(corruption=corruption, severity=5, return_X_y=True)
CIFAR-10 avversariale: fetch_attack
- Carica istanze avversariali su un classificatore ResNet-56 addestrato su CIFAR-10. Attacchi disponibili: Carlini-Wagner ('cw') e SLIDE ('slide'). Esempio: ```python from alibi_detect.datasets import fetch_attack
(X_train, y_train), (X_test, y_test) = fetch_attack('cifar10', 'resnet56', 'cw', return_X_y=True)

Tabellare

KDD Cup '99: fetch_kdd
- Dataset con diversi tipi di intrusioni di rete informatica. fetch_kdd ti consente di selezionare un sottoinsieme di intrusioni di rete come target o di scegliere solo caratteristiche specifiche. I dati originali possono essere trovati qui.

Modelli

I modelli e/o i componenti che possono essere utili al di fuori del rilevamento di outlier, avversariale o di deriva si trovano in alibi_detect.models. Implementazioni principali:

PixelCNN++: alibi_detect.models.pixelcnn.PixelCNN
Autoencoder variazionale: alibi_detect.models.autoencoder.VAE
Modello sequence-to-sequence: alibi_detect.models.autoencoder.Seq2Seq
ResNet: alibi_detect.models.resnet
- I modelli ResNet-20/32/44 pre-addestrati su CIFAR-10 possono essere trovati sul nostro Google Cloud Bucket e possono essere recuperati come segue: ```python from alibi_detect.utils.fetching import fetch_tf_model
model = fetch_tf_model('cifar10', 'resnet32')

Integrations

Alibi-detect è integrato nella piattaforma di deployment di modelli di machine learning Seldon Core e nel framework di model serving KFServing.

Seldon Core: esempi pratici di rilevamento di outlier e drift.
KFServing: esempi di rilevamento di outlier e drift.

Citazioni

Se utilizzi alibi-detect nella tua ricerca, ti preghiamo di considerare di citarlo.

Voce BibTeX:``` @software{alibi-detect, title = {Alibi Detect: Algorithms for outlier, adversarial and drift detection}, author = {Van Looveren, Arnaud and Klaise, Janis and Vacanti, Giovanni and Cobb, Oliver and Scillitoe, Ashley and Samoilescu, Robert and Athorne, Alex}, url = {https://github.com/SeldonIO/alibi-detect}, version = {0.13.0}, date = {2025-12-11}, year = {2019} }

alibi-detect

Più Popolari