文档首页 > > AI工程师用户指南> 模型包规范>

模型配置文件编写说明

模型配置文件编写说明

分享
更新时间:2021/04/23 GMT+08:00

模型开发者发布模型时需要编写配置文件。模型配置文件描述模型用途、模型计算框架、模型精度、推理代码依赖包以及模型对外API接口。

配置文件格式说明

配置文件为JSON格式,参数说明如表1所示。

表1 参数说明

参数

是否必选

参数类型

描述

model_algorithm

String

模型算法,表示该模型的用途,由模型开发者填写,以便使用者理解该模型的用途。只能以英文字母开头,不能包含中文以及&!'\"<>=,不超过36个字符。常见的模型算法有image_classification(图像分类)、object_detection(物体检测)、predict_analysis(预测分析)等。

model_type

String

模型AI引擎,表明模型使用的计算框架,可选的框架有TensorFlow、MXNet、Spark_MLlib、Caffe、Scikit_Learn、XGBoost、PyTorch、MindSpore、Image。

其中,Image并不是一个常用AI框架,当model_type设置为Image,表示以自定义镜像方式导入模型,此时swr_location为必填参数。Image镜像制作规范可参见自定义镜像制作规范

runtime

String

模型运行时环境,系统默认使用 Python2.7。runtime可选值与model_type相关,当model_type设置为Image时,不需要设置runtime,当model_type设置为其他常用框架时,请选择您使用的引擎及其对应开发环境。目前支持的运行环境列表请参见表1

需要注意的是,如果您的模型需指定CPU或GPU上运行时,请根据runtime的后缀信息选择,当runtime中未包含cpu或gpu信息时,请仔细阅读表1中每个runtime的说明信息。

swr_location

String

SWR镜像模板地址。

  • 如果您使用“从容器镜像中选择”的方式导入自定义镜像模型,“swr_location”参数无需配置。
  • 如果您使用“从对象存储服务(OBS)中选择”的方式导入自定义镜像模型(不推荐该方式),且model_type设置为Image时,“swr_location”参数必填。“swr_location”为docker镜像在SWR上的模板地址,表示直接使用SWR的docker镜像发布模型。

metrics

object数据结构

模型的精度信息,包括平均数、召回率、精确率、准确率,metrics object数据结构说明如表2所示。

只用于对外显示模型信息,可选填。

apis

api数据结构数组

表示模型接收和返回的请求样式,为结构体数据。

即模型可对外提供的Restful API数组,API数据结构如表3所示。

  • “model_type”“Image”时,即自定义镜像的模型场景,“apis”可根据镜像实际对外暴露的请求路径在“apis”中声明不同路径的API。
  • “model_type”不为“Image”时,“apis”只能声明一个请求路径为“/”的API,因为系统预置的AI引擎仅暴露一个请求路径为“/”的推理接口。

dependencies

dependency结构数组

表示模型推理代码需要依赖的包,为结构体数据。

模型开发者需要提供包名、安装方式、版本约束。目前只支持pip安装方式。dependency结构数组说明如表6所示。

如果模型包内没有推理代码customize_service.py文件,则该字段可不填。自定义镜像模型不支持安装依赖包。

说明:

“dependencies”参数支持多个“dependency”结构数组以ist格式填入,适用于安装包存在先后依赖关系。示例请参考使用OBS或者容器镜像导入模型时安装包存在前后依赖关系,模型配置文件应该如何说明?

health

health数据结构

镜像健康接口配置信息,只有“model_type”“Image”时才需填写。health数据结构如表8所示。

表2 metrics object数据结构说明

参数

是否必选

参数类型

描述

f1

Number

平均数。精确到小数点后17位,超过17位时,取前17位数值。

recall

Number

召回率。精确到小数点后17位,超过17位时,取前17位数值。

precision

Number

精确率。精确到小数点后17位,超过17位时,取前17位数值。

accuracy

Number

准确率。精确到小数点后17位,超过17位时,取前17位数值。

表3 api数据结构说明

参数

是否必选

参数类型

描述

protocol

String

请求协议。默认值为http。填写http或者https均可,请根据您的自定义镜像填写此参数。其他字段的详细指导可参考目标检测模型配置文件示例解读。

url

String

