更新时间:2022-04-25 GMT+08:00
分享

提交特征工程作业

功能介绍

该接口用于特征工程处理,包含数据预处理,特征提取和排序训练样本生成等。

URI

POST /v1/{project_id}/etl-job

参数说明请参见表1

表1 URI参数说明

名称

是否必选

类型

说明

project_id

String

项目编号,用于资源隔离。获取方法请参见获取项目ID

请求消息

请求参请参见表2

表2 请求参数说明

参数名称

是否必选

参数类型

说明

workspace_id

String

工作空间ID,默认为0

job_name

String

训练作业名称,最大长度为20字符。

job_description

String

训练作业描述,最大长度为256字符。

algorithm_type

String

算法类型

  • INITIAL_PROFILES_GENERATION
  • BUILD_RANK_UNIFORM_DATA_FROM_JSON

algorithm_parameters

JSON

算法参数,每一种算法都有其特定的参数。

  • INITIAL_PROFILES_GENERATION,请参见表8
  • BUILD_RANK_UNIFORM_DATA_FROM_JSON,请参见表9

data_source

List

算法数据源配置

  • INITIAL_PROFILES_GENERATION,数据源选择通用模板数据,
  • BUILD_RANK_UNIFORM_DATA_FROM_JSON,数据源选择通用格式。

storage

JSON

请参见表6,存储平台。

offline_platform

JSON

请参见表3,离线计算平台信息。

表3 offline_platform参数说明

参数名称

是否必选

参数类型

说明

platform

String

平台名称,最大长度64,支持DLI。

platform_parameter

JSON

请参见表4,平台参数。

computing_resource

String

指定DLI运行任务的资源规格。

config_load_path

String

读取配置源路径。

表4 platform_parameter参数说明

参数名称

是否必选

参数类型

说明

cluster_name

String

集群名称。

cluster_id

String

集群ID。

表5 data_source参数说明

参数名称

是否必选

参数类型

描述信息

table_type_id

String

推荐通用数据模板

  • 用户属性表USER_META
  • 物品属性表ITEM_META
  • 用户操作行为表USER_BEHAVIOR

数据格式请参见推荐系统离线数据源

通用格式

  • GENERAL_FORMAT

data_source_url

String

数据源路径,最大长度1000字符。

data_format

String

输入数据格式,可选值:csv、parquet、json、orc。

data_param

JSON

请参见表7,数据格式是csv的时候必选,其他可选。

start_time

String

文件开始时间,数据格式是json的时候必选,其他可选。

end_time

String

文件结束时间,数据格式是json的时候必选,其他可选。

表6 storage参数说明

参数名称

是否必选

参数类型

说明

user_profiles_table

JSON

用户属性存储表.请参见表8

algorithm_type为INITIAL_PROFILES_GENERATION时必选。

item_profiles_table

JSON

物品属性存储表请参见表8

algorithm_type为INITIAL_PROFILES_GENERATION时必选。

表7 data_param参数说明

参数名称

是否必选

参数类型

说明

header

Boolean

是否显示表头。

delimiter

String

分割符,最大长度10个字符。

quote

String

引用字符,最大长度10个字符。

escape

String

转义字符,最大长度10个字符。

表8 algorithm_parameters参数说明-INITIAL_PROFILES_GENERATION算子

参数名称

是否必选

参数类型

说明

输出路径(result_path)

String

所有输出数据(用户物品特征、特征映射、域特征值数目统计结果、训练集、测试集)的存储都路径,文件夹。

全局特征配置文件路径(global_features_information_path)

String

该文件为JSON格式,包含特征名、特征大类、特征值类型。全局特征文件详细内容可以通过查询全局特征配置获取。

高级设置(writer_parameters)

JSON

请参见表10

表9 algorithm_parameters参数说明-BUILD_RANK_UNIFORM_DATA_FROM_JSON算子

参数名称

是否必选

参数类型

说明

输出路径(result_path)

String

所有输出数据(用户物品特征、特征映射、域特征值数目统计结果、训练集、测试集)的存储都路径,文件夹。

全局特征配置文件路径(global_features_information_path)

String

该文件为JSON格式,包含特征名、特征大类、特征值类型。全局特征文件详细内容可以通过查询全局特征配置获取。

算子类型(rank_etl_type)

Enum

排序数据处理算子类型。

每一种排序算法都需要进行特定的数据处理,需要根据使用的排序算法来选择排序数据处理类型。

LR、FM、FFM、DEEPFM和Pin这五种算法的数据处理互相通用。

策略参数(rank_etl_parameters)

JSON

