Recommendation engine API call

API reference

POST /api/rec/feed

Request parameters

Parameter	Description	Type	Required	Example
uid	The user ID.	string	Yes	"1000079"
size	The number of recommended items to return.	integer	Yes	10
scene_id	The ID of the recommendation scenario. This parameter is used to differentiate requests for different recommendation scenarios.	string	Yes	home_feed
features	The contextual features.	json map	No	{"age":20, "sex":"male"}
complex_type_features	Contextual features of complex data types. Set this parameter if your model service requires type information in the request.	json array	No	[{"name":"age", "type":"int", "values":20}, {"name":"sex", "values":"male", "type":"string"}]
item_id	The item ID for similarity recommendations.	string	No	248791390
item_list	A custom list of items for the engine to rank.	json array	No	[{"item_id":"1111", "score":1},{"item_id":"222", "score":0.95}]
debug	Enables debugging. When true, this parameter returns additional logs, such as user and item details. If traffic control is enabled, the response also includes details about the traffic control process and parameter changes.	bool	No	true
request_id	The unique ID for the request. If you omit this parameter, the PAI-Rec recommendation engine generates one. If you provide a value, it is used as the request ID.	string	No	"c46c3f5e-6b32-4b5c-8aac-59a319941248"

item_list

If you have a pre-retrieved batch of items, you can pass them in the item_list parameter. The item_list parameter is an array of map objects. Each object in the array must contain an item_id field, which specifies the item ID. All other fields are optional. If an object includes a score field, the value is used as the retrieval score. All other fields are treated as item properties.

complex_type_features

Pass complex contextual features as an array where each element contains the following fields:

Parameter	Description	Example
name	The name of the contextual feature.	age
type	The type of the contextual feature.	int
values	The value of the contextual feature. This can be a single value, an array, or a map.	20

Examples:

1. Pass a single value: [{"name":"age", "type":"int", "values":20}, {"name":"sex", "values":"male", "type":"string"}]

2. Pass an array[{"name":"list_features", "type":"list<int>", "values":[1,2,3]}]

3. Pass a map [{"name":"map_features", "type":"map<int,int>", "values":{"1":10,"2":20,"3":30}}], or [{"name":"map_features", "type":"map<int,int>", "values":{"1":"10","2":"20","3":"30"}}],

The supported types for type include int,int64,float,double,string,list<int>,list<int64>,list<float>,list<double>,list<string>,map<int,int>,map<int,int64>,map<int,float>,map<int,double>,map<int,string>,map<string,int>,map<string,int64>,map<string,float>,map<string,double>,map<string,string>,map<int64,int>,map<int64,int64>,map<int64,float>,map<int64,double>, and map<int64,string>.

Note: You can use complex_type_features and features in the same request.

Response parameters

Parameter	Description	Type	Example
code	The API-specific status code.	int	200
msg	The corresponding status message.	string	success
request_id	The unique request ID.	string	e332fe9c-7d99-45a8-a047-bc7ec33d07f6
size	The number of recommended items returned.	int	10
experiment_id	The experiment ID. If an A/B test is not configured, this parameter is empty.	string	ER2_L1#EG1#E2
items	A list of recommended items.	json array	[{"item_id":"248791390","score":0.9991594902203332,"retrieve_id":"mock_recall"}]

The following table describes the parameters in the items array.

Parameter	Description	Type	Example
item_id	The ID of the recommended item.	string	3v5RE7417j7R
retrieve_id	The retrieval source ID.	string	u2i_recall
score	The recommendation score.	float	0.45

Error codes

Error code	Description	msg
200	The API call was successful.	success
299	Fewer items were returned than requested.	items size not enough
400	An invalid parameter was provided. The msg field contains details about the error.	uid not empty or unexpected end of JSON input
500	A server error occurred. This is returned as an HTTP status code, not in the JSON body.

Configuration and call examples

This section provides an example of contextual retrieval, where a retrieval list is passed in an API call. The following is a sample engine configuration using the home_feed recommendation scenario:

{
  "RunMode": "product",
  "ListenConf": {
    "HttpAddr": "",
    "HttpPort": 8000
  },
  "SortNames": {
    "default": ["ItemRankScore"]
  },
  "FilterNames": {
    "default": ["UniqueFilter"]
  },
  "SceneConfs": {
    "home_feed": {
      "default": {
        "RecallNames": ["ContextItemRecall"]
      }
    }
  }
}

Request body:

{
  "uid":"13579",
  "size":2,
  "scene_id":"home_feed",
  "item_list":[{"item_id":"1111", "score":1},{"item_id":"222", "score":0.95}]
}

API calls

Call with cURL

To call the engine service from your local machine with cURL, first obtain the request URL and token from the EAS console.

On the service details page, click View Endpoint Information to open the call information dialog box.

curl -X 'POST' -v \
'http://12*****.vpc.hangzhou.pai-eas.aliyuncs.com/api/predict/test/api/rec/feed' \
-H 'Authorization:YmRjZThkM2Z*****************TU5Mw==' \
-d '{
"uid":"13579",
"size":2,
"scene_id":"home_feed",
"item_list":[{"item_id":"1111", "score":1},{"item_id":"222", "score":0.95}]
}'

Response data

{
  "code":200,
  "msg":"success",
  "request_id":"e332fe9c-7d99-45a8-a047-bc7ec33d07f6",
  "size":2,
  "experiment_id":"",
  "items":[
    {
      "item_id":"1111",
      "score":0.9991594902203332,
      "retrieve_id":"ContextItemRecall"
    },
    ...
  ]
}

Call with the PAI-Rec diagnostic tool

If you deployed your service from the Service Management page in the PAI-Rec console, you can use the diagnostic tool to debug recommendation results.

You need to select the corresponding service and environment, and for routing information, select /api/rec/feed.

Item Table: If you have an item details table, select it to join item details with the returned data.

Request Data: Displays your recent request parameters. You can also enter the parameters manually.

After selecting and entering the parameters, click Diagnose to get the recommendation results.

In the response JSON, a code of 200 indicates a successful request. The response also includes fields such as request_id and experiment_id. The items array is a list of recommendation results. Each recommended item contains an item_id (item ID) and a score (recommendation score).