请求路径。默认值为“/”。自定义镜像的模型(即model_type为Image时)需要根据镜像内实际暴露的请求路径填写“url”。非自定义镜像模型(即model_type不为Image时)时,“url”只能为“/”

method

String

请求方法。默认值为“POST”

request

Object

请求体,request结构说明如表4所示。

response

Object

响应体,response结构说明如表5所示。

表4 request结构说明

参数

是否必选

参数类型

描述

Content-type

在线服务-非必选

批量服务-必选

String

data以指定内容类型发送。默认值为“application/json”

一般情况包括如下两种内容类型:

  • “application/json”,发送json数据。
  • “multipart/form-data”,上传文件。
说明:

针对机器学习类模型,仅支持“application/json”

data

在线服务-非必选

批量服务-必选

String

请求体以json schema描述。

表5 response结构说明

参数

是否必选

参数类型

描述

Content-type

在线服务-非必选

批量服务-必选

String

data以指定内容类型发送。默认值为“application/json”

一般情况包括如下两种内容类型:

  • “application/json”,发送json数据。
  • “multipart/form-data”,上传文件。
说明:

针对机器学习类模型,仅支持“application/json”

data

在线服务-非必选

批量服务-必选

String

响应体以json schema描述。

表6 dependency结构数组说明

参数

是否必选

参数类型

描述

installer

String

安装方式,当前只支持“pip”

packages

package结构数组

依赖包集合,package结构数组说明如表7所示。

表7 package结构数组说明

参数

是否必选

参数类型

描述

package_name

String

依赖包名称。不能含有中文及特殊字符&!'"<>=。

package_version

String

依赖包版本,如果不强依赖于版本号,则该项不填。不能含有中文及特殊字符&!'"<>=。

restraint

String

版本限制条件,当且仅当“package_version”存在时必填,可选“EXACT/ATLEAST/ATMOST”

  • “EXACT”表示安装给定版本。
  • “ATLEAST”表示安装版本不小于给定版本。
  • “ATMOST”表示安装包版本不大于给定版本。
    说明:
    • 如果对版本有明确要求,优先使用“EXACT”;如果使用“EXACT”与系统安装包有冲突,可以选择“ATLEAST”
    • 如果对版本没有明确要求,推荐不填写“restraint”“package_version”,只保留“package_name”参数
表8 health数据结构说明

参数

是否必选

参数类型

描述

url

String

健康检查接口请求路径。

protocol

String

健康检查接口请求协议,当前仅支持http。

initial_delay_seconds

String

实例启动后,延迟initial_delay_seconds秒再执行健康检查。

timeout_seconds

String

健康检查超时时间

目标检测模型配置文件示例

如下代码以TensorFlow引擎为例,您可以根据实际使用的引擎类型修改model_type参数后使用。

  • 模型输入

    key:images

    value:图片文件

  • 模型输出
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    ```
    {
        "detection_classes": [
            "face",
            "arm"
        ],
        "detection_boxes": [
            [
                33.6,
                42.6,
                104.5,
                203.4
            ],
            [
                103.1,
                92.8,
                765.6,
                945.7
            ]
        ],
        "detection_scores": [0.99, 0.73]
    }
    ```
    
  • 配置文件
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    ```
    {
        "model_type": "TensorFlow",
        "model_algorithm": "object_detection",
        "metrics": {
            "f1": 0.345294,
            "accuracy": 0.462963,
            "precision": 0.338977,
            "recall": 0.351852
        },
        "apis": [{
            "protocol": "http",
            "url": "/",
            "method": "post",
            "request": {
                "Content-type": "multipart/form-data",
                "data": {
                    "type": "object",
                    "properties": {
                        "images": {
                            "type": "file"
                        }
                    }
                }
            },
            "response": {
                "Content-type": "multipart/form-data",
                "data": {
                    "type": "object",
                    "properties": {
                        "detection_classes": {
                            "type": "array",
                            "items": [{
                                "type": "string"
                            }]
                        },
                        "detection_boxes": {
                            "type": "array",
                            "items": [{
                                "type": "array",
                                "minItems": 4,
                                "maxItems": 4,
                                "items": [{
                                    "type": "number"
                                }]
                            }]
                        },
                        "detection_scores": {
                            "type": "array",
                            "items": [{
                                "type": "number"
                            }]
                        }
                    }
                }
            }
        }],
        "dependencies": [{
            "installer": "pip",
            "packages": [{
                    "restraint": "EXACT",
                    "package_version": "1.15.0",
                    "package_name": "numpy"
                },
                {
                    "restraint": "EXACT",
                    "package_version": "5.2.0",
                    "package_name": "Pillow"
                }
            ]
        }]
    }
    ```
    

