mindspore_serving.server

MindSpore Serving是一个轻量级、高性能的服务模块，旨在帮助MindSpore开发者在生产环境中高效部署在线推理服务。

用户可通过MindSpore Serving server API启动服务，启动gRPC和RESTful（HTTP）服务器。其中一个服务一般可由一个模型或者一组模型组合提供。客户端通过gRPC和RESTful（HTTP）服务器发送推理任务，接收推理结果。

mindspore_serving.server.start_grpc_server(address, max_msg_mb_size=100, ssl_config=None)[源代码]

启动gRPC服务器，用于Serving客户端和Serving服务器之间的通信。

参数：

address (str) - gRPC服务器地址，地址可以是 {ip}:{port} 或 unix:{unix_domain_file_path} 。
- {ip}:{port} - Internet domain socket地址。
- unix:{unix_domain_file_path} - Unix domain socket地址，用于与同一台计算机上的多个进程通信。 {unix_domain_file_path} 可以是相对路径或绝对路径，但文件所在的目录必须已经存在。
max_msg_mb_size (int, optional) - 可接收的最大gRPC消息大小（MB），取值范围[1, 512]。默认值：100。
ssl_config (mindspore_serving.server.SSLConfig, optional) - 服务器的SSL配置，如果None，则禁用SSL。默认值：None。

异常：

RuntimeError - 启动gRPC服务器失败：参数校验失败，gRPC地址错误或端口重复。

样例：

>>> from mindspore_serving import server
>>>
>>> server.start_grpc_server("0.0.0.0:5500")

mindspore_serving.server.start_restful_server(address, max_msg_mb_size=100, ssl_config=None)[源代码]

启动RESTful服务器，用于Serving客户端和Serving服务器之间的通信。

参数：

address (str) - RESTful服务器地址，地址应为Internet domain socket地址。
max_msg_mb_size (int, optional) - 最大可接收的RESTful消息大小，以MB为单位，取值范围[1, 512]。默认值：100。
ssl_config (mindspore_serving.server.SSLConfig, optional) - 服务器的SSL配置，如果是None，则禁用SSL。默认值：None。

异常：

RuntimeError - 启动RESTful服务器失败：参数校验失败，RESTful地址错误或端口重复。

样例：

>>> from mindspore_serving import server
>>>
>>> server.start_restful_server("0.0.0.0:5900")

mindspore_serving.server.stop()[源代码]

停止Serving服务器的运行。

样例：

>>> from mindspore_serving import server
>>>
>>> server.start_grpc_server("0.0.0.0:5500")
>>> server.start_restful_server("0.0.0.0:1500")
>>> ...
>>> server.stop()

mindspore_serving.server.start_servables(servable_configs, enable_lite=False)[源代码]

用于Serving服务器中启动一个或多个服务，一个模型可结合预处理、后处理提供一个服务，多个模型也可串接组合提供一个服务。

本接口可以用来启动多个不同的服务。一个服务可以部署在多个设备上，其中每个设备运行一个服务副本。

在Atlas训练系列产品硬件平台上，每个服务的每个副本都独占一个设备。不同的服务或同一服务的不同版本需要部署在不同的设备上。在Atlas推理系列产品、Atlas 200/300/500推理产品和GPU硬件平台上，一个设备可以被多个服务共享，不同服务或同一服务的不同版本可以部署在同一设备上，实现设备复用。

如何配置模型提供服务请查看基于MindSpore Serving部署推理服务和通过配置模型提供Servable 。

参数：

servable_configs (Union[ServableStartConfig, list[ServableStartConfig], tuple[ServableStartConfig]]) - 一个或多个服务的启动配置。
enable_lite (bool) - 是否使用MindSpore Lite推理后端。默认值：False。

异常：

RuntimeError - 启动一个或多个服务失败。相关日志可查看本Serving服务器启动脚本所在目录的子目录serving_logs。

样例：

>>> import os
>>> from mindspore_serving import server
>>>
>>> servable_dir = os.path.abspath(".")
>>> resnet_config = server.ServableStartConfig(servable_dir, "resnet", device_ids=(0,1))
>>> add_config = server.ServableStartConfig(servable_dir, "add", device_ids=(2,3))
>>> server.start_servables(servable_configs=(resnet_config, add_config))  # press Ctrl+C to stop
>>> server.start_grpc_server("0.0.0.0:5500")

