Dashboard di Amministrazione

Potato 2.0 include una dashboard di amministrazione completa per monitorare il progresso delle annotazioni, tenere traccia delle prestazioni degli annotatori e gestire la configurazione del compito in tempo reale.

Accesso alla Dashboard

Autenticazione con Chiave API

Configura una chiave API di amministrazione nella tua configurazione:

admin_api_key: "your-secure-api-key-here"

Accedi alla dashboard su /admin e inserisci la tua chiave API quando richiesto.

Metodi di Autenticazione

1. Navigazione diretta - Vai su /admin e inserisci la chiave API
2. Basata su header - Includi l'header X-API-Key nelle richieste
3. Modalità debug - Con debug: true, le richieste che arrivano dalla macchina stessa del server aprono le pagine di amministrazione senza chiave

La modalità debug apre le pagine di amministrazione senza chiave solo per le richieste che arrivano dalla macchina stessa del server, cioè da un indirizzo di loopback senza intestazione X-Forwarded-For, X-Real-IP o Forwarded. Un tunnel o un reverse proxy sulla stessa macchina che non aggiunge alcuna intestazione di inoltro fa sembrare locale ogni chiamante, quindi non attivare mai debug su un server in produzione:

# Development only
debug: true  # Admin pages open without a key for requests from this machine

Schede della Dashboard

Scheda Panoramica

Metriche di alto livello per il tuo compito di annotazione:

• Utenti Totali - Numero di annotatori registrati
• Annotazioni Totali - Totale delle annotazioni completate
• Tasso di Completamento - Percentuale di dati annotati
• Sessioni Attive - Annotatori attualmente attivi
• Configurazione Compito - Riepilogo delle impostazioni attuali

Scheda Annotatori

Informazioni dettagliate su ciascun annotatore:

Funzionalità:

• Ordina per qualsiasi colonna
• Filtra per fase o attività
• Esporta i dati degli annotatori
• Visualizza i dettagli del singolo annotatore

Scheda Istanze

Sfoglia e gestisci le istanze di annotazione:

Funzionalità:

• Paginazione (25, 50 o 100 per pagina)
• Ordina per annotazioni, disaccordo, ecc.
• Filtra per numero di annotazioni
• Visualizza i dettagli completi dell'istanza

Scheda Configurazione

Modifica le impostazioni in tempo reale senza riavviare:

• Annotazioni Massime per Utente - Limita quanti elementi può annotare ciascun utente
• Annotazioni Massime per Elemento - Annotazioni target per istanza
• Strategia di Assegnazione - Come vengono assegnate le istanze agli utenti

Le modifiche hanno effetto immediato.

Strategie di Assegnazione

Configura come vengono assegnate le istanze dalla dashboard:

Analisi dei Tempi

La dashboard tiene traccia dei dati temporali dettagliati:

• Tempo Totale di Lavoro - Somma di tutte le sessioni di annotazione
• Tempo Medio per Annotazione - Tempo medio per elemento
• Annotazioni per Ora - Tasso di produzione
• Durata della Sessione - Tempo per sessione di login

I dati temporali derivano dal tracciamento comportamentale e dagli eventi di interazione con la pagina.

Configurazione

Impostazione di Base

# Enable admin dashboard
admin_api_key: "your-secure-api-key"

Configurazione Completa

admin_api_key: "your-secure-api-key"
 
# How long a session may sit idle before the server clears it.
# The clock restarts on every request, so it bounds inactivity,
# not the length of a shift. Default 480.
session_timeout_minutes: 480
 
# Editable from the Configuration tab while the server runs
assignment_strategy: least_annotated
max_annotations_per_user: 100
max_annotations_per_item: 3

Endpoint API

La dashboard di amministrazione è alimentata da endpoint REST API:

Statistiche

GET /api/admin/stats

Restituisce le statistiche generali del compito.

Annotatori

GET /api/admin/annotators
GET /api/admin/annotators/{user_id}

Elenca tutti gli annotatori o ottieni i dettagli per un utente specifico.

