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服务器中启动一个或多个服务,一个模型可结合预处理、后处理提供一个服务,多个模型也可串接组合提供一个服务。

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

在Ascend 910硬件平台上,每个服务的每个副本都独占一个设备。不同的服务或同一服务的不同版本需要部署在不同的设备上。在Ascend 310/310P和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、Ascend 310/310P/910时使用。默认值:None。

  • version_number (int, optional) - 要加载的服务的版本号。版本号应为正整数,从1开始,0表示加载最新版本。默认值:0。

  • device_type (str, optional) - 模型部署的目标设备类型,目前支持”Ascend”、”GPU”、”CPU”和None。默认值:None。

    • “Ascend”:目标设备为Ascend 310/310P/910等。

    • “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配置文件中使用,用于声明一个模型。

Note

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

Warning

参数 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) - 模型的选项,支持 AclOptionsGpuOptions 。默认值: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_modeldeclare_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函数和多个模型组合串接提供服务。

Note

本接口需要在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函数或者模型。

Note

入参 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)