building-inferencesh-apps

개요

building-inferencesh-apps란?

building-inferencesh-apps 스킬은 inference.sh 플랫폼에서 애플리케이션을 생성하고 배포하는 방법을 집중적으로 다루는 가이드입니다. 표준 앱 워크플로우, infsh CLI의 역할, 그리고 Python 또는 Node.js로 작성된 백엔드 스타일 앱을 안전하게 스캐폴딩하고 관리하는 방법을 설명합니다.

이 스킬은 일반적인 튜토리얼이 아니라, 공식 infsh app 명령과 inference.sh 런타임의 기대 사항에 맞춰 설계되어 있습니다. inf.yml 같은 핵심 파일을 수동으로 만들거나, 앱 리소스를 잘못 설정하거나, 잘못된 디렉터리에서 배포하는 등 흔한 실수를 피하도록 도와줍니다.

이 스킬은 누구를 위한 것인가요?

다음과 같은 경우 building-inferencesh-apps를 사용하면 좋습니다:

• inference.sh에서 API 스타일 앱을 만들려는 백엔드 개발자
• 모델 또는 외부 API를 래핑해 호스팅 서비스로 제공하려는 Python 또는 Node.js 엔지니어
• 예측 가능하고 스크립트 친화적인 배포 플로우를 원하는 CLI 중심 개발자
• GPU/VRAM 리소스, 앱 시크릿, 통합(Integration)에 대해 개략적으로 이해해야 하는 플랫폼 사용자

inference.sh 앱의 구조, inf.yml과 inference.py / inference.js 파일이 어떻게 생성되는지, 그리고 플랫폼을 안전하게 사용하는 방법이 궁금하다면 이 스킬이 출발점으로 적합합니다.

어떤 문제를 해결하나요?

building-inferencesh-apps 스킬은 inference.sh 앱 개발을 처음 시작할 때 자주 겪는 어려움을 다룹니다:

• 새 앱을 올바르게 스캐폴딩하는 방법에 대한 혼란
• 플랫폼의 기대와 충돌하는 inf.yml, inference.py, inference.js, package.json 등을 실수로 수동 생성하는 문제
• infsh 명령을 실행하기 전에 앱 디렉터리로 cd 하는 것을 잊는 문제
• 잘못된 베이스 클래스를 상속해 output_meta 데이터를 잃어버리는 문제
• 로깅 부족으로 원격/외부 API 의존도가 높은 앱을 디버깅하기 어려운 문제

이 스킬에서 정리한 원칙을 따르면 inference.sh 앱을 빌드하고 배포하는 작업을 일관되고 반복 가능한 워크플로우로 운영할 수 있습니다.

언제 building-inferencesh-apps를 쓰면 좋을까요?

다음과 같은 상황에 특히 잘 맞습니다:

• inference.sh에서 새 앱을 시작하면서 공식적인 워크플로우를 따르고 싶을 때
• 이미 infsh CLI를 설치했거나, 앞으로 설치해 모든 작업을 커맨드 라인에서 처리하려 할 때
• 외부 API나 모델 래퍼를 포함한 Python 또는 Node.js 백엔드를 만들고자 할 때

다음과 같은 경우에는 덜 유용할 수 있습니다:

• inference.sh를 배포 대상 플랫폼으로 사용하지 않을 때
• 클라이언트 사이드 코드나 프론트엔드 UI 패턴만 필요할 때
• CLI 기반 워크플로우 대신 포인트 앤 클릭 GUI를 기대할 때

주요 목표가 inference.sh 위에서 안정적이고 자동화된 백엔드 및 API 배포라면, building-inferencesh-apps는 요구 사항과 잘 맞는 스킬입니다.

사용 방법

1. inference.sh CLI 설치

building-inferencesh-apps 스킬은 모든 앱 작업을 공식 inference.sh CLI인 infsh로 수행한다고 가정합니다.

CLI 설치하기

터미널에서 설치 스크립트를 실행합니다:

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

설치 후에는 필요에 따라 최신 버전으로 업데이트합니다:

infsh update

CLI를 최신 상태로 유지해야 앱 스캐폴딩과 배포 동작이 현재 플랫폼의 기대와 정확히 일치합니다.

2. building-inferencesh-apps 스킬 추가

에이전트 환경에 이 스킬을 설치해 정리된 규칙과 가이드를 참고할 수 있도록 합니다:

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

이 명령은 inferen-sh/skills 리포지토리의 sdk/building-apps 콘텐츠를 에이전트에 연결해, 앱 빌딩 규칙을 재사용 가능한 기능으로 노출합니다.

