You need to enable JavaScript to run this app.
导航
长视频行业数据模板
最近更新时间:2023.10.18 20:09:21首次发布时间:2021.08.12 18:48:22

对于长视频行业的客户,接入智能推荐平台需要准备 3 张数据表,具体字段需求参见下文“数据字段说明”:
用户表(user)
建议上传前做去重处理。user_id为用户唯一标识。
物品表(item)
此处指视频(item),建议上传前做去重处理。item_id为视频唯一标识。
行为表(behavior)
测试数据建议提供1-2周的数据,历史数据建议提供3个月以上数据,可同步的时间越长,效果往往会越好。

数据字段说明

字段规范:

  • 字段类型:原始字段类型,与新建项目“表定义”中模板字段类型一致。
  • 字段等级:字段等级按字段需求程度分为必选、强烈建议和建议,必选字段在表定义时必须勾选。
  • 描述:该字段的具体含义。
  • 字段作用:该字段在推荐流程当中的作用。

说明

建议尽可能多传字段,数据越丰富,预期推荐效果越好。

API传输数据类型规范:

  • string、float、int 类型数据传输时使用原类型传即可。
  • bool类型的字段需要在平台上定义为int传输。
  • array类型需要用json string传输,如array类型的[1,2,3,4]需要传入json string的"[1,2,3,4]";array类型的["a","b","c","d"]需要传入json string的"[\"a\",\"b\",\"c\",\"d\"]";不要有 control characters ('\t', '\n', '\r', '\0'等)。

注意

API对字段的校验规则:

  1. 必传校验。以下字段如果不传,会拒绝整条数据,包括:
  • 用户表:user_id
  • 物品表:item_id、status
  • 行为表:bhv_time、bhv_type、user_id、spm、scm
  1. 字段类型校验。
  • 必传字段强校验,数值类型传string会cast,无法cast的话会拒绝整条数据。
  • 非必传但schema中定义的字段,数值类型传string也会cast,无法cast的话会拒绝整条数据。
  • 未在schema中定义的字段,不做类型校验。

如果因为类型校验失败,api会返回1001状态码,且在返回结果的errors字段中会有错误数据例子和错误原因说明。

用户表

字段名称

字段类型

字段等级

描述

字段作用

user_id

string

必选

用户id,不能包含中文

user_id唯一标识一个用户,作用:
1)产出样本时,用作Key去关联行为数据和用户数据,拼接用户侧特征。
2)归因行为数据时,用作归因的聚合key之一
3)在线服务流环节中的个性化召回中,用作key去维护候选召回池。

age

string

强烈建议

用户年龄或者年龄段

用作特征

city

string

强烈建议

用户城市

用作特征

gender

string

强烈建议

用户性别,例如:1:男性 2:女性 3:未知

用作特征

register_time

int32

强烈建议

用户注册时间戳,精确到秒,如1622476800

用作特征

tags

string

强烈建议

用户标签,多个标签使用$##$分隔,如“标签1$##$标签2$##$标签3”

用作特征

update_time

int32

强烈建议

用户信息更新时间戳,精确到秒,如1622476800

提供精确的字段更新时间,平台会根据此字段来判断是否做字段更新,如果该字段不准确则可能导致无法更新;如无法提供精确的更新时间,建议此字段传空。

client_version

string

建议

客户端版本

用作特征

country

string

建议

用户国家

用作特征

device_id

string

建议

终端ID

device_type

string

建议

终端类型

用作特征

district

string

建议

用户所在区县

用作特征

id_type

string

建议

id类型,手机/邮箱/微信 等

用作特征

language

string

建议

用户语言

用作特征

last_login_time

int32

建议

用户最后一次登陆时间戳,精确到秒,如1622476800

用作特征和推荐策略

membership_level

string

建议

用户会员等级

用作特征

network

string

建议

网络类型,5G/WIFI

用作特征

os

string

建议

操作系统,如IOS,Android

用作特征

os_version

string

建议

设备操作系统版本

用作特征

platform

string

建议

平台,如APP,WAP,H5

用作特征

province

string

建议

用户省份

用作特征

subscriber_type

string

建议

订阅类型

用作特征

物品表

字段名称

字段类型

字段等级

描述

字段作用

item_id

string

必选

表示推荐的ID,需要根据实际推荐纬度从series_id/entity_id/video_id中选择一个填入

item_id唯一标识一个候选,作用:
1)产出样本时,用作Key去关联行为数据和商品数据,拼接商品侧特征
2)归因行为数据时,用作归因的聚合key之一

status

int32

必选

可推荐状态,0:不可推荐, 1:可推荐

1)status=0的物品不会在推荐结果中出现
2)需要下架物品时,把status的值修改为0即可,若物品表是实时同步,生效周期为分钟级。当物品上下架频繁时,建议实时同步物品更新信息

video_duration

int32

必选

该节目的时长(单位为秒)

1)用作特征。 2)优化目标为播放完成率时,用来改写label

actors