class mindspore_serving.server.ServableStartConfig(servable_directory, servable_name, device_ids=None, version_number=0, device_type=None, num_parallel_workers=0, dec_key=None, dec_mode='AES-GCM')[源代码]

启动一个服务的配置。详情请查看基于MindSpore Serving部署推理服务和通过配置模型提供Servable 。

参数：

servable_directory (str) - 服务所在的目录。预期有一个名为 servable_name 的目录。
servable_name (str) - 服务名称。
device_ids (Union[int, list[int], tuple[int]], optional) - 模型部署和运行的设备列表，列表中的每个会设备将部署和运行一个服务副本。当设备类型为Nvidia GPU、Atlas训练系列产品、Atlas推理系列产品、Atlas 200/300/500推理产品时使用。默认值：None。
version_number (int, optional) - 要加载的服务的版本号。版本号应为正整数，从1开始，0表示加载最新版本。默认值：0。
device_type (str, optional) - 模型部署的目标设备类型，目前支持”Ascend”、”GPU”、”CPU”和None。默认值：None。
- “Ascend”：目标设备为Atlas训练系列产品、Atlas推理系列产品、Atlas 200/300/500推理产品等。
- “GPU”：目标设备为Nvidia GPU。
- “CPU”：目标设备为CPU。
- None：系统根据实际的后端设备和MindSpor推理包决定目标设备，推荐使用默认值None。
num_parallel_workers (int, optional) - 处理Python任务的进程数，用于提高预处理、后处理等Python任务的处理能力。值小于 device_ids 的长度时，处理Python任务的进程数为 device_ids 的长度。值的范围为[0,64]。默认值：0。
dec_key (bytes, optional) - 用于解密的字节类型密钥。有效长度为16、24或32。默认值：None。
dec_mode (str, optional) - 指定解密模式，设置 dec_key 时生效。值可为： ‘AES-GCM’ 或 ‘AES-CBC’ 。默认值： ‘AES-GCM’ 。

异常：

RuntimeError - 参数的类型或值无效。

class mindspore_serving.server.SSLConfig(certificate, private_key, custom_ca=None, verify_client=False)[源代码]

Serving服务器中，使能gRPC或RESTful服务器SSL功能时，SSL的参数配置。

参数：

certificate (str) - PEM编码的证书链内容，如果值为None，则表示不使用证书链。
private_key (str) - PEM编码的私钥内容，如果值为None，则表示不使用私钥。
custom_ca (str, optional) - PEM编码的根证书内容。当 verify_client 为True时， custom_ca 必须指定。当 verify_client 为False时，将忽略此参数。默认值：None。
verify_client (bool, optional) - 如果 verify_client 为True，则启用客户端服务器双向认证。如果为False，则仅启用客户端对服务器的单向认证。默认值：False。

异常：

RuntimeError - 参数的类型或值无效。

mindspore_serving.server.register

服务注册接口，在服务的servable_config.py配置文件中使用。如何配置servable_config.py文件，请查看通过配置模型提供Servable 。

mindspore_serving.server.register.declare_model(model_file, model_format, with_batch_dim=True, options=None, without_batch_dim_inputs=None, context=None, config_file=None)[源代码]

在服务的servable_config.py配置文件中使用，用于声明一个模型。

说明

本接口需要在Serving服务器导入servable_config.py时生效。因此，建议在servable_config.py中全局使用此接口。

警告

参数 options 从1.6.0版本中已弃用，并将在未来版本中删除，请改用参数 context 。

参数：

model_file (Union[str, list[str]]) - 模型文件名。
model_format (str) - 模型格式，”OM”、”MindIR” 或”MindIR_Lite”，忽略大小写。
with_batch_dim (bool, optional) - 模型输入和输出的shape第一个维度是否是batch维度。默认值：True。
options (Union[AclOptions, GpuOptions], optional) - 模型的选项，支持 AclOptions 或 GpuOptions 。默认值：None。
context (Context) - 用于配置设备环境的上下文信息，值为None时，Serving将依据部署的设备设置默认的设备上下文。默认值：None。
without_batch_dim_inputs (Union[int, tuple[int], list[int]], optional) - 当 with_batch_dim 为True时，用于指定shape不包括batch维度的模型输入的索引，比如模型输入0的shape不包括batch维度，则 without_batch_dim_inputs 可赋值为 (0,) 。默认值：None。
config_file (str, optional) - 用于设置混合精度推理的配置文件。文件路径可以是servable_config.py所在目录的绝对路径或相对路径。默认值：None。

