基于gRPC接口访问MindSpore Serving服务

概述

运行示例前，需确保已经正确安装了MindSpore Serving，并配置了环境变量。MindSpore Serving安装和配置可以参考MindSpore Serving安装页面。

MindSpore Serving提供gRPC接口访问Serving服务。在Python环境下，我们提供mindspore_serving.client 模块用于填写请求、解析回复。Serving服务端运行依赖具体的推理硬件环境，gRPC客户端运行不依赖特定硬件环境。接下来我们通过add和ResNet-50样例来详细说明gRPC Python客户端接口的使用。

add样例

样例来源于add example ，add Servable提供的add_common方法提供两个2x2 Tensor相加功能。其中gRPC Python客户端代码如下所示，一次gRPC请求包括了三对独立的2x2 Tensor：

from mindspore_serving.client import Client
import numpy as np


def run_add_common():
    """invoke Servable add method add_common"""
    client = Client("localhost:5500", "add", "add_common")
    instances = []

    # instance 1
    x1 = np.asarray([[1, 1], [1, 1]]).astype(np.float32)
    x2 = np.asarray([[1, 1], [1, 1]]).astype(np.float32)
    instances.append({"x1": x1, "x2": x2})

    # instance 2
    x1 = np.asarray([[2, 2], [2, 2]]).astype(np.float32)
    x2 = np.asarray([[2, 2], [2, 2]]).astype(np.float32)
    instances.append({"x1": x1, "x2": x2})

    # instance 3
    x1 = np.asarray([[3, 3], [3, 3]]).astype(np.float32)
    x2 = np.asarray([[3, 3], [3, 3]]).astype(np.float32)
    instances.append({"x1": x1, "x2": x2})

    result = client.infer(instances)
    print(result)


if __name__ == '__main__':
    run_add_common()

按照入门流程 导出模型、启动Serving服务器，并执行上述客户端代码。当运行正常后，将打印以下结果，为了展示方便，格式作了调整：

[{'y': array([[2., 2.], [2., 2.]], dtype=float32)},
 {'y': array([[4., 4.], [4., 4.]], dtype=float32)},
 {'y': array([[6., 6.], [6., 6.]], dtype=float32)}]

以下将对其中的细节进行说明。

1. 构造Client。

   构造Client时，指示Serving的网络地址，并给定Servable名称和它提供的方法。这里的Servable可以是单个模型，也可以是多个模型的组合，多个模型组合提供Servable当前尚未支持，一个Servable可以通过提供多种方法来提供不同的服务。

   上面的add样例， Serving运行在本地（localhost），指定的gRPC端口号为5500，运行了add Servable，add Servable提供了add_common方法。

2. 添加实例。

   每次gRPC请求可包括一个或多个实例，每个实例之间相互独立，结果互不影响。

   比如：add Servable提供的add_common方法提供两个2x2 Tensor相加功能，即一个实例包含两个2x2 Tensor输入，一个2x2 Tensor输出。一次请求可包括一个、两个或者多个这样的实例，针对每个实例返回一个结果。上述add样例提供了三个实例，预期将返回三个实例的结果。

   Client.infer接口入参可为一个或多个实例输入组成的list、tuple或者单个实例输入。每个实例输入由输入的名称和输入的值组成python字典，值可以是以下格式：

   • numpy array：用以表示Tensor。例如：np.ones((3,224), np.float32)。

   • numpy number：用以表示Scalar。例如：np.int8(5)。

   • python bool int float：用以表示Scalar, 当前int将作为int64, float将作为float64。例如：32.0。

   • python str：用以表示字符串。例如：”this is a text”。

   • python bytes：用以表示二进制数据。例如：图片数据。

   上面的add样例，add Servable提供的add_common方法入参名为x1和x2，添加每个实例时指定每个输入的值。

3. 获取推理结果。

   通过Client.infer填入一个或多个实例。 返回可能有以下形式：

   • 所有实例推理正确：

     [{'y': array([[2., 2.], [2., 2.]], dtype=float32)},
      {'y': array([[4., 4.], [4., 4.]], dtype=float32)},
      {'y': array([[6., 6.], [6., 6.]], dtype=float32)}]
     

   • 针对所有实例共同的错误，返回一个包含error的dict。将例子中Client构造时填入的add_common改为add_common2，将返回结果：

     {'error', 'Request Servable(add) method(add_common2), method is not available'}
     

   • 部分实例推理错误，出错的推理实例将返回包含error的dict。将instance2一个输入的dtype改为np.int32，将返回结果：

     [{'y': array([[2., 2.], [2., 2.]], dtype=float32)},
      {'error': 'Given model input 1 data type kMSI_Int32 not match ...'},
      {'y': array([[6., 6.], [6., 6.]], dtype=float32)}]
     

   每个实例返回一个dict，key的值来自于Servable的方法定义，例如本例子中，add Servable提供的add_common方法输出仅有一个，为y。value为以下格式：

   Serving输出类型	Client返回类型	说明	举例
   Tensor	numpy array	tensor array	np.ones((3,224), np.float32)
   Scalar: int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, float16, float32, float64	numpy scalar	Scalar格式的数据转为numpy scalar	np.int8(5)
   String	python str	字符串格式输出转为python str	“news_car”
   Bytes	python bytes	二进制格式输出转为python bytes	图片数据