请参见表11,每一种排序算法的数据预处理参数。

表10 writer_parameters高级设置参数说明

参数名称

是否必选

参数类型

说明

save_mode

String

对结果保存路径中已有宽表数据的保留方式:

  • new(否,不保留任何已有的数据)
  • append(是,保留全部已有的数据)
  • overwrite(覆盖,将相同日期下的数据覆盖掉,保留不同日期下的数据)
表11 rank_etl_parameters参数说明-LR、FM、FFM、DEEPFM、PIN排序预处理算子共用

参数名称

是否必选

参数类型

描述信息

训练集测试集划分方式

(divide_by_time_or_rate)

String

按时间或比例划分训练集测试集。

可选值为TIME或RATE。

训练数据起始时间

(training_data_start_time)

Long

训练数据起始时间。

divide_by_time_or_rate为TIME时必填。取值不大于行为数据中的最大时间且不大于training_data_end_time。如:1541987933

训练数据终止时间

(training_data_end_time)

Long

训练数据终止时间。

divide_by_time_or_rate为TIME时必填。取值不大于行为数据中的最大时间且不小于training_data_start_time。如:1541987933

测试数据起始时间

(test_data_start_time)

Long

测试数据起始时间。

divide_by_time_or_rate为TIME时必填。取值不大于行为数据中的最大时间且不大于test_data_end_time。如:1541987933

测试数据终止时间

(test_data_end_time)

Long

测试数据终止时间。

divide_by_time_or_rate为TIME时必填。取值不大于行为数据中的最大时间且不小于test_data_start_time。如:1541987933

训练数据占比

(training_data_rate)

Double

训练数据在输入数据中的占比。divide_by_time_or_rate为RATE时必填。取值范围[0,1]。

测试数据占比

(test_data_rate)

Double

测试数据在输入数据中的占比。divide_by_time_or_rate为RATE时必填。取值范围[0,1]。

待提取用户特征

(user_features)

JSONArray

从全局特征文件提取输入的用户特征,对不同类型的特征进行相应的处理,处理后的数据用于排序模型训练。

特征必须来自用户属性配置表中定义的特征。

[{

"feature_name": "age",

"feature_type": "numerical",

"feature_type":"BASIC_INFO",

"feature_process_parameters": {

"discrete_method": "equal_distance_discrete",

"lower_limit": 0.0,

"upper_limit": 120.0,

"distance": 20

}

},

{

"feature_name": "user_tag",

"feature_type": "map",

"feature_type":"TAGS",

"feature_process_parameters": {

"value_preserve_number": 4

}

}]

待提取物品特征

(item_features)

JSONArray

从全局特征文件中提取输入的物品特征,对不同类型的特征进行相应的处理,处理后的数据用于排序模型训练。特征必须来自物品属性配置表中定义的特征。

[{

"feature_name": "product_name",

"feature_type": "string",

"feature_type":"BASIC_INFO",

"feature_process_parameters": {

}

},

{

"feature_name": "categories",

"feature_type": "strArray",

"feature_type":"BASIC_INFO",

"feature_process_parameters": {

"value_preserve_number": 3

}

}]

正反馈行为类型

(positive_behaviors)

List[String]

正反馈行为类型的样本将被转换为排序数据中的正样本。取值必须来自行为表中”actionType”字段的值。示例:

[click,collect,purchase,share]

负反馈行为类型

(negative_behaviors)

List[String]

负反馈行为类型的样本将被转换为排序数据中的负样本。取值必须来自行为表中”actionType”字段的值。示例:[view,dislike]

表12 特征信息及其处理方式

参数名称

是否必选

参数类型

说明

特征名称

(feature_name)

String

该特征的名称。

特征类型

(feature_type)

String

用户特征类型 :

  • BASIC_INFO,基础信息类
  • TAGS,标签类
  • CONTEXT,上下文类

物品特征类型

  • BASIC_INFO,基础信息类
  • TAGS标签类

特征值类型

(feature_value _type)

String

该特征值的类型,支持4种不同类型的特征值,分别为:

  • 单值枚举型(string):字符串型,每一个值都被当做是字符串来进行处理,大部分的特征值都属于这种类型;
  • 单值数值型(numerical):每一个值都是一个数值,一般需要对这种类型的特征值进行离散化处理以降低特征维度;
  • 多值枚举型(strArray):字符串数组型,每一个特征值都是一个不定长的字符串数组,例如商品的类别特征、用户的兴趣爱好等。排序预处理算子会将所有特征值规范到统一长度以便后续处理;
  • KV数值型(map):Map[String,Double]型,每一个特征值都是一个不定长的key-value对,例如用户画像、物品画像等特征。排序预处理算子会将所有特征值规范到统一长度以便后续处理。

