構建 PAI-Rec 專案並驗證推薦 API - 智能推荐 AIRec - 阿里雲 -

快速開始

安裝命令

我們可以使用 pairecmd 快速建立專案。現在 V2 版本支援 PAI-Rec控制台（推薦使用）。

V2 版本

下載地址：

下載之後，在類 *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 檔案。

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}

註：可以通過阿里雲鏡像開通個人鏡像，然後建立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

請求參數

參數名稱	參數說明	類型	是否必須	用例
uid	使用者id	string	是	"1000079"
size	擷取item數量	integer	是	10
scene_id	情境id	String	是	home_feed
features	上下文特徵	json map	否	{"age":20, "sex":"male"}
complex_type_features	複雜類型的上下文特徵，如果需要有類型的資訊請求模型服務，需要設定此值。	json array	否	[{"name":"age", "type":"int", "values":20}, {"name":"sex", "values":"male", "type":"string"}]
item_id	相似性推薦傳入的物品ID	string	否	248791390
item_list	自訂的召回傳入列表	json array	否	[{"item_id":"1111", "score":1},{"item_id":"222", "score":0.95}]
debug	debug 用，列印更多的日誌	bool	否	true
request_id	請求唯一標識ID,此參數為空白時，PAI-Rec 引擎會自動產生，如果使用者傳入，使用參數值當成請求的ID	string	否	"c46c3f5e-6b32-4b5c-8aac-59a319941248"

當有一批召回的資料，希望通過介面傳遞進來，可以賦值給 item_list。 item_list 是一個數組，每個 item 是 map object ，item 中必須有 item_id 欄位，表示物品的ID。其餘都是可選的。 item 中如果包含 score 欄位，會當成召回得分處理。其餘欄位當成 item 屬性進行處理。

complex_type_features

複雜類型的上下文特徵需要數組傳遞過來，每個元素包含的內容如下：

名稱	說明	用例
name	上下文特徵名稱	age
type	上下文特徵類型	int
values	上下文特徵值，這裡可以設定多種類型，支援具體值，數組， map 等	20

使用樣本：

傳遞單個值，[{"name":"age", "type":"int", "values":20}, {"name":"sex", "values":"male", "type":"string"}]
傳遞數組 [{"name":"list_features", "type":"list<int>", "values":[1,2,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 可以同時使用。

介面返回

名稱	說明	類型	樣本
code	介面返回業務碼	int	200
msg	商務資訊	string	success
request_id	請求的唯一標識	string	e332fe9c-7d99-45a8-a047-bc7ec33d07f6
size	返回的推薦條目數量	int	10
experiment_id	實驗ID 標識, 沒有對接 AB 實驗，返回為空白	string	ER2_L1#EG1#E2
items	返回推薦條目的列表	json array	[{"item_id":"248791390","score":0.9991594902203332,"retrieve_id":"mock_recall"}]

items 條目具體說明如下：

名稱	說明	類型	樣本
item_id	推薦物品ID	string	3v5RE7417j7R
retrieve_id	召回源ID標識	string	u2i_recall
score	推薦得分	float	0.45
extra	使用者自訂欄位輸出，不指定的話，不會輸出	json map	參考下文自訂輸出欄位的說明

錯誤碼說明

錯誤碼	說明	msg
200	介面正常	success
299	返回的數量不足	items size not enough
400	參數錯誤，不同的情況， msg 說明不同	uid not empty 或者nexpected end of JSON input 等
500	伺服器錯誤, 以 HTTP 錯誤碼形式返回

請求範例

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實驗平台，配置自訂指標，計算報表資料之後，可以在實驗指標報表中查看實驗報表。