AIHub 算法应用开发

AIHub 是 CubeStudio 的「AI 应用市场」。一个 aihub 应用用一份 app.py（继承 Model 类）描述模型的基础信息、训练、推理、示例数据、自动化标注、流推理等能力；平台据此自动对接 可视化推理部署、一键微调转 pipeline、模型市场展示 等功能。

面向使用者的市场使用见 AIHub 模型市场。

aihub 应用开发视频教程

开发流程总览

1. 本地新增 aihub 代码、修改、调试代码；
2. 调试时会在 app.py 同级目录自动生成 info.json；
3. 基于自己编写的 Dockerfile 构建 aihub 应用镜像，并用新镜像再完整测试一遍代码；
4. 把 info.json 追加到 myapp/init/init-aihub.json（注意需含 pic 图片、resource 资源、images 镜像等信息）；
5. 重新打包后端镜像；
6. CubeStudio 升级该后端镜像后，AIHub 市场里就包含你的应用了。

已核实：注册清单路径为 myapp/init/init-aihub.json（本仓存在；英文版另有 myapp/init-en/init-aihub.json）。

应用目录构成

在 aihub/deep-learning/ 下新建应用目录（可直接复制参考应用 app1）。一个 aihub 应用必须包含的文件：

• app.py：应用主体，定义 Model 类的信息和函数（训练/推理/服务入口）。
• Dockerfile：模型训练和推理环境所用镜像的构建文件。
• init.sh：初始化脚本，在基础镜像之上做场景化初始化（可选，可不含该文件）。
• readme / README.md：描述模型功能与用法。
• example.jpg：在模型市场卡片上展示的样式图（建议 330×180 比例），文件名需配置到 app.py 的 pic 属性。
• 其他配套内容自行添加。

⚠️ 命名约束：目录名必须与 app.py 中 Model 的 name 属性一致，且只能用英文小写、数字和 -。

已核实：示例应用 aihub/deep-learning/app1/（含 app.py/Dockerfile/init.sh/example.jpg/info.json）存在。

镜像调试

基础镜像为 conda 环境。先用基础镜像启动容器：

可用的基础镜像 tag（均已在本仓 Dockerfile/构建脚本中核对存在）：

# 纯 CPU / conda
ccr.ccs.tencentyun.com/cube-studio/aihub:base-python3.8      # conda + python3.8
ccr.ccs.tencentyun.com/cube-studio/aihub:base-python3.9      # conda + python3.9
ccr.ccs.tencentyun.com/cube-studio/aihub:base-python3.10     # conda + python3.10
ccr.ccs.tencentyun.com/cube-studio/aihub:base-python3.11     # conda + python3.11

# CUDA 11.8
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda11.8-python3.8
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda11.8-python3.9
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda11.8-python3.10
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda11.8-python3.11

# CUDA 12.8.1
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda12.8.1-python3.9
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda12.8.1-python3.10
ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda12.8.1-python3.11

# modelscope 模型开发镜像
ccr.ccs.tencentyun.com/cube-studio/modelscope:base-cuda11.3-python3.7
ccr.ccs.tencentyun.com/cube-studio/modelscope:base-cuda11.8-python3.8
ccr.ccs.tencentyun.com/cube-studio/modelscope:base-cuda12.1-python3.10
ccr.ccs.tencentyun.com/cube-studio/modelscope:base-cuda12.1-python3.11

更多基础镜像 tag 见 镜像构建总览。

启动基础环境进入容器：

# 获取当前项目名作为应用名
aiapp=$(basename `pwd`)
cube_dir=($(dirname $(dirname "$PWD")))
chmod +x $cube_dir/src/docker/entrypoint.sh
docker run --name ${aiapp} --privileged -it \
  -e NVIDIA_VISIBLE_DEVICES=all -e APPNAME=$aiapp \
  -v $cube_dir/src:/src -v $PWD:/app -w /app -p 80:80 \
  --entrypoint='/src/docker/entrypoint.sh' \
  ccr.ccs.tencentyun.com/cube-studio/aihub:base-cuda11.8-python3.11 bash

补全 init.sh 环境脚本后执行（注意：环境文件不要放在容器 /app/ 目录下，否则会被加载进 git）：

# init.sh 会被复制到容器 / 根目录下再执行
cp init.sh /init.sh && bash /init.sh

补齐 app.py 后运行调试：

/src/docker/entrypoint.sh python app.py web

出问题时看两个日志：

• 日志1：上面命令直接打印的报错，是 cube-studio aihub 应用后台的报错；
• 日志2：容器内 /log.txt，是 gradio 的报错。

Web 界面体验：浏览器打开 http://xx.xx.xx/gradio/aihub/$aiapp/（$aiapp 替换为你的应用名/目录名）。