图像分类模型配置文件示例

如下代码以TensorFlow引擎为例,您可以根据实际使用的引擎类型修改model_type参数后使用。

  • 模型输入

    key:images

    value:图片文件

  • 模型输出
    1
    2
    3
    4
    5
    6
    7
    8
    9
    ```
    {
        "predicted_label": "flower",
        "scores": [
           ["rose", 0.99],
           ["begonia", 0.01]
        ]
    }
    ```
    
  • 配置文件
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    ```
    {
        "model_type": "TensorFlow",
        "model_algorithm": "image_classification",
        "metrics": {
            "f1": 0.345294,
            "accuracy": 0.462963,
            "precision": 0.338977,
            "recall": 0.351852
        },
        "apis": [{
            "protocol": "http",
            "url": "/",
            "method": "post",
            "request": {
                "Content-type": "multipart/form-data",
                "data": {
                    "type": "object",
                    "properties": {
                        "images": {
                            "type": "file"
                        }
                    }
                }
            },
            "response": {
                "Content-type": "multipart/form-data",
                "data": {
                    "type": "object",
                    "properties": {
                        "predicted_label": {
                            "type": "string"
                        },
                        "scores": {
                            "type": "array",
                            "items": [{
                                "type": "array",
                                "minItems": 2,
                                "maxItems": 2,
                                "items": [
                                    {
                                        "type": "string"
                                    },
                                    {
                                        "type": "number"
                                    }
                                ]
                            }]
                        }
                    }
                }
            }
        }],
        "dependencies": [{
            "installer": "pip",
            "packages": [{
                    "restraint": "ATLEAST",
                    "package_version": "1.15.0",
                    "package_name": "numpy"
                },
                {
                    "restraint": "",
                    "package_version": "",
                    "package_name": "Pillow"
                }
            ]
        }]
    }
    ```
    

预测分析模型配置文件示例

如下代码以TensorFlow引擎为例,您可以根据实际使用的引擎类型修改model_type参数后使用。

  • 模型输入
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    ```
    {
        "data": {
            "req_data": [
                {
                    "buying_price": "high",
                    "maint_price": "high",
                    "doors": "2",
                    "persons": "2",
                    "lug_boot": "small",
                    "safety": "low",
                    "acceptability": "acc"
                },
                {
                    "buying_price": "high",
                    "maint_price": "high",
                    "doors": "2",
                    "persons": "2",
                    "lug_boot": "small",
                    "safety": "low",
                    "acceptability": "acc"
                }
            ]
        }
    }
    ```
    
  • 模型输出
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    ```
    {
        "data": {
            "resp_data": [
                {
                    "predict_result": "unacc"
                },
                {
                    "predict_result": "unacc"
                }
            ]
        }
    }
    ```
    
  • 配置文件
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    ```
    {
        "model_type": "TensorFlow",
        "model_algorithm": "predict_analysis",
        "metrics": {
            "f1": 0.345294,
            "accuracy": 0.462963,
            "precision": 0.338977,
            "recall": 0.351852
        },
        "apis": [
            {
                "protocol": "http",
                "url": "/",
                "method": "post",
                "request": {
                    "Content-type": "application/json",
                    "data": {
                        "type": "object",
                        "properties": {
                            "data": {
                                "type": "object",
                                "properties": {
                                    "req_data": {
                                        "items": [
                                            {
                                                "type": "object",
                                                "properties": {
                                                }
                                            }],
                                        "type": "array"
                                    }
                                }
                            }
                        }
                    }
                },
                "response": {
                    "Content-type": "multipart/form-data",
                    "data": {
                        "type": "object",
                        "properties": {
                            "data": {
                                "type": "object",
                                "properties": {
                                    "resp_data": {
                                        "type": "array",
                                        "items": [
                                            {
                                                "type": "object",
                                                "properties": {
                                                }
                                            }]
                                    }
                                }
                            }
                        }
                    }
                }
            }],
        "dependencies": [
            {
                "installer": "pip",
                "packages": [
                    {
                        "restraint": "EXACT",
                        "package_version": "1.15.0",
                        "package_name": "numpy"
                    },
                    {
                        "restraint": "EXACT",
                        "package_version": "5.2.0",
                        "package_name": "Pillow"
                    }]
            }]
    }
    ```
    

