building-inferencesh-apps

概要

building-inferencesh-apps とは？

building-inferencesh-apps スキルは、inference.sh プラットフォーム上でアプリケーションを作成・デプロイするための、用途を絞ったガイドです。標準的なアプリ開発の流れ、infsh CLI の役割、Python や Node.js で書かれたバックエンド系アプリを安全にスキャフォールド・管理する方法を説明します。

このスキルは一般的なチュートリアルではなく、公式の infsh app コマンドと inference.sh ランタイムの前提条件に揃えられています。コアファイルの手動作成、リソース設定の誤り、誤ったディレクトリからのデプロイなど、よくあるミスを避けるのに役立ちます。

このスキルの対象者

building-inferencesh-apps は、次のような方に向いています。

• inference.sh 上で API 形式のアプリを動かす バックエンド開発者
• モデルや外部 API をラップしてホスト型サービスにしたい Python / Node.js エンジニア
• 予測可能でスクリプト化しやすいデプロイフローを求める CLI 中心 の開発者
• GPU / VRAM リソース、アプリシークレット、各種インテグレーションを高いレベルで理解したいプラットフォーム利用者

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 の init / deploy / test などを実行する前に、必ず対象アプリのディレクトリへ cd してください。
• シェルの作業ディレクトリは、ツール呼び出しごとに持ち越されるわけではありません。そのため、このスキルを使う自動化やエージェントは、毎回明示的に 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. CLI が生成した設定をベースに、GPU / VRAM や各種インテグレーションなどの リソースを設定 する（inf.yml を手動で作成しない）。
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、アプリディレクトリを手動で作成すると、微妙な設定ずれが発生しやすくなります。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() 内のログ出力を強調するのですか？

多くの inference.sh アプリは API ラッパー であったり、外部サービスへの依存度が高かったりします。run() の中で self.logger.info(...) によるログを出していないと、次のような点が把握しづらくなります。

• レイテンシやパフォーマンス上の問題の原因
• 上流 API で何が失敗しているのか
• デバッグ時にリクエストとレスポンスを突き合わせるための手がかり

デフォルトで info レベルのログを少なくとも入れておくことで、バックエンドが各リクエストで何をしているのかを可視化できるようになります。

building-inferencesh-apps は GPU や VRAM 設定を詳しく説明していますか？

このスキルは、inference.sh アプリ開発における ワークフローとルール（CLI によるスキャフォールド、ディレクトリの扱い、出力クラスの要件、ログの推奨など）に主眼を置いています。GPU や VRAM、シークレット、インテグレーションといったリソースを考える際に併せて使うことを想定していますが、リポジトリ抜粋部分では詳細な設定例までは扱っていません。具体的なリソース設定については、このスキルのワークフローガイダンスと公式 inference.sh ドキュメントを組み合わせて利用してください。

building-inferencesh-apps を使うべきでないのはどんなときですか？

このスキルが適さないのは次のような場合です。

• デプロイ先として inference.sh を使わない
• バックエンドではなく、フロントエンドや UI フレームワークのガイドだけが欲しい
• CLI 駆動ではなく、自分でファイルやディレクトリ構造を作り込みたい

それ以外、特に inference.sh 上で API 型バックエンドを構築する場合には、building-inferencesh-apps は信頼できる CLI 中心のパターンを提供してくれます。