特征处理参数

(feature_process_parameters)

JSON

每一种类型的特征都有其对应的处理方式,需要用户提供相应处理所需要的参数。示例:

{

"discrete_method":"equal_distance_discrete",

"lower_limit":0.0,

"upper_limit":120.0,

"distance":20

}

表13 离散方法及其对应的参数

参数名称

是否必选

参数类型

说明

离散方法(discrete_method)

等距离散

(equal_distance_discrete)

最小值

(lower_limit)

Double

如果特征值小于该值,则会被视为异常值进行处理。

用户可根据业务经验来确定该值,如果用户未提供该值,则会统计出数据中该特征的最小值作为输入。取值为

[Double.Minvalue, Double.MaxValue),

且必须小于参数“最大值”。

最大值

(upper_limit)

Double

如果特征值大于该值,则会被视为异常值进行处理。

用户可根据业务经验来确定该值,如果用户未提供该值,则会统计出数据中该特征的最大值作为输入。取值为

(Double.Minvalue, Double.Maxvalue],

且必须大于参数“最小值”。

距离

(distance)

Double

以该距离为间隔将特征区间划分为若干个片段,每一个片段对应一个离散值。取值为(0, Double.Maxvalue)。

等频离散

(equal_frequency_discrete)

最小值

(lower_limit)

Double

如果特征值小于该值,则会被视为异常值进行处理。

用户可根据业务经验来确定该值,如果用户未提供该值,则会统计出数据中该特征的最小值作为输入。取值为

[Double.Minvalue, Double.Maxvalue)

,且必须小于参数“最大值”。

最大值

(upper_limit)

Double

如果特征值大于该值,则会被视为异常值进行处理。

用户可根据业务经验来确定该值,如果用户未提供该值,则会统计出数据中该特征的最大值作为输入。取值为

(Double.Minvalue, Double.Maxvalue],

且必须大于参数“最小值”。

频率

(frequency)

Int

将特征值从小到大排列,每“频率”个值被划分为一个片段,每一个片段对应一个离散值。取值为(0, Int.Maxvalue)。

用户自定义离散

(user_define_discrete)

自定义区间列表

(period_list)

JSONArray

每一个区间的最小值、最大值、离散值都由用户来定义。

如果特征值位于某个区间的最小值最大值之间,则该特征值被离散为这个区间的离散值。

如果特征值不在用户定义的任何一个区间内,则被作为异常值进行处理。每一个区间都是半闭半开区间,即包含最小值但不包含最大值,不同区间之间不能重叠。示例:

[

{

"period_name": "young",

"lower_limit": 0.0,

"upper_limit": 18.0

} ,{

"period_name": "mid",

"lower_limit": 18.0,

"upper_limit": 60.0

} ,{

"period_name": "old",

"lower_limit": 60.0,

"upper_limit": 120.0

}

]

表14 用户自定义离散方法参数列表

参数名称

是否必选

参数类型

说明

最小值

(lower_limit)

Double

该区间的最小值。取值范围

[Double.Minvalue, Double.Maxvalue),

且必须小于参数“最大值”。

最大值

(upper_limit)

Double

该区间的最大值。取值范围

(Double.Minvalue, Double.Maxvalue],

且必须大于参数“最小值”。

区间名称

(period_name)

String

该区间对应的名称。

表15 多值枚举型特征处理参数列表

参数名称

是否必选

参数类型

说明

值保留个数

(value_preserve_number)

Int

多值枚举型特征的特征值保留个数,如果实际的值数目大于该值,

则多余的值会被删除;如果实际的值数目小于该值,

则保留所有值;如果用户未提供该参数,则会统计出

数据中该多值特征的最大取值数目作为输入。取值范围[1, 100]。

表16 KV数值型特征处理参数列表

参数名称

是否必选

参数类型

说明

值保留个数

(value_preserve_number)

Int

KV数值型特征的特征值保留个数,如果实际的值数目大于该值,

则多余的值会被删除;如果实际的值数目小于该值,

则保留所有值;如果用户未提供该参数,则会统计出

数据中该KV数值型特征的最大取值数目作为输入。取值范围[1, 100]。

响应消息

响应参数请参见表17

表17 响应参数说明

参数名称

参数类型

说明

job_name

String

作业名称。

job_id

String

作业的ID。

is_success

Boolean

请求是否成功。

error_message

String

请求失败时的错误信息,请求成功时无此字段。

