codait/max-object-detector

IBM开发者模型资产交换：对象检测器

本仓库包含实例化和部署对象检测模型的代码。该模型可识别图像中来自COCO数据集的80种不同高级类别对象。模型由用于图像特征提取的深度卷积网络基础模型，以及专为对象检测任务设计的额外卷积层组成，在COCO数据集上训练。模型的输入为图像，输出为图像中检测到的对象的估计类别概率列表。

该模型基于https://github.com/tensorflow/models/blob/master/research/object_detection/g3doc/detection_model_zoo.md%E3%80%82%E6%A8%A1%E5%9E%8B%E6%96%87%E4%BB%B6%E6%89%98%E7%AE%A1%E5%9C%A8IBM Cloud Object Storage：ssd_mobilenet_v1.tar.gz 和 faster_rcnn_resnet101.tar.gz。本仓库中的代码将模型部署为Docker容器中的Web服务。本仓库是IBM开发者模型资产交换的一部分，公共API由IBM Cloud提供支持。

模型元数据

参考文献

• J. Huang, V. Rathod, C. Sun, M. Zhu, A. Korattikara, A. Fathi, I. Fischer, Z. Wojna, Y. Song, S. Guadarrama, K. Murphy, "Speed/accuracy trade-offs for modern convolutional object detectors", CVPR 2017
• Tsung-Yi Lin, M. Maire, S. Belongie, L. Bourdev, R. Girshick, J. Hays, P. Perona, D. Ramanan, C. Lawrence Zitnick, P. Dollár, "Microsoft COCO: Common Objects in Context", arXiv 2015
• W. Liu, D. Anguelov, D. Erhan, C. Szegedy, S. Reed, C. Fu, A. C. Berg, "SSD: Single Shot MultiBox Detector", CoRR (abs/1512.02325), 2016
• A.G. Howard, M. Zhu, B. Chen, D. Kalenichenko, W. Wang, T. Weyand, M. Andreetto, H. Adam, "MobileNets: Efficient Convolutional Neural Networks for Mobile Vision Applications", arXiv 2017
• https://github.com/tensorflow/models/tree/master/research/object_detection

许可证

前置条件：

• docker：Docker命令行界面。按照系统的安装说明进行安装。
• 该模型的最低推荐资源为2GB内存和2个CPU。
• 如果使用x86-64/AMD64架构，CPU至少需支持AVX。

部署选项

• 从Quay部署
• 在Red Hat OpenShift上部署
• 在Kubernetes上部署
• 在Code Engine上部署
• 本地运行

从Quay部署

要运行自动启动模型服务API的Docker镜像，执行：

Intel CPU：

bash
$ docker run -it -p 5000:5000 quay.io/codait/max-object-detector

ARM CPU（如树莓派）：

bash
$ docker run -it -p 5000:5000 quay.io/codait/max-object-detector:arm-arm32v7-latest

这将从Quay.io容器 registry 拉取预构建镜像（或使用本地已缓存的现有镜像）并运行。如果希望本地检出并构建模型，可按照下面的本地运行步骤操作。

在Red Hat OpenShift上部署

可按照本教程中的OpenShift Web控制台或OpenShift容器平台CLI说明，将模型服务微服务部署到Red Hat OpenShift，指定quay.io/codait/max-object-detector作为镜像名称。

在Kubernetes上部署

也可使用Quay上的最新Docker镜像在Kubernetes上部署模型。

在Kubernetes集群上，执行以下命令：

bash
$ kubectl apply -f https://raw.githubusercontent.com/IBM/MAX-Object-Detector/master/max-object-detector.yaml

模型将在内部端口5000可用，也可通过NodePort从外部访问。

有关如何在IBM Cloud上将此MAX模型部署到生产环境的详细教程，可参见此处。

在Code Engine上部署

也可在IBM Cloud的Code Engine平台（基于Knative无服务器框架）上部署模型。使用IBM Cloud账户认证后，执行以下命令。

创建Code Engine项目，指定唯一名称：

bash
$ ibmcloud ce project create --name sandbox

通过指向quay.io镜像并暴露端口5000来运行容器：

bash
$ ibmcloud ce application create --name max-object-detector --image quay.io/codait/max-object-detector --port 5000

在浏览器中打开生成的URL，追加/app以查看应用而非API。

本地运行

1. 构建模型
2. 部署模型
3. 使用模型
4. 运行Notebook
5. 开发
6. 清理

1. 构建模型