已核实：entrypoint.sh 路径为 aihub/src/docker/entrypoint.sh（存在）；gradio 挂载路径为 /gradio/aihub/{应用名}，见 aihub/src/cubestudio/aihub/web/gradio_server.py:484。

构建 aihub 应用镜像

代码调试完成后，基于自己写的 Dockerfile 构建应用镜像，建议命名为 xx.xx.xx.xx/cube-studio/aihub:${aiapp}，并在 app.py 中把 images 属性设为该镜像名：

aiapp=$(basename `pwd`)
docker build --network=host -t ccr.ccs.tencentyun.com/cube-studio/aihub:${aiapp} .

构建完成后，建议再用构建后的镜像完整体验测试一遍：

aiapp=$(basename `pwd`)
cube_dir=($(dirname $(dirname "$PWD")))
chmod +x $cube_dir/src/docker/entrypoint.sh
sudo docker run --name ${aiapp} --privileged -d \
  -e NVIDIA_VISIBLE_DEVICES=all -e APPNAME=$aiapp \
  -v $cube_dir/src:/src -v $PWD:/app -w /app -p 80:80 \
  --entrypoint='/src/docker/entrypoint.sh' \
  ccr.ccs.tencentyun.com/cube-studio/aihub:${aiapp} python app.py web

运行时会在应用目录下生成 info.json，下一步注册要用。

注册到平台

1. 确保你的应用目录已更新到 aihub/deep-learning/ 下；
2. 把容器内启动时生成的 info.json 追加到 myapp/init/init-aihub.json；
3. 重新打包后端镜像，并将生产环境后端镜像更新为重新打包的镜像。

代码示例

AIHub 的入门示例应用是 app1，参考 aihub/deep-learning/app1/app.py。

Model 类属性与函数

app.py 中的应用类继承自 Model（from cubestudio.aihub.model import Model, Validator, Field_type, Field，基类见 aihub/src/cubestudio/aihub/model.py）。下列属性/函数均已与基类核对存在。

基础信息

• 属性：name、label、describe、field、scenes、status、version、pic（另含 images 指定镜像名）。
• 含义：定义模型名、所属领域、用途、版本、示例图等。
• 用途：对接平台时用于推理部署可视化和 AIHub 列表中展示应用信息。

已核实：基类 model.py:94-105 定义 name/field/scenes/status/version/label/describe/pic/images 等属性；field 取值如「机器视觉/听觉/自然语言/多模态/大模型」。

训练

• 属性：train_inputs + train 函数。
• 含义：训练输入的参数类型、参数名、描述、默认值、输入校验等（通过 Field 定义）。
• 用途：aihub 应用点击「开发/一键微调」时会转为 pipeline，其中模型微调节点的用户输入由 train_inputs 决定。

推理

• 属性：inference_inputs + load_model 函数 + inference 函数 + inference_resource + web_examples。
• 含义：确定推理输入、模型加载函数、推理函数，以及部署所需资源和可用的推理输入示例。
• 用途：
  • 点击「部署 web」时会部署为 k8s 的 Deployment，生成前后端界面并同时提供 API；
  • load_model 关注模型保存地址：为空则加载预训练模型；不为空则从指定地址加载（一键微调生成的 pipeline 最后一个节点是「部署微调后模型」，要求应用能加载微调后模型）；
  • 推理函数同时服务于离线推理和 Web 界面推理（调用同一函数），另有批推理能力主要用于离线推理。

已核实：基类有 inference_inputs、inference_outputs、web_examples、inference_resource（含 resource_memory/resource_cpu/resource_gpu）以及 train/load_model/inference 函数（model.py:138-191,353-366）。

示例数据集

• 属性：set_dataset 函数。
• 含义：下载/生成训练示例数据集。
• 用途：aihub 应用转 pipeline 时，第一个任务即「下载示例数据集」，帮助使用者熟悉如何配置训练数据。

已核实：model.py:346 有 def set_dataset(self, **kwargs)。

自动化标注

• 属性：labelstudio_predict 函数。
• 含义：标注函数。
• 用途：对接 LabelStudio 标注平台的模型服务接口，接收待标注内容，推理并生成标注格式回传给 LabelStudio。

详见 LabelStudio 标注平台二次开发 的「自动化标注」一节。

流推理

目前只有图片具备流推理能力，重写 rtsp_inference 函数即可。

已核实：基类 model.py:370 有 def rtsp_inference(self, img: numpy.ndarray, **kwargs) -> numpy.ndarray。

相关文档

• 使用侧：AIHub 模型市场
• 自动化标注对接：LabelStudio 标注平台二次开发
• 镜像 tag 与构建：镜像构建总览