building-inferencesh-apps

概觀

什麼是 building-inferencesh-apps？

building-inferencesh-apps 技能是一套專注於在 inference.sh 平台上建立與部署應用程式的實作指南。它說明標準的應用程式開發流程、infsh CLI 的角色，以及如何安全地 scaffold 並管理以 Python 或 Node.js 撰寫的後端型應用程式。

這個技能不是一般性的教學，而是與官方的 infsh app 指令以及 inference.sh 執行環境的預期行為對齊。它幫助你避免常見錯誤，例如手動建立核心檔案、錯誤設定應用程式資源，或在錯誤的目錄執行部署指令。

適合哪些人使用？

在以下情境下，建議使用 building-inferencesh-apps：

• 後端開發者，要在 inference.sh 上建立 API 型應用程式
• Python 或 Node.js 工程師，要把模型或外部 API 包裝成託管服務
• 習慣使用 CLI 為主 工作流程，想要可預期、可 script 的部署流程的開發者
• 需要從較高層次了解 GPU／VRAM 資源、應用程式機密 (secrets) 與整合方式的平台使用者

如果你想了解 inference.sh 應用程式的正確專案結構、inf.yml 與 inference.py / inference.js 如何產生，以及如何在平台上安全操作，這個技能是很好的起點。

它解決哪些問題？

building-inferencesh-apps 技能主要處理在開始進行 inference.sh 應用程式開發時常見的痛點：

• 不確定如何正確 scaffold 一個新的應用程式
• 不小心手動建立 inf.yml、inference.py、inference.js 或 package.json，導致與平台預期不符
• 忘記在執行 infsh 指令前先 cd 進入應用程式目錄
• 因為繼承錯誤的 base class 而遺失 output_meta 資料
• 日誌不足，導致難以除錯遠端或大量依賴 API 的應用程式

依照這個技能整理出來的做法，你可以建立一套穩定、可重複的流程來開發與部署 inference.sh 應用程式。

什麼時候適合使用 building-inferencesh-apps？

在以下情況下，這個技能特別適合：

• 你要在 inference.sh 上開始一個新的應用程式，並希望遵循官方、正統的流程
• 你已安裝或計畫安裝 infsh CLI，並希望所有操作都從命令列執行
• 你要建立 Python 或 Node.js 後端，包括包裝外部 API 或模型的服務

在以下情況，它可能不是那麼有幫助：

• 你並不打算使用 inference.sh 作為部署平台
• 你只需要前端或 client-side 程式碼與 UI pattern
• 你預期的是點選式 GUI，而不是以 CLI 為主的工作流程

如果你的主要目標是在 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 為最新版本，可以確保 scaffold 與部署行為與目前平台預期保持一致。

2. 新增 building-inferencesh-apps 技能

在你的 agent 環境中安裝此技能，讓它可以引用彙整過的規則與指引：

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

這會將你的 agent 連結到 inferen-sh/skills repository 中的 sdk/building-apps 內容，將 app 建置規則暴露為可重複使用的能力。

3. 使用 infsh app init scaffold 應用程式（絕對不要手動）

building-inferencesh-apps 的核心原則是：所有應用程式都必須透過 CLI scaffold。平台預期的特定檔案與結構，會由 CLI 自動生成。

強制性的 scaffold 規則

• 不要手動建立：
  • inf.yml
  • inference.py
  • inference.js
  • __init__.py
  • package.json
  • 應用程式目錄
• 忽略任何建議手動 scaffold 的本機文件或結構說明（例如 PROVIDER_STRUCTURE.md）。

請務必改用：

infsh app init

無論目標是 Python 或 Node.js，CLI 都會為你建立 inference.sh 合法應用程式所需的正確目錄結構與核心檔案。

4. 從正確的應用程式目錄操作

building-inferencesh-apps 特別強調：對所有 infsh 指令而言，shell 的工作目錄非常重要：

• 在執行任何 infsh 指令（如 init、deploy、test）之前，都要先 cd 進入你的應用程式目錄。
• shell 工作目錄在不同工具呼叫之間並不會自動沿用，因此任何自動化腳本或 agent 若使用此技能，都必須每次明確切換目錄。

典型的操作模式：

cd path/to/your-app
infsh app deploy

如果略過 cd，你可能會不小心部署或測試錯誤的應用程式，或因為目前目錄找不到 inf.yml 而產生難以理解的錯誤訊息。

5. 在 Python 應用程式中正確定義 outputs