本地克隆本仓库。在终端中执行以下命令：

bash
$ git clone https://github.com/IBM/MAX-Object-Detector.git

进入仓库基础文件夹：

bash
$ cd MAX-Object-Detector

要为Intel CPU本地构建Docker镜像，执行：

bash
$ docker build -t max-object-detector .

要选择模型，传递--build-arg model=<desired-model>参数：

bash
$ docker build --build-arg model=faster_rcnn_resnet101 -t max-object-detector .

目前支持两种模型：ssd_mobilenet_v1（默认）和faster_rcnn_resnet101。

对于ARM CPU（如树莓派），执行：

bash
$ docker build -f Dockerfile.arm32v7 -t max-object-detector .

构建过程中将下载所有必需的模型资产。注意：当前此Docker镜像仅支持CPU（后续将添加GPU镜像支持）。

2. 部署模型

要运行自动启动模型服务API的Docker镜像，执行：

bash
$ docker run -it -p 5000:5000 max-object-detector

3. 使用模型

API服务器自动生成交互式Swagger文档页面。访问http://localhost:5000即可加载。从中可浏览API并创建测试请求。

使用model/predict端点加载测试图像（可使用samples文件夹中的测试图像），从API获取图像的预测标签。边界框坐标在detection_box字段中返回，包含归一化坐标数组（范围0到1），格式为[ymin, xmin, ymax, xmax]。

!Swagger文档截图

也可在命令行测试，例如：

bash
$ curl -F "image=@samples/dog-human.jpg" -XPOST http://127.0.0.1:5000/model/predict

应看到如下JSON响应：

json
{
  "status": "ok",
  "predictions": [
      {
          "label_id": "1",
          "label": "person",
          "probability": 0.944034993648529,
          "detection_box": [
              0.1242099404335022,
              0.12507188320159912,
              0.8423267006874084,
              0.5974075794219971
          ]
      },
      {
          "label_id": "18",
          "label": "dog",
          "probability": 0.8645511865615845,
          "detection_box": [
              0.10447660088539124,
              0.17799153923988342,
              0.8422801494598389,
              0.732001781463623
          ]
      }
  ]
}

还可使用threshold参数控制返回对象的概率阈值，如下所示：

bash
$ curl -F "image=@samples/dog-human.jpg" -XPOST http://127.0.0.1:5000/model/predict?threshold=0.5

可选的threshold参数是模型返回的预测标签的最小probability值。threshold的默认值为0.7。

4. 运行Notebook

演示Notebook介绍如何使用模型检测图像中的对象并可视化结果。默认情况下，Notebook使用托管演示实例，但也可使用本地运行的实例（参见单元格3中的注释了解详情）。注意：演示需要jupyter、matplotlib、Pillow和requests。

在模型仓库基础文件夹中，在新终端窗口执行以下命令：

bash
$ jupyter notebook

这将启动Notebook服务器。点击demo.ipynb即可启动演示Notebook。

5. 开发

要以调试模式运行Flask API应用，编辑config.py，在应用设置下将DEBUG = True。然后需要重新构建Docker镜像（参见步骤1）。

6. 清理

要停止Docker容器，在终端中按CTRL + C。

对象检测器Web应用

https://github.com/IBM/MAX-Object-Detector-Web-App%E7%9A%84%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC%E5%8C%85%E5%90%AB%E5%9C%A8%E5%AF%B9%E8%B1%A1%E6%A3%80%E6%B5%8B%E5%99%A8Docker%E9%95%9C%E5%83%8F%E4%B8%AD%E3%80%82

当模型API服务器运行时，可在http://localhost:5000/app访问Web应用，提供模型返回的边界框及其相关标签的交互式可视化。

!迷你Web应用截图

如果希望禁用Web应用，通过以下命令启动模型服务API：

bash
$ docker run -it -p 5000:5000 -e DISABLE_WEB_APP=true quay.io/codait/max-object-detector

在Watson Machine Learning上训练此模型

该模型支持在自定义数据集上从头训练。请按照训练README中的步骤，在Watson Machine Learning（IBM Cloud的深度学习即服务产品）上重新训练模型。

资源和贡献

如果有兴趣为模型资产交换项目做出贡献或有任何疑问，请按照https://github.com/CODAIT/max-central-repo%E7%9A%84%E8%AF%B4%E6%98%8E%E6%93%8D%E4%BD%9C%E3%80%82

链接

• 对象检测器Web应用：IBM CODAIT团队创建的参考应用，使用对象检测器。