Build a PAI-Rec Project and Validate Recommendation APIs - Artificial Intelligence Recommendation - Alibaba Cloud -

Quickstart

Install the CLI

You can use pairecmd to quickly create a project. We recommend using Version 2 from the PAI-Rec console.

Version 2

Download links:

After downloading on a Unix-like system, make the file executable. Run the following command: chmod +x pairecmd

Create a project

To create a project named pairec-demo, run the following command. This creates a directory named pairec-demo in your current working directory with the project's source code.

./pairecmdmac project --name pairec-demo

The generated directory has the following structure:

pairec-demo
├── Makefile
├── conf
│   └── config.json.production
├── docker
│   └── Dockerfile
├── go.mod
└── src
    ├── controller
    │   └── feed.go
    └── main.go

Navigate to the pairec-demo directory and run the following command:

go mod tidy

Compile and package project

The project includes a Makefile. To compile the project, run the following command:

make && make build

If you encounter any errors, first run the following command:

go mod tidy

To package the project as an image, run the following command:

make release

You can modify the Makefile to suit your specific needs.

DOCKER?=docker
SOURCE_DIR=src
BIN_NAME=pairec_demo
REGISTRY?=registry.cn-beijing.cr.aliyuncs.com
DOCKER_TAG?=0.0.1
TEMP_DIR_SERVER:=$(shell mktemp -d)
.PHONY: setup build clean
setup:
        go mod vendor
build:
        cd ${SOURCE_DIR}; CGO_ENABLED=0 GOARCH=amd64 GOOS=linux ${BUILD} -o ${BIN_NAME} .
        cd ${SOURCE_DIR}; mv ${BIN_NAME} ../
release:
        cd ${SOURCE_DIR}; CGO_ENABLED=0 GOARCH=amd64 GOOS=linux ${BUILD} -o ${BIN_NAME} .
        cd ${SOURCE_DIR}; mv ${BIN_NAME} ${TEMP_DIR_SERVER}/appd
        cp docker/Dockerfile ${TEMP_DIR_SERVER}/
        cp conf/config.json.production ${TEMP_DIR_SERVER}/config.json
        cd ${TEMP_DIR_SERVER}  &&  ${DOCKER} build  -t ${REGISTRY}/${BIN_NAME}:${DOCKER_TAG} .
        ${DOCKER} push ${REGISTRY}/${BIN_NAME}:${DOCKER_TAG}
clean:
        -rm -rf ${BIN_NAME}

Note: You can use Alibaba Cloud Container Registry to activate a personal image service and then create an image repository specified by BIN_NAME.

Run the project

Navigate to the pairec-demo directory and run the following command to start the service. The service prints logs to the terminal.

Use the config parameter to specify the path to the configuration file.

go run src/main.go --config=conf/config.json.production --alsologtostderr

You can test the API by running the following command in a separate terminal:

curl -v http://localhost:8000/api/rec/feed -d '{"uid":"76295990", "size":10, "scene_id":"home_feed"}'

For details about the configuration, see Engine Configuration.

API reference

The generated project includes a recommendation API. For implementation details, see controller/feed.go. The API is defined as follows:

Endpoint

/api/rec/feed

Request parameters

Parameter	Description	Type	Required	Example
uid	The user ID.	string	Yes	"1000079"
size	The number of items to return.	integer	Yes	10
scene_id	The scenario ID.	string	Yes	home_feed
features	The context features.	json map	No	{"age":20, "sex":"male"}
complex_type_features	Complex context features. This parameter is required if the model service needs 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 used for a similarity-based recommendation.	string	No	248791390
item_list	A custom list of items for recall.	json array	No	[{"item_id":"1111", "score":1},{"item_id":"222", "score":0.95}]
debug	A flag for debugging. If set to `true`, the system prints additional logs.	bool	No	true
request_id	A unique identifier for the request. If this parameter is omitted, the PAI-Rec engine automatically generates an ID. If a value is provided, the PAI-Rec engine uses it as the request ID.	string	No	"c46c3f5e-6b32-4b5c-8aac-59a319941248"

To pass a batch of recalled data through the API, assign it to the item_list parameter. The item_list is an array of map objects. Each object must contain an item_id field that specifies the item ID. All other fields are optional. If an object contains a score field, the engine treats its value as the recall score. The engine treats all other fields as item properties.

complex_type_features

Pass complex context features as an array. Each element in the array contains the following fields:

Parameter	Description	Example
name	The name of the context feature.	age
type	The type of the context feature.	int
values	The value of the context feature. This field supports various types, including single values, arrays, and maps.	20

Examples:

Pass a single value: [{"name":"age", "type":"int", "values":20}, {"name":"sex", "values":"male", "type":"string"}]
Pass an array: [{"name":"list_features", "type":"list<int>", "values":[1,2,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 values for the type field 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>.

You can use the complex_type_features and features parameters together in the same request.

Response body

Parameter	Description	Type	Example
code	The business status code.	int	200
msg	The business message.	string	success
request_id	The unique identifier of the request.	string	e332fe9c-7d99-45a8-a047-bc7ec33d07f6
size	The number of recommended items returned.	int	10
experiment_id	The experiment ID. If you do not use A/B testing, this field 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 fields for each object in the items array.

Parameter	Description	Type	Example
item_id	The ID of the recommended item.	string	3v5RE7417j7R
retrieve_id	The ID of the recall source.	string	u2i_recall
score	The recommendation score.	float	0.45
extra	Custom output fields. If you specify no custom fields, the API does not return this field.	json map	See the description of custom output fields below.

Error codes

Code	Description	msg
200	The request was successful.	success
299	The API returned an insufficient number of items.	items size not enough
400	A parameter error occurred. The `msg` field provides details.	uid not empty or unexpected end of JSON input
500	A server error occurred. The server returns this error as an HTTP status code.

Request example

curl -v http://host/api/rec/feed -d '{"uid":"76295990", "size":10, "scene_id":"home_feed"}'

Sample response

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

Custom output fields

By default, each item in the response includes the item_id, retrieve_id, and score fields. You may also want to output custom fields, such as item properties or model scores. You can customize the output fields for a scenario in SceneConfs. Define this configuration in OutputFields, and the API returns the custom fields in the extra field.

The following code shows a sample configuration:

"SceneConfs": {
  "${scene_name}": {
    "default": {
      "RecallNames": [
        "collaborative_filter"
      ],
      "OutputFields": [
           "item:type",
           "item:age",
           "score:*",
           "score:model_v1_ctr"
      ]
    }
  }
}

Fields that start with item: output the corresponding item properties. If a property does not exist, the API returns null.
Fields that start with score: output the scores returned by the model.
score:* outputs all model scores. The API places the scores in the algo_scores field.

FAQ

Pass an item list for reranking

Pass the item list in the item_list parameter. Then, in the engine configuration, configure a Context Item Recall to allow the PAI-Rec engine to read the item list from the item_list parameter.

Implement client-side tracking for reports

The recommendation API returns the request_id and experiment_id fields. You must log these two fields on the client. At a minimum, include them in the impression and click behavior log. We recommend that you also include these fields in other behavior logs, such as logs for playback duration, add-to-cart events, and purchases. Omitting these fields from other behavior logs can affect metric accuracy. See the SQL examples in Data Registration and Field Configuration to generate an offline experiment report source table. Then, register the table with the A/B testing platform, configure custom metrics, and calculate report data. After the A/B testing platform calculates the report data, you can view the experiment report in the Experiment Metrics Report.