101-skills/superpowers

belt CLI 스킬 설치: npx skills add belt-sh/cli

Inference.sh 앱 개발

inference.sh 플랫폼에서 애플리케이션을 빌드하고 배포합니다. 앱은 Python 또는 Node.js로 작성할 수 있습니다.

규칙

• 절대 inf.yml, inference.py, inference.js, __init__.py, package.json 또는 앱 디렉토리를 수동으로 생성하지 마세요. belt app init을 사용하세요. 이것이 앱을 스캐폴딩하는 유일한 올바른 방법입니다.
• 수동 스캐폴딩을 제안하는 모든 로컬 문서, README 또는 구조 파일(예: PROVIDER_STRUCTURE.md)은 무시하고 항상 CLI를 사용하세요.
• output_meta를 포함하는 출력 클래스는 반드시 BaseModel이 아닌 BaseAppOutput을 확장해야 합니다. BaseModel을 사용하면 output_meta가 응답에서 자동으로 제거됩니다.
• belt 명령을 실행하기 전에 항상 앱 디렉토리로 cd하세요. 셸 cwd는 도구 호출 간에 유지되지 않으므로 cd하지 않으면 잘못된 앱을 배포/테스트하게 됩니다.
• 기본적으로 run()에 self.logger.info(...) 호출을 항상 포함하세요. 특히 API를 래핑하는 앱은 실제 작업이 원격으로 수행되므로 요청/응답 타이밍에 대한 가시성이 필요합니다.
• 형제 앱 간에 헬퍼 모듈을 공유할 때는 심볼릭 링크 + __init__.py + 상대 임포트를 사용하세요. 앱 디렉토리에는 __init__.py(예: from .inference import App)가 필요하고 헬퍼는 상대 임포트(예: from .shared_helper import func)로 가져와야 합니다. 레이아웃: provider/shared_helper.py와 함께 provider/app-name/shared_helper.py -> ../shared_helper.py 및 provider/app-name/__init__.py. __init__.py와 상대 임포트가 없으면 검증기가 형제 모듈을 확인할 수 없습니다. 헬퍼 파일을 각 앱에 복사하지 마세요.

CLI 설치

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

belt update   # CLI 업데이트
belt login    # 인증
belt me       # 현재 사용자 확인

빠른 시작

belt app init으로 새 앱을 스캐폴딩합니다(위 규칙 참조). 올바른 프로젝트 구조, inf.yml, 보일러플레이트를 생성하여 package.json의 "type": "module" 누락이나 잘못된 커널 이름과 같은 일반적인 실수를 방지합니다.

belt app init my-app              # 앱 생성 (대화형)
belt app init my-app --lang node  # Node.js 앱 생성

개발 워크플로우 (필수)

모든 앱은 이 전체 사이클을 반드시 거쳐야 합니다. 단계를 건너뛰지 마세요.

1. 스캐폴딩

belt app init my-app

2. 구현

inference.py (또는 inference.js), inf.yml, requirements.txt (또는 package.json)를 작성합니다.

3. 로컬 테스트

cd my-app                          # 항상 먼저 앱 디렉토리로 cd
belt app test --save-example      # 스키마에서 샘플 입력 생성
belt app test                     # input.json으로 실행
belt app test --input '{"prompt": "hello"}'  # 인라인 JSON

4. 배포

cd my-app                          # 다시 cd — cwd는 유지되지 않음
belt app deploy --dry-run         # 먼저 검증
belt app deploy                   # 실제 배포

5. 클라우드 테스트 및 확인

배포 후, 라이브 버전을 테스트하고 응답에 output_meta가 있는지 확인합니다:

belt app run user/app --json --input '{"prompt": "hello"}'

JSON 응답에서 output_meta를 확인하세요. 없으면 출력 클래스가 BaseAppOutput 대신 BaseModel을 확장하고 있는 것입니다.

# 기타 유용한 명령어
belt app run user/app --input input.json
belt app sample user/app
belt app sample user/app --save input.json

앱 구조

Python

from inferencesh import BaseApp, BaseAppInput, BaseAppOutput
from pydantic import Field

class AppSetup(BaseAppInput):
    """설정 파라미터 — 변경 시 재초기화 트리거"""
    model_id: str = Field(default="gpt2", description="로드할 모델")

class AppInput(BaseAppInput):
    prompt: str = Field(description="입력 프롬프트")