Istanze

GET /api/admin/instances
GET /api/admin/instances/{instance_id}

Elenca le istanze con paginazione e filtraggio.

Configurazione

GET /api/admin/config
POST /api/admin/config

Ottieni o aggiorna la configurazione del compito.

Progresso dell'Addestramento

GET /api/admin/training/stats
GET /api/admin/training/user/{user_id}

Statistiche della fase di addestramento e progresso per utente.

Apprendimento Attivo

GET /api/admin/active-learning/status
GET /api/admin/active-learning/metrics

Stato del modello di apprendimento attivo e metriche di prestazione.

Funzionalità di Monitoraggio

Rilevamento di Attività Sospette

La dashboard può segnalare comportamenti potenzialmente problematici:

• Velocità di annotazione molto elevate
• Pattern di sessione insoliti
• Pattern di risposta costanti
• Annotazioni mancanti

Metriche di Qualità

Tieni traccia degli indicatori di qualità delle annotazioni:

• Accordo inter-annotatore
• Distribuzione del tempo per annotazione
• Bilanciamento della distribuzione delle etichette
• Prestazioni della fase di addestramento

Best Practice di Sicurezza

Gestione della Chiave API

# Use environment variables
admin_api_key: ${ADMIN_API_KEY}

export ADMIN_API_KEY="your-secure-key"

Controllo degli Accessi

• Usa chiavi API forti e univoche
• Ruota le chiavi periodicamente
• Non esporre gli endpoint di amministrazione pubblicamente
• Usa HTTPS in produzione

Registro di Audit

La dashboard tiene traccia delle azioni di amministrazione:

• Modifiche alla configurazione
• Azioni di gestione degli utenti
• Esportazioni dei dati
• Tentativi di accesso

Configurazione di Esempio

annotation_task_name: "Sentiment Analysis"
task_dir: "."
port: 8000
 
# Admin dashboard
admin_api_key: ${ADMIN_API_KEY}
session_timeout_minutes: 480
 
# Data and annotation configuration
data_files:
  - "data/reviews.json"
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "How does this review read?"
    labels:
      - Positive
      - Negative
      - Neutral
 
# Assignment settings (editable from the Configuration tab)
assignment_strategy: least_annotated
max_annotations_per_user: 100
max_annotations_per_item: 3
 
output_annotation_dir: "output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

Considerazioni sulle Prestazioni

Dataset di Grandi Dimensioni

Per dataset con migliaia di istanze:

• Usa la paginazione (scheda istanze)
• Abilita il caricamento lazy
• Considera un backend database per prestazioni migliori

Molti Annotatori

Per compiti con molti annotatori concorrenti:

• Imposta intervalli di aggiornamento appropriati
• Monitora le risorse del server
• Usa un backend database per la scalabilità

# For large-scale deployments
database:
  type: mysql
  host: localhost
  database: potato_db
  username: ${DB_USER}
  password: ${DB_PASSWORD}

Risoluzione dei Problemi

Impossibile Accedere alla Dashboard

• Verifica che la chiave API sia impostata nella configurazione
• Controlla che l'URL sia /admin
• Assicurati che la chiave API corrisponda esattamente
• Controlla eventuali errori di battitura nella configurazione

Dashboard Lenta nel Caricamento

• Riduci le dimensioni della pagina
• Aumenta l'intervallo di aggiornamento
• Considera un backend database
• Controlla le risorse del server

Statistiche Non Aggiornate

• Verifica che l'aggiornamento automatico sia abilitato
• Controlla l'impostazione dell'intervallo di aggiornamento
• Aggiorna manualmente la pagina
• Controlla eventuali errori JavaScript

Ulteriori Letture

• Tracciamento Comportamentale - Tracciamento dettagliato delle interazioni
• Controllo della Qualità - Verifiche di attenzione e standard gold
• Panoramica API - Endpoint API di amministrazione

Per i dettagli di implementazione, consulta la documentazione sorgente.