文档

Function: set_dump

C Prototype

aclError aclmdlSetDump(const char *dumpCfgPath)

Python Function

ret = acl.mdl.set_dump(dump_cfg_path)

Function Usage

Sets dump configuration.

Input Description

dump_cfg_path: string, path of the configuration file, including the file name.

Currently, the following dump information can be configured:

  • Model dump configuration (used to export the input and output data of operators at each layer in the model) and single-operator dump configuration (used to export the input and output data of an operator). The exported data is used to compare with that of a specified model or operator to locate accuracy issues. For details about the configuration example, description, and restrictions, see Configuration File Example (for Model Dump and Single-Operator Dump). Dump configurations are disabled by default.
  • Dump configuration of the exception operator (used to export the input and output data, workspace information, and tiling information of the exception operator). The exported data is used to analyze AI Core errors. For details about the configuration example, see Configuration File Example (Exception Operator Dump Configuration). Dump configurations are disabled by default.
  • Overflow/Underflow operator dump configuration (used to export the input and output data of the overflow/underflow operator in the model). The exported data is used to analyze overflow/underflow causes and locate model accuracy issues. For details about the configuration example, description, and restrictions, see Example Configuration (Overflow/Underflow Operator Dump). Dump configurations are disabled by default.

Return Value

ret: int, error code.

Restrictions
  • The configured dump data is valid only when the model is loaded after this API call. The dump configuration does not take effect on models loaded before this API call unless you reload the models after this API call.

    For example, in the following API call sequence, the dump configuration is valid only for model 2:

    acl.mdl.init_dump --> model 1 loading --> acl.mdl.set_dump --> model 2 loading --> acl.mdl.finalize_dump

  • If this API is called repeatedly to set dump configuration for the same model, the most recent configuration is applied.

    For example, in the following API call sequence, the second dump configuration call overwrites the first call:

    acl.mdl.init_dump --> acl.mdl.set_dump --> acl.mdl.set_dump --> model 1 loading --> acl.mdl.finalize_dump

API

pyACL also provides the acl.init API. During pyACL initialization, the dump configuration is passed as a JSON configuration file to dump the app data at run time. In this mode, the acl.init API can be invoked only once in a process. To modify the dump configuration, you need to modify the configuration in the JSON file.

Configuration File Example (for Model Dump and Single-Operator Dump)

Model dump configuration example:

{                                                                                            
	"dump":{
		"dump_list":[                                                                        
			{	"model_name":"ResNet-101"
			},
			{                                                                                
				"model_name":"ResNet-50",
				"layer":[
				      "conv1conv1_relu",
				      "res2a_branch2ares2a_branch2a_relu",
				      "res2a_branch1",
				      "pool1"
				] 
			}  
		],  
		"dump_path":"$HOME/output",
                "dump_mode":"output",
		"dump_op_switch":"off",
                "dump_data":"tensor"
	}                                                                                        
}

Single-operator dump configuration:

{
    "dump":{
        "dump_path":"output",
        "dump_list":[], 
	"dump_op_switch":"on",
        "dump_data":"tensor"
    }
}
Table 1 Format of the acl.json file

Parameter

Description

Note

dump

-
  • For TBE and AI CPU operators that do not output results, (for example, StreamActive, Send, Recv, and const), dump data is not generated. For operators that are not executed on AI CPU or AI Core (for example, concatD) after build, dump data cannot be generated.
  • If only certain operators are to be dumped, since the Data operators are not executed on AI CPU or AI Core, you need to select all the downstream operators of the Data operator.

dump_list

(Required) List of network-wide models for data dump.

Create model dump configuration information. If multiple models need to be dumped, separate them with commas (,).

In the single-operator execution scenario, dump_list is empty.

-

model_name