返回：

Model ，此模型的标识，可以用来调用 Model.call 或作为 add_stage 的输入。

异常：

RuntimeError - 参数的类型或值无效。

class mindspore_serving.server.register.Model(model_key)[源代码]

用于表示一个声明的模型。用户不应该直接构造 Model 对象，而是来自于 declare_model 或 declare_servable 的返回。

参数：

model_key (str) - 模型的唯一标志。

call(*args, subgraph=0)[源代码]

调用模型推理接口。

参数：

subgraph (int, optional) - 子图索引，当一个模型中存在多个子图时使用。
args - 实例的元组/列表，或一个实例的输入。

返回：

当输入参数 args 为元组/列表时，返回为instances的元组，当前输入 args 为一个实例的输入时，输出为这个实例的输出。

异常：

RuntimeError - 输入无效。

样例：

>>> import numpy as np
>>> from mindspore_serving.server import register
>>> import mindspore.dataset.vision.c_transforms as VC
>>> model = register.declare_model(model_file="resnet_bs32.mindir", model_format="MindIR") # batch_size=32
>>>
>>> def preprocess(image):
...     decode = VC.Decode()
...     resize = VC.Resize([224, 224])
...     normalize = VC.Normalize(mean=[125.307, 122.961, 113.8575], std=[51.5865, 50.847, 51.255])
...     hwc2chw = VC.HWC2CHW()
...     image = decode(image)
...     image = resize(image) # [3,224,224]
...     image = normalize(image) # [3,224,224]
...     image = hwc2chw(image) # [3,224,224]
...     return input
>>>
>>> def postprocess(score):
>>>     return np.argmax(score)
>>>
>>> def call_resnet_model(image):
...     image = preprocess(image)
...     score = model.call(image)  # for only one instance
...     return postprocess(score)
>>>
>>> def call_resnet_model_batch(instances):
...     input_instances = []
...     for instance in instances:
...         image = instance[0] # only one input
...         image = preprocess(image) # [3,224,224]
...         input_instances.append([image])
...     output_instances = model.call(input_instances)  # for multiply instances
...     for instance in output_instances:
...         score = instance[0]  # only one output for each instance
...         index = postprocess(score)
...         yield index
>>>
>>> @register.register_method(output_names=["index"])
>>> def predict_v1(image):  # without pipeline, call model with only one instance a time
...     index = register.add_stage(call_resnet_model, image, outputs_count=1)
...     return index
>>>
>>> @register.register_method(output_names=["index"])
>>> def predict_v2(image):  # without pipeline, call model with maximum 32 instances a time
...     index = register.add_stage(call_resnet_model_batch, image, outputs_count=1, batch_size=32)
...     return index
>>>
>>> @register.register_method(output_names=["index"])
>>> def predict_v3(image):  # pipeline
...     image = register.add_stage(preprocess, image, outputs_count=1)
...     score = register.add_stage(model, image, outputs_count=1)
...     index = register.add_stage(postprocess, score, outputs_count=1)
...     return index

class mindspore_serving.server.register.AscendDeviceInfo(**kwargs)[源代码]

用于设置Ascend设备配置。

参数：