array

强烈建议

演员列表,API传输要用json序列化的string,如"["a","b","c",...]"

用作特征

category

string

强烈建议

节目不同级类目之间用$##$分隔,且自左向右类目层级逐渐细化。类目值推荐全部传名称,举例如“喜剧$##$小品”。某一段为空时直接传空字符串,如第二段为空, 则传“喜剧”。

1)用作特征
2)在线服务会用到该字段**(可使用前三级)**进行召回过滤或业务规则

copyright_end

int64

强烈建议

版权结束时间,精确到秒,如1622476800

时间在版权开始之前和之后的物品不可推

copyright_start

int64

强烈建议

版权开始时间,精确到秒,如1622476800

时间在版权开始之前和之后的物品不可推

item_name

string

强烈建议

表示推荐的item_name,填入推荐维度id对应name字段,如推荐ID为series_id,则item_name=series_name

用作特征

keyword

string

强烈建议

关键词。多个关键词用英文逗号分割。

用作特征

tags

string

强烈建议

视频标签,如首页展示标签 “热播”、“贺岁”、“惊闻”等。多值示例:“动作$##$冒险"

1)用作特征
2)服务流会用到该字段进行召回过滤/规则打散

update_time

int32

建议

视频信息更新时间,精确到秒,如1622476800

提供精确的字段更新时间,平台会根据此字段来判断是否做字段更新,如果该字段不准确则可能导致无法更新;如无法提供精确的更新时间,建议此字段传空。

video_count

int32

强烈建议

该节目所属的剧目一共有多少集

用作特征

video_index

int32

强烈建议

该节目在剧目中的索引,比如是第6集。从1开始

用作特征

video_type

string

强烈建议

视频类型,枚举值包括:电视剧、电影、综艺、儿童动漫、新闻、音乐、体育、纪录片、游戏、直播、短内容合辑、戏曲、公开课,其他类型填"未知"

1)用作特征
2)服务流会用到该字段进行召回过滤/规则打散

author_fans

int32

建议

作者粉丝数

用作特征

authors

array

建议

创作者(导演)/出品方。可有多个,API传输要用json序列化的string,如"["a","b","c",...]"

用作特征

chargeable

bool

建议

是否收费。该字段已弃用,新项目不建议使用,存量项目仍可正常使用。

用作特征

cover

array

建议

list of string,封面图的url,API传输要用json序列化的string,如"["a","b","c",...]"

用作特征

current_price

float

建议

当前订阅或者购买价格

用作特征

description

string

建议

剧情描述

用作特征

entity_id

string

建议

实体编码。一个实体有若干季(剧目)。

用作特征

entity_name

string

建议

实体名称。比如《大秦帝国》

用作特征

language

string

建议

视频语言

用作特征

original_price

float

建议

订阅或者购买原始价格

用作特征

pic_url

string

建议

封面url

pub_region

string

建议

发布国家

1)用作特征
2)服务流会用到该字段进行召回过滤/规则打散

pub_time

int32

建议

发布时间,精确到秒,如1622476800

服务流会用到该字段进行召回过滤/规则打散

rating

float

建议

该剧目的打分

用作特征

region

array

建议

播放限制区域,API传输要用json序列化的string,如"["a","b","c",...]"

sale_number

int32

建议

累计售卖次数

用作特征

series_count

int32

建议

该节目所属的实体一共有多少季

用作特征

series_id

string

建议

剧目编码。一个剧目有若干集(节目)

用作特征

series_index

int32

建议

该节目在实体中的索引,比如是第3季。从1开始

用作特征

series_name

string

建议

剧目名称。比如《大秦帝国第三季》

用作特征

source_id

string

建议

视频来源。比如自有、三方平台等。

用作特征

video_id

string

建议

节目编码。一个节目是最小的粒度。如果是小视频则是视频id

用作特征

video_name

string

建议

节目名称。比如《大秦帝国第三季第6集》

用作特征

video_url

string

建议

视频url。如果有多个,使用$##$链接多个url

行为表

字段名称

字段类型

字段等级

描述

字段作用

bhv_time

int32

必选

行为发生时间戳,以秒为单位的unix timestamp,如1622476800,需要在当天时间分区内

作用:
1)行为数据归因时,需要根据bhv_time来对行为排序,从而判断行为发生的先后顺序
2)挖掘用户行为序列特征时,需要将特征列表按bhv_time排序
影响:bhv_time需要传准确的值,否则会影响归因的结果和特征的质量,对推荐效果折损较大。

bhv_type

string

必选

行为类型。不同行为的bhv_type值可以自定义。
平台内置行为类型如下:[曝光:exposure],[点击:click],[播放: play],[播放完成:playover],[点赞:like],[评论:comment],[收藏:favorite],[加购物车:cart],[下单:order],[不喜欢:dislike]。

