6.3 KiB
Flusso KNN Shadow — progetto s190js
Panoramica
Il confronto KNN in modalità shadow viene eseguito lato server Node.js, non nel browser. Il flusso parte dal worker che aggiorna i prototipi facciali e arriva al binario nativo face_knn, passando attraverso il modulo di confronto, il runtime KNN e uno script shell.
Server Node.js
└── tools/runPrototypeWorker.js
└── tools/runFaceKnnShadow.js
└── tools/faceKnnRuntime.js
└── native/face-knn/run-face-knn.sh
└── native/face-knn/bin/face_knn
Percorso del progetto usato negli esempi:
/home/nvme/dockerdata/prove/s190js
Ruolo dei componenti
1. tools/runPrototypeWorker.js — worker Node.js
È il processo server che gestisce i job di aggiornamento dei prototipi facciali.
In sintesi:
- recupera un job in stato
pending; - lo porta in elaborazione (
processing); - esegue la procedura principale di selezione dei prototipi;
- salva il risultato nel database;
- dopo il salvataggio, avvia il confronto KNN shadow.
Il confronto shadow viene quindi eseguito dopo il salvataggio del risultato principale. Non è il componente che decide quali prototipi selezionare nella procedura ordinaria.
2. tools/runFaceKnnShadow.js — confronto KNN in modalità shadow
Questo modulo coordina il confronto tra i risultati KNN nativi e quelli di riferimento prodotti dall'esperimento.
Il suo compito è verificare e registrare eventuali differenze. In modalità shadow, il risultato del KNN nativo è usato per validazione e analisi: non sostituisce la selezione principale dei prototipi.
Eventuali errori o discrepanze del confronto vengono registrati nei log; secondo il flusso esaminato, non annullano il salvataggio dei prototipi già completato.
3. tools/faceKnnRuntime.js — runtime KNN
Questo modulo prepara e avvia l'esecuzione del KNN nativo.
In base al codice esaminato, si occupa di attività come:
- leggere la configurazione KNN;
- recuperare gli embedding delle facce e i prototipi da confrontare;
- preparare i file di input temporanei richiesti dal programma nativo;
- invocare il launcher configurato;
- leggere e interpretare l'output JSON del binario.
Il launcher è configurato nel file:
native/face-knn/config.json
Il valore atteso per launcher è:
native/face-knn/run-face-knn.sh
L'effettiva esecuzione dipende dalla configurazione: il KNN deve essere abilitato e la modalità shadow deve essere attiva.
4. native/face-knn/run-face-knn.sh — script shell
È il punto di ingresso shell usato per lanciare il programma nativo.
Lo script cambia nella propria directory e poi esegue il binario:
./bin/face_knn
Questo passaggio permette al programma nativo di trovare correttamente i file relativi alla propria directory, come il kernel OpenCL, senza dipendere dalla directory da cui è stato avviato il server.
Lo script è quindi un launcher lato server. Non viene eseguito dal browser.
5. native/face-knn/bin/face_knn — binario nativo
È il programma compilato che esegue il confronto KNN.
Riceve dal runtime i percorsi dei file di input e i parametri necessari, come il numero di query, il numero di prototipi, la dimensione degli embedding, il valore di top-k e il backend richiesto.
Il programma restituisce i risultati al processo Node.js, che li interpreta e li usa nel rapporto di confronto shadow.
Quando viene eseguito il flusso
Il flusso non viene eseguito semplicemente perché un utente apre una pagina web.
Viene avviato dal worker server durante l'elaborazione di un job di aggiornamento dei prototipi, dopo il completamento del salvataggio principale, se la configurazione KNN abilita il confronto shadow.
L'assegnazione di un cluster a una persona accoda un job di aggiornamento dei prototipi. Il daemon/worker elabora quel job; il confronto KNN shadow è una fase successiva del lavoro server.
Cosa fa e cosa non fa la modalità shadow
| Attività | Componente principale |
|---|---|
| Gestire il job di aggiornamento | runPrototypeWorker.js |
| Selezionare e salvare i prototipi principali | Worker e procedura di selezione |
| Coordinare il confronto di validazione | runFaceKnnShadow.js |
| Preparare input e invocare il programma nativo | faceKnnRuntime.js |
| Avviare il binario | run-face-knn.sh |
| Eseguire il calcolo KNN nativo | bin/face_knn |
Importante: in modalità shadow, il KNN nativo è un controllo parallelo di validazione. Non è il motore che determina direttamente quali prototipi vengono salvati. Per cambiare questo comportamento servirebbe una modifica esplicita al flusso applicativo e una verifica separata.
Verifiche sul server
Per controllare la configurazione effettiva e i punti di collegamento, eseguire sul server:
cd /home/nvme/dockerdata/prove/s190js
echo "=== Configurazione KNN ==="
cat native/face-knn/config.json
echo
echo "=== Collegamenti nel codice ==="
grep -n -E \
'runFaceKnnShadow|runNativeKnn|launcher|spawnSync' \
tools/runPrototypeWorker.js \
tools/runFaceKnnShadow.js \
tools/faceKnnRuntime.js
Per verificare che lo script shell lanci il binario previsto:
cd /home/nvme/dockerdata/prove/s190js
cat native/face-knn/run-face-knn.sh
ls -l native/face-knn/run-face-knn.sh \
native/face-knn/bin/face_knn
Nota sul fallback
La configurazione può contenere un backend di fallback, ad esempio CPU. La sola presenza di un'impostazione come fallbackBackend non dimostra però che il codice esegua automaticamente un secondo tentativo in caso di errore. Per affermarlo con certezza occorre verificare nel runtime il percorso di gestione degli errori e l'eventuale seconda invocazione.
Conclusione
La catena è interamente lato server:
runPrototypeWorker.js
→ runFaceKnnShadow.js
→ faceKnnRuntime.js
→ run-face-knn.sh
→ bin/face_knn
Il worker principale salva i prototipi; successivamente, se la configurazione lo consente, viene lanciato il confronto KNN shadow per confrontare e validare i risultati. Il browser non esegue né lo script shell né il binario nativo.
Questo documento descrive il flusso ricostruito dal codice esaminato. Per confermare che una specifica esecuzione sia avvenuta, occorre controllare la configurazione attiva e i log del worker.