ResNet-50样例

样例来源于ResNet-50 example，ResNet-50 Servable提供的classify_top1方法提供对图像进行识别的服务。classify_top1方法输入为图像数据，输出为字符串，方法中预处理对图像进行解码、Resize等操作，接着进行推理，并通过后处理返回得分最大的分类标签。

import os
from mindspore_serving.client import Client


def run_classify_top1():
    client = Client("localhost:5500", "resnet50", "classify_top1")
    instances = []
    for path, _, file_list in os.walk("./test_image/"):
        for file_name in file_list:
            image_file = os.path.join(path, file_name)
            print(image_file)
            with open(image_file, "rb") as fp:
                instances.append({"image": fp.read()})
    result = client.infer(instances)
    print(result)


if __name__ == '__main__':
    run_classify_top1()

resnet50 Servable提供的classify_top1方法需要用户提供输入image，上面例子中，每个实例的输入image为图像的二进制数据。 正常结束执行后，预期将会有以下打印：

[{'label': 'tabby, tabby cat'}, {'label': 'ox'}]

如果ResNet-50模型未训练，可能有其他未知分类结果。

通过Unix domain socket访问Serving服务器

MindSpore Serving服务器和客户端可通过TCP/IP进行通信，当它们在一个机器内部时，也可通过Unix domain socket的方式通信，提升通讯性能。

Serving服务器启动gRPC服务时，mindspore_serving.server.start_grpc_server的address参数填写为'unix:{some_file_path}'作为gRPC服务的访问地址，其中{some_file_path}为相对或者绝对的文件路径，文件所在目录需要已经存在，接口成功调用后，文件将被复写。同时mindspore_serving.client.Client的address参数填写为上述的地址。比如：

服务器：

import os
import sys
from mindspore_serving import server


def start():
    servable_dir = os.path.dirname(os.path.realpath(sys.argv[0]))

    servable_config = server.ServableStartConfig(servable_directory=servable_dir, servable_name="resnet50",
                                                 device_ids=(0, 1))
    server.start_servables(servable_configs=servable_config)

    server.start_grpc_server(address="unix:/tmp/serving_resnet50_test_temp_file")


if __name__ == "__main__":
    start()

客户端：

import os
from mindspore_serving.client import Client


def run_classify_top1():
    client = Client("unix:/tmp/serving_resnet50_test_temp_file", "resnet50", "classify_top1")
    instances = []
    for path, _, file_list in os.walk("./test_image/"):
        for file_name in file_list:
            image_file = os.path.join(path, file_name)
            print(image_file)
            with open(image_file, "rb") as fp:
                instances.append({"image": fp.read()})
    result = client.infer(instances)
    print(result)


if __name__ == '__main__':
    run_classify_top1()

访问开启SSL/TLS的Serving服务

Mindspore Serving的服务器和客户端可以通过SSL/TLS协议进行通信。

SSL/TLS是一个安全通信协议，可以用来验证客户端或服务器的身份，加密所有的数据，保证通信的安全。数字证书用来标识服务器或客户端的身份，私钥用来解密数据和对信息摘要进行签名。我们可以用openssl来生成服务器与客户端相关的私钥和证书。

下面举个例子展示如何生成证书并进行单双向认证：

单向认证

仅客户端验证服务器的身份，所以我们需要服务器的证书和私钥。可以执行下面的openssl命令来生成相关证书。

# 生成根证书 用来签发服务器或客户端的证书
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt -subj "/C=CN/ST=xx/L=xx/OU=gRPC/CN=Root"

# 生成服务器的私钥
openssl genrsa -out server.key 2048
# 生成服务器证书签名请求
# 参数CN可以自定义证书上服务器名，这里我们可以配置成localhost，gRPC客户端访问时地址需要设置为localhost
openssl req -new -key server.key -out server.csr -subj "/C=XX/ST=MyST/L=XX/O=HW/OU=gRPC/CN=localhost"
# 使用根证书签发服务器证书
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256

我们得到了server.key，server.crt和ca.crt三个文件。将他们传入对应的SSLConfig。

