[译]TensorFlow Serving RESTful API
[译]TensorFlow Serving RESTful API
今年六月TensorFlow Serving在以往的gRPC API之外，开始支持RESTful API了，使得访问更加符合常用的JSON习惯，本文翻译自官方文档，提供RESTful API的使用指南，如与官网有出入，以官网为准，以下为正文。
除了gRPC APIs，TensorFlow ModelServer也开始支持使用RESTful API在TensorFlow模型上进行分类、回归、和预测了。本文介绍使用这些API的端点和request/response格式。
TensorFlow ModelServer通过host:port接受下面这种RESTful API请求：
POST http://host:port/<URI>:<VERB> URI: /v1/models/
其中“/versions/${MODEL_VERSION}”是可选的，如果省略，则使用最新的版本。
该API基本遵循gRPC版本的PredictionService API。
请求URL的示例：
http://host:port/v1/models/iris:classify http://host:port/v1/models/mnist/versions/314:predict
请求和回复都是JSON对象。该对象的组成取决于请求类型或操作。细节请查看下面的API特性一节。
为防错误，所有的API都会在返回体中返回一个JSON对象，其中“error”作为key，错误信息则是value：
{ "error": <error message string> }
分类和回归API
请求格式
分类和回归的API的请求体必须是一个遵循下述格式的JSON对象：
{
// Optional: serving signature to use.
// If unspecifed default serving signature is used.
"signature_name": <string>,
// Optional: Common context shared by all examples.
// Features that appear here MUST NOT appear in examples (below).
"context": {
"<feature_name3>": <value>|<list>
"<feature_name4>": <value>|<list>
},
// List of Example objects
"examples": [
{
// Example 1
"<feature_name1>": <value>|<list>,
"<feature_name2>": <value>|<list>,
...
},
{
// Example 2
"<feature_name1>": <value>|<list>,
"<feature_name2>": <value>|<list>,
...
}
...
]
}其中“<value>”是一个JSON数字（整数或小数）或字符串，“<list>”则是一系列该<value>。查看下面的编码二进制值 一节可获知如何表示二进制（比特流）值。该格式和gRPC的“ClassificationRequest”和“RegressionRequest”接口很像。这些版本都接受Example对象的list。
回复格式
分类请求会在返回体中返回一个格式如下的JSON对象：
{
"result": [
// List of class label/score pairs for first Example (in request)
[ [<label1>, <score1>], [<label2>, <score2>], ... ],
// List of class label/score pairs for next Example (in request)
[ [<label1>, <score1>], [<label2>, <score2>], ... ],
...
]
}其中“<label>”是字符串（如果模型没有关联分数的label，可以为空字符串" "）。 “<score>”是小数（浮点型）。
回归请求会在返回体中返回一个格式如下的JSON对象：
{
// One regression value for each example in the request in the same order.
"result": [ <value1>, <value2>, <value3>, ...]
}“<value>”是个小数。
gRPC API的用户会注意到这些格式和“ClassificationRequest”和“RegressionRequest”接口很像。
预测 API
请求格式
预测API的请求体必须是如下格式的JSON对象：
{
// (Optional) Serving signature to use.
// If unspecifed default serving signature is used.
"signature_name": <string>,
// Input Tensors in row ("instances") or columnar ("inputs") format.
// A request can have either of them but NOT both.
"instances": <value>|<(nested)list>|<list-of-objects>
"inputs": <value>|<(nested)list>|<object>
}以行的形式说明输入的tensor。
该格式和gRPC API和CMLE predict API的PredictRequest接口类似。如果所有命名的输入的tensor都有同样的0维，则使用这个格式。如果不是，则使用下面的列的形式。
在行形式中，输入的JSON请求中以instances为key。
如果只有一个命名的输入，则指定instances key的值作为输入值：
{
// List of 3 scalar tensors.
"instances": [ "foo", "bar", "baz" ]
}
{
// List of 2 tensors each of [1, 2] shape
"instances": [ [[1, 2]], [[3, 4]] ]
}因为不需要手动展平list，tensor会以内嵌的形式表示。
对于多命名的输入，每个条目都需要成为包含输入的“名称/tensor”对的对象。比如说，下面就是一个有两个instances的请求，每个都有三个命名的输入tensor的集合：
{
"instances": [
{
"tag": "foo",
"signal": [1, 2, 3, 4, 5],
"sensor": [[1, 2], [3, 4]]
},
{
"tag": "bar",
"signal": [3, 4, 1, 2, 5]],
"sensor": [[4, 5], [6, 8]]
}
]
}注意，每个命名的输入（"tag", "signal", "sensor"）都假设有着同样的0维（在上面的例子中是2，因为在instances list中有两个对象）。如果你命名了不同0维的输入，就要使用下面描述的列形式。
以列的形式说明输入的tensor。
如果各个命名的输入的0维不一样，或者你想要一个更加紧凑的表现形式，就使用列的形式来说明你的输入tensor。该形式和gPRC的Predict请求的输入很像。
在列形式中，inputs被作为JSON请求的key。
inputs的值可以是单个输入tensor，或者是一个输入map（以其本身的嵌入格式排列）。每个输入可以是任意形式，不需要像上面的行形式一样包含相同的0维（也就是批尺寸batch size）。
上个例子的列形式如下：
{
"inputs": {
"tag": ["foo", "bar"],
"signal": [[1, 2, 3, 4, 5], [3, 4, 1, 2, 5]],
"sensor": [[[1, 2], [3, 4]], [[4, 5], [6, 8]]]
}
}注意，inputs是个JSON对象，不是像instances（行形式中所用）一样的list。并且所有的命名的输入都是一起说明的，不同于行形式的分到单独的行中去。这让表现形式更紧凑（但可能可读性不太好）。
回复格式
预测请求会在回复体中返回一个JSON对象。
行形式的请求有如下格式的回复：
{
"predictions": <value>|<(nested)list>|<list-of-objects>
}如果模型的输出只包含一个命名的tensor，我们省略名字和predictions key map，直接使用标量或者值的list。如果模型输出多个命名的tensor，我们输出对象list，和上面提到的行形式输入类似。
列形式的请求有如下格式的回复：
{
"outputs": <value>|<(nested)list>|<object>
}如果模型的输出只包含一个命名的tensor，我们省略名字和outputs key map，直接使用标量或者值的list。如果模型输出多个命名的tensor，我们输出对象，其每个key都和输出的tensor名对应，和上面提到的列形式输入类似。
输出二进制值
TensorFlow不区分非二进制和二进制值。所有的都是DT_STRING类型。tensor名中有_bytes后缀的表示有二进制值，每个值有着下面 编码二进制值中不同的编码。
JSON映射
RESTful APIs支持JSON的标准编码，使得不同系统间共享数据更简单。对于支持的类型，会按照下面的表进行一一对应编码。下表没列出的类型说明未支持。
TensorFlow数据类型 | JSON值 | JSON示例 | 备注 |
|---|---|---|---|
DT_BOOL | true, false | true, false | - |
DT_STRING | string | "Hello World!" | 如果DT_STRING 表示的是二进制值（比如序列化的图片比特流），会以Base64编码。查看编码二进制值获取更多内容 |
DT_INT8, DT_UINT8, DT_INT16, DT_INT32, DT_UINT32, DT_INT64, DT_UINT64 | number | 1, -10, 0 | JSON值为十进制整数 |
DT_FLOAT, DT_DOUBLE | number | 1.1, -10.0, 0, NaN, Infinity | JSON值会是一个数字或者特殊标示值NaN和Infinity，查看JSON一致性获取更多内容。指数符号也是接受的。 |
编码二进制值
JSON使用UTF-8编码。如果你输入了需要变成二进制的feature或者tensor值（比如图片比特流），你必须用Base64编码数据，并且将其放入有b64作为key的JSON对象，如下：
{ "b64": <base64 encoded string> }你可以将该值作为feature或者tensor的值，回复体也会以同样的形式编码。
一个有着image（二进制数据）和caption features 的分类请求如下：
{
"signature_name": "classify_objects",
"examples": [
{
"image": { "b64": "aW1hZ2UgYnl0ZXM=" },
"caption": "seaside"
},
{
"image": { "b64": "YXdlc29tZSBpbWFnZSBieXRlcw==" },
"caption": "mountains"
}
]
}JSON一致性
很多feature或者tensor都是浮点型。除了有限的值外（e.g. 3.14, 1.0 等等），可以使用NaN或者无限值（Infinity 和-Infinity）。不幸的是JSON标准（RFC 7159）不识别这些值（即使JavaScript标准识别）。
REST API允许请求和回复体包含这些值。也就是说如下的请求是有效的：
{
"example": [
{
"sensor_readings": [ 1.0, -3.14, Nan, Infinity ]
}
]
}遵循严格标准的JSON解析器会拒绝它并返回解析错误。为了准确地处理你的代码中的请求和回复，请使用支持这些标识的JSON解析器。
NaN, Infinity, -Infinity标识能被proto3、Python JSON模块和JavaScript语言识别。
示例
我们使用 half_plus_three模型来看看REST APIs的操作。
从REST API端口启动ModelServer
按照setup instructions来在你的系统上安装TensorFlow ModelServer。然后从git 仓库下载half_plus_three模型：
$ mkdir -p /tmp/tfserving
$ cd /tmp/tfserving
$ git clone --depth=1 https://github.com/tensorflow/serving使用--rest_api_port选项来启动ModelServer输出REST API端口：
--model_name=half_plus_three \
--model_base_path=$(pwd)/serving/tensorflow_serving/servables/tensorflow/testdata/saved_model_half_plus_three/使用REST API调用ModelServer
在不同的终端，使用curl 工具来进行REST API调用。一个预测调用如下所示：
$ curl -d '{"instances": [1.0,2.0,5.0]}' -X POST http://localhost:8501/v1/models/half_plus_three:predict
{
"predictions": [3.5, 4.0, 5.5]
}回归调用如下：
$ curl -d '{"signature_name": "tensorflow/serving/regress", "examples": [{"x": 1.0}, {"x": 2.0}]}' \
-X POST http://localhost:8501/v1/models/half_plus_three:regress
{
"results": [3.5, 4.0]
}注意，回归可用于非默认签名，必须明确说明。不正确的请求URL或者body会返回错误状态.
curl -i -d '{"instances": [1.0,5.0]}' -X POST http://localhost:8501/v1/models/half:predict
HTTP/1.1 404 Not Found
Content-Type: application/json
Date: Wed, 06 Jun 2018 23:20:12 GMT
Content-Length: 65
{ "error": "Servable not found for request: Latest(half)" }