快速创建项目

快速开始

安装命令

我们可以使用 pairecmd 快速创建项目。现在 V2 版本支持 PAI-Rec控制台（推荐使用）。

V2 版本

下载地址：

linux 版本

mac 版本

mac arm版本

window 版本

下载之后，在类 *nix 系统，需要设置下可执行文件。命令：chmod +x pairecmd

创建项目

以创建项目名称 pairec-demo 举例，执行命令后，会在当前目录生成 pairec-demo 目录，该目录包含项目代码。

./pairecmdmac project --name pairec-demo

生成的目录结构如下：

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

进入 pairec-demo 目录，执行

go mod tidy

编译打包项目

项目里提供了 Makefile 文件， 如果要编译的话，直接运行

make && make build

如果遇到错误的话，可以先执行

go mod tidy

如果要打包成镜像的话，执行

make release

可以结合实际情况来修改 Makefile 文件。

注：可以通过 阿里云镜像 开通个人镜像，然后创建BIN_NAME 指定的镜像仓库。

运行项目

可以进入到 pairec-demo 目录， 运行一下命令启动服务，日志会输出到终端上。

通过config参数传入配置文件路径。

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

可以用下面的接口进行测试（开启另一个终端，运行）：

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

config 具体的配置可以参考引擎配置单。

接口测试

在生成的项目中，本身已经实现了一个推荐接口，具体实现可以参考 controller/feed.go 。 接口定义如下：

接口名称

/api/rec/feed

请求参数

当有一批召回的数据，希望通过接口传递进来，可以赋值给 item_list。 item_list 是一个数组，每个 item 是 map object ，item 中必须有 item_id 字段，表示物品的ID。其余都是可选的。 item 中如果包含 score 字段，会当成召回得分处理。其余字段当成 item 属性进行处理。

complex_type_features

复杂类型的上下文特征需要数组传递过来，每个元素包含的内容如下：

使用示例：

1. 传递单个值，[{"name":"age", "type":"int", "values":20}, {"name":"sex", "values":"male", "type":"string"}]

2. 传递数组 [{"name":"list_features", "type":"list<int>", "values":[1,2,3]}]

3. 传递map [{"name":"map_features", "type":"map<int,int>", "values":{"1":10,"2":20,"3":30}}], 或者 [{"name":"map_features", "type":"map<int,int>", "values":{"1":"10","2":"20","3":"30"}}],

type 支持的类型包括 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>, map<int64,string>

传递上下文中， complex_type_features 和 features 可以同时使用。

接口返回

items 条目具体说明如下：

错误码说明

请求样例

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

返回数据

{
    "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"
          },
                ...
    ]
}

输出自定义字段

在上文item条目的说明中，默认会输出item_id，retrieve_id，score字段。但很多情况下，用户想自定义输出更多的字段，比如item的属性字段或者模型的得分等等。可以在SceneConfs的某个场景下自定义输出字段名称，配置定义在OutputFields里，接口会放到extra字段中。

配置参考示例如下：

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

• 以item开头的会输出item相应的属性字段，如果不存在的话，会输出 null

• 以score开头的会输出模型返回的得分

• score:*会输出所有的模型得分，放在algo_scores里

常见问题

问题1：如何通过推荐接口传入一个物品列表再排序？

回答：把指定物品列表通过接口的参数item_list传入；然后在引擎配置单中设置一个上下文召回（ContextItemRecall），让PAI-Rec引擎从接口参数item_list中读取物品列表。

问题2：客户端如何埋点可以记录PAI-Rec的埋点信息并使用实验报表？

回答：推荐接口中返回两个字段：request_id和experiment_id，用户需要把这两个字段在客户端埋点，然后至少在曝光、点击行为日志中包含这两个字段。其他如播放时长、加入购物车、购买等行为日志中埋点更好，如果其他行为中没有埋点，则效果统计会受到一些影响。参考数据注册与字段配置中的SQL案例，生成离线“实验报表来源表”，然后注册到AB实验平台，配置自定义指标，计算报表数据之后，可以在实验指标报表中查看实验报表。