insert_op_cfg_path (str, optional) - AIPP配置文件的路径。
input_format (str, optional) - 模型输入格式，取值可以是 “ND” 、 “NCHW” 、 “NHWC” 、 “CHWN” 、 “NC1HWC0” 或 “NHWC1C0” 。
input_shape (str, optional) - 模型输入形状，如 “input_op_name1: n1,c2,h3,w4;input_op_name2: n4,c3,h2,w1” 。
output_type (str, optional) - 模型输出类型，值可以是 “FP16” 、 “UINT8” 或 “FP32” ，默认值： “FP32” 。
precision_mode (str, optional) - 模型精度模式，取值可以是 “force_fp16” 、 “allow_fp32_to_fp16” 、 “must_keep_origin_dtype” 或者 “allow_mix_precision” 。默认值： “force_fp16” 。
op_select_impl_mode (str, optional) - 运算符选择模式，值可以是 “high_performance” 或 “high_precision” 。默认值： “high_performance” 。
fusion_switch_config_path (str, optional) - 融合配置文件路径，包括图融合和UB融合。系统内置图融合和UB融合规则，默认启用。您可以通过设置此参数禁用指定的融合规则。
buffer_optimize_mode (str, optional) - 数据缓存优化策略，值可以是 “l1_optimize” 、 “l2_optimize” 、 “off_optimize” 或者 “l1_and_l2_optimize” 。默认 “l2_optimize” 。

异常：

RuntimeError - Ascend设备配置无效。

样例：

>>> from mindspore_serving.server import register
>>> context = register.Context()
>>> context.append_device_info(register.AscendDeviceInfo(input_format="NCHW"))
>>> model = register.declare_model(model_file="deeptext.ms", model_format="MindIR_Lite", context=context)

class mindspore_serving.server.register.CPUDeviceInfo(**kwargs)[源代码]

用于CPU设备配置。

参数：

precision_mode (str, optional) - 推理精度选项，值可以是 “origin” 或 “fp16” ， “origin” 表示以模型中指定精度进行推理， “fp16” 表示以FP16精度进行推理。默认值： “origin” 。

异常：

RuntimeError - 选项无效，或值类型不是字符串。

样例：

>>> from mindspore_serving.server import register
>>> context = register.Context()
>>> context.append_device_info(register.CPUDeviceInfo(precision_mode="fp16"))
>>> model = register.declare_model(model_file="deeptext.ms", model_format="MindIR_Lite", context=context)

class mindspore_serving.server.register.GPUDeviceInfo(**kwargs)[源代码]

用于GPU设备配置。

参数：

precision_mode (str, optional) - 推理精度选项，值可以是 “origin” 或 “fp16” ， “origin” 表示以模型中指定精度进行推理， “fp16” 表示以FP16精度进行推理。默认值： “origin” 。

异常：

RuntimeError - 选项无效，或值类型不是字符串。

样例：

>>> from mindspore_serving.server import register
>>> context = register.Context()
>>> context.append_device_info(register.GPUDeviceInfo(precision_mode="fp16"))
>>> model = register.declare_model(model_file="deeptext.mindir", model_format="MindIR", context=context)

class mindspore_serving.server.register.Context(**kwargs)[源代码]

Context用于自定义设备配置，如果不指定Context，MindSpore Serving将使用默认设备配置。当使用推理后端为MindSpore Lite，且目标设备为Ascend或Nvidia GPU时，模型部分算子可能运行在CPU设备上，将额外配置 CPUDeviceInfo 。

参数：

thread_num (int, optional) - 设置运行时的CPU线程数量，该选项仅当推理后端为MindSpore Lite有效。
thread_affinity_core_list (tuple[int], list[int], optional) - 设置运行时的CPU绑核列表，该选项仅当推理后端为MindSpore Lite有效。
enable_parallel (bool, optional) - 设置运行时是否支持并行，该选项仅当推理后端为MindSpore Lite有效。

异常：

RuntimeError - 输入参数的类型或值无效。

样例：

>>> from mindspore_serving.server import register
>>> import numpy as np
>>> context = register.Context(thread_num=1, thread_affinity_core_list=[1,2], enable_parallel=True)
>>> context.append_device_info(register.GPUDeviceInfo(precision_mode="fp16"))
>>> model = declare_model(model_file="tensor_add.mindir", model_format="MindIR", context=context)

append_device_info(device_info)[源代码]

用于添加一个用户自定义的设备配置。

参数：

device_info (Union[CPUDeviceInfo, GPUDeviceInfo, AscendDeviceInfo]) - 用户自定义设备配置，用户不指定设备配置时将使用默认值。可以为每个可能的设备自定义设备配置，系统根据实际的后端设备和推理包选择所需的设备信息。

异常：

RuntimeError - 输入参数的类型或值无效。

mindspore_serving.server.register.register_method(output_names)[源代码]

