FastDeploy/docs/Windows-CPP-SDK-Serving.md

简介

本文档以千分类模型_MobileNetV3为例，本文档介绍FastDeploy中的模型SDK，在Intel x86_64 / NVIDIA GPU、Windows操作系统 的C++环境：（1）HTTP服务化推理部署步骤，（2）介绍推理全流程API，方便开发者了解项目后二次开发。 如果开发者对Python语言的相关能力感兴趣，可以参考Windows Python请参考Windows Python环境下的推理部署文档。

• 简介

• 环境准备

  • 1. SDK下载
  • 2. CPP环境

• 快速开始

  • 1. 项目结构说明
  • 2. 测试EasyEdge服务
  • 3. 启动HTTP预测服务
  • 4. 编译Demo

• HTTP API流程详解

  • 1. 开启http服务
  • 2. 请求http服务
    • 2.1 http 请求方式一:不使用图片base64格式
    • 2.2 http 请求方法二:使用图片base64格式
  • 3. http 返回数据

• FAQ

环境准备

1. SDK下载

根据开发者模型、部署芯片、操作系统需要，在图像界面飞桨开源模型或GIthub中选择对应的SDK进行下载。解压缩后的文件结构如快速开始中1项目介绍说明介绍。

2. CPP环境

建议使用Microsoft Visual Studio 2015及以上版本，获取核心 C 和 C++ 支持，安装时请选择“使用 C++ 的桌面开发”工作负载。

快速开始

1. 项目结构说明

EasyEdge-win-xxx
        ├── data
        │   ├── model    # 模型文件资源文件夹，可替换为其他模型
        │   └── config   # 配置文件
        ├── bin          # demo二进制程序
           │   ├── xxx_image    # 预测图像demo
           │   ├── xxx_video    # 预测视频流demo
        │  └── xxx_serving  # 启动http预测服务demo
        ├── dll          # demo二进制程序依赖的动态库
        ├── ...          # 二次开发依赖的文件
        ├── python       # Python SDK文件
        ├── EasyEdge.exe # EasyEdge服务
        └── README.md    # 环境说明

2. 测试EasyEdge服务

模型资源文件默认已经打包在开发者下载的SDK包中，请先将zip包整体拷贝到具体运行的设备中，再解压缩使用。

SDK下载完成后，双击打开EasyEdge.exe启动推理服务，输入要绑定的Host ip及端口号Port，点击启动服务。

服务启动后，打开浏览器输入http://{Host ip}:{Port}，添加图片或者视频来进行测试。

## 3. 启动HTTP预测服务

除了通过上述方式外，您还可以使用bin目录下的可执行文件来体验单一的功能。在dll目录下，点击右键，选择"在终端打开"，执行如下命令。

需要将bin目录下的可执行文件移动到dll目录下执行，或者将dll目录添加到系统环境变量中。

.\easyedge_serving {模型model文件夹路径} 

启动后，日志中会显示如下字样。

HTTP is now serving at 0.0.0.0:24401

此时，开发者可以打开浏览器，http://127.0.0.1:24401，执行和之前一样的操作即可。

4. 编译Demo

在项目结构说明中，bin路径下的可执行文件是由src下的对应文件编译得到的，具体的编译命令如下。

cd src
mkdir build && cd build
cmake .. && make

编译完成后，在build文件夹下会生成编译好的可执行文件，如图像推理的二进制文件：build/demo_serving/easyedge_serving。

HTTP API流程详解

本章节主要结合2.1 HTTP Demo的API介绍，方便开发者学习并将运行库嵌入到开发者的程序当中，更详细的API请参考include/easyedge/easyedge*.h文件。http服务包含服务端和客户端，目前支持的能力包括以下几种方式，Demo中提供了不使用图片base格式的方式一：浏览器请求的方式，其他几种方式开发者根据个人需要，选择开发。

1. 开启http服务

http服务的启动可直接使用bin/easyedge_serving，或参考src/demo_serving.cpp文件修改相关逻辑

 /**
     * @brief 开启一个简单的demo http服务。
     * 该方法会block直到收到sigint/sigterm。
     * http服务里，图片的解码运行在cpu之上，可能会降低推理速度。
     * @tparam ConfigT
     * @param config
     * @param host
     * @param port
     * @param service_id service_id  user parameter, uri '/get/service_id' will respond this value with 'text/plain'
     * @param instance_num 实例数量，根据内存/显存/时延要求调整
     * @return
     */
    template<typename ConfigT>
    int start_http_server(
            const ConfigT &config,
            const std::string &host,
            int port,
            const std::string &service_id,
            int instance_num = 1);

2. 请求http服务

开发者可以打开浏览器，http://{设备ip}:24401，选择图片来进行测试。

2.1 http 请求方式一:不使用图片base64格式

URL中的get参数：

参数	说明	默认值
threshold	阈值过滤， 0~1	如不提供，则会使用模型的推荐阈值

HTTP POST Body即为图片的二进制内容(无需base64, 无需json)

Python请求示例

import requests

with open('./1.jpg', 'rb') as f:
    img = f.read()
    result = requests.post(
        'http://127.0.0.1:24401/',
        params={'threshold': 0.1},
        data=img).json()

2.2 http 请求方法二:使用图片base64格式

HTTP方法：POST Header如下：

参数	值
Content-Type	application/json

Body请求填写：

• 分类网络： body 中请求示例

  {
    "image": "<base64数据>"
    "top_num": 5
  }
  

  body中参数详情

参数	是否必选	类型	可选值范围	说明
image	是	string	-	图像数据，base64编码，要求base64图片编码后大小不超过4M,最短边至少15px，最长边最大4096px，支持jpg/png/bmp格式 注意去掉头部
top_num	否	number	-	返回分类数量，不填该参数，则默认返回全部分类结果

• 检测和分割网络： Body请求示例：

  {
    "image": "<base64数据>"
  }
  

  body中参数详情：

参数	是否必选	类型	可选值范围	说明
image	是	string	-	图像数据，base64编码，要求base64图片编码后大小不超过4M,最短边至少15px，最长边最大4096px，支持jpg/png/bmp格式 注意去掉头部
threshold	否	number	-	默认为推荐阈值，也可自行根据需要进行设置

3. http 返回数据

字段	类型说明	其他
error_code	Number	0为成功,非0参考message获得具体错误信息
results	Array	内容为具体的识别结果。其中字段的具体含义请参考预测图像-返回格式一节
cost_ms	Number	预测耗时ms，不含网络交互时间

返回示例

{
    "cost_ms": 52,
    "error_code": 0,
    "results": [
        {
            "confidence": 0.94482421875,
            "index": 1,
            "label": "IronMan",
            "x1": 0.059185408055782318,
            "x2": 0.18795496225357056,
            "y1": 0.14762254059314728,
            "y2": 0.52510076761245728,
            "mask": "...",  // 图像分割模型字段
            "trackId": 0,  // 目标追踪模型字段
        },

      ]
}

*** 关于矩形坐标 ***

x1 * 图片宽度 = 检测框的左上角的横坐标

y1 * 图片高度 = 检测框的左上角的纵坐标

x2 * 图片宽度 = 检测框的右下角的横坐标

y2 * 图片高度 = 检测框的右下角的纵坐标

*** 关于分割模型 ***

其中，mask为分割模型的游程编码，解析方式可参考 http demo。

FAQ

1. 执行infer_demo文件时，提示your generated code is out of date and must be regenerated with protoc >= 3.19.0

进入当前项目，首先卸载protobuf

python3 -m pip uninstall protobuf

安装低版本protobuf

python3 -m pip install protobuf==3.19.0