安装 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的输出类必须继承BaseAppOutput，而不是BaseModel。使用BaseModel会静默地从响应中丢弃output_meta。 - 在运行任何
belt命令之前，始终先cd进入应用目录。Shell 的当前工作目录不会在工具调用之间持久化——如果忘记先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——如果缺失，说明输出类可能继承了 BaseModel 而不是 BaseAppOutput。
# 其他常用命令
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: "done" };
}
async unload() {
/** 关闭时清理 */
}
async onCancel() {
/** 用户取消时调用——用于长时间运行的任务 */
return true;
}
}
多函数应用
应用可以暴露多个具有不同输入/输出模式的函数。函数会被自动发现。
Python： 添加带有类型提示的 Pydantic 输入/输出模型的方法。
Node.js： 为每个方法导出 {PascalName}Input 和 {PascalName}Output Zod 模式。
函数必须是公开的（无 _ 前缀）且不能是生命周期方法（setup、unload、on_cancel/onCancel、constructor）。
通过 API 调用时，在请求体中指定 "function": "method_name"。在 inf.yml 中设置 default_function 来更改未指定函数时的默认行为（默认为 run）。
API 封装应用模板（Python）
大多数仅使用 CPU 且封装外部 API 的应用遵循以下模式。可以将其作为起点：
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 token
optional: false
integrations:
- key: google.sheets
description: 访问 Google Sheets
optional: true
资源单位
CLI 会自动转换人类友好的值：
- < 1000 → GB（例如，
80= 80GB） - 1000 到 1B → 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))
# 小型模型或不支持 device_map 的库——加载后再移动
self.model = SomeModel.from_pretrained("org/model")
self.model = self.model.to(device=self.device, dtype=torch.float16)
记得将 accelerate 添加到 requirements.txt。
参考文件
根据语言和主题加载相应的参考文件：
应用逻辑与模式
- 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/导入调试、流式处理、内存管理、并发、取消
Secret 与 OAuth
- references/python-secrets-oauth.md — Python：os.environ、OpenAI 客户端、HuggingFace token、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 命令参考，两种语言的先决条件