162 lines
6.3 KiB
Markdown
162 lines
6.3 KiB
Markdown
# 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.
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
/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:
|
|
|
|
1. recupera un job in stato `pending`;
|
|
2. lo porta in elaborazione (`processing`);
|
|
3. esegue la procedura principale di selezione dei prototipi;
|
|
4. salva il risultato nel database;
|
|
5. 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:
|
|
|
|
```text
|
|
native/face-knn/config.json
|
|
```
|
|
|
|
Il valore atteso per `launcher` è:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
./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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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.
|