自定义镜像类型的模型配置文件示例

模型输入和输出与目标检测模型配置文件示例类似。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
    "model_algorithm": "image_classification",
    "model_type": "Image",

    "metrics": {
        "f1": 0.345294,
        "accuracy": 0.462963,
        "precision": 0.338977,
        "recall": 0.351852
    },
    "apis": [{
        "protocol": "http",
        "url": "/",
        "method": "post",
        "request": {
            "Content-type": "multipart/form-data",
            "data": {
                "type": "object",
                "properties": {
                    "images": {
                        "type": "file"
                    }
                }
            }
        },
        "response": {
            "Content-type": "multipart/form-data",
            "data": {
                "type": "object",
                "required": [
                    "predicted_label",
                    "scores"
                ],
                "properties": {
                    "predicted_label": {
                        "type": "string"
                    },
                    "scores": {
                        "type": "array",
                        "items": [{
                            "type": "array",
                            "minItems": 2,
                            "maxItems": 2,
                            "items": [{
                                    "type": "string"
                                },
                                {
                                    "type": "number"
                                }
                            ]
                        }]
                    }
                }
            }
        }
    }]
}

机器学习类型的模型配置文件示例

以XGBoost为例:

  • 模型输入:
{
	"data": {
		"req_data": [{
			"sepal_length": 5,
			"sepal_width": 3.3,
			"petal_length": 1.4,
			"petal_width": 0.2
		}, {
			"sepal_length": 5,
			"sepal_width": 2,
			"petal_length": 3.5,
			"petal_width": 1
		}, {
			"sepal_length": 6,
			"sepal_width": 2.2,
			"petal_length": 5,
			"petal_width": 1.5
		}]
	}
}
  • 模型输出:
{
	"data": {
		"resp_data": [{
			"predict_result": "Iris-setosa"
		}, {
			"predict_result": "Iris-versicolor"
		}]
	}
}
  • 配置文件:
{
  "model_type": "XGBoost",
  "model_algorithm": "xgboost_iris_test",
  "runtime": "python2.7",
  "metrics": {
    "f1": 0.345294,
    "accuracy": 0.462963,
    "precision": 0.338977,
    "recall": 0.351852
  },
  "apis": [
    {
      "protocol": "http",
      "url": "/",
      "method": "post",
      "request": {
        "Content-type": "application/json",
        "data": {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "properties": {
                "req_data": {
                  "items": [
                    {
                      "type": "object",
                      "properties": {}
                    }
                  ],
                  "type": "array"
                }
              }
            }
          }
        }
      },
      "response": {
        "Content-type": "applicaton/json",
        "data": {
          "type": "object",
          "properties": {
            "resp_data": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "predict_result": {
                      "type": "number"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  ]
}

使用自定义依赖包的模型配置文件示例

如下示例中,定义了1.16.4版本的numpy的依赖环境。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
     "model_algorithm": "image_classification",
     "model_type": "TensorFlow",
     "runtime": "python3.6",
     "apis": [{
             "procotol": "http",
             "url": "/",
             "method": "post",
             "request": {
                 "Content-type": "multipart/form-data",
                 "data": {
                     "type": "object",
                     "properties": {
                         "images": {
                             "type": "file"
                         }
                     }
                 }
             },
             "response": {
                 "Content-type": "applicaton/json",
                 "data": {
                     "type": "object",
                     "properties": {
                         "mnist_result": {
                             "type": "array",
             "item": [{
                "type": "string"
                         }]
                         }
                     }
                 }
             }
         }
     ],
     "metrics": {
         "f1": 0.124555,
         "recall": 0.171875,
         "precision": 0.0023493892851938493,
         "accuracy": 0.00746268656716417
     },
    "dependencies": [{
        "installer": "pip",
        "packages": [{
                "restraint": "EXACT",
                "package_version": "1.16.4",
                "package_name": "numpy"
            }
        ]
    }]
 }
分享:

    相关文档

    相关产品