• 服务器：

  import os
  import sys
  from mindspore_serving import server
  
  
  def start():
      servable_dir = os.path.dirname(os.path.realpath(sys.argv[0]))
  
      servable_config = server.ServableStartConfig(servable_directory=servable_dir, servable_name="add",
                                                   device_ids=(0, 1))
      server.start_servables(servable_configs=servable_config)
  
      ssl_config = server.SSLConfig(certificate="server.crt", private_key="server.key", custom_ca=None, verify_client=False)
  
      server.start_grpc_server(address="127.0.0.1:5500", ssl_config=ssl_config)
  
  
  if __name__ == "__main__":
      start()
  

  • ssl_config表示服务器的SSL配置。该参数默认为None，表示不开启SSL/TLS。开启SSL/TLS则需要传入mindspore_serving.server.SSLConfig对象。

  • certificate为服务器证书文件的路径。

  • private_key为服务器私钥文件的路径。

  • custom_ca为服务器的根证书文件的路径，用来验证客户端的身份。当verify_client 的为True时，需要验证客户端的证书，所以该参数不能为None，必须传入对应的路径。

  • verify_client表示是否验证客户端的身份。

  将verify_client设为False表示单向认证。我们分别传入服务器的证书server.crt和私钥server.key，由于服务器不需要验证客户端的证书，此时服务器的custom_ca参数会被忽略。

• 客户端：

  from mindspore_serving.client import Client
  from mindspore_serving.client import SSLConfig
  import numpy as np
  
  
  def run_add_common():
      """invoke Servable add method add_common"""
      ssl_config = SSLConfig(custom_ca="ca.crt")
      client = Client("localhost:5500", "add", "add_common", ssl_config=ssl_config)
      instances = []
  
      # instance 1
      x1 = np.asarray([[1, 1], [1, 1]]).astype(np.float32)
      x2 = np.asarray([[1, 1], [1, 1]]).astype(np.float32)
      instances.append({"x1": x1, "x2": x2})
  
      result = client.infer(instances)
      print(result)
  
  
  if __name__ == '__main__':
      run_add_common()
  

  • ssl_config表示客户端的SSL配置。该参数默认为None，表示不开启SSL/TLS。开启SSL/TLS则需要传入mindspore_serving.client.SSLConfig对象。

  • certificate为客户端证书文件的路径。

  • private_key为客户端私钥文件的路径。

  • custom_ca为客户端的根证书文件的路径，用来验证服务器的身份。该参数可以为None，这个时候gRPC会通过gRPC安装路径下的grpc/_cython/_credentials/roots.pem文件或GRPC_DEFAULT_SSL_ROOTS_FILE_PATH环境变量找到对应的根证书。pem文件或GRPC_DEFAULT_SSL_ROOTS_FILE_PATH环境变量找到对应的根证书。

  由于仅客户端验证服务器证书，所以只需要将custom_ca设置为签发服务器证书的ca.crt。

双向认证

客户端和服务器都需要验证对方的身份，所以除了服务器的证书，我们还需要执行下面的命令生成客户端的证书。

# 生成客户端的私钥
openssl genrsa -out client.key 2048
# 生成客户端证书签名请求
openssl req -new -key client.key -out client.csr -subj "/C=XX/ST=MyST/L=XX/O=HW/OU=gRPC/CN=client"
# 使用根证书签发客户端证书
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256

我们得到了client.key和cleint.crt。

• 服务器：

  import os
  import sys
  from mindspore_serving import server
  
  
  def start():
      servable_dir = os.path.dirname(os.path.realpath(sys.argv[0]))
  
      servable_config = server.ServableStartConfig(servable_directory=servable_dir, servable_name="add",
                                                   device_ids=(0, 1))
      server.start_servables(servable_configs=servable_config)
  
      ssl_config = server.SSLConfig(certificate="server.crt", private_key="server.key", custom_ca="ca.crt", verify_client=True)
  
      server.start_grpc_server(address="127.0.0.1:5500", ssl_config=ssl_config)
  
  
  if __name__ == "__main__":
      start()
  

  将verify_client设为True表示双向认证。同时将custom_ca设置为ca.crt来验证客户端证书。

• 客户端：

  from mindspore_serving.client import Client
  from mindspore_serving.client import SSLConfig
  import numpy as np
  
  
  def run_add_common():
      """invoke Servable add method add_common"""
      ssl_config = SSLConfig(certificate="client.crt", private_key="client.key", custom_ca="ca.crt")
      client = Client("localhost:5500", "add", "add_common", ssl_config=ssl_config)
      instances = []
  
      # instance 1
      x1 = np.asarray([[1, 1], [1, 1]]).astype(np.float32)
      x2 = np.asarray([[1, 1], [1, 1]]).astype(np.float32)
      instances.append({"x1": x1, "x2": x2})
  
      result = client.infer(instances)
      print(result)
  
  
  if __name__ == '__main__':
      run_add_common()
  

  客户端需要提供自己的证书给服务器验证，我们分别传入客户端的证书client.crt和私钥client.key。

当gRPC服务器与客户端SSL/TLS开启状态不一致的时候，服务器或客户端会出现ssl3_get_record:wrong version number的错误，这时需要确认服务器与客户端是否都开启了SSL/TLS。