Imagina que has desplegado el modelo de conducción autónoma Alpamayo-R1-10B tras mucho esfuerzo. Abres tu navegador y escribes localhost:7860, pero la página está en blanco o muestra un error de conexión. La frustración es inmediata.

No te preocupes, es una situación común para cualquier desarrollador. El despliegue exitoso es solo el primer paso; verificar que el servicio funcione y sea accesible es crucial para empezar a usarlo.

En esta guía, te enseñaré a usar curl, una herramienta de línea de comandos, para realizar una revisión completa del servicio web de Alpamayo-R1-10B. Comenzaremos con pruebas de conectividad básicas y avanzaremos hasta simular llamadas a la API. Al finalizar, podrás diagnosticar problemas de servicio rápidamente y adquirir una metodología de depuración general aplicable a otros servicios.

¿Por qué usar curl en lugar de un navegador?

Un navegador web es como una máquina de café automática: presionas un botón y obtienes una bebida lista. Solo sabes si está buena o no, pero no qué pasó durante el proceso. curl, en cambio, es como un laboratorio de pruebas. Te permite examinar cada etapa de la comunicación:

• Capa de red: ¿Llegó mi solicitud al servidor?
• Capa de transporte: ¿El servidor respondió?
• Capa de aplicación: ¿Qué datos brutos devolvió el servidor (código HTTP, cabeceras, cuerpo)?

Cuando algo falla, el navegador a menudo muestra una página de error genérica. curl proporciona información precisa para diagnosticar el problema.

Objetivos del tutorial

1. Diagnóstico de conectividad: Verificar que el servicio en localhost:7860 esté activo y responda.
2. Estado del servicio: Comprobar no solo que responda, sino que esté sano (por ejemplo, que el modelo esté cargado).
3. Simulación de peticiones: Aprender a construir solicitudes similares a las del navegador para futuras automatizaciones o consumo de API.

Pruebas básicas de conectividad

Este es el paso más fundamental. Lo dividiremos en varios niveles.

Prueba 1: El "toque" más simple

En tu terminal (en el servidor donde desplegaste Alpamayo-R1-10B), ejecuta:

curl -I http://localhost:7860

Explicación: El parámetro -I indica que solo se obtengan las cabeceras de respuesta HTTP, no el contenido completo. Es rápido y adecuado para una verificación inicial.

Resultado esperado si funciona:

HTTP/1.1 200 OK
server: Gradio
date: Thu, 06 Feb 2025 08:00:00 GMT
content-type: text/html; charset=utf-8
content-length: 1234
...

Si ves HTTP/1.1 200 OK, el servidor (Gradio) está funcionando y respondió correctamente a la solicitud.

Problemas comunes y solución:

• Conexión rechazada (Connection refused)

  curl: (7) Failed to connect to localhost port 7860: Connection refused
  

  Causa: No hay ningún programa escuchando en el puerto 7860. El servicio web no se inició. Solución:

  # Verificar estado del servicio
  supervisorctl status alpamayo-webui
  # Si no está en RUNNING, iniciarlo
  supervisorctl start alpamayo-webui
  # Esperar unos segundos y probar de nuevo
  curl -I http://localhost:7860
  

• Sin respuesta (tiempo de espera agotado)
  Causa: El servicio puede estar atascado durante el inicio (por ejemplo, cargando un modelo grande) o completamente bloqueado. Solución:

  # Ver registros para ver dónde se detiene
  tail -f /root/Alpamayo-R1-10B/logs/webui_stderr.log
  # Intentar reiniciar el servicio
  supervisorctl restart alpamayo-webui
  

Prueba 2: Obtener el contenido completo de la página principal

Una vez que confirmas que el servicio responde, veamos qué devuelve. Elimina el parámetro -I:

curl http://localhost:7860

Verás un gran bloque de código HTML. Este es el código que el navegador recibe para renderizar la interfaz web de Gradio. Si aquí obtienes HTML completo pero el navegador muestra una pantalla en blanco, el problema probablemente esté en tu navegador, proxy de red o caché, no en el servicio.

Prueba 3: Especificar un tiempo de espera máximo

Para servicios lentos, el tiempo de espera predeterminado de curl puede ser insuficiente. Puedes establecerlo explícitamente:

curl --max-time 30 http://localhost:7860

--max-time 30 indica que toda la operación esperará como máximo 30 segundos. Esto evita que curl se rinda prematuramente si el servicio tarda en iniciar.

Comprobaciones de salud avenzadas

Que un servicio responda con un código 200 no significa que esté listo. Por ejemplo, el modelo podría no haberse cargado aún. Aunque Alpamayo-R1-10B no expone un endpoint estándar /health, podemos usar otros métodos.

Verificar el endpoint de configuración de Gradio

Las aplicaciones Gradio suelen tener un endpoint /config que devuelve la configuración de la aplicación. Esto indica si el framework se ha inicializado completamente.

curl -s http://localhost:7860/config | python3 -m json.tool

Explicación: -s suprime mensajes de progreso y errores. | python3 -m json.tool da formato al JSON devuelto para que sea legible.

Si este comando devuelve un objeto JSON estructurado (con componentes, funciones, etc.), la aplicación Gradio está sana.

Comprobar el estado del proceso de forma indirecta

A veces, las pruebas HTTP directas no son suficientes y necesitas combinarlas con el estado del sistema.

# 1. Verificar si el proceso está en ejecución
ps aux | grep -E "webui.py|gradio" | grep -v grep

