The ranking service accepts requests and returns ranked candidate arms in JSON format. This page describes the request parameters, response fields, configuration items, and feature types you need to set up the service.
Request parameters
All request parameters are passed as a JSON body.
| Parameter | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | A unique identifier for the request. |
scene | string | No | The scenario name. |
algo | string | Yes | The algorithm name. |
user_id | string | Yes | The user ID. |
items | string array | Yes | The set of candidate arms to rank. |
user_feature | dict | Yes | User features used for ranking. |
item_features | dict array | No | The arm features. This parameter is optional. |
limit | — | Yes | The maximum number of arms to return. |
Response
The service returns a JSON object with an output array. Each element represents a ranked arm.
| Field | Type | Description |
|---|---|---|
output[].id | string | The arm ID, corresponding to an entry in the input items array. |
output[].score | string | The predicted score for the arm. Arms are ordered by descending score. |
Example response:
{
"output": [
{
"id": "123",
"score": "0.8"
},
{
"id": "223",
"score": "0.7"
},
{
"id": "323",
"score": "0.6"
}
]
}Configuration items
The configuration file is a JSON object with two top-level keys: HologresDSN and AlgoConf.
| Configuration item | Type | Description |
|---|---|---|
HologresDSN | dict | Connection strings for Hologres databases. Each key is a database alias referenced elsewhere in the configuration. |
AlgoConf | dict | Algorithm configurations keyed by scenario name. Each value is the algorithm configuration for that scenario. |
AlgoConf.${algo}.AlgoType | string | The algorithm type. Valid values: random, disjoint, hybrid. See Algorithm types. |
AlgoConf.${algo}.CompressFeature | boolean | Specifies whether to compress features before storing them. |
AlgoConf.${algo}.ArmFeatureDao | array | Configuration for loading arm features from Hologres at startup. See ArmFeatureDao fields. |
AlgoConf.${algo}.LinUCBConf | dict | LinUCB algorithm parameters. |
AlgoConf.${algo}.LinUCBConf.Alpha | number | Controls the exploration-exploitation tradeoff. A larger value favors exploration. |
AlgoConf.${algo}.LinUCBConf.GlobalModelParamId | string | The primary key of shared feature parameters of the hybrid algorithm in the model parameter table. |
AlgoConf.${algo}.LinUCBConf.HologresName | string | The database alias from HologresDSN to use for this algorithm. |
AlgoConf.${algo}.LinUCBConf.ModelTable | string | The Hologres table that stores model parameters. |
AlgoConf.${algo}.LinUCBConf.FeatureTable | string | The Hologres table that stores feature vectors after feature transformation. |
AlgoConf.${algo}.LinUCBConf.FeatureTablePKey | string | The primary key of the feature vector table. |
AlgoConf.${algo}.LinUCBConf.ArmIdKey | string | The column name for arm IDs in the Hologres table. |
AlgoConf.${algo}.LinUCBConf.CacheMaxSize | integer | The maximum number of model parameters to cache in local memory. |
AlgoConf.${algo}.LinUCBConf.CacheTimeInSeconds | integer | How long to keep model parameters in local memory cache, in seconds. |
AlgoConf.${algo}.LinUCBConf.RequestArmNumPerTime | integer | The maximum number of model parameters to sync per request. |
AlgoConf.${algo}.LinUCBConf.RequestArmInterval | integer | The time interval for synchronizing model parameters. |
AlgoConf.${algo}.LinUCBConf.Parallelism | integer | The parallelism of model prediction. |
AlgoConf.${algo}.FeatureConf | array | Feature configuration for the feature generator. Each element defines how one feature is extracted and transformed. See FeatureConf fields. |
Algorithm types
AlgoType | Description |
|---|---|
random | Returns a random subset of the input candidate arms up to the limit. No model training or inference is performed. |
disjoint | LinUCB variant where each arm has independent weight parameters. Use for standard contextual bandit scenarios. |
hybrid | LinUCB variant where arms share some weight parameters, controlled by GlobalModelParamId. Use for cold-start scenarios where shared representations such as embeddings are available across arms. |
ArmFeatureDao fields
Each element in ArmFeatureDao defines one feature table to load from Hologres.
| Field | Description |
|---|---|
HologresName | The database alias from HologresDSN. |
HologresTableName | The fully qualified Hologres table name in schema.table format. |
FeatureKey | The primary key column of the feature table. |
SelectFields | Columns to load. Use * to load all columns. |
FeatureConf fields
Each element in FeatureConf defines one feature. The feature_type field determines which additional fields apply.
feature_type | Additional fields | Description |
|---|---|---|
raw_feature | expression, value_dimension (optional), separator (optional), share_weight (optional) | A numeric or multi-value feature loaded as-is. Use value_dimension for vector features. Set share_weight: true to mark the feature as a shared weight in hybrid LinUCB. |
binary_feature | expression, vocab_list | A binary feature. The value is 1 if it matches any item in vocab_list, otherwise 0. |
id_feature | expression, and one of: hash_bucket_size, vocab_list, boundaries, or num_buckets + offset | A categorical or bucketed feature. Use boundaries for numeric bucketing, vocab_list for fixed vocabularies, or hash_bucket_size for hashing. |
geohash_feature | expression (array of two fields: latitude, longitude), geohash_precision, hash_bucket_size | Encodes a geographic location as a geohash and hashes it into a bucket. |
combo_feature | expression (array), hash_bucket_size | Combines multiple fields into a single hashed feature. |
Complete configuration example
The following example shows a configuration file with three scenarios: default (random), cold_start (hybrid LinUCB), and linucb (disjoint LinUCB). Both LinUCB scenarios connect to the same Hologres database aliased as vv_rec.
{
"HologresDSN": {
"vv_rec": "postgres://${asscessId}:${asscessKey}@hgpostcn-cn-xxxx-cn-beijing-vpc.hologres.aliyuncs.com:80/${db_name}?sslmode=disable&connect_timeout=10"
},
"AlgoConf": {
"default": {
"AlgoType": "random"
},
"cold_start": {
"ArmFeatureDao": [
{
"HologresName": "vv_rec",
"HologresTableName": "sv_rec.sv_dropoutnet_embedding",
"FeatureKey": "svid",
"SelectFields": "svid,embedding"
}
],
"AlgoType": "hybrid",
"CompressFeature": false,
"LinUCBConf": {
"Alpha": 1.0,
"ArmIdKey": "arm_id",
"HologresName": "vv_rec",
"ModelTable": "sv_rec.contextual_bandit_models_v2",
"FeatureTable": "sv_rec.contextual_bandit_features_v2",
"FeatureTablePKey": "user_id,arm_id",
"CacheTimeInSeconds": 86400,
"CacheMaxSize": 100000,
"RequestArmNumPerTime": 100,
"RequestArmInterval": 5,
"Parallelism": 8
},
"FeatureConf": [
{
"feature_type": "raw_feature",
"expression": "user:ColdStartVideoVectorRecall_embedding",
"value_dimension": 64,
"separator": ","
},
{
"feature_type": "raw_feature",
"expression": "arm:embedding",
"value_dimension": 64,
"share_weight": true
},
{
"feature_type": "raw_feature",
"expression": "arm:recall_score",
"share_weight": true
}
]
},
"linucb": {
"ArmFeatureDao": [
{
"HologresName": "vv_rec",
"HologresTableName": "vvarticle.smart_video",
"FeatureKey": "smartVideoId",
"SelectFields": "*"
}
],
"AlgoType": "disjoint",
"CompressFeature": true,
"LinUCBConf": {
"Alpha": 1.0,
"ArmIdKey": "arm_id",
"HologresName": "vv_rec",
"ModelTable": "sv_rec.contextual_bandit_models",
"FeatureTable": "sv_rec.contextual_bandit_features",
"FeatureTablePKey": "user_id,arm_id",
"CacheTimeInSeconds": 86400,
"CacheMaxSize": 100000,
"RequestArmNumPerTime": 100,
"RequestArmInterval": 5,
"Parallelism": 8
},
"FeatureConf": [
{
"feature_type": "binary_feature",
"expression": "gender",
"vocab_list": ["M"]
},
{
"feature_type": "raw_feature",
"expression": "is_member"
},
{
"feature_type": "raw_feature",
"expression": "is_new_userid"
},
{
"feature_type": "id_feature",
"expression": "province",
"hash_bucket_size": 36
},
{
"feature_type": "id_feature",
"expression": "constellation",
"vocab_list": ["Cancer", "Taurus", "Capricorn", "Leo", "Gemini", "Aries", "Scorpio", "Pisces", "Sagittarius", "Aquarius", "Virgo", "Libra"]
},
{
"feature_type": "id_feature",
"expression": "birthyear",
"boundaries": [1967, 1971, 1974, 1977, 1980, 1982, 1985, 1988, 1992, 2001]
},
{
"feature_type": "id_feature",
"expression": "fans_num",
"boundaries": [2, 7, 16, 29, 54, 104, 210, 455, 1022]
},
{
"feature_type": "id_feature",
"expression": "follow_num",
"boundaries": [1, 4, 9, 17, 30, 53, 99, 214, 544]
},
{
"feature_type": "id_feature",
"expression": "visitor_num",
"boundaries": [0, 58, 157, 349, 795, 1865, 4796, 12664, 35753]
},
{
"feature_type": "id_feature",
"expression": "level",
"num_buckets": 50,
"offset": 1
},
{
"feature_type": "geohash_feature",
"expression": ["latitude", "longitude"],
"geohash_precision": 4,
"hash_bucket_size": 128
},
{
"feature_type": "id_feature",
"expression": "familyid",
"hash_bucket_size": 50
},
{
"feature_type": "id_feature",
"expression": "userid_exposure_cnt_distinct_svid_15",
"boundaries": [63, 159, 252, 348, 439, 508, 580, 679, 878]
},
{
"feature_type": "id_feature",
"expression": "userid_click_cnt_15",
"boundaries": [0, 3, 7, 13, 19, 27, 42, 72, 151]
},
{
"feature_type": "binary_feature",
"expression": "os",
"vocab_list": ["ios"]
},
{
"feature_type": "combo_feature",
"expression": ["os", "os_version"],
"hash_bucket_size": 100
},
{
"feature_type": "id_feature",
"expression": "userid_likes_comment_collect_share_cnt_15",
"boundaries": [0, 1, 2, 3, 6, 11, 27]
},
{
"feature_type": "id_feature",
"expression": "userid_max_duration_15",
"boundaries": [13.3, 44, 80.8, 137, 200.8, 240.4, 276.9, 317.9, 443.9]
},
{
"feature_type": "id_feature",
"expression": "userid_min_duration_15",
"boundaries": [0, 0.1, 5.1, 6.2, 7, 8, 9.7, 12.7]
},
{
"feature_type": "id_feature",
"expression": "userid_avg_duration_15",
"boundaries": [11, 20.15, 25.2857, 29.3875, 32.8862, 36.2385, 39.915, 44.7783, 54.0227]
},
{
"feature_type": "id_feature",
"expression": "author_play_ct",
"boundaries": [0, 50, 356, 2130]
},
{
"feature_type": "id_feature",
"expression": "user_auth_type",
"vocab_list": ["0", "1", "13", "24", "14", "20", "30", "11", "5", "15", "3", "16", "12", "2", "10", "29", "19", "4", "17", "21", "31", "25", "7", "8", "9"]
},
{
"feature_type": "id_feature",
"expression": "author_av_ct",
"boundaries": [0, 1, 2, 5, 14, 34, 90]
},
{
"feature_type": "id_feature",
"expression": "flower_ct",
"boundaries": [0, 72, 347, 1070, 2610, 6463, 16157]
},
{
"feature_type": "id_feature",
"expression": "userid_avg_hot_15",
"boundaries": [0, 0.018, 0.0741, 0.25, 8.53, 46.37, 94.11, 159.86]
},
{
"feature_type": "id_feature",
"expression": "diamond_ct",
"boundaries": [0, 10, 50, 160, 460, 1332, 4910]
},
{
"feature_type": "id_feature",
"expression": "userid_exposure_cnt_distinct_svid_7",
"boundaries": [36, 93, 146, 201, 248, 285, 332, 399, 521]
},
{
"feature_type": "id_feature",
"expression": "family_member_ct",
"boundaries": [0, 82, 159, 234, 322, 438, 642, 1113]
},
{
"feature_type": "id_feature",
"expression": "author_sv_ct",
"boundaries": [0, 2, 8, 34]
},
{
"feature_type": "id_feature",
"expression": "userid_exposure_cnt_15",
"boundaries": [63, 162, 257, 354, 446, 514, 587, 687, 890]
}
]
}
}
}该文章对您有帮助吗？