# 模型配置文件编写说明 模型开发者发布模型时需要编写配置文件config.json。模型配置文件描述模型用途、模型计算框架、模型精度、推理代码依赖包以及模型对外API接口。 #### 配置文件格式说明 配置文件为JSON格式，参数说明如[表1]所示。 表1参数说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | model_algorithm | 是 | String | 模型算法，表示该模型的用途，由模型开发者填写，以便使用者理解该模型的用途。只能以英文字母开头，不能包含中文以及\&!'\\"\<\>=，不超过36个字符。常见的模型算法有image_classification（图像分类）、object_detection（物体检测）、predict_analysis（预测分析）等。 | | model_type | 是 | String | 模型AI引擎，表明模型使用的计算框架，支持常用AI框架和"Image"。 - 可选的常用AI框架请参见[推理支持的AI引擎](https://support.huaweicloud.com/inference-modelarts/inference-modelarts-0003.html#ZH-CN_TOPIC_0000001986022785__zh-cn_topic_0171858287_section04192617912)。 - 当model_type设置为Image，表示以自定义镜像方式创建模型，此时swr_location为必填参数。Image镜像制作规范可参见[模型镜像规范](https://support.huaweicloud.com/docker-modelarts/modelarts_23_0219.html#section2)。 | | runtime | 否 | String | 模型运行时环境，系统默认使用python2.7。runtime可选值与model_type相关，当model_type设置为Image时，不需要设置runtime，当model_type设置为其他常用框架时，请选择您使用的引擎所对应的运行时环境。目前支持的运行时环境列表请参见[推理支持的AI引擎](https://support.huaweicloud.com/inference-modelarts/inference-modelarts-0003.html#ZH-CN_TOPIC_0000001986022785__zh-cn_topic_0171858287_section04192617912)。 需要注意的是，如果您的模型需指定CPU或GPU上运行时，请根据runtime的后缀信息选择，当runtime中未包含cpu或GPU信息时，请仔细阅读"推理支持的AI引擎"中每个runtime的说明信息。 | | metrics | 否 | object数据结构 | 模型的精度信息，包括平均数、召回率、精确率、准确率，metrics object数据结构说明如[表2]所示。 结果会显示在模型详情页面的"模型精度"模块。 | | apis | 否 | api数据结构数组 | 表示模型接收和返回的请求样式，为结构体数据。 即模型可对外提供的RESTful API数组，API数据结构如[表3]所示。示例代码请参见[apis参数代码示例]。 - "model_type"为"Image"时，即自定义镜像的模型场景，"apis"可根据镜像实际对外暴露的请求路径在"apis"中声明不同路径的API。 - "model_type"不为"Image"时，"apis"只能声明一个请求路径为"/"的API，因为系统预置的AI引擎仅暴露一个请求路径为"/"的推理接口。 | | dependencies | 否 | dependency结构数组 | 表示模型推理代码需要依赖的包，为结构体数据。 模型开发者需要提供包名、安装方式、版本约束。目前只支持pip安装方式。dependency结构数组说明如[表6]所示。 如果模型包内没有推理代码customize_service.py文件，则该字段可不填。自定义镜像模型不支持安装依赖包。 说明： "dependencies"参数支持多个"dependency"结构数组，以list格式填入，默认安装包存在先后依赖关系（即写在前面的先安装，写在后面的后安装），且支持线下wheel包安装（wheel包必须与模型文件放在同一目录），当前不支持用户指定pip源。示例请参考[导入模型时安装包依赖配置文件如何书写？](https://support.huaweicloud.com/modelarts_faq/modelarts_05_0161.html) | | health | 否 | health数据结构 | 镜像健康接口配置信息，只有"model_type"为"Image"时才需填写。 如果在滚动升级时要求不中断业务，那么必须提供健康检查的接口供ModelArts调用。health数据结构如[表8]所示。 | 表2metrics object数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | f1 | 否 | Number | 平均数。精确到小数点后17位，超过17位时，取前17位数值。 | | recall | 否 | Number | 召回率。精确到小数点后17位，超过17位时，取前17位数值。 | | precision | 否 | Number | 精确率。精确到小数点后17位，超过17位时，取前17位数值。 | | accuracy | 否 | Number | 准确率。精确到小数点后17位，超过17位时，取前17位数值。 | 表3api数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | url | 否 | String | 请求路径。默认值为"/"。自定义镜像的模型（即model_type为Image时）需要根据镜像内实际暴露的请求路径填写"url"。非自定义镜像模型（即model_type不为Image时）时，"url"只能为"/"。 | | method | 否 | String | 请求方法。默认值为"POST"。 | | request | 否 | Object | 请求体，request结构说明如[表4]所示。 | | response | 否 | Object | 响应体，response结构说明如[表5]所示。 | 表4request结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Content-type | 在线服务-非必选 批量服务-必选 | String | data以指定内容类型发送。默认值为"application/json"。 一般情况包括如下两种内容类型： - "application/json"，发送json数据。 - "multipart/form-data"，上传文件。 说明： 针对机器学习类模型，仅支持"application/json" | | data | 在线服务-非必选 批量服务-必选 | String | 请求体以json schema描述。参数说明请参考[官方指导](https://json-schema.org/understanding-json-schema/reference/array.html)。 | 表5response结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Content-type | 在线服务-非必选 批量服务-必选 | String | data以指定内容类型发送。默认值为"application/json"。 说明： 针对机器学习类模型，仅支持"application/json" | | data | 在线服务-非必选 批量服务-必选 | String | 响应体以json schema描述。参数说明请参考[官方指导](https://json-schema.org/understanding-json-schema/reference/array.html)。 | 表6dependency结构数组说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | installer | 是 | String | 安装方式，当前只支持"pip"。 | | packages | 是 | package结构数组 | 依赖包集合，package结构数组说明如[表7]所示。 | 表7package结构数组说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | package_name | 是 | String | 依赖包名称。不能含有中文及特殊字符\&!'"\<\>=。 | | package_version | 否 | String | 依赖包版本，如果不强依赖于版本号，则该项不填。不能含有中文及特殊字符\&!'"\<\>=。 | | restraint | 否 | String | 版本限制条件，当且仅当"package_version"存在时必填，可选"EXACT/ATLEAST/ATMOST"。 - "EXACT"表示安装给定版本。 - "ATLEAST"表示安装版本不小于给定版本。 - "ATMOST"表示安装包版本不大于给定版本。 说明： - 如果对版本有明确要求，优先使用"EXACT"；如果使用"EXACT"与系统安装包有冲突，可以选择"ATLEAST" - 如果对版本没有明确要求，推荐不填写"restraint"、"package_version"，只保留"package_name"参数 | 表8health数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | check_method | 是 | String | 健康检查方式。可选"HTTP/EXEC"。 - HTTP：HTTP请求检查 - EXEC：执行命令检查。 | | command | 否 | String | 健康检查命令。健康检查方式为EXEC时必选。 | | url | 否 | String | 健康检查接口请求路径。健康检查方式为HTTP时必选。 | | protocol | 否 | String | 健康检查接口请求协议，默认为http。健康检查方式为HTTP时必选。 | | initial_delay_seconds | 否 | String | 健康检查初始化延迟时间。 | | timeout_seconds | 否 | String | 健康检查超时时间。 | | period_seconds | 是 | String | 健康检查周期。填写1到2147483647的整数，单位为秒。 | | failure_threshold | 是 | String | 健康检查最大失败次数。填写1到2147483647的整数。 | #### apis参数代码示例 ``` [{ "url": "/", "method": "post", "request": { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } }, "response": { "Content-type": "application/json", "data": { "type": "object", "properties": { "mnist_result": { "type": "array", "item": [ { "type": "string" } ] } } } } }] ``` #### 目标检测模型配置文件示例 如下代码以TensorFlow引擎为例，您可以根据实际使用的引擎类型修改model_type参数后使用。 - 模型输入 key：images value：图片文件 - 模型输出 ``` { "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] } ``` - 配置文件 ``` { "model_type": "TensorFlow", "model_algorithm": "object_detection", "metrics": { "f1": 0.345294, "accuracy": 0.462963, "precision": 0.338977, "recall": 0.351852 }, "apis": [{ "url": "/", "method": "post", "request": { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } }, "response": { "Content-type": "application/json", "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：图片文件 - 模型输出 ``` { "predicted_label": "flower", "scores": [ ["rose", 0.99], ["begonia", 0.01] ] } ``` - 配置文件 ``` { "model_type": "TensorFlow", "model_algorithm": "image_classification", "metrics": { "f1": 0.345294, "accuracy": 0.462963, "precision": 0.338977, "recall": 0.351852 }, "apis": [{ "url": "/", "method": "post", "request": { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } }, "response": { "Content-type": "application/json", "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" } ] }] } ``` 如下代码以MindSpore引擎为例，您可以根据实际使用的引擎类型修改model_type参数后使用。 - 模型输入 key：images value：图片文件 - 模型输出 ``` "[[-2.404526 -3.0476532 -1.9888215 0.45013925 -1.7018927 0.40332815\n -7.1861157 11.290332 -1.5861531 5.7887416 ]]" ``` - 配置文件 ``` { "model_algorithm": "image_classification", "model_type": "MindSpore", "metrics": { "f1": 0.124555, "recall": 0.171875, "precision": 0.0023493892851938493, "accuracy": 0.00746268656716417 }, "apis": [{ "url": "/", "method": "post", "request": { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } }, "response": { "Content-type": "application/json", "data": { "type": "object", "properties": { "mnist_result": { "type": "array", "item": [{ "type": "string" }] } } } } } ], "dependencies": [] } ``` #### 预测分析模型配置文件示例 如下代码以TensorFlow引擎为例，您可以根据实际使用的引擎类型修改model_type参数后使用。 - 模型输入 ``` { "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" } ] } } ``` - 模型输出 ``` { "data": { "resp_data": [ { "predict_result": "unacc" }, { "predict_result": "unacc" } ] } } ``` - 配置文件 ![](https://support.huaweicloud.com/inference-modelarts/public_sys-resources/note_3.0-zh-cn.png) 代码中request结构和response结构中的data参数是json schema数据结构。data/properties里面的内容对应"模型输入"和"模型输出"。 ``` { "model_type": "TensorFlow", "model_algorithm": "predict_analysis", "metrics": { "f1": 0.345294, "accuracy": 0.462963, "precision": 0.338977, "recall": 0.351852 }, "apis": [ { "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": "application/json", "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" } ] } ] } ``` #### 自定义镜像类型的模型配置文件示例 模型输入和输出与[目标检测模型配置文件示例]类似。 - 模型预测输入为**图片类型** 时，request请求示例如下： 该示例表示模型预测接收一个参数名为images、参数类型为file的预测请求，在推理界面会显示文件上传按钮，以文件形式进行预测。 ``` { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } } ``` - 模型预测输入为**json数据类型** 时，request请求示例如下： 该示例表示模型预测接收json请求体，只有一个参数名为input、参数类型为string的预测请求，在推理界面会显示文本输入框，用于填写预测请求。 ``` { "Content-type": "application/json", "data": { "type": "object", "properties": { "input": { "type": "string" } } } } ``` 完整请求示例如下： ``` { "model_algorithm": "image_classification", "model_type": "Image", "metrics": { "f1": 0.345294, "accuracy": 0.462963, "precision": 0.338977, "recall": 0.351852 }, "apis": [{ "url": "/", "method": "post", "request": { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } }, "response": { "Content-type": "application/json", "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为例。 - 模型输入： ``` { "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 } ] } ``` - 模型输出： ``` { "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": [ { "url": "/", "method": "post", "request": { "Content-type": "application/json", "data": { "type": "object", "properties": { "req_data": { "items": [ { "type": "object", "properties": {} } ], "type": "array" } } } }, "response": { "Content-type": "application/json", "data": { "type": "object", "properties": { "resp_data": { "type": "array", "items": [ { "type": "object", "properties": { "predict_result": {} } } ] } } } } } ] } ``` #### 使用自定义依赖包的模型配置文件示例 如下示例中，定义了1.16.4版本的numpy的依赖环境。 ``` { "model_algorithm": "image_classification", "model_type": "TensorFlow", "runtime": "python3.6", "apis": [ { "url": "/", "method": "post", "request": { "Content-type": "multipart/form-data", "data": { "type": "object", "properties": { "images": { "type": "file" } } } }, "response": { "Content-type": "application/json", "data": { "type": "object", "properties": { "mnist_result": { "type": "array", "item": [ { "type": "string" } ] } } } } } ], "metrics": { "f1": 0.124555, "recall": 0.171875, "precision": 0.00234938928519385, "accuracy": 0.00746268656716417 }, "dependencies": [ { "installer": "pip", "packages": [ { "restraint": "EXACT", "package_version": "1.16.4", "package_name": "numpy" } ] } ] } ```