在服务的servable_config.py配置文件中使用，用于注册服务的方法，一个服务可以包括一个或多个方法，每个方法可基于模型提供不同的功能，客户端访问服务时需要指定服务和方法。MindSpore Serving支持由多个Python函数和多个模型组合串接提供服务。

说明

本接口需要在Serving服务器导入servable_config.py时生效。因此，建议在servable_config.py中全局使用此接口。

此接口将定义方法的签名和处理流程。

签名包括方法名称、方法的输入和输出名称。当Serving客户端访问服务时，客户端需要指定服务名称、方法名称，并提供一个或多个推理实例。每个实例通过输入名称指定输入数据，并通过输出名称获取输出结果。

处理流程由一个或多个阶段（stage）组成，每个阶段可以是一个Python函数或模型。即，一个方法的处理流程可以包括一个或多个Python函数和一个或多个模型。此外，接口还定义了这些阶段之间的数据流。

参数：

output_names (Union[str, tuple[str], list[str]]) - 指定方法的输出名称。输入名称通过注册函数的参数名称指定。

异常：

RuntimeError - 参数的类型或值无效，或发生其他错误。

样例：

>>> from mindspore_serving.server import register
>>> add_model = register.declare_model(model_file="tensor_add.mindir", model_format="MindIR")
>>> sub_model = register.declare_model(model_file="tensor_sub.mindir", model_format="MindIR")
>>>
>>> @register.register_method(output_names=["y"]) # register predict method in servable
>>> def predict(x1, x2, x3): # x1+x2-x3
...     y = register.add_stage(add_model, x1, x2, outputs_count=1)
...     y = register.add_stage(sub_model, y, x3, outputs_count=1)
...     return y

mindspore_serving.server.register.add_stage(stage, *args, outputs_count, batch_size=None, tag=None)[源代码]

在服务的 servable_config.py 中，通过 register_method 装饰（wrap）Python函数定义服务的一个方法（method），本接口用于定义这个方法中的一个运行步骤（stage），可以是一个Python函数或者模型。

说明

入参 args 的长度应等于函数或模型的输入个数。

参数：

stage (Union(function, Model)) - 用户定义的Python函数或由 declare_model 返回 Model 对象。
outputs_count (int) - 用户定义的Python函数或模型的输出个数。
batch_size (int, optional) - 仅当stage是Python函数，且函数一次可以处理多实例时，此参数有效。默认值：None。
- None，函数的输入将是一个实例的输入。
- 0，函数的输入将是实例的元组对象，实例元组的最大长度由服务器根据模型的batch大小确定。
- int value >= 1，函数的输入将是实例的元组对象，实例元组的最大长度是 batch_size 指定的值。
args - stage输入占位符，可以是 register_method 装饰（wrap）的函数的输入或其他 add_stage 的输出。 args 的长度应等于Python函数或模型的输入数量。
tag (str, optional) - stage的自定义标签，如”preprocess”，默认值：None。

异常：

RuntimeError - 参数的类型或值无效，或发生其他错误。

样例：

>>> import numpy as np
>>> from mindspore_serving.server import register
>>> add_model = register.declare_model(model_file="tensor_add.mindir", model_format="MindIR")
>>>
>>> def preprocess(x1, x2):
...     return x1.astype(np.float32), x2.astype(np.float32)
>>>
>>> @register.register_method(output_names=["y"]) # register add_common method in add
>>> def add_common(x1, x2):
...     x1, x2 = register.add_stage(preprocess, x1, x2, outputs_count=2) # call preprocess in stage 1
...     y = register.add_stage(add_model, x1, x2, outputs_count=1) # call add model in stage 2
...     return y

mindspore_serving.server.distributed

Serving服务器启动分布式模型服务的接口。如何配置和启动分布式模型，请查看基于MindSpore Serving部署分布式推理服务。

mindspore_serving.server.distributed.start_servable(servable_directory, servable_name, rank_table_json_file, version_number=1, distributed_address='0.0.0.0:6200', wait_agents_time_in_seconds=0)[源代码]

启动在 servable_directory 中定义的名为 servable_name 的分布式服务。

参数：