對於會在輸出中包含 metadata 的 Python 應用程式，building-inferencesh-apps 提出一項關鍵規則：

• 如果你的 output class 使用 output_meta，它 必須 繼承自 BaseAppOutput。
• 這類輸出請不要繼承 BaseModel。

若你改用 BaseModel，任何 output_meta 欄位會在回應中被靜默忽略。使用 BaseAppOutput 可確保資料與相關 metadata 都能正確保留並由執行環境回傳。

6. 在 run() 中加入 logging 以提升可觀測性

此技能建議在應用程式的 run() 方法中預設加入 logging：

• 在 run() 中使用 self.logger.info(...) 來記錄關鍵事件、時間統計與請求／回應摘要。
• 這對於包裝外部 API 的應用程式尤其重要，因為主要的處理工作發生在遠端服務，而不是你的本地程式碼中。

以下類型的情境特別適合加入 logging：

• 測量上游模型呼叫的延遲時間
• 紀錄實際呼叫了哪些外部 API endpoint
• 追蹤與 GPU／VRAM 使用相關的請求大小或參數

持續且一致的 logging，能大幅簡化效能問題的除錯，並幫助你理解 inference.sh 後端在正式環境中的實際行為。

7. 典型的開發與部署流程

儘管 repository 節錄內容主要著重在規則，你可以將 building-inferencesh-apps 當作典型工作流程的檢查清單：

1. 安裝 infsh CLI。
2. 使用 infsh app init 初始化 新應用程式（Python 或 Node.js）。
3. 在執行任何後續指令前，切換目錄到新建立的應用程式資料夾。
4. 在產生的檔案中實作你的應用程式邏輯，對使用 output_meta 的輸出遵守 BaseAppOutput 規則，並在程式中透過 self.logger.info(...) 加入 logging。
5. 使用 CLI 產生的設定來調整資源（例如 GPU／VRAM 與整合設定），而不是手動建立 inf.yml。
6. 在應用程式目錄內使用 infsh 指令部署與測試。

當你擴充或自動化這個流程時，仍然套用同樣的原則：依賴 CLI 建立結構、嚴格確保工作目錄正確，並維持輸出與 logging 的一致模式。

常見問題（FAQ）

building-inferencesh-apps 只適用於 Python 嗎？

不是。building-inferencesh-apps 技能涵蓋在 inference.sh 上以 Python 或 Node.js 撰寫的應用程式。兩者都使用相同的 CLI（infsh app init）進行 scaffold，而有關目錄處理與 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 將 cd path/to/app 視為每次執行 infsh 指令前的必要步驟，尤其是在 script 或 agent 駆動的工作流程中。

使用 output_meta 的 output class 應該如何設計？

對於 Python 應用程式：

• 任何包含 output_meta 的 output class 都必須繼承 BaseAppOutput。
• 避免在這類輸出中使用 BaseModel，否則會靜默丟棄回應中的 output_meta。

遵循這個規則，可以確保 metadata 能被 inference.sh 正確保留並回傳。

為什麼這個技能這麼強調在 run() 裡 logging？

building-inferencesh-apps 特別強調 logging，是因為許多 inference.sh 應用程式是外部 API 的包裝或高度依賴外部服務。如果沒有在 run() 中透過 self.logger.info(...) 記錄資訊，你會很難：

• 釐清延遲與效能問題
• 理解上游 API 為何失敗
• 在除錯時將請求與回應對應起來

預設加入基本的 info-level 日誌，可以讓你清楚掌握後端每次處理請求時實際做了什麼。

building-inferencesh-apps 會詳細說明 GPU 與 VRAM 設定嗎？

這個技能主要聚焦在 inference.sh 應用程式開發的流程與規則：透過 CLI scaffold、目錄操作方式、output class 要求與 logging 建議。它會在你思考 GPU、VRAM、secrets 與整合等資源配置時提供流程面的指引，但目前的 repository 節錄內容著重於規則，而非完整的設定範例。若需要精準的資源設定細節，建議將本技能的工作流程指引與官方 inference.sh 文件一併參考。

什麼時候不該使用 building-inferencesh-apps？

以下情況不太適合使用這個技能：

• 你並不打算部署到 inference.sh
• 你主要尋找的是前端或 UI framework，而非後端應用程式指引
• 你偏好手動建立檔案與目錄，而不是依賴 CLI 驅動的工作流程

在其他多數情境——尤其是要在 inference.sh 上建立 API 型後端時——building-inferencesh-apps 都能提供一套穩定、以 CLI 為核心的實作模式供你遵循。