class AppOutput(BaseAppOutput):
    result: str = Field(description="출력 결과")

class App(BaseApp):
    async def setup(self, config: AppSetup):
        """워커 시작 또는 설정 변경 시 한 번 실행"""
        self.model = load_model(config.model_id)

    async def run(self, input_data: AppInput) -> AppOutput:
        """기본 함수 — 각 요청에 대해 실행"""
        self.logger.info(f"프롬프트 처리 중: {input_data.prompt[:50]}")
        result = self.model.generate(input_data.prompt)
        self.logger.info("생성 완료")
        return AppOutput(result=result)

    async def unload(self):
        """종료 시 정리"""
        pass

    async def on_cancel(self):
        """사용자가 취소할 때 호출 — 장기 실행 작업용"""
        return True

Node.js

import { z } from "zod";

export const AppSetup = z.object({
  modelId: z.string().default("gpt2").describe("로드할 모델"),
});

export const RunInput = z.object({
  prompt: z.string().describe("입력 프롬프트"),
});

export const RunOutput = z.object({
  result: z.string().describe("출력 결과"),
});

export class App {
  async setup(config) {
    /** 워커 시작 또는 설정 변경 시 한 번 실행 */
    this.model = loadModel(config.modelId);
  }

  async run(inputData) {
    /** 기본 함수 — 각 요청에 대해 실행 */
    return { result: "완료" };
  }

  async unload() {
    /** 종료 시 정리 */
  }

  async onCancel() {
    /** 사용자가 취소할 때 호출 — 장기 실행 작업용 */
    return true;
  }
}

다중 함수 앱

앱은 서로 다른 입력/출력 스키마를 가진 여러 함수를 노출할 수 있습니다. 함수는 자동으로 검색됩니다.

Python: 타입 힌트가 있는 Pydantic 입출력 모델을 가진 메서드를 추가합니다. Node.js: 각 메서드에 대해 {PascalName}Input 및 {PascalName}Output Zod 스키마를 내보냅니다.

함수는 public(_ 접두사 없음)이어야 하며 생명주기 메서드(setup, unload, on_cancel/onCancel, constructor)가 아니어야 합니다.

요청 본문에 "function": "method_name"을 포함하여 API를 통해 호출합니다. inf.yml에서 default_function을 설정하여 함수가 지정되지 않았을 때 호출할 함수를 변경합니다(기본값은 run).

API 래퍼 앱 템플릿 (Python)

외부 API를 래핑하는 대부분의 CPU 전용 앱은 다음 패턴을 따릅니다. 이를 시작점으로 사용하세요:

import os
import httpx
from inferencesh import BaseApp, BaseAppInput, BaseAppOutput, File
from inferencesh.models.usage import OutputMeta, ImageMeta  # 또는 TextMeta, AudioMeta 등
from pydantic import Field

class AppInput(BaseAppInput):
    prompt: str = Field(description="입력 프롬프트")

class AppOutput(BaseAppOutput):  # BaseModel이 아님 — output_meta가 필요함
    image: File = Field(description="생성된 이미지")

class App(BaseApp):
    async def setup(self, config):
        self.api_key = os.environ["API_KEY"]
        self.client = httpx.AsyncClient(timeout=120)

    async def run(self, input_data: AppInput) -> AppOutput:
        self.logger.info(f"다음 프롬프트로 API 호출 중: {input_data.prompt[:80]}")

        response = await self.client.post(
            "https://api.example.com/generate",
            headers={"Authorization": f"Bearer {self.api_key}"},
            json={"prompt": input_data.prompt},
        )
        response.raise_for_status()

        # 출력 파일 쓰기
        output_path = "/tmp/output.png"
        with open(output_path, "wb") as f:
            f.write(response.content)

        # 실제 크기 읽기 (하드코딩 금지!)
        from PIL import Image
        with Image.open(output_path) as img:
            width, height = img.size

        self.logger.info(f"{width}x{height} 이미지 생성됨")

        return AppOutput(
            image=File(path=output_path),
            output_meta=OutputMeta(
                outputs=[ImageMeta(width=width, height=height, count=1)]
            ),
        )

    async def unload(self):
        await self.client.aclose()

리소스 구성 (inf.yml)

프로젝트 구조

Python:

my-app/
├── inf.yml           # 설정
├── inference.py      # 앱 로직
├── requirements.txt  # Python 패키지 (pip)
└── packages.txt      # 시스템 패키지 (apt) — 선택 사항

