Resolución de problemas

¿Funciona o se ha quedado bloqueado?

docker logs -f openplate-inference pasa por tres etapas en orden. Así se ve cada una, para que puedas distinguir entre "ocupado" y "averiado".

Etapa 1: descarga de pesos (solo en el primer arranque; de unos minutos a una hora con una conexión doméstica). Los tamaños se muestran al principio para que puedas comparar con la velocidad de tu enlace:

═══════════════════════════════════════════════════════════════════════
  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%

¿Se ha bloqueado? Si el porcentaje no cambia en cinco minutos, la descarga se ha interrumpido. Reinicia el contenedor: la descarga se reanuda, no empieza de cero. En arranques posteriores, esta etapa dura solo unos segundos para calcular los hashes:

▶ [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.

Si falla una suma de comprobación, el registro muestra el comando exacto para eliminar el archivo corrupto y reintentar. Ejecútalo. Si falla dos veces con el mismo archivo, algo entre tu máquina y Hugging Face está alterando la descarga (un portal cautivo o un proxy con filtrado provocan esto). Prueba con otra red o precarga el volumen manualmente (más abajo).

Etapa 2: carga del modelo (de 5 a 60 s, en cada arranque):

═══════════════════════════════════════════════════════════════════════
  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

Revisa la línea de GPU:. Aquí se diagnostica el problema de "le pasé --gpus all y sigue yendo lento": si indica none detected, la GPU no llega al contenedor, y ningún ajuste en otra parte servirá de nada.

Etapa 3: listo:

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

/readyz devuelve 200 a partir de aquí. El servicio empieza a escuchar antes el modelo termina de cargarse, de forma deliberada: un arranque bloqueado esperando una carga de varios gigabytes es indistinguible de un contenedor colgado. Hasta que el runtime esté levantado, /readyz así lo indica.

Fallos habituales, en el orden en que ocurren

Instalación sin conexión o con datos precargados

Copia tú mismo los GGUF en el volumen y la etapa de descarga pasará a ser una etapa de verificación. Los nombres de archivo deben coincidir de forma exacta; el manifiesto con cada nombre de archivo y sha256 está al principio de 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/

Si tienes una copia réplica de los pesos en tu propio almacenamiento, define WEIGHTS_MIRROR_BASE con una URL base que contenga esos nombres de archivo; Hugging Face sigue siendo el recurso de respaldo y las sumas de comprobación se aplican en ambos casos, así que una réplica no puede entregarte pesos distintos.

¿Sigues con problemas?

• Problemas de compatibilidad con el runtime (502 en cada escaneo, salida corrupta, concurrencia incorrecta): Trae tu propio runtime.
• Lento pero funciona: Hardware y latencia medida.
• Cualquier otro caso: abre una incidencia indicando el tipo y versión de tu runtime, el modelo en uso, la petición y respuesta implicadas, y la salida de tu /readyz.