3. 앱은 반드시 infsh app init으로 스캐폴딩하기 (수동 생성 금지)

building-inferencesh-apps의 핵심 규칙은 모든 앱을 반드시 CLI로 스캐폴딩해야 한다는 점입니다. 플랫폼은 CLI가 생성해 주는 특정 파일과 디렉터리 구조를 전제로 동작합니다.

필수 스캐폴딩 규칙

• 다음 항목은 절대 수동으로 생성하지 마세요:
  • inf.yml
  • inference.py
  • inference.js
  • __init__.py
  • package.json
  • 앱 디렉터리
• 수동 스캐폴딩을 권장하는 로컬 문서나 구조 파일(예: PROVIDER_STRUCTURE.md)은 무시합니다.

항상 다음 명령을 사용하세요:

infsh app init

CLI는 Python이든 Node.js이든 상관없이 유효한 inference.sh 앱에 필요한 올바른 디렉터리 구조와 핵심 파일을 생성합니다.

4. 올바른 앱 디렉터리에서 작업하기

building-inferencesh-apps 스킬은 모든 infsh 명령에 대해 셸의 현재 작업 디렉터리가 매우 중요하다는 점을 강조합니다:

• infsh app init, infsh app deploy, infsh app test와 같은 명령을 실행하기 전에 항상 앱 디렉터리로 cd 하세요.
• 셸의 작업 디렉터리는 도구 호출 사이에 자동으로 유지되지 않습니다. 따라서 이 스킬을 사용하는 모든 자동화나 에이전트는 매번 명시적으로 디렉터리를 변경해야 합니다.

일반적인 패턴:

cd path/to/your-app
infsh app deploy

cd를 건너뛰면 잘못된 앱을 배포하거나 테스트할 수 있고, 현재 디렉터리에 inf.yml이 없어서 이해하기 어려운 에러가 발생할 수 있습니다.

5. Python 앱에서 출력 정의를 올바르게 구성하기

출력에 메타데이터를 포함하는 Python 앱의 경우, building-inferencesh-apps는 다음과 같은 중요한 규칙을 제시합니다:

• 출력 클래스에서 output_meta를 사용한다면 반드시 BaseAppOutput을 상속해야 합니다.
• 이런 출력 클래스에서는 BaseModel을 상속하면 안 됩니다.

BaseModel을 상속하면 output_meta 필드는 응답에서 조용히 삭제됩니다. BaseAppOutput을 사용해야 데이터와 관련 메타데이터가 런타임에서 제대로 보존되고 반환됩니다.

6. 관측 가능성을 위해 run()에 로깅 추가하기

이 스킬은 앱의 run() 메서드에 기본적으로 로깅을 포함할 것을 권장합니다:

• run() 내부에서 self.logger.info(...) 호출을 사용해 주요 이벤트, 처리 시간, 요청/응답 요약을 기록합니다.
• 특히 실제 작업이 대부분 외부 서비스에서 수행되는 API 래핑 앱에서는 로깅이 중요합니다.

로깅이 특히 도움이 되는 예시는 다음과 같습니다:

• 상위 모델 호출의 지연 시간 측정
• 어떤 외부 API 엔드포인트가 호출되었는지 기록
• GPU/VRAM 사용과 관련 있는 요청 크기나 파라미터를 추적

일관된 로깅은 성능 문제를 디버깅하고, 프로덕션 환경에서 inference.sh 백엔드가 어떻게 동작하는지 이해하는 데 큰 도움이 됩니다.

7. 전형적인 개발 및 배포 플로우

리포지토리 일부는 주로 규칙에 초점을 맞추고 있지만, building-inferencesh-apps를 다음과 같은 전형적인 워크플로우를 위한 체크리스트처럼 활용할 수 있습니다:

1. infsh CLI를 설치합니다.
2. infsh app init으로 새 앱을 초기화합니다 (Python 또는 Node.js).
3. 이후 모든 명령은 새로 생성된 앱 폴더로 디렉터리를 변경한 뒤 실행합니다.
4. 생성된 파일에서 앱 로직을 구현합니다. output_meta를 사용하는 출력 클래스는 BaseAppOutput을 따르게 하고, self.logger.info(...)로 로깅을 추가합니다.
5. GPU/VRAM 및 통합(Integrations) 같은 리소스 설정은 inf.yml을 직접 만들지 말고, CLI가 생성한 설정을 기준으로 구성합니다.
6. 앱 디렉터리 안에서 infsh 명령을 사용해 배포 및 테스트를 진행합니다.