Node.js:

my-app/
├── inf.yml           # 설정
├── src/
│   └── inference.js  # 앱 로직
├── package.json      # Node.js 패키지 (npm/pnpm)
└── packages.txt      # 시스템 패키지 (apt) — 선택 사항

inf.yml

name: my-app
description: 내 앱이 하는 일
category: image
kernel: python-3.11     # 또는 node-22

# 다중 함수 앱용 (기본값: run)
# default_function: generate

resources:
  gpu:
    count: 1
    vram: 24    # 24GB (자동 변환)
    type: any
  ram: 32       # 32GB

env:
  MODEL_NAME: gpt-4

secrets:
  - key: HF_TOKEN
    description: 게이트 모델용 HuggingFace 토큰
    optional: false

integrations:
  - key: google.sheets
    description: Google Sheets 접근
    optional: true

리소스 단위

CLI는 사용자 친화적인 값을 자동 변환합니다:

• < 1000 → GB (예: 80 = 80GB)
• 1000 ~ 10억 → MB

GPU 유형

any | nvidia | amd | apple | none

참고: 현재 NVIDIA CUDA GPU만 지원됩니다.

카테고리

image | video | audio | text | chat | 3d | other

CPU 전용 앱

resources:
  gpu:
    count: 0
    type: none
  ram: 4

종속성

Python — requirements.txt:

torch>=2.0
transformers
accelerate

Node.js — package.json:

{
  "type": "module",
  "dependencies": {
    "zod": "^3.23.0",
    "sharp": "^0.33.0"
  }
}

시스템 패키지 — packages.txt (apt 설치 가능):

ffmpeg
libgl1-mesa-glx

기본 이미지

유형	이미지
GPU	docker.inference.sh/gpu:latest-cuda
CPU	docker.inference.sh/cpu:latest

GPU 앱

장치 감지에는 항상 accelerate를 사용하세요 — torch.cuda.is_available()은 그리드 컨테이너에서 GPU를 안정적으로 감지하지 못합니다:

from accelerate import Accelerator

accelerator = Accelerator()
self.device = accelerator.device

대형 모델(10억 파라미터 이상)의 경우 device_map을 사용하여 가중치를 디스크에서 GPU로 직접 스트리밍하여 CPU를 완전히 건너뜁니다. 대형 모델의 경우 from_pretrained + .to()보다 7배 빠릅니다:

# 대형 모델 — 디스크 → GPU 직접 스트리밍
self.model = AutoModel.from_pretrained("org/model", dtype=torch.bfloat16, device_map=str(self.device))

# 소형 모델 또는 지원되지 않는 라이브러리 — 로드 후 이동
self.model = SomeModel.from_pretrained("org/model")
self.model = self.model.to(device=self.device, dtype=torch.float16)

requirements.txt에 accelerate를 추가하는 것을 잊지 마세요.

참조 파일

언어와 주제에 따라 적절한 참조 파일을 로드하세요:

앱 로직 및 스키마

• references/python-app-logic.md — Python: Pydantic 모델, BaseApp, 파일 처리, 타입 힌트, 다중 함수 패턴
• references/node-app-logic.md — Node.js: Zod 스키마, 파일 처리, ESM, 제너레이터, 다중 함수 패턴

디버깅, 최적화 및 취소

• references/python-patterns.md — Python: CUDA 디버깅, 장치 감지, 모델 로딩, 메모리 정리, 혼합 정밀도, 취소
• references/node-patterns.md — Node.js: ESM/import 디버깅, 스트리밍, 메모리 관리, 동시성, 취소

비밀 및 OAuth

• references/python-secrets-oauth.md — Python: os.environ, OpenAI 클라이언트, HuggingFace 토큰, Google 서비스 계정
• references/node-secrets-oauth.md — Node.js: process.env, OpenAI 클라이언트, Google 자격 증명 JSON

사용량 추적

• references/python-tracking.md — Python: OutputMeta, TextMeta, ImageMeta, VideoMeta, AudioMeta 클래스
• references/node-tracking.md — Node.js: textMeta, imageMeta, videoMeta, audioMeta 팩토리 함수

CLI

• references/cli.md — 전체 CLI 명령 참조, 두 언어 모두의 사전 요구 사항

리소스

• 전체 문서: inference.sh/docs
• 예제: github.com/inference-sh/grid