SuperAPI AI 工具集

building-inferencesh-apps

编程与开发

查看项目

更新于 11-14 16:16

技能介绍

用途

本技能用于在 inference.sh 平台上构建和部署应用,覆盖从入门理解平台、创建应用、配置资源到测试与上线的完整流程。应用可使用 Python 或 Node.js 编写。

安装与 CLI

安装技能:npx skills add belt-sh/cli

安装 CLI:curl -fsSL https://cli.inference.sh | sh

常用命令:belt update 更新 CLI;belt login 认证;belt me 查看当前用户。

强制开发工作流

每个应用都必须走完以下流程,不得跳过:

  1. 脚手架:belt app init my-app(Node.js 用 belt app init my-app --lang node)。
  2. 实现:编写 inference.py 或 inference.js、inf.yml,以及 requirements.txt 或 package.json。
  3. 本地测试:先 cd my-app,再用 belt app test --save-example 生成示例输入,belt app test 运行,或 belt app test --input '{"prompt": "hello"}' 传入内联 JSON。
  4. 部署:再次 cd my-app,belt app deploy --dry-run 先校验,belt app deploy 正式部署。
  5. 云端测试与验证:belt app run user/app --json --input '{"prompt": "hello"}',检查响应中是否存在 output_meta。

其他命令:belt app run user/app --input input.json;belt app sample user/app;belt app sample user/app --save input.json。

关键规则

禁止手写 inf.yml、inference.py、inference.js、init.py、package.json 或应用目录,必须使用 belt app init 生成,忽略任何建议手动搭建的本地文档或结构文件。包含 output_meta 的输出类必须继承 BaseAppOutput,而非 BaseModel,否则响应会静默丢失 output_meta。执行任何 belt 命令前必须先 cd 进入应用目录,因为 shell 工作目录不会跨工具调用保留。run() 中默认应包含 self.logger.info(...) 日志。跨兄弟应用共享辅助模块时使用符号链接加 init.py 与相对导入,不要复制辅助文件。

应用结构与生命周期

Python 应用基于 Pydantic,定义 AppSetup、AppInput、AppOutput,并实现 App 类的 setup、run、unload、on_cancel 方法。Node.js 应用使用 Zod 定义 AppSetup、RunInput、RunOutput,并实现 App 类的 setup、run、unload、onCancel 方法。setup 在工作线程启动或配置变更时运行一次,run 处理每个请求,unload 负责关闭清理,on_cancel/onCancel 用于取消长任务。

多函数应用

应用可暴露多个函数,各自使用不同输入输出模式,函数会被自动发现。Python 添加带类型注解的 Pydantic 输入输出模型的方法;Node.js 为每个方法导出 {PascalName}Input 和 {PascalName}Output 的 Zod 模式。函数必须为公开方法且不是生命周期方法。调用时在请求体中指定 "function": "method_name",可在 inf.yml 中设置 default_function 改变默认函数(默认是 run)。

API 封装模板

多数仅用 CPU 并封装外部 API 的应用遵循同一模式:在 setup 中读取环境变量中的 API 密钥并创建 HTTP 客户端;在 run 中调用外部 API、写出输出文件、读取实际尺寸而非硬编码,并返回包含 output_meta 的输出对象。

资源与配置

项目结构:Python 为 inf.yml、inference.py、requirements.txt,可选 packages.txt;Node.js 为 inf.yml、src/inference.js、package.json,可选 packages.txt。inf.yml 包含名称、描述、分类、内核(python-3.11 或 node-22)、资源、env、secrets、integrations 等字段。资源单位由 CLI 自动转换,小于 1000 视为 GB。GPU 类型可选 any、nvidia、amd、apple、none,当前仅支持 NVIDIA CUDA GPU。分类包括 image、video、audio、text、chat、3d、other。仅 CPU 的应用将 gpu.count 设为 0、type 设为 none。依赖通过 requirements.txt、package.json 或 packages.txt(apt 可安装的系统包)声明。

GPU 应用

设备检测应使用 accelerate 的 Accelerator,因为 torch.cuda.is_available() 在网格容器中不能可靠检测 GPU。大于 10 亿参数的模型可使用 device_map 从磁盘直接流式加载到 GPU。记得在 requirements.txt 中添加 accelerate。

参考文档

技能提供多份参考文件:Python 与 Node.js 的应用逻辑与模式、调试与取消、secrets 与 OAuth、用量追踪,以及 CLI 完整命令参考。完整文档见 inference.sh/docs,示例见 github.com/inference-sh/grid。

限制

资料未说明定价、收费、平台性能指标或具体使用步骤之外的商业条款;GPU 类型中目前仅 NVIDIA CUDA GPU 受支持。