Il runtime di inferenza

Configurazione

Tutte le variabili d'ambiente e le opzioni del database alimentare (FOOD_SOURCE)

Questa pagina è tradotta automaticamente dalla documentazione in inglese.

Tutto si gestisce con variabili d'ambiente, convalidate all'avvio; un valore errato arresta il processo anziché degradare in silenzio. L'elenco principale commentato è .env.example. La documentazione di openplate elenca ogni variabile per questo container in una pagina. Compaiono accanto a quelle per l'app e per il servizio di sincronizzazione. Le variabili più importanti sono:

variabile	predefinito
`MODEL_PROFILE`	`lite`	`lite` \	`lite-apache` \	`quality` \	`external`
`API_KEYS`	(generato)	Chiavi bearer separate da virgole. Imposta questo valore.
`PORT`	`8300`	L'unica porta esposta.
`CONCURRENCY`	`2`	Scansioni in corso; imposta anche gli slot KV di llama.cpp. Non aggiunge thread di CPU: gli slot condividono i `LLAMA_THREADS` thread.
`MAX_QUEUE_DEPTH`	`8`	Oltre questo valore, i client ricevono 429 + `Retry-After`.
`RATE_LIMIT_RPM`	`60`	Per chiave.
`LATENCY_CEILING_MS`	`0`	0 = disabilitato. Criterio di ammissione: rifiuta il lavoro che non puoi completare in tempo. Vedi Hardware.
`RUNTIME_COMPLETION_TIMEOUT_MS`	`600000`	Limite complessivo su una singola chiamata di completamento; `0` = disabilitato. Criterio di disponibilità operativa, non di latenza: libera uno slot del worker che un runtime bloccato non restituirebbe mai. Si applica anche in modalità integrata. Vedi Runtime.
`IMAGE_MAX_LONG_EDGE`	`896`	Obiettivo di riduzione della scala. La latenza aumenta con il quadrato.
`MAX_IMAGE_BYTES`	`8388608`	La dimensione massima della foto accettata dopo la decodifica base64, in byte (8 MiB). Un file più grande viene rifiutato con un messaggio che chiede di ridimensionarlo. Il limite del corpo della richiesta deriva da questo valore.
`FOOD_SOURCE`	`fdc`	Vedi Dati sugli alimenti.
`CONTEXT_SIZE`	`8192`	Contesto per scansione in corso. Il container lo moltiplica per `CONCURRENCY` prima di passarlo a llama.cpp, poiché il valore `-c` di llama.cpp corrisponde al valore totale che viene suddiviso tra gli slot.
`LLAMA_EXTRA_ARGS`	(vuoto)	Flag aggiuntivi inseriti alla fine del comando llama-server, separati da spazi. Solo in modalità inclusa.
`LLAMA_THREADS`	`nproc - 2`	Thread di CPU per llama.cpp (il suo `-t`). Vengono lasciati due core per il servizio, la decodifica delle immagini e il sistema operativo, quindi una macchina a 6 core esegue 4 thread e una a 4 core ne esegue 2, a prescindere da quanto indicato in `CONCURRENCY`. Assegnare a llama.cpp ogni core rende la macchina congestionata, non più veloce. Il log di avvio stampa il valore come `-t N`. Solo in modalità integrata.
`MODELS_DIR`	`/models`	Il volume dei pesi.
`RUNTIME_PORT`	`8080`	La porta del server llama-server incluso, su `127.0.0.1` all'interno del container. Solo in modalità inclusa.
`WEIGHTS_MIRROR_BASE`	(vuoto)	Mirror facoltativo, Hugging Face è il ripiego.
`GPU_LAYERS`	(automatico)	Sovrascrive il rilevamento automatico della GPU. `0` forza la CPU.
`NVIDIA_VISIBLE_DEVICES`	(impostato dal runtime)	Il container runtime NVIDIA lo imposta quando passi `--gpus all`. Il rilevamento automatico lo legge. Qualsiasi valore diverso da `void` o `none` scarica ogni layer sulla GPU. Non impostarlo manualmente.
`LOG_LEVEL`	`info`	`debug` \	`info` \	`warn` \	`error`
`PROFILE`	(da `MODEL_PROFILE`)	Il nome del profilo nel log di avvio: `lite`, `quality` o `custom`. Il container lo imposta da `MODEL_PROFILE`. Se lo imposti manualmente, modifichi solo quella riga di log.

Le variabili per la modalità esterna (MODEL_RUNTIME_URL, MODEL_ID, MODEL_RUNTIME_API_KEY) sono documentate in Usa il tuo runtime.

llama-server viene eseguito all'interno del container con binding su solo 127.0.0.1 e non è raggiungibile dall'esterno. Questo aspetto non è configurabile: si tratta di un endpoint di visione grezzo non autenticato, e il punto è proprio evitare che tu possa pubblicarlo per errore.

Dati sugli alimenti (`FoodSource`)

Il modello identifica gli alimenti e stima i grammi. I macronutrienti vengono ricavati da una banca dati di alimenti in base al nome, non sono mai generati dal modello.