Model name.

  • To load a model from a file, enter the model file name without the name extension. You can also set this parameter to the value of the outermost name field in the .json file after ATC-based model conversion.
  • To load a model from memory, set this parameter to the value of the name field in the .json file after ATC-based model conversion.
  • Ensure that each model_name is unique.
  • A model can be loaded from the memory or a file. Assume that a model is loaded from a file and this parameter is set to the value of the outermost name field in the .json file after ATC-based model conversion. If the model_name configuration item in the acl.json file contains two values: model file name and the value of name obtained here, the model file name takes effect.

layer

Operator name. The value can be the name of the operator after ATC model conversion or the name of the original operator before conversion.

  • To dump certain operators, configure each operator in a line in the layer field and separate them with commas (,). If the input of the specified operator involves the data operator, the data operator information is also dumped.
  • To dump all operators of a model, the layer field does not need to be included.

If you do not set model_name, the operators of all models are dumped by default. If model_name is set, the corresponding operators of the model are dumped.

It is advised to dump certain operators only. Otherwise, excessive data may induce timeouts if the I/O performance is poor.

dump_path

(Required) Dump path in the operating environment.

The path can be either absolute or relative.
  • An absolute path starts with a slash (/), for example, $HOME/output.
  • A relative path starts with a directory name, for example, output.

The directory specified by this parameter must be created in advance and the user configured during installation must have the read and write permissions on the directory.

dump_mode

Dump mode.

  • input: dumps operator inputs.
  • output (default): dumps operator outputs.
  • all: dumps both operator inputs and outputs.

-

dump_op_switch

Dump switch of a single-operator model.

  • on: enables dump for the single-operator model.
  • off (default): disables dump for the single-operator model.

-

dump_step

Iterations to dump. This parameter is not required in the inference scenario.

If this parameter is not configured, dump data will be generated for all iterations by default, which may result in a large amount of data. You are advised to specify iterations as required.

Separate multiple iterations using vertical bars (|), for example, 0|5|10. You can also use hyphens (-) to specify the iteration range, for example, 0|3-5|10.

Configuration example:

{                                                                                            
	"dump":{
		"dump_list":[                                                                        
			...... 
		],  
		"dump_path":"$HOME/output",
                "dump_mode":"output",
		"dump_op_switch":"off"
                "dump_step": "0|3-5|10"
	}                                                                                        
}

-

dump_data

Type of operator content to dump.

  • tensor (default): dumps operator data.
  • stats: dumps operator statistics. The result file is in .csv format and contains the operator name, input/output data type, maximum value, and minimum value.

Dumping a large amount of data typically requires a significant amount of time. One solution is to first dump operator statistics, use the statistics to identify potentially abnormal operators, and then proceed to dump the data of the identified operators.

In the model dump scenario, the information of operator input or output or both can be collected based on the configuration of dump_mode.

-

Configuration File Example (Exception Operator Dump Configuration)

Set dump_scene to lite_exception to enable the dump function of the exception operator. In addition, you can use the ASCEND_WORK_PATH environment variable to configure the dump path. Otherwise, the data is dumped to the current execution directory of the app.

The following gives a configuration example:

{
   "dump":{
           "dump_scene":"lite_exception"
    }
}

The dump configuration of the abnormal operator cannot be enabled together with the model dump configuration or single-operator dump configuration. Otherwise, the model dump or single-operator dump does not take effect.

Example Configuration (Overflow/Underflow Operator Dump)

Restrictions:
  • If dump_debug is set to on, overflow/underflow operator configuration is enabled. If dump_debug is not set or is set to off, this function is disabled.
  • If this function is enabled, dump_path must be set, indicating the directory for storing exported data files.
    The path can be either absolute or relative.
    • An absolute path starts with a slash (/), for example, /home.
    • A relative path starts with a directory name, for example, output.

    For details about how to parse the exported data file, see Overflow/Underflow Operator Data Collection and Analysis.

  • This function cannot be enabled when model or single-operator dump configuration is enabled. Otherwise, an error is returned.
The following gives a configuration example. 
{
    "dump":{
        "dump_path":"output",
        "dump_debug":"on"
    }
}