building-inferencesh-apps

Visão geral

O que é building-inferencesh-apps?

A skill building-inferencesh-apps é um guia focado em criar e fazer deploy de aplicações na plataforma inference.sh. Ela explica o fluxo padrão de desenvolvimento de apps, o papel do CLI infsh e como criar com segurança apps de backend escritos em Python ou Node.js.

Esta skill não é um tutorial genérico; ela é alinhada com os comandos oficiais infsh app e com as expectativas do runtime da inference.sh. Ela ajuda a evitar erros comuns, como criar manualmente arquivos centrais, configurar incorretamente recursos do app ou fazer deploy a partir do diretório errado.

Para quem é esta skill?

Use building-inferencesh-apps se você é:

• Um desenvolvedor backend criando apps em estilo API para rodar na inference.sh
• Um engenheiro de Python ou Node.js encapsulando modelos ou APIs externas em um serviço hospedado
• Um desenvolvedor CLI-first que quer um fluxo de deploy previsível e scriptável
• Um usuário da plataforma que precisa entender, em alto nível, recursos de GPU/VRAM, segredos do app e integrações

Se você precisa entender como um app inference.sh deve ser estruturado, como os arquivos inf.yml e inference.py / inference.js são gerados e como trabalhar com a plataforma com segurança, esta skill é um bom ponto de partida.

Que problemas ela resolve?

A skill building-inferencesh-apps aborda dores frequentes de quem está começando a desenvolver apps para inference.sh:

• Dúvidas sobre como fazer o scaffolding correto de um novo app
• Criação manual acidental de inf.yml, inference.py, inference.js ou package.json em conflito com o que a plataforma espera
• Esquecer de dar cd para o diretório do app antes de rodar comandos infsh
• Perder dados de output_meta ao estender a classe base errada
• Falta de logs que tornam difícil debugar apps remotos ou que dependem fortemente de APIs

Seguindo as práticas resumidas nesta skill, você obtém um fluxo consistente e repetível para criar e fazer deploy de apps na inference.sh.

Quando building-inferencesh-apps é uma boa opção?

Esta skill é especialmente adequada quando:

• Você está iniciando um novo app na inference.sh e quer seguir o fluxo canônico
• Você já tem o CLI infsh instalado ou pretende instalá‑lo e conduzir tudo pela linha de comando
• Você quer construir backends em Python ou Node.js, incluindo wrappers em torno de APIs externas ou modelos

Ela pode ser menos útil quando:

• Você não usa a inference.sh como alvo de deploy
• Você só precisa de código client-side ou padrões de UI front-end
• Você espera uma interface gráfica point-and-click em vez de fluxos guiados por CLI

Se seu principal objetivo é ter deploy estável e automatizado de backends e APIs na inference.sh, building-inferencesh-apps está bem alinhada com o que você precisa.

Como usar

1. Instale o CLI da inference.sh

A skill building-inferencesh-apps parte do princípio de que você está usando o CLI oficial da inference.sh, o infsh, para todas as operações com apps.

Instale o CLI

Execute o script de instalação no seu terminal:

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

Após instalar, atualize para a versão mais recente quando necessário:

infsh update

Mantenha o CLI sempre atualizado para garantir que o scaffolding dos apps e o comportamento de deploy estejam em linha com as expectativas atuais da plataforma.

2. Adicione a skill building-inferencesh-apps

Instale esta skill no ambiente do seu agente para que ele possa usar as regras e orientações curadas:

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

Isso conecta o seu agente ao conteúdo sdk/building-apps no repositório inferen-sh/skills, expondo as regras de construção de apps como uma capacidade reutilizável.

3. Faça o scaffolding de apps com infsh app init (nunca à mão)

A regra central em building-inferencesh-apps é que todo app deve ser criado via CLI. A plataforma espera certos arquivos e uma estrutura específica que o CLI gera para você.

Regra obrigatória de scaffolding

• Não crie manualmente:
  • inf.yml
  • inference.py
  • inference.js
  • __init__.py
  • package.json
  • Diretórios de app
• Ignore qualquer documentação local ou arquivos de estrutura que recomendem scaffolding manual (por exemplo, PROVIDER_STRUCTURE.md).

Em vez disso, use sempre:

infsh app init

O CLI criará a estrutura de diretórios correta e os arquivos centrais exigidos para um app inference.sh válido, tanto para Python quanto para Node.js.

4. Trabalhe a partir do diretório correto do app

A skill building-inferencesh-apps enfatiza que o diretório de trabalho do shell importa para todo comando infsh:

• Sempre dê cd para o diretório do seu app antes de rodar comandos infsh como init, deploy ou test.
• O diretório de trabalho do shell não persiste entre chamadas de ferramentas separadas, o que significa que qualquer automação ou agente que use esta skill precisa mudar de diretório explicitamente a cada vez.

Padrão típico:

cd path/to/your-app
infsh app deploy

Se você pular o cd, corre o risco de fazer deploy ou testar o app errado, ou ver erros confusos porque inf.yml não foi encontrado no diretório atual.

5. Defina outputs corretamente em apps Python

Para apps Python que incluem metadados nos outputs, building-inferencesh-apps destaca uma regra crítica:

