# 创建AI应用 #### 功能介绍 导入元模型创建AI应用。 执行代码、模型需先上传至OBS（训练作业生成的模型已默认存储到OBS）。 #### 接口约束 使用模板导入模型与不使用模板导入这两类导入方式的Body参数要求不一样。以下Body参数说明中以**模板参数** 表示适合使用模板导入模型时填写的参数，**非模板参数** 表示适合不使用模板导入时填写的参数，**公共参数**表示与导入方式无关的参数。 - 使用模板导入模型时(model_type为Template)，template字段必填，source_location不需要填。 - 不使用模板导入模型时(即model_type不为Template)，source_location必填，template不需要填。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/ModelArts/doc?api=CreateModel)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-modelarts/modelarts_03_0138.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | modelarts:model:create | Write | model \* | - | - | - | | modelarts:model:create | Write | - | - g:RequestTag/\ - g:TagKeys | - | - | #### URI POST /v1/{project_id}/models 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 用户项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-modelarts/modelarts_03_0147.html)。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | 用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | model_docs | 否 | Array of [GuideDoc] objects | 模型说明文档列表，最多三篇。**公共参数** | | template | 否 | [ModelTemplate] object | 模板的相关配置项。使用模板导入模型(即model_type为Template)时必选。**模板参数** | | model_version | 是 | String | 模型版本，格式需为"数值.数值.数值"，其中数值为1-2位正整数, 注意：版本不可以出现例如01.01.01等以0开头的版本号形式。**公共参数** | | source_job_version | 否 | String | 来源训练作业的版本，模型是从训练作业产生的可填写，用于溯源；如模型是从第三方元模型导入，则为空。默认值为空。**非模板参数** | | source_location | 是 | String | 模型所在的OBS路径或SWR镜像地址。 | | source_copy | 否 | String | 镜像复制开关，仅当"model_type"为"Image"时有效。 取值范围： - true：默认值，复制镜像模式，无法极速创建AI应用，SWR源目录中的镜像更改或删除不影响服务部署。 - false：不复制镜像模式，可极速创建AI应用，更改或删除SWR源目录中的镜像会影响服务部署。 | | initial_config | 否 | String | 模型配置文件转成的字符串。建议通过配置文件initial_config来提供"apis"、"dependencies"、"input_params"、"output_params"、"health"、"readiness_health"、"startup_health"等字段的信息。**非模板参数** | | execution_code | 否 | String | 执行代码存放的OBS地址，默认值为空，名称固定为"customize_service.py"。推理代码文件需存放在模型"model"目录。该字段不需要填，系统也能自动识别出model目录下的推理代码。**公共参数** | | source_job_id | 否 | String | 来源训练作业的ID，模型是从训练作业产生的可填写，用于溯源；如模型是从第三方元模型导入，则为空。默认值为空。**非模板参数** | | model_type | 是 | String | 模型类型，取值为TensorFlow/Image/PyTorch/Template/MindSpore，从配置文件读取。**公共参数** | | output_params | 否 | Array of [CreateModelRequestInferParams] objects | 模型的输出参数集，默认为空，params结构如表 params结构所示。从配置文件的apis读取，用户提供"initial_config"字段即可，可不填该字段。**非模板参数** | | description | 否 | String | 模型备注信息，1-100位长度，不能包含\&!'"\<\>=。**公共参数** | | runtime | 否 | String | 模型运行时环境，runtime可选值与model_type相关。 | | model_metrics | 否 | String | 模型精度信息，从配置文件读取，可不填。**非模板参数** | | source_type | 否 | String | 模型来源的类型，当前仅可取值"auto"，用于区分通过自动学习部署过来的模型(不提供模型下载功能)；用户通过训练作业和其他方式部署的模型不设置此值。默认值为空。**非模板参数** | | dependencies | 否 | Array of [ModelDependencies] objects | 推理代码及模型需安装的包，默认为空。从配置文件读取，可不填。**非模板参数** | | workspace_id | 否 | String | 工作空间ID。获取方法请参见[查询工作空间列表](https://support.huaweicloud.com/api-modelarts/ListWorkspace.html)。未创建工作空间时默认值为"0"，存在创建并使用的工作空间，以实际取值为准。 | | model_algorithm | 否 | String | 模型算法，从配置文件读取，可不填。如："predict_analysis"、"object_detection "、"image_classification"。**非模板参数** | | apis | 否 | Array of [CreateModelRequestModelApis] objects | 模型所有的apis入参出参信息，从配置文件中解析出来的，可不填。**非模板参数** | | model_name | 是 | String | 模型名称，支持1-64位可见字符（含中文），名称可以包含字母、中文、数字、中划线、下划线。**公共参数** | | install_type | 否 | Array of strings | 部署类型，只支持小写。可选real-time、edge、batch，默认为\["real-time","edge","batch"\]。 | | input_params | 否 | Array of [CreateModelRequestInferParams] objects | 模型的输入参数集，默认为空，params结构如表 params结构所示。从配置文件的apis读取，用户提供"initial_config"字段即可，可不填该字段。**非模板参数** | | cmd | 否 | String | 镜像启动命令 | | deployment_constraints | 否 | [deployment_constraints] object | 模型部署约束 | 表4GuideDoc | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | doc_url | 是 | String | 文档http(s)链接。 | | doc_name | 是 | String | 文档名称，支持1-48位可见字符（含中文），只能以英文大小写字母或者中文字符开头，名称可以包含字母、中文、数字、中划线、下划线。 | 表5ModelTemplate | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | infer_format | 否 | String | 输入输出模式id，提供时覆盖模板中的内置输入输出模式。 | | template_inputs | 是 | Array of [CreateModelRequestTemplateInput] objects | 模板输入项配置，即配置模型的源路径。 | | template_id | 是 | String | 所使用的模板id，模板中会内置一个输入输出模式。 | 表6CreateModelRequestTemplateInput | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | input | 是 | String | 模板输入路径，可以是obs文件路径，obs目录路径，使用多输入项的模板创建模型时，如果模板定义的目标路径input_properties是一样的，则此处输入的obs目录或者obs文件不能重名，否则会覆盖。 | | input_id | 是 | String | 输入项id，从模板详情中获取。 | 表7ModelDependencies | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | installer | 是 | String | 安装方式，当前只支持pip。 | | packages | 是 | Array of [Packages] objects | 依赖包集合。 | 表8Packages | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | package_version | 否 | String | 依赖包版本。不填时默认安装最新版本。不能含有中文及特殊字符\&!'"\<\>=。 | | package_name | 是 | String | 依赖包名称。请确保包名正确且存在。不能含有中文及特殊字符\&!'"\<\>=。 | | restraint | 否 | String | 版本限制条件，当且仅当package_version存在时必填，取值包含： - EXACT：和指定的版本完全一致。 - ATLEAST：不低于指定的版本。 - ATMOST：不高于指定的版本。 | 表9CreateModelRequestModelApis | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | protocol | 否 | String | 请求协议，可选HTTP和HTTPS。 | | method | 否 | String | 请求方法，可选post、get。 | | input_params | 否 | [ModelInOutputParams] object | apis中的输入输出参数，以JSON Schema格式描述。 | | output_params | 否 | [ModelInOutputParams] object | apis中的输入输出参数，以JSON Schema格式描述。 | | url | 否 | String | 推理请求URL路径 | 表10ModelInOutputParams | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 否 | String | JSON Schema中表示类型的字段，可选object。 | | properties | 否 | Object | JSON Schema中表示对象元素的properties字段，可在其中定义参数，包括参数名及其类型。 | 表11CreateModelRequestInferParams | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | protocol | 是 | String | 请求协议，可选HTTP和HTTPS。 | | min | 否 | Number | 参数的最小值。当param_type为int或float时可选填，默认为空。 | | method | 是 | String | 请求方法，可选"post"、"get"。 | | max | 否 | Number | 参数的最大值。当param_type为int或float时可选填，默认为空。 | | param_desc | 否 | String | 参数描述，建议长度设置不超过100个字符，默认为空。 | | param_name | 是 | String | 参数名，建议长度设置不超过64个字符。 | | url | 是 | String | api代表的url路径。 | | param_type | 是 | String | 参数类型，取值可选int/string/float/timestamp/date/file。 | 表12deployment_constraints | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | request_mode | 否 | String | 模型部署为服务时作业的请求模型 | | cpu_type | 否 | String | cpu类型 | | input_types | 否 | Array of strings | 在异步模式、视频业务场景下使用，表示输入输出类型如OBS,VIS。为自定义镜像导入使用，非自定义进行在runtime声明 | | outputTypes | 否 | Array of strings | 在异步模式、视频业务场景下使用，表示输入输出类型如OBS,DIS。自定义镜像导入使用，非自定义进行在runtime声明 | | service_config | 否 | String | 服务部署字段声明，服务部署时可指定具体的值。自定义镜像导入使用，非自定义进行在runtime声明。由于结构较为复杂，该值为xml格式 | | task_config | 否 | String | 作业相关的配置字段声明，作业创建时可指定具体的值。自定义镜像导入使用，非自定义进行在runtime声明。由于结构较为复杂，该值为xml格式 | | model_security | 否 | [model_security] object | 使用Edge加密模型后，可获取Root Key和modelKey，以及加密后的模型 | 表13model_security | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | model_key | 否 | String | 使用Edge加密模型后，获取模型key | | rootKey | 否 | String | 使用Edge加密模型后，获取模型rootKey | | security_policy | 否 | String | 使用Edge加密模型后，获取模型加密策略 | | is_verify_app | 否 | Boolean | Edge边缘场景，是否校验技能中的文件，包括配置文件、容器镜像、库文件等 | #### 响应参数 **状态码：200** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | model_id | String | 模型id。 | #### 请求示例 创建AI应用。设置AI应用名称为"mnist"，版本为"1.0.0"，类型为"TensorFlow"，模型文件来源于OBS桶。 ``` POST https://{endpoint}/v1/{project_id}/models { "model_name" : "mnist", "model_version" : "1.0.0", "source_location" : "https://models.obs.xxxxx.com/mnist", "source_job_id" : "55", "source_job_version" : "Vnt1", "model_type" : "TensorFlow", "runtime" : "python2.7", "description" : "mnist model", "execution_code" : "https://testmodel.obs.xxxxx.com/customize_service.py", "input_params" : [ { "url" : "/v1/xxx/image", "protocol" : "http", "method" : "post", "param_name" : "image_url", "param_type" : "string", "min" : 0, "max" : 9, "param_desc" : "http://test/test.jpeg" } ], "output_params" : [ { "url" : "/v1/xxx/image", "protocol" : "http", "method" : "post", "param_name" : "face_location", "param_type" : "box", "param_desc" : "face_location param value description" } ], "dependencies" : [ { "installer" : "pip", "packages" : [ { "package_name" : "numpy", "package_version" : "1.5.0", "restraint" : "ATLEAST" } ] } ], "model_algorithm" : "object_detection", "model_metrics" : "{\"f1\":0.52381,\"recall\":0.666667,\"precision\":0.466667,\"accuracy\":0.625}", "apis" : [ { "url" : "/v1/xxx/image", "protocol" : "http", "method" : "post", "input_params" : { "type" : "object", "properties" : { "image_url" : { "type" : "string" } } }, "output_params" : { "type" : "object", "properties" : { "face_location" : { "type" : "box" } } } } ], "initial_config" : "{\"protocol\":\"http\",\"port\":\"8080\",\"health\":{\"check_method\":\"HTTP\",\"protocol\":\"http\",\"url\":\"/health\",\"period_seconds\":\"5\",\"failure_threshold\":\"10\",\"initial_delay_seconds\":\"12\"},\"readiness_health\":{\"check_method\":\"HTTP\",\"protocol\":\"http\",\"url\":\"/readiness_health\",\"period_seconds\":\"5\",\"failure_threshold\":\"20\",\"initial_delay_seconds\":\"12\"},\"startup_health\":{\"check_method\":\"HTTP\",\"protocol\":\"http\",\"url\":\"/startup_health\",\"period_seconds\":\"5\",\"failure_threshold\":\"10\",\"initial_delay_seconds\":\"12\"}}" } ``` #### 响应示例 **状态码：200** 模型创建成功。 ``` { "model_id" : "7feb7235-ed9c-48ae-9833-2876b2458445" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 模型创建成功。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-modelarts/modelarts_03_0095.html)。