# 2. Comprobar el uso de memoria de la GPU; tras cargar el modelo, ocupará mucha VRAM
nvidia-smi | grep -A 5 "python"

# 3. Ver los registros de servicio más recientes en busca de "Model loaded" o errores
tail -20 /root/Alpamayo-R1-10B/logs/webui_stdout.log

Si el proceso existe, la VRAM está muy ocupada (por ejemplo, >20 GB) y el registro muestra que el modelo se cargó correctamente, el servicio está prácticamente sano.

Simulación de uso real: probar la funcionalidad de inferencia

Esta es la parte más interesante. Intentaremos simular el comportamiento de un usuario que hace clic en el botón "Inferir" en la interfaz web. Esto implica enviar una petición POST a un endpoint interno.

Nota: Los endpoints de la API interna de Gradio pueden variar según la versión. Este método se basa en un patrón común, pero es posible que necesites ajustarlo.

Paso 1: Encontrar el endpoint de la API de Gradio

Cuando accedes a la interfaz web, abre las "Herramientas de desarrollador" de tu navegador (F12) y ve a la pestaña "Red". Luego, haz clic en el botón "Iniciar inferencia" en la interfaz. Verás que el navegador realiza una solicitud de red.

La dirección de esta solicitud suele ser similar a http://localhost:7860/run/predict. Este es el endpoint que Gradio utiliza para prcoesar las solicitudes de predicción desde el frontend.

Paso 2: Construir una solicitud de prueba simple

Construimos un cuerpo JSON simple y lo enviamos a ese endpoint. Supongamos que usamos una instrucción de conducción predeterminada.

curl -X POST http://localhost:7860/run/predict \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      null,       // Imagen de cámara frontal (placeholder, necesita codificación base64)
      null,       // Imagen de cámara izquierda
      null,       // Imagen de cámara derecha
      "Navigate through the intersection safely", // Instrucción de conducción
      0.98,       // top_p
      0.6,        // temperature
      1           // num_samples
    ]
  }'

Explicación: -X POST especifica el método POST. -H "Content-Type: application/json" establece el tipo de contenido. -d '...' contiene los datos JSON. El orden del array data debe coincidir con el orden de los parámetros de la función del backend. Las imágenes son placeholders (null).

Respuesta esperada: Obtendrás una respuesta JSON. Si el modelo no se ha cargado, puede contener un error como "error": "Please load the model first". Si el modelo está cargado pero las imágenes son nulas, podría devolver una respuesta basada en datos predeterminados o aleatorios, u otro error.

Paso 3: Interpretar la respuesta y gestionar errores

• Si devuelve el error "modelo no cargado": Debes cargar el modelo primero a través de la interfaz web o verificar que se haya cargado por otros medios.
• Si devuelve un JSON con campos como "reasoning" y "trajectory": ¡Enhorabuena! El servicio no solo está en línea, sino que su funcionalidad de inferencia principal funciona correctamente.
• Si la conexión falla o se agota el tiempo: Vuelve a la sección de pruebas básicas de conectividad.

Comandos de gestión del servicio y monitorización de estado

Durante las pruebas, a menudo necesitarás reiniciar el servicio o comprobar su estado. Aquí tienes un resumen de los comandos más útiles.

Gestión del ciclo de vida del servicio

# Ver el estado de todos los servicios gestionados (alpamayo-webui debería aparecer)
supervisorctl status

# Ver solo el estado de la interfaz web
supervisorctl status alpamayo-webui

# Iniciar el servicio
supervisorctl start alpamayo-webui

# Detener el servicio
supervisorctl stop alpamayo-webui

# Reiniciar el servicio (el más común)
supervisorctl restart alpamayo-webui

# Recargar archivos de configuración (tras modificarlos)
supervisorctl reread
supervisorctl update

Monitorización de registros: localización de problemas

Los registros son tu primera fuente de información para solucionar problemas.

# Ver la salida de registros en tiempo real (salida estándar)
tail -f /root/Alpamayo-R1-10B/logs/webui_stdout.log

# Ver la salida de errores en tiempo real (error estándar)
tail -f /root/Alpamayo-R1-10B/logs/webui_stderr.log

# Ver las últimas 50 líneas del registro de errores
tail -50 /root/Alpamayo-R1-10B/logs/webui_stderr.log

# Buscar palabras clave en los registros, como "error", "fail", "load"
grep -i "error\|fail" /root/Alpamayo-R1-10B/logs/webui_stderr.log

Monitorización de recursos

# Monitorizar el estado de la GPU
watch -n 1 nvidia-smi

# Ver el uso de recursos del proceso (CPU, memoria)
top -p $(pgrep -f webui.py)

Con estas pruebas de curl, ahora podrás examinar el servicio web de Alpamayo-R1-10B desde su "latido" (conectividad) hasta su "función orgánica" (API de inferencia).

Recuerda la cadena de diagnóstico: Sin acceso -> Verifica el puerto y el estado del servicio -> Revisa los registros de errores -> Analiza el uso de recursos -> Intenta reparar (reiniciar, configurar) -> Vuelve a probar.

Dominar estas habilidades de línea de comandos te permitirá manejar con soltura no solo Alpamayo-R1-10B, sino cualquier servicio web desplegado en un puerto local (como otras aplicaciones Gradio, servicios FastAPI, etc.). La próxima vez que veas "localhost:7860" inaccesible, ya no entrarás en pánico: abrirás la terminal y comenzarás tu diagnóstico con confianza.