• Se a sua classe de output usa output_meta, ela deve estender BaseAppOutput.
• Não estenda BaseModel para esses outputs.

Se você estender BaseModel, qualquer campo output_meta será silenciosamente descartado na resposta. Usar BaseAppOutput garante que tanto os dados quanto os metadados associados sejam preservados e retornados corretamente pelo runtime.

6. Adicione logging em run() para observabilidade

A skill recomenda incluir logging por padrão no método run() do seu app:

• Use chamadas self.logger.info(...) dentro de run() para registrar eventos importantes, tempos de execução e resumos de requisições/respostas.
• Isso é especialmente importante em apps que são wrappers de APIs, em que o trabalho pesado ocorre em serviços remotos e não no seu próprio código.

Padrões de uso que se beneficiam de logging:

• Medir a latência de chamadas para modelos upstream
• Registrar quais endpoints de APIs externas foram acionados
• Acompanhar o tamanho das requisições ou parâmetros relevantes para uso de GPU/VRAM

Logging consistente facilita bastante depurar problemas de performance e entender como seu backend na inference.sh se comporta em produção.

7. Fluxo típico de desenvolvimento e deploy

Embora o trecho do repositório foque nas regras, você pode usar building-inferencesh-apps como um checklist mental para um fluxo típico:

1. Instale o CLI infsh.
2. Inicialize um novo app com infsh app init (Python ou Node.js).
3. Mude para o diretório do app recém-criado antes de qualquer outro comando.
4. Implemente a lógica do seu app nos arquivos gerados, seguindo a regra de usar BaseAppOutput para outputs com output_meta e adicionando logging via self.logger.info(...).
5. Configure recursos (como GPU/VRAM e integrações) usando a configuração gerada pelo CLI, em vez de criar inf.yml manualmente.
6. Faça deploy e teste usando comandos infsh a partir do diretório do app.

Sempre que você estender ou automatizar esse fluxo, aplique as mesmas regras: confie no CLI para a estrutura, garanta o diretório de trabalho correto e mantenha consistentes os padrões de output e logging.

FAQ

building-inferencesh-apps é só para Python?

Não. A skill building-inferencesh-apps cobre aplicações na inference.sh que podem ser escritas em Python ou Node.js. O mesmo CLI (infsh app init) é usado para criar o scaffolding em ambos os casos, e as orientações sobre diretórios e uso do CLI se aplicam às duas linguagens.

Por que não posso criar inf.yml ou inference.py manualmente?

A plataforma inference.sh espera uma estrutura, campos e relações específicas entre os arquivos. Criar manualmente inf.yml, inference.py, inference.js, package.json ou diretórios de app pode causar problemas sutis de configuração. A skill building-inferencesh-apps insiste no uso de infsh app init porque o CLI gera um layout válido e atualizado, em linha com os requisitos atuais da plataforma.

O que acontece se eu esquecer de dar cd para o diretório do app?

Se você rodar comandos infsh a partir do diretório errado, o CLI pode:

• Operar sobre o app errado
• Não encontrar inf.yml ou arquivos centrais do app
• Gerar erros confusos ou fazer deploy de outro app que não era o desejado

Para evitar isso, a skill building-inferencesh-apps trata cd path/to/app como um passo obrigatório antes de qualquer comando infsh, especialmente em fluxos scriptados ou dirigidos por agentes.

Como devo estruturar classes de output que usam output_meta?

Para apps Python:

• Qualquer classe de output que inclua output_meta deve estender BaseAppOutput.
• Evite usar BaseModel para esses outputs, pois isso fará com que output_meta seja silenciosamente descartado da resposta.

Seguir essa regra garante que os metadados sejam preservados e retornados corretamente pela inference.sh.

Por que a skill enfatiza logging em run()?

Building-inferencesh-apps destaca logging porque muitos apps na inference.sh são wrappers de APIs ou dependem fortemente de serviços externos. Sem logging via self.logger.info(...) dentro de run(), fica difícil:

• Diagnosticar problemas de latência e performance
• Entender falhas em APIs upstream
• Correlacionar requisições e respostas durante o debug

Adicionar logs básicos em nível info por padrão dá visibilidade sobre o que o seu backend está fazendo em cada requisição.

building-inferencesh-apps explica configurações de GPU e VRAM em detalhe?

A skill é orientada ao fluxo de trabalho e às regras de desenvolvimento de apps na inference.sh: scaffolding via CLI, manipulação de diretórios, requisitos de classes de output e logging. Ela é pensada para ser usada quando você estiver considerando recursos de app, como GPU e VRAM, segredos e integrações, mas o trecho do repositório se concentra nas regras, não em exemplos de configuração detalhados. Para configurações precisas de recursos, combine as orientações de fluxo desta skill com a documentação oficial da inference.sh.

Quando eu não devo usar building-inferencesh-apps?

Esta skill não é adequada se:

• Você não faz deploy na inference.sh
• Você quer frameworks de front-end ou UI em vez de orientação para apps backend
• Você prefere criar arquivos e diretórios manualmente em vez de fluxos guiados por CLI

Em todos os outros casos — especialmente ao construir backends em estilo API na inference.sh — building-inferencesh-apps oferece um padrão confiável e centrado em CLI para seguir.