error_code

String

请求失败时的错误码,请求成功时无此字段。

create_time

Long

作业的创建时间。

etl_uuid

String

候选集ID。

示例

  • 请求示例
    {
      "job_name": "ETL-rank_test1",
      "job_description": "hhx test",
      "algorithm_type": "BUILD_RANK_UNIFORM_DATA_FROM_JSON",
      "data_source": [
        {
          "table_type_id": "GENERAL_FORMAT",
          "data_format": "json",
          "data_source_url": "<数据源存储路径>",
    
          "start_time": ""
        }
      ],
      "algorithm_parameters": {
        "result_path": "<所有输出数据存储路径>",
        "global_features_information_path": "<全局特征配置文件路径>",
        "rank_etl_type": "LR",			
        "rank_etl_parameters": {
          "divide_by_time_or_rate": "RATE",
          "training_data_start_time": "1552117770165",
          "training_data_end_time": "1517414400000",
          "test_data_start_time": "1517414400000",
          "test_data_end_time": "1519217998000",
          "training_data_rate": "0.8",
          "test_data_rate": "0.2",
          "user_features": [
            {
              "feature_name": "provinceId",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "no_discrete"
              }
            },
            {
              "feature_name": "cityId",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "equal_distance_discrete",
                "lower_limit": 0,
                "upper_limit": 10000,
                "distance": 1000
              }
            },
            {
              "feature_name": "districtId",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "no_discrete"
              }
            },
            {
              "feature_name": "payment_type",
              "feature_type": "CONTEXT",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "no_discrete"
              }
            },
            {
              "feature_name": "payment_method",
              "feature_type": "CONTEXT",
              "feature_value_type": "string",
              "feature_process_parameters": {}
            },
            {
              "feature_name": "payment_channel",
              "feature_type": "CONTEXT",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "no_discrete"
              }
            },
            {
              "feature_name": "salary",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "user_define_discrete",
                "period_list": [
                  {
                    "period_name": "low",
                    "lower_limit": 0,
                    "upper_limit": 5000
                  },
                  {
                    "period_name": "mid",
                    "lower_limit": 5000,
                    "upper_limit": 30000
                  },
                  {
                    "period_name": "high",
                    "lower_limit": 30000,
                    "upper_limit": 100000
                  }
                ]
              }
            },
            {
              "feature_name": "user_tags",
              "feature_type": "TAGS",
              "feature_value_type": "map",
              "feature_process_parameters": {
                "process_method": "map_format",
                "value_preserve_number": 4
              }
            },
            {
              "feature_name": "hobbies",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "strArray",
              "feature_process_parameters": {
                "process_method": "string_array_format",
                "value_preserve_number": 3
              }
            }
          ],
          "item_features": [
            {
              "feature_name": "product_name",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "string",
              "feature_process_parameters": {}
            },
            {
              "feature_name": "order_price",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "numerical",
              "feature_process_parameters": {
                "discrete_method": "equal_frequency_discrete",
                "frequency": 10
              }
            },
            {
              "feature_name": "weight",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "string",
              "feature_process_parameters": {}
            },
            {
              "feature_name": "volume",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "string",
              "feature_process_parameters": {}
            },
            {
              "feature_name": "categories",
              "feature_type": "BASIC_INFO",
              "feature_value_type": "strArray",
              "feature_process_parameters": {
                "process_method": "string_array_format",
                "value_preserve_number": 3
              }
            },
            {
              "feature_name": "item_tags",
              "feature_type": "TAGS",
              "feature_value_type": "map",
              "feature_process_parameters": {
                "process_method": "map_format",
                "value_preserve_number": 3
              }
            }
          ],
          "positive_behaviors": [
            "consume"
          ],
          "negative_behaviors": [
            "uncollect",
            "dislike"
          ]
        }
      },
      "offline_platform": {
        "platform": "DLI",
        "platform_parameter": {
          "cluster_name": "res_two"
        },
        "config_load_path": "<配置源路径>"
      },
      "storage": {}
    }
  • 成功响应示例
    {
        "is_success": true,
        "job_id": "d832b07540594ea980c140fea5a10849",
        "job_name": "gggggggggggggggggg",
        "create_time": "1543891781990",
        "etl_uuid": "a53a685c52f4476f833d256620b6fc80"
    }
  • 失败响应示例
    {
    "is_success": false,
    "error_code": "res.2006",
    "error_msg": "The datasourceUrl(<数据源路径>) is not match Bucket structure."
    }

状态码

状态码请参见状态码

分享:

    相关文档

    相关产品

close