building-inferencesh-apps

Descripción general

¿Qué es building-inferencesh-apps?

La skill building-inferencesh-apps es una guía específica para crear y desplegar aplicaciones en la plataforma inference.sh. Explica el flujo estándar de trabajo de una app, el papel de la CLI infsh y cómo crear y gestionar de forma segura apps de tipo backend escritas en Python o Node.js.

Esta skill no es un tutorial genérico; está alineada con los comandos oficiales infsh app y con las expectativas del runtime de inference.sh. Te ayuda a evitar errores habituales, como crear a mano archivos clave, configurar mal los recursos de la app o desplegar desde el directorio equivocado.

¿Para quién es esta skill?

Utiliza building-inferencesh-apps si eres:

• Un desarrollador backend que crea apps tipo API para ejecutar en inference.sh
• Un ingeniero de Python o Node.js que envuelve modelos o APIs externas en un servicio gestionado
• Un desarrollador que prefiere CLI y quiere un flujo de despliegue predecible y automatizable
• Un usuario de la plataforma que necesita entender a alto nivel los recursos de GPU/VRAM, los secretos de la app y las integraciones

Si necesitas comprender cómo debe estructurarse una app de inference.sh, cómo se generan los archivos inf.yml y inference.py / inference.js, y cómo trabajar con la plataforma de forma segura, esta skill es un buen punto de partida.

¿Qué problemas resuelve?

La skill building-inferencesh-apps aborda puntos de dolor frecuentes al empezar con el desarrollo de apps en inference.sh:

• Dudas sobre cómo hacer correctamente el scaffolding de una app nueva
• Creación accidental manual de inf.yml, inference.py, inference.js o package.json que entra en conflicto con las expectativas de la plataforma
• Olvidar hacer cd al directorio de la app antes de ejecutar comandos infsh
• Pérdida de datos de output_meta por extender la clase base incorrecta
• Falta de logging que dificulta depurar apps remotas o con mucho uso de APIs

Siguiendo las prácticas resumidas en esta skill obtendrás un flujo de trabajo consistente y repetible para crear y desplegar apps en inference.sh.

¿Cuándo encaja bien building-inferencesh-apps?

Esta skill es especialmente útil cuando:

• Estás empezando una app nueva en inference.sh y quieres seguir el flujo de trabajo canónico
• Ya tienes instalada la CLI infsh o planeas instalarla y gestionar todo desde la línea de comandos
• Quieres crear backends en Python o Node.js, incluidos wrappers sobre APIs externas o modelos

Puede ser menos útil cuando:

• No usas inference.sh como destino de despliegue
• Solo necesitas código del lado del cliente o patrones de interfaz de usuario
• Esperas una interfaz gráfica de tipo point-and-click en lugar de flujos basados en CLI

Si tu objetivo principal es tener despliegues de backend y APIs estables y automatizados en inference.sh, building-inferencesh-apps está muy alineada con tus necesidades.

Cómo usarla

1. Instala la CLI de inference.sh

La skill building-inferencesh-apps parte de la base de que usas la CLI oficial de inference.sh, infsh, para todas las operaciones sobre apps.

Instalar la CLI

Ejecuta el script de instalación desde tu terminal:

curl -fsSL https://cli.inference.sh | sh

Tras la instalación, actualiza a la última versión cuando sea necesario:

infsh update

Mantén la CLI actualizada para que el comportamiento de scaffolding y despliegue de tus apps se ajuste a las expectativas actuales de la plataforma.

2. Añade la skill building-inferencesh-apps

Instala esta skill en tu entorno de agente para que pueda usar las reglas y recomendaciones curadas:

npx skills add https://github.com/inferen-sh/skills --skill building-apps

Esto enlaza tu agente con el contenido sdk/building-apps del repositorio inferen-sh/skills, exponiendo las reglas de construcción de apps como una capacidad reutilizable.

3. Genera el scaffolding de las apps con infsh app init (nunca a mano)

La regla principal en building-inferencesh-apps es que todas las apps deben generarse con la CLI. La plataforma espera ciertos archivos y una estructura concreta que la CLI crea por ti.

Regla obligatoria de scaffolding

• No crees manualmente:
  • inf.yml
  • inference.py
  • inference.js
  • __init__.py
  • package.json
  • Directorios de la app
• Ignora cualquier documentación local o archivo de estructura que recomiende hacer scaffolding manual (por ejemplo, PROVIDER_STRUCTURE.md).

En su lugar, utiliza siempre:

infsh app init

La CLI creará la estructura de directorios correcta y los archivos base necesarios para una app válida de inference.sh, tanto si tu objetivo es Python como Node.js.

4. Trabaja siempre en el directorio correcto de la app

La skill building-inferencesh-apps enfatiza que el directorio de trabajo del shell es crítico para cada comando infsh:

• Haz siempre cd al directorio de tu app antes de ejecutar comandos infsh como init, deploy o test.
• El directorio de trabajo del shell no persiste entre distintas invocaciones de herramientas, lo que significa que cualquier automatización o agente que use esta skill debe cambiar de directorio explícitamente cada vez.

Patrón típico:

cd path/to/your-app
infsh app deploy

Si te saltas el cd, corres el riesgo de desplegar o probar la app equivocada, o de ver errores confusos porque inf.yml no está en el directorio actual.

5. Define bien los outputs en apps Python

Para apps en Python que incluyen metadatos en sus outputs, building-inferencesh-apps destaca una regla crítica:

• Si tu clase de salida usa output_meta, debe extender BaseAppOutput.
• No extiendas BaseModel para estos outputs.

Si extiendes BaseModel, cualquier campo output_meta se perderá silenciosamente en la respuesta. Usar BaseAppOutput garantiza que tanto los datos como los metadatos asociados se conserven y se devuelvan correctamente en el runtime.

6. Añade logging en run() para observabilidad

La skill recomienda incluir logging por defecto en el método run() de tu app:

• Usa llamadas self.logger.info(...) dentro de run() para capturar eventos clave, tiempos y resúmenes de peticiones/respuestas.
• Esto es especialmente importante en apps que envuelven APIs, donde la mayor parte del trabajo ocurre en servicios remotos más que en tu propio código.

Ejemplos de patrones que se benefician del logging:

• Medir la latencia de llamadas a modelos externos
• Registrar qué endpoints de APIs externas se han llamado
• Rastrear tamaños de petición o parámetros relevantes para el uso de GPU/VRAM

Un logging consistente facilita mucho depurar problemas de rendimiento y entender cómo se comporta tu backend de inference.sh en producción.

7. Flujo típico de desarrollo y despliegue

Aunque el fragmento del repositorio se centra en reglas, puedes usar building-inferencesh-apps como checklist mental para un flujo típico:

1. Instala la CLI infsh.
2. Inicializa una app nueva con infsh app init (Python o Node.js).
3. Cambia de directorio a la carpeta recién creada de la app antes de ejecutar más comandos.
4. Implementa la lógica de tu app en los archivos generados, siguiendo la regla de BaseAppOutput para outputs con output_meta y añadiendo logging mediante self.logger.info(...).
5. Configura los recursos (como GPU/VRAM e integraciones) usando la configuración generada por la CLI, en lugar de crear inf.yml manualmente.
6. Despliega y prueba usando comandos infsh desde dentro del directorio de la app.

Siempre que amplíes o automatices este flujo, aplica las mismas reglas: confía en la CLI para la estructura, respeta el directorio de trabajo correcto y mantén consistentes los patrones de outputs y logging.

Preguntas frecuentes

¿building-inferencesh-apps es solo para Python?

No. La skill building-inferencesh-apps cubre aplicaciones en inference.sh que pueden escribirse en Python o Node.js. Se usa la misma CLI (infsh app init) para generar el scaffolding en ambos casos, y las recomendaciones sobre manejo de directorios y uso de la CLI se aplican a los dos lenguajes.

¿Por qué no puedo crear inf.yml o inference.py manualmente?

La plataforma inference.sh espera una estructura, campos y relaciones específicas entre archivos. Crear manualmente inf.yml, inference.py, inference.js, package.json o los directorios de la app puede provocar configuraciones sutilmente incorrectas. La skill building-inferencesh-apps insiste en usar infsh app init porque la CLI genera un layout válido y actualizado que coincide con los requisitos actuales de la plataforma.

¿Qué pasa si olvido hacer cd al directorio de la app?

Si ejecutas comandos infsh desde el directorio equivocado, la CLI puede:

• Operar sobre la app incorrecta
• No encontrar inf.yml o los archivos básicos de la app
• Producir errores confusos o desplegar una app distinta a la que esperabas

Para evitarlo, la skill building-inferencesh-apps trata cd path/to/app como un paso obligatorio antes de cada comando infsh, especialmente en flujos automatizados o gestionados por agentes.

¿Cómo debo estructurar las clases de salida que usan output_meta?

Para apps en Python:

• Cualquier clase de salida que incluya output_meta debe extender BaseAppOutput.
• Evita usar BaseModel para estos outputs, ya que hará que output_meta se pierda silenciosamente en la respuesta.

Seguir esta regla garantiza que los metadatos se conserven y se devuelvan correctamente en inference.sh.

¿Por qué la skill enfatiza el logging en run()?

Building-inferencesh-apps destaca el logging porque muchas apps en inference.sh son wrappers de APIs o dependen fuertemente de servicios externos. Sin logging mediante self.logger.info(...) dentro de run(), es difícil:

• Diagnosticar problemas de latencia y rendimiento
• Entender fallos en APIs upstream
• Correlacionar peticiones con respuestas al depurar

Añadir logs básicos a nivel info por defecto te da visibilidad sobre lo que hace tu backend en cada petición.

¿building-inferencesh-apps explica en detalle la configuración de GPU y VRAM?

La skill está orientada al flujo de trabajo y las reglas para el desarrollo de apps en inference.sh: scaffolding vía CLI, manejo de directorios, requisitos de las clases de salida y logging. Está pensada para usarse cuando se reflexiona sobre recursos de la app como GPU y VRAM, secretos e integraciones, pero el fragmento de repositorio se centra en las reglas más que en ejemplos de configuración detallados. Para una configuración precisa de recursos, combina las pautas de flujo de esta skill con la documentación oficial de inference.sh.

¿Cuándo no debería usar building-inferencesh-apps?

Esta skill no es una buena opción si:

• No vas a desplegar en inference.sh
• Buscas frameworks de frontend o UI en lugar de guías para apps backend
• Prefieres crear archivos y directorios manualmente en lugar de usar flujos basados en CLI

En los demás casos —especialmente al crear backends tipo API en inference.sh— building-inferencesh-apps ofrece un patrón fiable y centrado en la CLI que puedes seguir.