Risoluzione dei problemi

Funziona o è bloccato?

docker logs -f openplate-inference attraversa tre fasi in sequenza. Ecco cosa compare in ciascuna, per distinguere un'operazione in corso da un blocco anomalo.

Fase 1: download dei pesi (solo al primo avvio; da pochi minuti a un'ora con una connessione domestica). Le dimensioni sono mostrate all'inizio, così puoi confrontarle con la velocità della tua connessione:

═══════════════════════════════════════════════════════════════════════
  openplate-inference: weights for MODEL_PROFILE=lite
  destination: /models   total: 1.96 GiB
═══════════════════════════════════════════════════════════════════════
▶ [model] downloading LFM2.5-VL-1.6B-Q8_0.gguf (1.16 GiB) from https://huggingface.co/...
   This is a one-time download into /models. It is resumable:
   restarting the container continues where it stopped.
######################################                            54.2%

Bloccato? Se la percentuale non cambia per cinque minuti, il download si è interrotto. Riavvia il container: riprende dal punto raggiunto, non ricomincia da capo. Agli avvii successivi questa fase richiede invece solo pochi secondi per il calcolo degli hash:

▶ [model] LFM2.5-VL-1.6B-Q8_0.gguf: already present, verifying sha256 (1.16 GiB)...
✅ [model] LFM2.5-VL-1.6B-Q8_0.gguf verified, skipping download.
✅ All weights for profile 'lite' are present and verified.

Se un checksum non corrisponde, il log mostra il comando esatto per eliminare il file corrotto e riprovare. Eseguilo. Se fallisce due volte sullo stesso file, qualcosa tra te e Hugging Face altera il download (succede con un captive portal o un proxy di filtraggio). Prova con un'altra rete, oppure pre-popola il volume a mano (vedi sotto).

Fase 2: caricamento del modello (da 5 a 60 s, a ogni avvio):

═══════════════════════════════════════════════════════════════════════
  Starting llama-server (this loads the model, expect 5 to 60 s)
    profile:  lite
    model:    /models/LFM2.5-VL-1.6B-Q8_0.gguf
    mmproj:   /models/mmproj-LFM2.5-VL-1.6b-F16.gguf
    GPU:      none detected, CPU only (-ngl 0, -t 8)
    context:  8192   slots: 2
═══════════════════════════════════════════════════════════════════════
...
main: server is listening on http://127.0.0.1:8080 - starting the main loop

Controlla la riga GPU:. Qui si diagnostica l'errore tipico di chi nota lentezza pur avendo specificato --gpus all: se c'è scritto none detected, la GPU non è accessibile al container, e nessuna modifica altrove risolverà il problema.

Fase 3: pronto:

{"level":"info","msg":"openplate-inference listening","port":8300,
 "model":"openplate-plate-1","profile":"lite","concurrency":2,"keyIds":"a1b2c3d4"}

Da questo momento in poi, /readyz restituisce 200. Il servizio inizia ad ascoltare prima il completamento del caricamento del modello, di proposito: un avvio bloccato dal caricamento di svariati gigabyte non si distinguerebbe da un container congelato. Finché il runtime non è operativo, /readyz lo segnala.

Errori frequenti, nell'ordine in cui si verificano

Installazione offline o pre-popolata

Copia tu stesso i file GGUF nel volume e la fase di download diventerà una fase di verifica. I nomi dei file devono corrispondere esattamente; il manifesto con ogni nome di file e sha256 si trova all'inizio di scripts/fetch-weights.sh.

docker run --rm -v openplate-models:/models -v "$PWD:/src" alpine \
  cp /src/LFM2.5-VL-1.6B-Q8_0.gguf /src/mmproj-LFM2.5-VL-1.6b-F16.gguf /models/

Se crei un mirror dei pesi sul tuo spazio di archiviazione, imposta WEIGHTS_MIRROR_BASE su un URL di base che contiene quei nomi di file; Hugging Face resta la soluzione di riserva e i checksum vengono comunque verificati, quindi un mirror non può fornirti pesi diversi.

Ancora bloccato?

• Problemi di compatibilità con il runtime (502 su ogni scansione, output illeggibile, concorrenza errata): Usa il tuo runtime.
• Lento ma funzionante: Hardware e latenza misurata.
• Per qualsiasi altra cosa: apri una issue indicando tipo e versione del runtime, il modello in uso, la richiesta e la risposta interessate e l'output del tuo /readyz.