新建在线服务_推荐系统 RES_API参考_API_在线服务_华为云

(1)

API 参考

文档版本 02

发布日期 2021-11-17

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

华为技术有限公司

地址：深圳市龙岗区坂田华为总部办公楼邮编：518129

网址：

https://www.huawei.com

客户服务邮箱：

[email protected]

客户服务电话：4008302118

(3)

1 ^{使用前必读}

1.1 概述

欢迎使用推荐系统（Recommender System，简称RES）。基于华为大数据和人工智能技术，提供推荐平台和算法服务，并帮助企业构建个性化推荐应用，助力提升网站/APP的点击率、留存率和用户体验。

您可以使用本文档提供推荐系统服务API的描述、语法、参数说明及样例等内容，进行相关操作，例如推荐系统的具体接口使用说明。支持的全部操作请参见API概览。

在调用推荐系统API之前，请确保已经充分了解推荐系统相关概念，详细信息请参见产

品介绍。

1.2 调用说明

推荐系统提供了REST（Representational State Transfer）风格API，支持您通过 HTTPS请求调用，调用方法请参见如何调用API。

1.3 终端节点

终端节点即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和

终端节点中查询所有服务的终端节点。

推荐系统的终端节点如表1-1所示，请您根据业务需要选择对应区域的终端节点。

表1-1 推荐系统的终端节点

区域名称区域终端节点（Endpoint）

华北-北京四 cn-north-4 res.cn-north-4.myhuaweicloud.com

(8)

1.4 约束与限制

● 您能创建的在线服务的数量与配额有关系，具体请参见关于配额。

● 更详细的限制请参见具体API的说明。

1.5 基本概念

● 账号

用户注册华为云时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。

● 用户

由账号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。

在我的凭证下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。

● 区域（Region）

从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属 Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。

详情请参见区域和可用区。

● 可用区（AZ，Availability Zone）

一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。

● 项目

华为云的区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。

(9)

图1-1 项目隔离模型

同样在我的凭证下，您可以查看项目ID。

● 企业项目

企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。

关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理服务用户

指南》。

1.6 API 版本选择建议

当前RES服务对外API开放存在2种：

1. RES新版本的API接口，推荐使用。

2. RES旧版本的API接口，现仅为存量用户提供，即将下线。

(10)

2 ^{API 概览}

类型 API 说明

工作空间查询企业项目

列表查询用户在当前项目id下的企业项目列表。

创建工作空间用于在推荐系统下面创建独立的工作空间，用于资源的隔离

查询工作空间列表

用于查询当前用户具有操作权限的工作空间列表。

查询工作空间详情

查询指定工作空间的具体信息。

更新工作空间更新工作空间信息, 只允许更新描述信息。

删除工作空间删除指定工作空间。

查询规格查询训练规格查询当前推荐系统所提供的离线计算规格，实时

计算规格和排序模型训练规格。在创建数据源和场景时，需要提供此信息。

数据源创建数据源在指定的工作空间下面创建一个新的数据源。

查询数据源列表

查询当前工作空间下的数据源列表。

查询数据源详情

查询指定数据源的详情信息。

修改数据源内容

修改指定数据源的配置内容。

修改数据源特征

修改数据源中的特征。

删除数据源删除数据源。

查询数据源任务结果

查询指定数据源下离线任务的结果。其中包括数据格式，数据检测、数据探索及效果评估的内容。

(11)

类型 API 说明

场景创建自定义场

景

在指定工作空间下面创建自定义场景。

创建智能场景在指定工作空间下面创建智能场景。

查询场景详情查询指定场景的详情。

查询场景列表查询当前工作空间下的场景列表。

更新自定义场景内容

更新自定义场景的内容信息。

更新智能场景内容

更新智能场景的内容信息。

删除场景该接口用于删除场景，删除之后不能恢复，请您

谨慎操作。

训练作业新建训练作业新建训练作业元数据，新建成功之后可手动执行

此任务。

新建多个训练作业

批量新建作业。

查询训练作业查询resource_id（数据源id或场景id）下的指定类型的作业。

修改训练作业参数

修改指定作业的元数据信息。

修改训练作业

状态修改作业状态(启用，禁用)。

查询训练作业候选集

查询给定workspaces_id和指定resource_id下的候选集。

删除训练作业删除训练作业信息。

在线服务新建在线服务新建在线服务元数据，新建成功之后可手动发布

此服务。

查询在线服务详情

根据给定的workspace_id和resource_id及 category查询在线服务。

修改在线服务参数

修改指定在线服务的元数据内容。

删除在线服务删除在线服务实例。

调度执行作业执行独立的作业。

执行场景执行场景下面的所有作业和服务。

(12)

3 ^{如何调用 API}

3.1 构造请求

本节介绍REST API请求的组成，并以调用IAM服务的获取用户Token接口说明如何调用API，该API获取用户的Token，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API：https://

bbs.huaweicloud.com/videos/102987 。

请求 URI

请求URI由如下部分组成。

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。

● URI-scheme：表示用于传输请求的协议，当前所有API均采用HTTPS协议。

● Endpoint：指定承载REST服务端点的服务器域名或IP，不同服务不同区域的

Endpoint不同，您可以从地区和终端节点中获取。例如RES服务在“华北-北京四”区域的Endpoint为“res.cn-north-4.myhuaweicloud.com”。

