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。
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) - 模型的选项,支持 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)
- 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)