Solución de problemas
Obtener registros
Sección titulada «Obtener registros»Por defecto, Piixie registra solo en la consola y no escribe ficheros de registro. Para capturar registros JSON estructurados para un informe de error, inicia la aplicación con la variable de entorno PIIXIE_DEV=1; los ficheros de registro aparecen entonces en una carpeta logs/ dentro del directorio de datos de la aplicación:
| Plataforma | Ubicación |
|---|---|
| macOS | ~/Library/Application Support/Piixie/logs/ |
| Windows | %APPDATA%\Piixie\logs\ |
| Linux | ~/.config/Piixie/logs/ |
Cuando algo falla, el fichero de registro más reciente suele indicar la causa. Los registros son ficheros locales; no se informa de nada a ninguna parte.
La descarga del modelo falla o se queda atascada
Sección titulada «La descarga del modelo falla o se queda atascada»La descarga del primer inicio obtiene ~5 GB de Hugging Face. Si falla:
- Comprueba la conectividad y el espacio en disco (el modelo E4B necesita ~5 GB libres, el modelo 12B ~7,1 GB)
- Los proxies corporativos y los cortafuegos con inspección de TLS pueden romper la descarga; prueba con otra red
- Un fichero descargado parcialmente se reanuda o se reinicia en el siguiente intento
El modelo no arranca
Sección titulada «El modelo no arranca»Piixie lanza llama-server en segundo plano. Si el estado nunca pasa a listo:
- La poca memoria es la causa habitual. El modelo E4B quiere aproximadamente 6 GB de margen; cierra otras aplicaciones pesadas o cambia al modelo más pequeño si estás en el 12B
- Reinicia con
PIIXIE_DEV=1y revisa el fichero de registro más nuevo en busca de errores de arranque del servidor - Salir y volver a abrir la aplicación reinicia el proceso del servidor de forma limpia
Las ejecuciones son lentas
Sección titulada «Las ejecuciones son lentas»La velocidad de inferencia está limitada por el hardware. Opciones, por orden de efecto:
- Usa el modelo E4B por defecto en lugar del 12B
- Descarga la inferencia a una máquina con GPU con el modo servidor
- Usa un endpoint remoto si tu política de datos lo permite
Los PDF largos con muchas imágenes son el caso más pesado, ya que cada imagen pasa por el análisis de visión. Elegir el procesamiento con difuminado automático o solo texto cuando se te pregunte se salta ese trabajo.
Se ha colado PII
Sección titulada «Se ha colado PII»Ningún detector es perfecto. Si una ejecución pasó algo por alto:
- Añade indicaciones al prompt de tu perfil (“trata siempre los nombres en clave de proyecto como ORION como PII”) para que futuras ejecuciones lo capten
- El modelo 12B, más grande, y los modelos remotos de frontera captan más casos límite que el modelo por defecto
- Vuelve a ejecutar el fichero y compara las tablas de sustitución; la detección tiene cierta variabilidad entre ejecuciones
Un endpoint remoto no se conecta
Sección titulada «Un endpoint remoto no se conecta»- “Authentication failed”: la clave de API es incorrecta o no tiene acceso
- “Could not reach the endpoint”: comprueba la URL base, y recuerda que va sin el sufijo
/v1 - En los servidores autoalojados, confirma que el servidor es accesible desde tu equipo (
curl http://host:port/v1/models)
El fichero de salida parece incorrecto
Sección titulada «El fichero de salida parece incorrecto»Los problemas de formato en los PDF o DOCX reescritos son errores que merece la pena reportar. Conserva el fichero original, anota el modo y el perfil usados (la entrada del historial tiene la instantánea) y coge el fichero de registro correspondiente.