servable_directory (str) - 服务所在的目录。预期有一个名为 servable_name 的目录。详细信息可以查看通过配置模型提供Servable 。
servable_name (str) - 服务名称。
version_number (int, optional) - 要加载的服务版本号。版本号应为正整数，从1开始。默认值：1。
rank_table_json_file (str) - rank table json文件名。
distributed_address (str, optional) - Worker代理（Agent）连接的分布式Worker服务器地址。默认值： “0.0.0.0:6200” 。
wait_agents_time_in_seconds (int, optional) - 等待所有Worker代理就绪的最长时间（以秒为单位），0表示无限时间。默认值：0。

异常：

RuntimeError - 启动分布式服务失败。

样例：

>>> import os
>>> from mindspore_serving.server import distributed
>>>
>>> servable_dir = os.path.abspath(".")
>>> distributed.start_servable(servable_dir, "matmul", startup_worker_agents="hccl_8p.json", \
...                            distributed_address="127.0.0.1:6200")

mindspore_serving.server.distributed.startup_agents(distributed_address, model_files, group_config_files=None, agent_start_port=7000, agent_ip=None, rank_start=None, dec_key=None, dec_mode='AES-GCM')[源代码]

在当前计算机上启动所有所需的Worker代理（Agent），这组Worker代理进程将负责本机器设备上的推理任务，详细可参考基于MindSpore Serving部署分布式推理服务。

参数：

distributed_address (str) - Worker代理连接分布式Worker服务器地址。
model_files (Union[list[str], tuple[str]]) - 当前计算机中需要的所有模型文件，为绝对路径或相对于此启动Python脚本的路径。
group_config_files (Union[list[str], tuple[str]], optional) - 当前计算机中需要的所有组配置文件，相对于此启动Python脚本的绝对路径或相对路径，为None时表示没有配置文件。默认值：None。
agent_start_port (int, optional) - Worker代理连接Worker服务器的起始端口号。默认值：7000。
agent_ip (str, optional) - 本地Worker代理ip，如果为无，则代理ip将从rank table文件中获取。参数 agent_ip 和参数 rank_start 必须同时有值，或者同时是None。默认值：None。
rank_start (int, optional) - 此计算机的起始rank id，如果为None，则将从rank table文件中获取rank id。参数 agent_ip 和参数 rank_start 必须同时有值，或者同时是None。默认值：None。
dec_key (bytes, optional) - 用于解密的密钥，类型为字节。有效长度为16、24或32。默认值：None。
dec_mode (str, optional) - 指定解密模式，在设置了 dec_key 时生效。值可为： ‘AES-GCM’ 或 ‘AES-CBC’ 。默认值： ‘AES-GCM’ 。

异常：

RuntimeError - 启动Worker代理失败。

样例：

>>> import os
>>> from mindspore_serving.server import distributed
>>> model_files = []
>>> for i in range(8):
>>>    model_files.append(f"models/device{i}/matmul.mindir")
>>> distributed.startup_agents(distributed_address="127.0.0.1:6200", model_files=model_files)

mindspore_serving.server.distributed.declare_servable(rank_size, stage_size, with_batch_dim=True, without_batch_dim_inputs=None, enable_pipeline_infer=False)[源代码]

用于在servable_config.py中声明分布式服务，详细可参考基于MindSpore Serving部署分布式推理服务。

参数：

rank_size (int) - 分布式模型的rank大小。
stage_size (int) - 分布式模型的stage大小。
with_batch_dim (bool, optional) - 模型输入和输出shape的第一个维度是否是batch维度。默认值：True。
without_batch_dim_inputs (Union[int, tuple[int], list[int]], optional) - 当 with_batch_dim 为True时，用于指定shape不包括batch维度的模型输入的索引，比如模型输入0的shape不包括batch维度，则 without_batch_dim_inputs=(0,) 。默认值：None。
enable_pipeline_infer (bool, optional) - 是否开启流水线并行推理，流水线并行可有效提升推理性能，详情可参考流水线并行。默认值：False。

返回：

Model ，此模型的标识，可以用来调用 Model.call 或作为 add_stage 的输入。

异常：

RuntimeError - 参数的类型或值无效。

样例：

>>> from mindspore_serving.server import distributed
>>> model = distributed.declare_servable(rank_size=8, stage_size=1)