● resource-path：资源路径，也即API访问路径。从具体API的URI模块获取，例如

“获取用户Token”API的resource-path为“/v3/auth/tokens”。

● query-string：查询参数，是可选部分，并不是每个API都有查询参数。查询参数 前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

例如您需要获取IAM在“华北-北京四”区域的Token，则需使用“华北-北京四”区域的Endpoint（iam.cn-north-4.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。

https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens

(13)

图3-1 URI 示意图

说明

为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。

这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

● GET：请求服务器返回指定资源。

● PUT：请求服务器更新指定资源。

● POST：请求服务器新增资源或执行特殊操作。

● DELETE：请求服务器删除指定资源，如删除对象等。

● HEAD：请求服务器资源头部。

● PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会

去创建一个新的资源。

在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

如下公共消息头需要添加到请求中。

● Content-Type：消息体的类型（格式），必选，默认取值为“application/

json”，有其他取值时会在具体接口中专门说明。

● X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字 段。用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。

说明

公有云API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。

AK/SK认证的详细说明请参加AK/SK认证。

● X-Project-ID：子项目ID，可选，在多项目场景中使用。

● X-Domain-ID：账号ID。

对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。

(14)

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求消息体

请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中

username

为用户名，

domainname

为用户所属的账号名称，

********

为用户登录密码，

xxxxxxxxxx

为project的名称，如“cn-north-4”，获取方法请参见获取用户名、

账号名和项目name。

说明

scope参数定义了Token的作用域，下面示例中获取的Token仅能访问project下的资源。您还可以设置Token的作用域为某个账号下所有资源或账号的某个project下的资源，详细定义请参见获取用户Token。

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

} } } }

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x- subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

3.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证通用请求。

(15)

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key)加密调用请求。

Token 认证

说明

Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。

Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的 Token，即调用获取用户Token接口时，请求body中“auth.scope”的取值需要选择

“project”，如下所示。

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

} } } }

获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，

其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:

ABCDEFJ....”加到请求消息头即可，如下所示。

GET https://iam.cn-north-4.myhuaweicloud.com/v3/auth/projects Content-Type: application/json

X-Auth-Token: ABCDEFJ....

您还可以通过这个视频教程了解如何使用Token认证：https://

bbs.huaweicloud.com/videos/101333 。

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12M以内，12M以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。

● AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥 ID和私有访问密钥一起使用，对请求进行加密签名。

(16)

● SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，

可标识发送方，并防止请求被修改。

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。

须知

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

3.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。

对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”。

对于获取用户Token接口，返回如图3-2所示的消息头，其中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

图3-2 获取用户 Token 响应消息头

(17)

响应消息体

响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。

对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