作用:
1)不同优化目标强依赖于相应bhv_type的行为,比如优化目标为点击率,那么点击行为必传;若优化目标为播放率,那么曝光和播放行为必传
2)挖掘用户特征,传的行为类型越多,平台挖掘的用户特征越多,推荐效果越好
3)用作消重和规则系统

item_id

string

必选

表示推荐的ID,需要根据实际推荐纬度从series_id/entity_id/video_id中选择一个填入

需要与候选表中的item_id相匹配

play_type

string

必选

播放类型,如0:开始播放,1:续播,2:试播

1)用作特征
2)统计效果时,根据客户口径过滤某些类型的行为

scm

string

必选

scm主要用于标识行为产生自哪个合作方。如字节推荐接口返回的候选产生行为,scm可传bytedance,其他可传google、other等等。如无法区分其他合作方,历史数据中可传other,需要保证上线后字节推荐接口返回的候选产生的行为scm都传bytedance。

用于统计不同来源算法的效果

spm

string

必选

SPM(Super Position Model)全称超级位置模型,主要用于标识行为发生的位置。SPM位置编码由A/B/C/D四段构成,各分段分别代表 A: 业务,B:屏幕名称, C: 模块名称, D: 位置。段之间用$##$分隔,即A$##$B$##$C$##$D,spm各段建议传明文。某一段为空时直接传空字符串,如第二段为空, 则传“A$##$$##$C$##$D”。
1.业务:业务名称,如今日头条
2.屏幕名称:一般是推荐页、详情页、电视剧栏目页等
3.模块名称:屏幕中的几个推荐模块,比如猜你喜欢是box2; 同类热播是box5
4.位置:在box中的具体位置

1)归因的时候用作归因依据
2)当传多场景行为数据时,需要spm作为特征刻画不同场景用户行为分布的差异
3)服务流会用到该字段进行召回过滤
4)统计效果按照spm统计单场景效果

user_id

string

必选

用户id,即机顶盒id

登录用户需要与用户表中user_id一致;未登录用户建议使用device_id/imei填充user_id

end_time

int32

强烈建议

结束播放时视频的终点

1)用于除以视频总时长,判断是否完播,优化播放完成率
2)主要刻画退出视频时是在哪个时间点

parent_item_id

string

强烈建议

进入详情页观看的内容的ID,该字段是生成详情页特征的必要字段

用于生成详情页特征

play_duration

int32

强烈建议

播放时长(单位为秒)

用于效果指标统计

pos_id

int32

强烈建议

返回的内容实体在推荐列表中的位置,从0开始

用作特征

request_id

string

强烈建议

请求推荐接口时的request_id

1)便于排查问题
2)后续平台支持request_id作为归因key

start_time

int32

强烈建议

开始播放时视频的起点

device_id

string

建议

行为发生的设备标识

用作数据校验和特征

dislike_type

string

建议

负反馈规则的维度。需要用到负反馈规则时,必须勾选并传输。例如,若不喜欢此视频,需同时过滤同一类型的其他视频,则传输video_type。需要用到多个属性做负反馈时,dislike行为分别传输多个dislike_type和dislike_value。 注意:1)当前item_id不需要再填充到dislike_type,可直接用于负反馈规则;2)dislike_type必须为内容表中的字段,包括:item_id, video_type, category, tags, pub_region以及自定义字段。

和dislike_value一起,作为负反馈规则的条件

dislike_value

string

建议

负反馈规则的维度值,即dislike_type字段对应的字段值。需要用到负反馈规则时,必须勾选。例如,若不喜欢此视频,需同时过滤同一类型的其他视频,则传输video_type的值。若此字段不传,则默认使用当前item对应的属性值过滤。 注意:使用到tags字段过滤时,可以传输多个值(以$##$分隔),触发其中任意值的视频都视作触发负反馈规则。

和dislike_type一起,作为负反馈规则的条件

entity_id

string

建议

实体id

用作特征

ipv4

string

建议

ipv4地址

用作特征

ipv6

string

建议

ipv6地址

用作特征

series_id

string

建议

剧目id

用作特征

trace_id

string

建议

trace_id用于将用户的连续行为关联起来,例如用户曝光了某视频,并点击、播放了该视频,那么这一系列的行为可以用trace_id进行关联,将点击、播放事件归因到对应的曝光事件。此字段由客户侧生成。

后续平台支持trace_id用于归因

trans_data

string

建议

trans_data是个性化推荐请求api返回结果中所携带的transData字段(详细作用可见api文档),用于追踪物品相关的所有行为,进行深入分析,提升推荐效果。

便于平台帮助客户分析优化点

video_id

string

建议

节目id

用作特征

行为类型说明

长视频行业支持以下10种模板行为,如需更多行为,可进行自定义,详见数据表定义

bhv_type

行为名称

说明

exposure

曝光

强烈建议传输

click

点击

强烈建议传输

play

播放

playover

播放完成

playover行为建议传play_duration字段

like

点赞

comment

评论

favorite

收藏

cart

加购

order

订单

提交订单(即建单)或者到了提交订单页面的行为

dislike

不喜欢