MindSpore-Serving

7.4 kB

Raw Blame History

RESTful 接口使用说明
概述

RESTful 接口使用说明

Linux Ascend Serving 初级 中级 高级

RESTful 接口使用说明
概述

概述

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

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

与通过master.start_grpc_server("127.0.0.1", 5500)启动GRPC服务不同的是，RESTful服务需要通过master.start_restful_server("0.0.0.0", 1500)来启动。

请求方式

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

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

其中：

HOST：指定访问的IP地址；
PORT：指定访问的端口号；
MODEL_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是数字1图片经过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编码之后的省略字符串。不同图片编码出来的字符串可能不同，上述是示意说明。

bytes类型需要通过base64编码进行表示。base64除了支持bytes类型，也支持表示其他标量和张量，此时需要通过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":[
        {
            "tag":"one",
            "box":{"b64":"AQACAAIAAwADAAQA", "type":"int16", "shape":[3,2]},
            "image":{"b64":"iVBOR...ggg==="}
        }
    ]
}

其中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` `float16`,`float32`,`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"
}

7.4 kB Raw Blame History