이 플로우를 확장하거나 자동화할 때도 동일한 원칙을 적용하세요. 구조는 CLI에 맡기고, 작업 디렉터리를 엄격히 관리하며, 출력 구조와 로깅 패턴을 일관되게 유지하는 것이 핵심입니다.

FAQ

building-inferencesh-apps는 Python 전용인가요?

아니요. building-inferencesh-apps 스킬은 Python과 Node.js로 작성된 inference.sh 애플리케이션 모두를 다룹니다. 두 언어 모두 같은 CLI(infsh app init)로 스캐폴딩하며, 디렉터리 처리와 CLI 사용에 대한 가이드는 양쪽에 동일하게 적용됩니다.

왜 inf.yml이나 inference.py를 직접 만들면 안 되나요?

inference.sh 플랫폼은 파일 간의 구조, 필드, 관계에 대해 명확한 기대치를 가지고 있습니다. inf.yml, inference.py, inference.js, package.json, 앱 디렉터리를 수동으로 만들면 미묘한 설정 오류가 쉽게 생길 수 있습니다. building-inferencesh-apps 스킬이 infsh app init 사용을 강하게 요구하는 이유는, CLI가 현재 플랫폼 요구 사항에 맞는 유효하고 최신 레이아웃을 자동으로 생성해 주기 때문입니다.

앱 디렉터리로 cd 하는 것을 잊으면 어떻게 되나요?

잘못된 디렉터리에서 infsh 명령을 실행하면 CLI는 다음과 같이 동작할 수 있습니다:

• 엉뚱한 앱을 기준으로 작업을 수행
• inf.yml이나 핵심 앱 파일을 찾지 못함
• 이해하기 어려운 에러를 내거나 예상과 다른 앱을 배포

이런 문제를 방지하기 위해, building-inferencesh-apps 스킬은 특히 스크립트나 에이전트 기반 워크플로우에서 모든 infsh 명령 전에 cd path/to/app을 필수 단계로 간주합니다.

output_meta를 사용하는 출력 클래스는 어떻게 구조화해야 하나요?

Python 앱의 경우:

• output_meta를 포함하는 모든 출력 클래스는 BaseAppOutput을 상속해야 합니다.
• 이런 출력에 BaseModel을 사용하면 응답에서 output_meta가 조용히 사라지므로 피해야 합니다.

이 규칙을 따르면 메타데이터가 inference.sh에서 올바르게 보존되고 반환됩니다.

왜 이 스킬은 run()에서의 로깅을 강조하나요?

building-inferencesh-apps는 많은 inference.sh 앱이 API 래퍼이거나 외부 서비스 의존도가 높다는 점 때문에 로깅을 중요하게 다룹니다. run() 내부에서 self.logger.info(...)로 로깅하지 않으면 다음과 같은 일이 어려워집니다:

• 지연 시간과 성능 문제를 진단
• 상위 API의 장애 원인 파악
• 디버깅 시 요청과 응답을 서로 연관 지어 추적

기본적인 info 레벨 로그만 추가해도, 각 요청마다 백엔드가 무엇을 하고 있는지 훨씬 잘 파악할 수 있습니다.

이 스킬이 GPU와 VRAM 설정을 자세히 설명하나요?

이 스킬은 inference.sh 앱 개발을 위한 워크플로우와 규칙—CLI 기반 스캐폴딩, 디렉터리 처리, 출력 클래스 요구사항, 로깅—에 초점을 맞추고 있습니다. GPU·VRAM, 시크릿, 통합 같은 리소스를 고려할 때 함께 사용하기 좋은 흐름 가이드이긴 하지만, 리포지토리 발췌본은 규칙 중심이라 상세 설정 예시는 포함하지 않습니다. 구체적인 리소스 설정은 이 스킬에서 제시하는 워크플로우와 함께 공식 inference.sh 문서를 참고하는 것이 좋습니다.

언제 building-inferencesh-apps를 사용하지 않는 것이 좋나요?

다음과 같은 경우에는 이 스킬이 적합하지 않습니다:

• inference.sh로 배포하지 않을 때
• 백엔드 앱 가이드가 아니라 프론트엔드나 UI 프레임워크 관련 내용이 필요할 때
• CLI 중심이 아닌, 파일과 디렉터리를 수동으로 만들며 작업하길 선호할 때

그 외, 특히 inference.sh 위에서 API 스타일 백엔드를 구축하려는 경우에는 building-inferencesh-apps가 신뢰할 수 있는 CLI 중심 패턴을 제공합니다.