`FOOD_SOURCE`	cosa fa	rete	note
`fdc` (predefinito)	Cerca i nomi in un estratto integrato di USDA FoodData Central, 8.041 alimenti generici, distribuito dentro l'immagine in `data/fdc-foods.json`.	nessuno	Offline, senza chiave, senza account, nessuna richiesta in uscita. Dominio pubblico. È l'opzione predefinita perché è l'unica a non richiedere nulla a nessuno.
`off`	Interroga Open Food Facts in tempo reale sul tuo runtime.	in uscita, per scansione	Efficace su prodotti di marca e confezionati, meno su cibi cotti generici. L'indirizzo è `OFF_API_URL`, `https://world.openfoodfacts.org` come valore predefinito. Leggi la nota sulla licenza qui sotto prima di abilitarlo. Questa immagine non distribuisce nulla di derivato da OFF.
`lcc`	Interroga le API pubbliche di lowcarbcheck.	in uscita, per scansione	I dati più ampi tra i tre (curati + BLS + USDA), e permanentemente solo remoti, poiché BLS 4.0 vieta la ridistribuzione. L'attribuzione viene inoltrata nella risposta affinché raggiunga la UI. Senza `LCC_API_KEY`, ogni richiesta viene eseguita sul livello anonimo gratuito di LowCarbCheck, vedi sotto.
`none`	Nessuna risoluzione. Ogni alimento restituisce macronutrienti nulli.	nessuno	Per i client che eseguono autonomamente la ricerca dei valori nutrizionali.

bash

-e FOOD_SOURCE=fdc                         # default
-e FDC_DATASET_PATH=./data/fdc-foods.json  # relative to the working directory
-e OFF_API_URL=https://world.openfoodfacts.org  # only read when FOOD_SOURCE=off
-e LCC_API_URL=https://lowcarbcheck.org    # only read when FOOD_SOURCE=lcc
-e LCC_API_KEY=lcc_live_…                   # optional; only read when FOOD_SOURCE=lcc
-e EMBEDDING_RUNTIME_URL=http://…          # optional; enables hybrid re-ranking

Senza LCC_API_KEY, FOOD_SOURCE=lcc viene eseguito sul livello anonimo di LowCarbCheck: 1.000 crediti per giorno UTC, condivisi da tutte le richieste provenienti dal tuo indirizzo IP. Una ricerca costa 1 credito. Una scansione invia fino a 3 query di ricerca per elemento identificato, valore stabilito dal limite di perfezionamento in search-foods.ts, su un massimo di 8 elementi. Questo porta lo scenario peggiore a 24 crediti per scansione. La pipeline non chiama mai l'endpoint per singolo alimento, quindi ciò copre l'intero costo. Tale scenario peggiore consente circa 41 scansioni al giorno. La maggior parte dei giorni ne consente di più, perché una ricerca si interrompe non appena una query supera la soglia di accettazione. Quando la quota del livello si esaurisce, ogni elemento rimanente restituisce macro nulli fino al giorno UTC successivo, e la scansione restituisce comunque 200. Una chiave gratuita da lowcarbcheck.org/developers porta la quota a 100.000 crediti al mese fino a 120 richieste al minuto. Questa quota appartiene alla chiave anziché al tuo indirizzo IP. Impostala come LCC_API_KEY. Il servizio la invia come bearer token a LCC_API_URL e in nessun altro luogo, e non la registra mai nei log. Una chiave rifiutata da LowCarbCheck fallisce nello stesso modo di una quota esaurita: macro nulli e un 200. fdc non richiede alcuna rete e alcuna quota.

I macronutrienti risolti hanno un'etichetta. Gli alimenti trovati nel database includono un provenance pari a "corpus", oltre a una stringa attribution quando richiesta dalla fonte. Gli alimenti senza corrispondenza omettono entrambi i campi, e macrosPer100g è null. openplate espone questi valori, così gli utenti possono distinguere le voci confermate nel database dagli elementi privi di dati sui macronutrienti.

L'assenza del database degli alimenti non blocca le scansioni. Se FDC_DATASET_PATH non punta a nulla, il servizio registra un avviso, disabilita la risoluzione e continua a identificare i piatti. Ottieni nomi e grammi con macronutrienti nulli: degradato, non bloccato. Rigenera l'estratto con pnpm food-data:fdc (richiede la rete).

EMBEDDING_RUNTIME_URL è opzionale. Se lo fai puntare a un secondo runtime compatibile con OpenAI che serve /v1/embeddings (ad esempio llama-server --embedding), il recupero diventa ibrido: il calcolatore lessicale individua i candidati e il modello di embedding li riordina, così che "coscia di pollo alla griglia" finisca sulla riga corretta anche quando il database usa una dicitura diversa. Se lo lasci vuoto, che è il comportamento predefinito, il recupero rimane solo lessicale, offrendo una classificazione leggermente inferiore ma senza generare errori. Se il runtime di inferenza per gli embedding non è raggiungibile, il servizio degrada alla modalità solo lessicale con un avviso, senza mai far fallire una scansione.

`FOOD_SOURCE=off` e clausola share-alike della ODbL

I dati di Open Food Facts sono concessi sotto la Open Database Licence (ODbL), che prevede la clausola condivisione allo stesso modo (share-alike). Se abiliti questo connettore e poi pubblichi o ridistribuisci un database che integra dati di OFF (non le singole ricerche visualizzate, ma un database derivato), la ODbL ti obbliga a distribuire anche tale database derivato sotto la ODbL e ad attribuire i crediti a Open Food Facts.

Per un'istanza a uso personale che mostra una ricerca e la salva nel tuo diario, questo obbligo non si applica. Si applica invece se costruisci un prodotto basato su di essa, ed è per questo motivo che off non è l'opzione predefinita. fdc non impone alcun obbligo di tipo share-alike.

I termini di licenza di modelli e dati sono raccolti in Licenza.