基于RESTful接口访问MindSpore Serving服务

Linux Serving Ascend 初级 中级 高级

概述

MindSpore Serving支持gPRC和RESTful两种请求方式。本章节介绍RESTful类型请求。

RESTful是一种基于HTTP协议的网络应用程序的设计风格和开发方式，通过URI实现对资源的管理及访问，具有扩展性强、结构清晰的特点。基于其轻量级以及通过HTTP直接传输数据的特性，RESTful已经成为最常见的Web服务访问方式。用户通过RESTful方式，能够简单直接的与服务进行交互。

部署Serving参考快速入门章节。

通过master.start_restful_server接口启动RESTful服务；另外，可通过master.start_grpc_server启动gRPC服务。

RESTful客户端不依赖特定硬件平台，Serving服务端当前仅支持Ascend310和Ascend910硬件环境。

请求方式

当前仅支持POST类型的RESTful请求，请求格式如下：

POST http://${HOST}:${PORT}/model/${MODLE_NAME}[/version/${VERSION}]:${METHOD_NAME}

其中：

${HOST}：指定访问的IP地址；
${PORT}：指定访问的端口号；
${MODLE_NAME}：请求的模型名称；
${VERSION}：表示版本号。版本号是可选的，若未指定具体版本号，则默认使用模型的最新版本。
${METHOD_NAME}：表示请求模型的具体方法名称。

如果使用curl工具，RESTful请求方式如下：

curl -X POST -d '${REQ_JSON_MESSAGE}' http://${HOST}:${PORT}/model/${MODLE_NAME}[/version/${VERSION}]:${METHOD_NAME}

例子：请求LeNet模型的predict方法进行数字图片的推理，请求如下：

curl -X POST -d '{"instances":{"image":{"b64":"babe64-encoded-string"}' http://127.0.0.1:1500/model/lenet/version/1:predict

其中：babe64-encoded-string表示数字图片经过base64编码之后的字符串。由于字符串比较长，不显式列出。

请求输入格式

RESTful支持Json请求格式，key固定为instances，value表示多个实例。

每个实例通过key-value格式的Json对象来表示。其中：

key：表示输入名称，需要与请求模型提供的方法的输入参数名称一致，若不一致，则请求失败。
value：表示具体的值。当前支持的value类型：
- 标量：str、bytes、int、float、bool。
  
  bytes：通过base64编码方式支持。
- 张量：int、float、bool组成的一级或多级数组。
  
  张量通过数组格式表示数据和维度信息。

Json中支持的int类型：是int32表示的范围，float类型：是float32表示的范围。

请求格式：

{
    "instances":[
        {
            "input_name1":<value>|<list>|<object>,
            "input_name2":<value>|<list>|<object>,
            ...
        },
        {
            "input_name1":<value>|<list>|<object>,
            "input_name2":<value>|<list>|<object>,
            ...
        }
        ...
    ]
}

例子：

{
    "instances":[
        {
            "tag":"one",
            "box":[[1,1],[2,3],[3,4]],
            "image":{"b64":"iVBOR...ggg==="}
        },
        {
            "tag":"two",
            "box":[[2,2],[5,5],[6,6]],
            "image":{"b64":"iVBOR...QmCC", "type":"bytes"}
        }
    ]
}

其中：iVBOR...ggg===是图片数字0经过base64编码之后的省略字符串。iVBOR...QmCC是图片数字1经过base64编码之后的省略字符串。不同图片编码出来的字符串可能不同，上述是示意说明。

base64数据编码

bytes类型需要通过base64编码进行表示。base64除了可以表示bytes类型，也可以表示其他标量和张量数据，此时将标量和张量的二进制数据通过base64进行编码，并额外通过type指定数据类型，通过shape指定维度信息：

type：可选，如果不指定，默认为bytes。

支持int8、int16、int32、int64、uint8、uint16、uint32、uint64、fp16、fp32、fp64、bool、str、bytes。
shape：可选，如果不指定，默认为[1]。

例子：

如果要用base64编码表示：int16的数据类型，shape为3*2，值是[[1,1],[2,3],[3,4]]的张量，则表示如下：

{
    "instances":[
        {
            "box":{"b64":"AQACAAIAAwADAAQA", "type":"int16", "shape":[3,2]}
        }
    ]
}

其中AQACAAIAAwADAAQA：是[[1,1],[2,3],[3,4]]的二进制数据格式经过base64编码后的字符串。

支持的类型总结如下:

支持的类型	例子	备注
`int`	1，[1,2,3,4]	默认`int32`表示范围
`float`	1.0，[[1.2, 2.3], [3.0, 4.5]]	默认`float32`表示范围
`bool`	true，false，[[true],[false]]	`bool`类型
`string`	“hello”或者 {“b64”:”aGVsbG8=”, “type”:”str”}	直接表示或者指定`type`方式表示
`bytes`	{“b64”:”AQACAAIAAwADAAQA”} 或者 {“b64”:”AQACAAIAAwADAAQA”, “type”:”bytes”}	如果不填`type`，默认为`bytes`
`int8`,`int16`,`int32`,`int64`,`uint8`,`uint16`,`uint32`,`uint64` `f16`,`f32`,`f64`,`bool`	{“b64”:”AQACAAIAAwADAAQA”, “type”:”int16”, “shape”:[3,2]}	利用base64编码，表示指定type的数据

请求应答格式

应答格式与请求格式保持一致。返回Json格式信息。应答格式如下：

{
    "instances":[
        {
            "output_name1":<value>|<list>|<object>,
            "output_name2":<value>|<list>|<object>,
            ...
        },
        {
            "output_name1":<value>|<list>|<object>,
            "output_name2":<value>|<list>|<object>,
            ...
        }
        ...
    ]
}

多实例请求后，如果多实例全部成功处理，则响应格式如下：

例子：LeNet请求识别数字0和数字1。

{
    "instances":[
        {
            "result":0
        },
        {
            "result":1
        }
    ]
}

如果部分实例出错，则响应格式如下：

例子：lenet请求识别数字0和一个错误数字图片。

{
    "instances":[
        {
            "result":0
        },
        {
            "error_msg":"Preprocess Failed"
        }
    ]
}

如果请求全部失败，则响应格式如下：

例子：lenet请求识别两张错误数字图片为例。

{
    "instances":[
        {
            "error_msg":"Preprocess Failed"
        },
        {
            "error_msg":"Time out"
        }
    ]
}

出现系统性或者其他解析等错误，则返回格式：

例子：lenet传入非法Json字符串。
```
{
    "error_msg":"Parse request failed"
}
```