{ "token": {

"expires_at": "2019-02-13T06:52:13.855000Z", "methods": [

"password"

],

"catalog": [ {

"endpoints": [ {

"region_id": "cn-north-4", ...

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_msg": "The format of message is error", "error_code": "res.0001"

}

其中，error_code表示错误码，error_msg表示错误描述信息。

(18)

4 ^API

4.1 在线服务

4.1.1 新建在线服务

功能介绍

新建在线服务元数据，新建成功之后可手动发布此服务。

URI

POST /v2.0/{project_id}/workspaces/{workspace_id}/resources/{resource_id}/

service-instance

表4-1 路径参数

参数是否必选参数类型描述

project_id 是 String 项目id，获取方式请参见获取项

目ID。

resource_id 是 String 资源id（数据源id或场景id）。

workspace_id 是 String 工作空间id。

请求参数

表4-2 请求 Header 参数

Content-Type 是 String 内容类型，取值为application/

json。

(19)

X-Auth-Token 是 String 用户token，获取方式请参见获

取用户Token。

表4-3 请求 Body 参数

job_name 是 String 作业名称，1-64位的字母、数

字、下划线、中划线组合。

最小长度：1 最大长度：64 description 否 String 描述。

category 是 String 类别:

● SERVICE，在线服务

job_type 是 String 作业类型：

● infer，推理服务 job_config 是 jobConfig

object 作业配置。

topicUrn 否 String 通知消息配置。

表4-4 jobConfig

nearline_recal

l_param 否 NearLineRec allParam object

近线召回作业参数（近线召回作业需要提供此参数）。

max_recomm

ended_num 否 Integer 最大候选集个数（所有召回作业需提供此参数）。

最小值：1 最大值：200 match_featur

e_pairs 否 Array of MatchFeatur ePair objects

匹配特征对（属性匹配召回作业需要提供此参数）。

striping 否 Striping

object 行条化策略（属性匹配召回作业、物品协同过滤召回作业、用户协同过滤召回作业需要提供此参数）。

(20)

match_type 否 String 匹配类型（属性匹配召回作业需提供此参数）：

● UI，基于用户推荐物品

● UU，基于用户推荐用户

● II，基于物品推荐物品

● IU，基于物品推荐用户 matrix_factori

zation 否 MatrixFactori

zation object 矩阵分解参数配置（交替最小二乘协同过滤作业需提供此参数）。

behavior_freq

uencys 否 Array of BehaviorFreq uency objects

行为频率信息（历史行为记忆召回作业、历史行为过滤作业需提供此参数）。

file_path 否 String 文件路径（人工配置候选集作业

需要提供此参数）。

ucb_param 否 UcbParam

object UCB作业参数（UCB召回作业需要提供此参数）。

behavior_grav

ity 否 BehaviorGrav

ity object 重力衰减因子（综合行为热度召

回作业需要提供此参数）。

category 否 Category

object 类别（综合行为热度召回作业需要提供此参数）。

behavior_logic 否 String 行为逻辑过滤（历史行为过滤作业需提供此参数）：

● AND，同时满足则过滤

● OR，满足一个则过滤 features_engi

neering 否 EtlBasicPara

meter object 特征参数（离线特征工程作业需要提供此参数）。

sample_para

m 否 SamplePara

m object 样本参数（离线特征工程作业需

要提供此参数）。

deep_learning

_parameters 否 DeepLearing

Param object 排序作业通用参数（LR、

DEEPFM、AutoGroup需要提供此参数）。

algorithm_spe cify_paramete rs

否 AlgorithmSp

ecifyParamet ers object

排序算法特定参数（LR、

DEEPFM、AutoGroup需要提供此参数）。

load_widetabl

e 否 Boolean 导入宽表（离线数据导入作业需

load_profile 否 Boolean 导入画像（离线数据导入作业需要提供此参数）。

(21)

save_mode 否 String 保留已有宽表（离线数据导入作

业需要提供此参数）：

● append，是

● new，否

● overwirte，覆盖 indicators 否 Array of

Indicator objects

统计指标（效果评估作业需要提供此参数）。

offline_rank_j

ob_name 否 String 离线排序作业名称（在线训练任

务需要提供此参数）。

update_interv

al 否 Integer 更新周期（在线训练任务需要提

供此参数）。

optimizer 否 Optimizer

object 优化器（在线训练任务需要提供此参数）。

flows 否 Flow object 在线流程（在线训练任务需要提供此参数）。

表4-5 NearLineRecallParam

time_limit 否 Boolean 时间过滤。

timeFeature 否 String 时间特征。

retainDays 否 Integer 保留期(天)。

recall_fileds 否 Array of RecallFiled objects

召回字段。

itemCF_job_n

ame 否 String 物品协同过滤作业名称。

表4-6 RecallFiled

name 否 String 字段名称。

(22)

value 否 Integer 使用字段值的个数。

最小值：1 最大值：10 缺省值：1

表4-7 MatchFeaturePair

user_feature_

name 否 String 用户特征。

item_feature_

name 否 String 物品特征。

weight 否 Double 权重。

match_count 否 Boolean 匹配个数度量。

表4-8 Striping

nearest_neigh

borhood 是 Integer 最近领域个数。

band 是 Integer 相似程度。

最小值：1 最大值：20

row 是 Integer 相似距离。

表4-9 MatrixFactorization

implicit_vecto

r_rank 是 Integer 隐向量维度。

(23)

参数是否必选参数类型描述 regular_para

m 是 Double 优化正则化系数。

最小值：1.0E-8 最大值：1 max_iterator_

num 是 Integer 迭代次数。

表4-10 BehaviorFrequency

behavior_type 是 String 行为类型：

● view，曝光

● click，点击

● collect，收藏

● uncollect，取消收藏

● search_click，搜索后点击

● comment，评论

● share，分享

● like，点赞

● dislike，点衰

● grade，评分

● consume，消费

● use，观看视频/听音乐/阅读

● download，下载

● tip，打赏

● subscribe，关注 lower_limit 否 Integer 最小次数。

最小值：1 upper_limit 否 Integer 最大次数。

最小值：1 time_interval 是 Integer 时间区间。

最小值：1

(24)

表4-11 UcbParam

alpha 是 Double 折中参数。

最小值：0 最大值：1 min_used_nu

m 是 Integer 最小行为次数。

表4-12 BehaviorGravity

weaken_facto

r 否 Double 衰减因子。

最小值：0.1 最大值：5

view_type 否 String 行为次数统计方法：

● pv，访问量

● uv，独立访客

algo_type 否 String 算法类型:

● normal，通用

● time，时间

表4-13 Category

user_meta_list 否 Array of

strings 用户特征。

item_meta_lis

t 否 Array of

strings 物品特征。

表4-14 EtlBasicParameter

user_features 否 Array of FeatureTrans formation objects

用户特征。

(25)

参数是否必选参数类型描述 item_features 否 Array of

FeatureTrans formation objects

物品特征。

rank_etl_filter 否 RankETLFilte

r object 过滤参数。

表4-15 FeatureTransformation

attr 否 Attribute

object 特征。

discrete_meth

od 否 String 离散方法：

● equal_distance_discrete，等距离散

● user_define_discrete，自定义离散

● normalize，归一化

● null，不离散

params 否 Object 具体处理参数。

表4-16 Attribute

name 是 String 名称。

data_type 否 String 数据类型。

other_uses 否 Array of

strings 其他用途。

表4-17 RankETLFilter

filter_type 是 String 行为去重方式：

● abs_weight，权重绝对值

● date，日期

(26)

time_type 是 String 时间类型：

● day，天

● week，周

● month，月 is_monday_fir

st 否 Boolean 周一是否是第一天。

表4-18 SampleParam

divide_type 是 String 训练集测试集划分方式：

● TIME，时间比例

● RAMDOM，个数比例

train_rate 否 Double 训练数据占比。

test_rate 否 Double 测试数据占比。

表4-19 DeepLearingParam

initial_parame

ters 否 Initial object 初始化参数。

optimize_para

meters 否 Optimizer

object 优化参数。

regular_para

meters 否 Regular

object 正则化参数。

max_iteration

s 否 Integer 最大迭代轮数。

最小值：1 最大值：1000 early_stop_ite

rations 否 Integer 提前终止训练轮数。

(27)

参数是否必选参数类型描述 batch_size 否 Integer 批量大小。

最小值：1 dataset_split_

parts 否 Integer 训练数据集切分数量。

最小值：1 最大值：10 restart_train 否 Boolean 重新训练。

表4-20 Initial

initial_metho

d 是 String 初始化方法。

枚举值：

● normal

● uniform

● xavier

mean_value 否 Double 平均值。

最小值：-1 最大值：1 standard_devi

ation 否 Double 标准差。

min_value 否 Double 最小值。

最小值：-1 最大值：0

max_value 否 Double 最大值。

(28)

表4-21 Optimizer

type 否 String 优化器类型。

枚举值：

● adam

● adagrad

● ftrl learning_rate 否 Integer 学习率。

最小值：0 最大值：1 initial_accum

ulator_value 否 Double 初始梯度累加和。

lambda1 否 Double L1正则项系数。

lambda2 否 Double L2正则项系数。

epsilon 否 Double 数值稳定常量。

decay_rate 否 Double 衰减因子。

最小值：0 最大值：1 decay_steps 否 Double 衰减步长。

最小值：1

表4-22 Regular

l2_regularizati

on 否 Double L2正则项系数。

(29)

参数是否必选参数类型描述 regular_loss_c

ompute_mod e

否 String 正则损失计算方式。

枚举值：

● full

● batch embed_l2_reg

ularization 否 Double 隐向量层L2正则化系数。

最小值：0 最大值：1 wide_l2_regul

arization 否 Double wide部分L2正则化系数。

最小值：0 最大值：1 structure_l2_r

egularization 否 Double 结构化部分L2正则化系数。

表4-23 AlgorithmSpecifyParameters

latent_vector_

length 否 Integer 隐向量长度(DEEPFM需要提供

此参数)。

最小值：1 最大值：100 architecture 否 Array of

integers 神经网络结构(DEEPFM需要提供此参数)。

active_functio

n 否 String 激活函数(DEEPFM需要提供此

参数,AutoGroup需要提供此参数)。

枚举值：

● relu

● sigmoid

● tanh value_keep_pr

obability 否 Double 神经元值保留概率(DEEPFM需要提供此参数,AutoGroup需要提供此参数)。

最小值：0 最大值：1 embed_size 否 Array of

integers 各阶隐向量长度(AutoGroup需要提供此参数)。

(30)

参数是否必选参数类型描述 mlp_architect

ure 否 Array of

integers 神经网络结构(AutoGroup需要提供此参数)。

max_order 否 Integer 最大交互阶数(AutoGroup需要提供此参数)。

hash_sizes 否 Array of

integers 哈希长度(AutoGroup需要提供此参数)。

hash_compen

sation 否 Array of

numbers 特征交互层惩罚项系数

(AutoGroup需要提供此参数)。

use_wide_part 否 Boolean 使用线性部分(AutoGroup需要提供此参数)。

structure_opti

mizer 否 Optimizer

object 优化器参数(AutoGroup需要提供此参数)。

merge_multi_

hot 否 Boolean 融合多值特征(AutoGroup需要

提供此参数)。

fix_structure 否 Boolean 固定哈希结构(AutoGroup需要提供此参数)。

表4-24 Indicator

indicator_nam

e 否 String 指标名称：

● clickPVRate，点击PV率

● clickUVRate，点击UV率

● customize，自定义 indicator_para

ms 否 IndicatorPara

m object 指标参数（自定义指标需要提

供）。

表4-25 IndicatorParam

customize_par

ameter 否 CustomizePa rameter object

自定义参数。

customize_for

mula 否 CustomizeFor

mula object 自定义公式。

(31)

表4-26 CustomizeParameter

alias 是 String 别名。

behavior_type 是 String 行为类型。

threshold 否 Double 阈值。

最小值：0 最大值：1 deduplication 是 String 去重。

表4-27 CustomizeFormula

alias 否 String 别名。

formula 否 String 公式。

表4-28 Flow

flow_id 是 String 流程id。

attr_pair_rules

_filter 否 Array of AttrPairRules objects

属性对过滤。

attr_pair_rules

_reserve 否 Array of AttrPairRules objects

属性对保留。

deduplication

_list 否 Array of

Deduplicatio n objects

属性去重。

attribute_info 否 AttributeInfo

object 综合排序信息。

bloom_filter_c

onf 否 BloomFilterC

onf object 布隆过滤器配置。

group_attr 否 String 分组打散属性。

pre_deal 否 Boolean 在排序前去重。

rank_setting 否 String 排序配置信息。

rules 否 Rule object 候选集融合。

(32)

参数是否必选参数类型描述 filter_sets 否 Array of

strings 过滤配置信息。

attr_value_rul

es_filter 否 Array of AttrValueRul es objects

属性值过滤。

attr_value_rul

es_reserve 否 Array of AttrValueRul es objects

属性值保留。

ctr_job 否 String 排序作业（使用点击率预估时需

ratio 否 Integer 流量占比。

最小值：1 最大值：100 toppings 否 Array of

strings 需要置顶的候选集列表。

表4-29 AttrPairRules

attr_pairs 否 Array of AttrPair objects

属性对。

表4-30 AttrPair

party_a 否 String 被推荐对象的属性名。

party_b 否 String 被推荐对象的属性名。

表4-31 Deduplication

attributes 否 Array of

strings 属性。

(33)

表4-32 AttributeInfo

rank_feature_

pairs 否 Array of

RankFeature Pair objects

属性匹配对。

numerical_att

rs 否 Array of

NumericalAtt r objects

属性权重。

num_statistics

_type 否 String 统计方式：

● ORDER，顺序

● ABS，绝对值枚举值：

● ORDER

● ABS

表4-33 RankFeaturePair

feature_name

_a 否 String 待推荐对象的属性。

feature_name

_b 否 String 被推荐对象的属性。

weight 否 Float 权重。

表4-34 NumericalAttr

name 是 String 特征名。

weight 是 Float 权重。

(34)

表4-35 BloomFilterConf

behaviors 否 Array of

strings 待过滤行为类型。

interval 否 Integer 过滤时间。

表4-36 Rule

table_name 是 String 候选集表名。

rule_ratio 是 Integer 规则占比。

priority 是 Integer 优先级。

表4-37 AttrValueRules

attr_values_a 否 Array of AttrValue objects

被推荐对象的属性-值配置。

attr_values_b 是 Array of AttrValue objects

待推荐对象的属性-值配置。

表4-38 AttrValue

name 是 String 属性名称。

value 是 String 属性值。

(35)

响应参数

状态码： 200

表4-39 响应 Body 参数

参数参数类型描述

is_success Boolean 是否成功

job jobs object 服务描述信息

message String 返回消息（请求成功时，不返回此字段）

error_code String 错误码（请求成功时，不返回此字段）

表4-40 jobs

category String 类别。

config_info String 配置信息。

description String 描述。

job_id String 作业id。

job_name String 作业名称。

job_type String 作业类型。

next_schedule

_time Integer 下次调度时间。

platform String 平台。

resource_id String 资源id。

schedule String 调度参数。

status String 状态。

workspace_id String 工作空间id。

job_config jobConfig

(36)

nearline_recal

l_param NearLineRec allParam object

max_recomm

ended_num Integer 最大候选集个数（所有召回作业需提供此参数）。

e_pairs Array of MatchFeatur ePair objects

striping Striping

match_type String 匹配类型（属性匹配召回作业需提供此参数）：

zation MatrixFactori

zation object 矩阵分解参数配置（交替最小二乘协同过滤作业

需提供此参数）。

behavior_freq

uencys Array of BehaviorFreq uency objects

file_path String 文件路径（人工配置候选集作业需要提供此参数）。

ucb_param UcbParam

behavior_grav

ity BehaviorGrav

ity object 重力衰减因子（综合行为热度召回作业需要提供

此参数）。

category Category

behavior_logic String 行为逻辑过滤（历史行为过滤作业需提供此参数）：

neering EtlBasicPara

meter object 特征参数（离线特征工程作业需要提供此参

数）。

(37)

参数参数类型描述 sample_para

m SamplePara

m object 样本参数（离线特征工程作业需要提供此参

数）。

deep_learning

_parameters DeepLearing

Param object 排序作业通用参数（LR、DEEPFM、AutoGroup 需要提供此参数）。

AlgorithmSp ecifyParamet ers object

排序算法特定参数（LR、DEEPFM、AutoGroup 需要提供此参数）。

load_widetabl

e Boolean 导入宽表（离线数据导入作业需要提供此参

数）。

load_profile Boolean 导入画像（离线数据导入作业需要提供此参数）。

save_mode String 保留已有宽表（离线数据导入作业需要提供此参数）：

● append，是

● new，否

● overwirte，覆盖 indicators Array of

offline_rank_j

ob_name String 离线排序作业名称（在线训练任务需要提供此参数）。

update_interv

al Integer 更新周期（在线训练任务需要提供此参数）。

optimizer Optimizer

flows Flow object 在线流程（在线训练任务需要提供此参数）。

time_limit Boolean 时间过滤。

timeFeature String 时间特征。

retainDays Integer 保留期(天)。

recall_fileds Array of RecallFiled objects

召回字段。

(38)

参数参数类型描述 itemCF_job_n

ame String 物品协同过滤作业名称。

name String 字段名称。

value Integer 使用字段值的个数。

表4-44 MatchFeaturePair

user_feature_

name String 用户特征。

item_feature_

name String 物品特征。

weight Double 权重。

match_count Boolean 匹配个数度量。

表4-45 Striping

nearest_neigh

borhood Integer 最近领域个数。

band Integer 相似程度。

row Integer 相似距离。

(39)

表4-46 MatrixFactorization

implicit_vecto

r_rank Integer 隐向量维度。

最小值：1 最大值：100 regular_para

m Double 优化正则化系数。

最小值：1.0E-8 最大值：1 max_iterator_

num Integer 迭代次数。

表4-47 BehaviorFrequency

behavior_type String 行为类型：

● view，曝光

● click，点击

● collect，收藏

● uncollect，取消收藏

● search_click，搜索后点击

● comment，评论

● share，分享

● like，点赞

● dislike，点衰

● grade，评分

● consume，消费

● use，观看视频/听音乐/阅读

● download，下载

● tip，打赏

● subscribe，关注 lower_limit Integer 最小次数。

最小值：1 upper_limit Integer 最大次数。

最小值：1 time_interval Integer 时间区间。

最小值：1

(40)

表4-48 UcbParam

alpha Double 折中参数。

最小值：0 最大值：1 min_used_nu

m Integer 最小行为次数。

表4-49 BehaviorGravity

weaken_facto

r Double 衰减因子。

view_type String 行为次数统计方法：

● pv，访问量

● uv，独立访客 algo_type String 算法类型:

● normal，通用

● time，时间

表4-50 Category

user_meta_list Array of

strings 用户特征。

item_meta_lis

t Array of

strings 物品特征。

(41)

表4-51 EtlBasicParameter

user_features Array of FeatureTrans formation objects

用户特征。

item_features Array of FeatureTrans formation objects

物品特征。

rank_etl_filter RankETLFilte

r object 过滤参数。

表4-52 FeatureTransformation

attr Attribute

object 特征。

discrete_meth

od String 离散方法：

● equal_distance_discrete，等距离散

● user_define_discrete，自定义离散

● normalize，归一化

● null，不离散 params Object 具体处理参数。

表4-53 Attribute

name String 名称。

data_type String 数据类型。

other_uses Array of

strings 其他用途。

(42)

表4-54 RankETLFilter

filter_type String 行为去重方式：

● abs_weight，权重绝对值

● date，日期 time_type String 时间类型：

● day，天

● week，周

● month，月 is_monday_fir

st Boolean 周一是否是第一天。

表4-55 SampleParam

divide_type String 训练集测试集划分方式：

● TIME，时间比例

● RAMDOM，个数比例 train_rate Double 训练数据占比。

最小值：0.01 最大值：1 test_rate Double 测试数据占比。

表4-56 DeepLearingParam

initial_parame

ters Initial object 初始化参数。

optimize_para

meters Optimizer

object 优化参数。

regular_para

meters Regular

object 正则化参数。

(43)

参数参数类型描述 max_iteration

s Integer 最大迭代轮数。

最小值：1 最大值：1000 early_stop_ite

rations Integer 提前终止训练轮数。

最小值：1 最大值：1000 batch_size Integer 批量大小。

最小值：1 dataset_split_

parts Integer 训练数据集切分数量。

最小值：1 最大值：10 restart_train Boolean 重新训练。

表4-57 Initial

initial_metho

d String 初始化方法。

枚举值：

● normal

● uniform

● xavier mean_value Double 平均值。

最小值：-1 最大值：1 standard_devi

ation Double 标准差。

最小值：0 最大值：1 min_value Double 最小值。

最小值：-1 最大值：0 max_value Double 最大值。

(44)

表4-58 Optimizer

type String 优化器类型。

枚举值：

● adam

● adagrad

● ftrl learning_rate Integer 学习率。

最小值：0 最大值：1 initial_accum

ulator_value Double 初始梯度累加和。

最小值：0 最大值：1 lambda1 Double L1正则项系数。

最小值：0 最大值：1 lambda2 Double L2正则项系数。

最小值：0 最大值：1 epsilon Double 数值稳定常量。

最小值：0 最大值：1 decay_rate Double 衰减因子。

最小值：0 最大值：1 decay_steps Double 衰减步长。

最小值：1

表4-59 Regular

l2_regularizati

on Double L2正则项系数。

(45)

参数参数类型描述 regular_loss_c

ompute_mod e

String 正则损失计算方式。

枚举值：

● full

● batch embed_l2_reg

ularization Double 隐向量层L2正则化系数。

最小值：0 最大值：1 wide_l2_regul

arization Double wide部分L2正则化系数。

最小值：0 最大值：1 structure_l2_r

egularization Double 结构化部分L2正则化系数。

表4-60 AlgorithmSpecifyParameters

latent_vector_

length Integer 隐向量长度(DEEPFM需要提供此参数)。

最小值：1 最大值：100 architecture Array of

integers 神经网络结构(DEEPFM需要提供此参数)。

active_functio

n String 激活函数(DEEPFM需要提供此参数,AutoGroup需要提供此参数)。

枚举值：

● relu

● sigmoid

● tanh value_keep_pr

obability Double 神经元值保留概率(DEEPFM需要提供此参数,AutoGroup需要提供此参数)。

最小值：0 最大值：1 embed_size Array of

integers 各阶隐向量长度(AutoGroup需要提供此参数)。

mlp_architect

ure Array of

integers 神经网络结构(AutoGroup需要提供此参数)。

(46)

max_order Integer 最大交互阶数(AutoGroup需要提供此参数)。

hash_sizes Array of

integers 哈希长度(AutoGroup需要提供此参数)。

hash_compen

sation Array of

numbers 特征交互层惩罚项系数(AutoGroup需要提供此参数)。

use_wide_part Boolean 使用线性部分(AutoGroup需要提供此参数)。

structure_opti

mizer Optimizer

object 优化器参数(AutoGroup需要提供此参数)。

merge_multi_

hot Boolean 融合多值特征(AutoGroup需要提供此参数)。

fix_structure Boolean 固定哈希结构(AutoGroup需要提供此参数)。

表4-61 Indicator

indicator_nam

e String 指标名称：

● clickPVRate，点击PV率

● clickUVRate，点击UV率

● customize，自定义 indicator_para

ms IndicatorPara

m object 指标参数（自定义指标需要提供）。

表4-62 IndicatorParam

customize_par

ameter CustomizePa rameter object

自定义参数。

customize_for

mula CustomizeFor

mula object 自定义公式。

表4-63 CustomizeParameter

alias String 别名。

(47)

参数参数类型描述 behavior_type String 行为类型。

threshold Double 阈值。

最小值：0 最大值：1 deduplication String 去重。

表4-64 CustomizeFormula

alias String 别名。

formula String 公式。

表4-65 Flow

flow_id String 流程id。

attr_pair_rules

_filter Array of AttrPairRules objects

属性对过滤。

attr_pair_rules

_reserve Array of AttrPairRules objects

属性对保留。

deduplication

_list Array of Deduplicatio n objects

属性去重。

attribute_info AttributeInfo

object 综合排序信息。

bloom_filter_c

onf BloomFilterC

onf object 布隆过滤器配置。

group_attr String 分组打散属性。

pre_deal Boolean 在排序前去重。

rank_setting String 排序配置信息。

rules Rule object 候选集融合。

filter_sets Array of

strings 过滤配置信息。

(48)

参数参数类型描述 attr_value_rul

es_filter Array of AttrValueRul es objects

属性值过滤。

attr_value_rul

es_reserve Array of AttrValueRul es objects

属性值保留。

ctr_job String 排序作业（使用点击率预估时需要提供此参数）。

ratio Integer 流量占比。

最小值：1 最大值：100 toppings Array of

strings 需要置顶的候选集列表。

表4-66 AttrPairRules

attr_pairs Array of AttrPair objects

属性对。

表4-67 AttrPair

party_a String 被推荐对象的属性名。

party_b String 被推荐对象的属性名。

表4-68 Deduplication

attributes Array of

strings 属性。

(49)

表4-69 AttributeInfo

rank_feature_

pairs Array of RankFeature Pair objects

属性匹配对。

numerical_att

rs Array of NumericalAtt r objects

属性权重。

num_statistics

_type String 统计方式：

● ORDER，顺序

● ABS，绝对值枚举值：

● ORDER

● ABS

表4-70 RankFeaturePair

feature_name

_a String 待推荐对象的属性。

feature_name

_b String 被推荐对象的属性。

weight Float 权重。

表4-71 NumericalAttr

name String 特征名。

weight Float 权重。

(50)

表4-72 BloomFilterConf

behaviors Array of

strings 待过滤行为类型。

interval Integer 过滤时间。

表4-73 Rule

table_name String 候选集表名。

rule_ratio Integer 规则占比。

最小值：1 最大值：100 priority Integer 优先级。

表4-74 AttrValueRules

attr_values_a Array of AttrValue objects

被推荐对象的属性-值配置。

attr_values_b Array of AttrValue objects

待推荐对象的属性-值配置。

表4-75 AttrValue

name String 属性名称。

value String 属性值。

(51)

请求示例

发布推理服务

/v2.0/testuuidxxxxxxxxxxxxxxxxxxxxxxxx/workspaces/testuuidxxxxxxxxxxxxxxxxxxxxxxxx/resources/

testuuidxxxxxxxxxxxxxxxxxxxxxxxx/service-instance { "category" : "SERVICE",

"job_type" : "infer", "job_config" : { "flows" : [ { "ratio" : 100, "rules" : [ {

"table_name" : "item-UIREC", "rule_ratio" : 100,

"priority" : "1"

} ],

"flow_id" : "flow1"

} ]

}, "description" : "inference service", "job_name" : "online1"

}

响应示例

状态码： 200 OK

{ "job" : {

"category" : "SERVICE", "job_name" : "online1",

"job_id" : "testuuidxxxxxxxxxxxxxxxxxxxxxxxx", "description" : "inference service",

"job_type" : "infer", "status" : "Draft", "platform" : "AIP",

"workspace_id" : "testuuidxxxxxxxxxxxxxxxxxxxxxxxx", "resource_id" : "testuuidxxxxxxxxxxxxxxxxxxxxxxxx"

}, "is_success" : true }

状态码

状态码描述

200 OK

错误码

请参见错误码。

4.1.2 查询在线服务详情

功能介绍

根据给定的workspace_id和resource_id及category查询在线服务。

(52)

URI

GET /v2.0/{project_id}/workspaces/{workspace_id}/resources/{resource_id}/service- instance

表4-76 路径参数

project_id 是 String 项目id，获取方式请参见获取项

目ID。

resource_id 是 String 资源id。

workspace_id 是 String 工作空间id。

表4-77 Query 参数

category 是 String 服务类别：

● SERVICE，在线服务

请求参数

表4-78 请求 Header 参数

Content-Type 是 String 内容类型，取值为application/

json。

X-Auth-Token 是 String 用户token，获取方式请参见获

取用户Token。

响应参数

状态码： 200

表4-79 响应 Body 参数

is_success Boolean 是否成功。

jobs jobs object 作业详情。

message String 返回消息（请求成功时，不返回此字段）。

(53)

error_code String 错误码（请求成功时，不返回此字段）。

表4-80 jobs

category String 类别。

config_info String 配置信息。

description String 描述。

job_id String 作业id。

job_name String 作业名称。

job_type String 作业类型。

next_schedule

_time Integer 下次调度时间。

platform String 平台。

resource_id String 资源id。

schedule String 调度参数。

status String 状态。

workspace_id String 工作空间id。

job_config jobConfig

nearline_recal

l_param NearLineRec allParam object

max_recomm

ended_num Integer 最大候选集个数（所有召回作业需提供此参数）。

e_pairs Array of MatchFeatur ePair objects

(54)

参数参数类型描述 striping Striping

match_type String 匹配类型（属性匹配召回作业需提供此参数）：

zation MatrixFactori

zation object 矩阵分解参数配置（交替最小二乘协同过滤作业

需提供此参数）。

behavior_freq

uencys Array of BehaviorFreq uency objects

file_path String 文件路径（人工配置候选集作业需要提供此参数）。

ucb_param UcbParam

behavior_grav

ity BehaviorGrav

ity object 重力衰减因子（综合行为热度召回作业需要提供

此参数）。

category Category

behavior_logic String 行为逻辑过滤（历史行为过滤作业需提供此参数）：

neering EtlBasicPara

meter object 特征参数（离线特征工程作业需要提供此参

数）。

sample_para

m SamplePara

m object 样本参数（离线特征工程作业需要提供此参

数）。

deep_learning

_parameters DeepLearing

Param object 排序作业通用参数（LR、DEEPFM、AutoGroup 需要提供此参数）。

AlgorithmSp ecifyParamet ers object

排序算法特定参数（LR、DEEPFM、AutoGroup 需要提供此参数）。

load_widetabl

e Boolean 导入宽表（离线数据导入作业需要提供此参

数）。

load_profile Boolean 导入画像（离线数据导入作业需要提供此参数）。

(55)

save_mode String 保留已有宽表（离线数据导入作业需要提供此参数）：

● append，是

● new，否

● overwirte，覆盖 indicators Array of

offline_rank_j

ob_name String 离线排序作业名称（在线训练任务需要提供此参数）。

update_interv

al Integer 更新周期（在线训练任务需要提供此参数）。

optimizer Optimizer

flows Flow object 在线流程（在线训练任务需要提供此参数）。

time_limit Boolean 时间过滤。

timeFeature String 时间特征。

retainDays Integer 保留期(天)。

recall_fileds Array of RecallFiled objects

召回字段。

itemCF_job_n

ame String 物品协同过滤作业名称。

name String 字段名称。

value Integer 使用字段值的个数。

新建在线服务_推荐系统 RES_API参考_API_在线服务_华为云

API 参考

华为技术有限公司

https://www.huawei.com

[email protected]

目 录

1 使用前必读... 1

1.1 概述... 1

1.2 调用说明...1

1.3 终端节点...1

1.4 约束与限制... 2

1.5 基本概念...2

1.6 API 版本选择建议... 3

2 API 概览... 4

3 如何调用 API...6

3.1 构造请求...6

3.2 认证鉴权...8

3.3 返回结果... 10

4 API...12

4.1 在线服务... 12

4.1.1 新建在线服务... 12

4.1.2 查询在线服务详情... 45

4.1.3 修改在线服务参数... 64

4.1.4 删除在线服务... 81

4.2 场景... 83

4.2.1 创建自定义场景...83

4.2.2 创建智能场景... 86

4.2.3 查询场景详情...105

4.2.4 查询场景列表...108

4.2.5 更新自定义场景内容...112

4.2.6 更新智能场景内容... 115

4.2.7 删除场景... 133

4.3 工作空间... 135

4.3.1 查询企业项目列表... 135

4.3.2 创建工作空间...137

4.3.3 查询工作空间列表... 139

4.3.4 查询工作空间详情... 141

4.3.5 更新工作空间...143

4.3.6 删除工作空间...145

4.4 数据源... 147

4.4.1 创建数据源... 147

4.4.2 查询数据源列表... 150

4.4.3 查询数据源详情... 154

4.4.4 修改数据源内容... 174

4.4.5 修改数据源特征... 177

4.4.6 删除数据源... 182

4.4.7 查询数据源任务结果...184

4.5 查询规格... 191

4.5.1 查询训练规格...191

4.6 训练作业... 193

4.6.1 新建训练作业...193

4.6.2 新建多个训练作业... 233

4.6.3 查询训练作业...253

4.6.4 修改训练作业参数... 272

4.6.5 删除训练作业...291

4.6.6 查询训练作业候选集...293

4.7 调度... 296

4.7.1 执行作业... 296

4.7.2 执行场景... 298

5 API（V1 不推荐）... 301

5.1 平台资源 API... 301

5.1.1 绑定依赖资源...301

5.1.2 获取资源列表...303

5.1.3 解绑依赖资源...304

5.1.4 创建跨源连接...306

5.1.5 获取跨源连接...307

5.1.6 删除跨源连接...308

5.1.7 开启公共终端节点... 310

5.2 作业相关 API... 311

5.2.1 提交组合作业...311

5.2.2 提交召回作业...322

5.2.3 提交过滤作业...327

5.2.4 提交特征工程作业... 330

5.2.4.1 提交特征工程作业...330

5.2.4.2 查询全局特征配置...345

5.2.5 提交排序作业...347

5.2.5.1 提交排序任务 API...347

5.2.5.2 查询 ModelArts 服务 AK/SK... 351

5.2.5.3 关联 AK/SK 到 ModelArts 服务...352

5.2.5.4 查询 ModelArts 计算节点规格... 353

目录

1 ^{使用前必读}

2 ^{API 概览}

3 ^{如何调用 API}