modelarts-umn/api-ref/source/model_management/importing_a_model.rst

original_name

modelarts_03_0076.html

Importing a Model

Function

You can use the API to import a model.

Ensure that the execution code and model have been uploaded to OBS. By default, the models generated by a training job are stored in OBS.

URI

POST /v1/{project_id}/models

Table 1 <modelarts_03_0076__en-us_topic_0130147365_table16518993181628> describes the required parameters.

Table 1 Parameters

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID <modelarts_03_0147>.

Request Body

Table 2 <modelarts_03_0076__en-us_topic_0130147365_table24514577587> describes the request parameters.

Table 2 Parameters

Parameter	Mandatory	Type	Description
model_name	Yes	String	Model name. Enter 1 to 64 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed.
model_version	Yes	String	Model version in the format of Digit.Digit.Digit. The value range of the digits is [1, 99]. Note that no part of the version number can start with 0. For example, 01.01.01 is not allowed.
source_location	Yes	String	OBS path where the model is located or the SWR image location
source_job_id	No	String	ID of the source training job. If the model is generated from a training job, input this parameter for source tracing. If the model is imported from a third-party meta model, leave this parameter blank. By default, this parameter is left blank.
source_job_version	No	String	Version of the source training job. If the model is generated from a training job, input this parameter for source tracing. If the model is imported from a third-party meta model, leave this parameter blank. By default, this parameter is left blank.
source_type	No	String	Model source type. The value can only be auto, which indicates ExeML models (model download is not supported). If a model is deployed through a training job, this parameter is left blank by default.
model_type	Yes	String	Model type. The value can be TensorFlow, MXNet, Caffe, Spark_MLlib, Scikit_Learn, XGBoost, Image, PyTorch, or Template, which is read from the configuration file.
runtime	No	String	For details about runtime options, see Model Management > Importing a Model > Importing a Meta Model from OBS in ModelArts User Guide.
description	No	String	Model remarks. The value contains a maximum of 100 characters and cannot contain the following special characters and more: &!'\"<>=
model_algorithm	No	String	Model algorithm. If the algorithm is read from the configuration file, this parameter can be left blank. For example, the value can be predict_analysis, object_detection, or image_classification. The value must start with a letter and contain no more than 36 characters. Chinese characters and special characters (&!'\"<>=) are not allowed.
execution_code	No	String	OBS path for storing the execution code. By default, this parameter is left blank. The name of the execution code file is fixed to customize_service.py. The inference code file must be stored in the model directory. If this parameter is left blank, the system can automatically identify the inference code in the model directory.
input_params	No	params array	Collection of input parameters of a model. By default, this parameter is left blank. For details, see Table 3 <modelarts_03_0076__en-us_topic_0130147365_table01082501075>. If the collection of input parameters is read from apis in the configuration file, you only need to provide the initial_config field and do not need to set input_params. input_params is optional when the initial_config field exists.
output_params	No	params array	Collection of output parameters of a model. By default, this parameter is left blank. For details, see Table 3 <modelarts_03_0076__en-us_topic_0130147365_table01082501075>. If the collection of output parameters is read from apis in the configuration file, you only need to provide the initial_config field and do not need to set output_params.
dependencies	No	dependency array	Package required for inference code and model. By default, this parameter is left blank. If the package is read from the configuration file, this parameter can be left blank. Table 4 <modelarts_03_0076__en-us_topic_0130147365_table649013511785> shows the dependency structure.
model_metrics	No	String	Model precision, which is read from the configuration file
apis	No	apis array	All apis input and output parameters of the model. If the parameters are read from the configuration file, this parameter can be left blank. For details, see Table 10 <modelarts_03_0076__en-us_topic_0130147365_table53974919117>.
initial_config	No	String	Character string converted from the final model configuration file. It is recommended that the initial_config file be used to provide information about the fields such as apis, dependencies, input_params, and output_params.
workspace_id	No	String	ID of the workspace to which a service belongs. The default value is 0, indicating the default workspace.
model_docs	No	doc array	List of model description documents. A maximum of three documents are supported. For details, see Table 7 <modelarts_03_0076__en-us_topic_0130147365_table9739172671118>.
install_type	No	String array	Deployment type. Only lowercase letters are supported. The value can be real-time, or batch. Default value: [real-time, batch]
template	No	Template object	Template configuration items. This parameter is mandatory when model_type is set to Template. For details, see Table 8 <modelarts_03_0076__en-us_topic_0130147365_table89901124131016>.

Table 3 params parameters

Parameter	Mandatory	Type	Description
url	Yes	String	API URL
method	Yes	String	Request method. Possible values are post and get.
protocol	Yes	String	Request protocol
param_name	Yes	String	Parameter name. It is recommended that the parameter name contain a maximum of 64 characters.
param_type	Yes	String	Parameter type. The value can be int, string, float, timestamp, date, or file.
min	No	Number	This parameter is optional when param_type is set to int or float. By default, this parameter is left blank.
max	No	Number	This parameter is optional when param_type is set to int or float. By default, this parameter is left blank.
param_desc	No	String	Parameter description. It is recommended that the parameter description contain a maximum of 100 characters. By default, this parameter is left blank.

Table 4 dependency parameters

Parameter	Mandatory	Type	Description
installer	Yes	String	Installation mode. Only pip is supported.
packages	Yes	package array	Collection of dependency packages. For details, see Table 5 <modelarts_03_0076__en-us_topic_0130147365_table137621937181116>.

Table 5 package parameters

Parameter	Mandatory	Type	Description
package_name	Yes	String	Name of a dependency package. Ensure that the package name is correct and exists. Chinese characters and special characters (&!'"<>=) are not allowed.
package_version	No	String	Version of a dependency package. If this parameter is left blank, the latest version is installed by default. Chinese characters and special characters (&!'"<>=) are not allowed.
restraint	No	String	Version restriction. The value can be EXACT, ATLEAST, or ATMOST. This parameter is mandatory only when package_version exists.

Table 6 metric parameters

Parameter	Mandatory	Type	Description
f1	No	Double	F1 score
recall	No	Double	Recall
precision	No	Double	Precision
accuracy	No	Double	Accuracy

Table 7 doc parameters

Parameter	Mandatory	Type	Description
doc_name	Yes	String	Document name, which must start with a letter. Enter 1 to 48 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed.
doc_url	Yes	String	HTTP(S) link of the document

Table 8 Template parameters

Parameter	Mandatory	Type	Description
infer_format	No	String	Input and output mode. When this parameter is used, the input and output mode built in the template does not take effect.
template_id	Yes	String	ID of the used template. The template has a built-in input and output mode.
template_inputs	Yes	Array of TemplateInputs objects	Template input configuration, specifying the source path for configuring a model. For details, see Table 9 <modelarts_03_0076__en-us_topic_0130147365_table12364181131310>.

Table 9 template_inputs parameters

Parameter	Mandatory	Type	Description
input	Yes	String	Template input path, which can be an OBS file path or OBS directory path. When you use a template with multiple input items to create a model, if the target paths input_properties specified in the template are the same, the OBS directory or OBS file name entered here must be unique to prevent files from being overwritten.
input_id	Yes	String	Input item ID, which is obtained from the template details.

Table 10 apis parameters

Parameter	Mandatory	Type	Description
input_params	No	Object	Input parameters in apis, described in JSON Schema format. For details, see Table 11 <modelarts_03_0076__en-us_topic_0130147365_table116145629>.
method	No	String	Request method. The options are POST and GET.
output_params	No	Object	Output parameters in apis, described in JSON Schema format. For details, see Table 12 <modelarts_03_0076__en-us_topic_0130147365_table890117461320>.
protocol	No	String	Request protocol.
url	No	String	Inference request URL.

Table 11 InputParams parameters

Parameter	Mandatory	Type	Description
properties	No	Map<String,Object>	Properties of an object element in JSON Schema. You can set parameters, including the parameter name and type, in properties.
type	No	String	Type in JSON Schema, which can be object.

Table 12 OutputParams parameters

Parameter	Mandatory	Type	Description
properties	No	Map<String,Object>	Properties of an object element in JSON Schema. You can set parameters, including the parameter name and type, in properties.
type	No	String	Type in JSON Schema, which can be object.

Response Body

Table 13 <modelarts_03_0076__en-us_topic_0130147365_table88391251102419> describes the response parameters.

Table 13 Parameters

Parameter	Type	Description
model_id	String	Model ID

Samples

The following shows how to import a model whose name is mnist, version is 1.0.0, and type is TensorFlow. The model file comes from an OBS bucket.

• Sample request

  POST    https://endpoint/v1/{project_id}/models
  {
  "model_name": "mnist",
  "model_version": "1.0.0",
  "source_location": "https://models.obs.xxxx.com/mnist",
  "source_job_id": "55",
  "source_job_version": "V100",
  "model_type": "TensorFlow",
  "runtime": "python2.7",
  "description": "mnist model",
  "execution_code": "https://testmodel.obs.xxxx.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"
        }
      }
    }
  }
  ]
  }

• Sample response

  {
    "model_id": "10eb0091-887f-4839-9929-cbc884f1e20e"
  }

Status Code

For details about the status code, see Table 1 <modelarts_03_0094__en-us_topic_0132773864_table1450010510213>.

Error Codes

See Error Codes <modelarts_03_0095>.