:レコメンデーションエンジンの API 呼び出し

API リファレンス

POST /api/rec/feed

リクエストパラメーター

パラメーター	説明	型	必須	例
uid	ユーザー ID。	string	はい	"1000079"
size	返すレコメンデーションアイテムの数。	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	デバッグを有効にします。 true の場合、このパラメーターはユーザーやアイテムの詳細などの追加ログを返します。 トラフィックコントロールが有効な場合、レスポンスにはトラフィックコントロールのプロセスとパラメーターの変更に関する詳細も含まれます。	bool	いいえ	true
request_id	リクエストの一意の ID。 このパラメーターを省略した場合、PAI-Rec レコメンデーションエンジンが ID を生成します。 値を指定した場合、その値がリクエスト ID として使用されます。	string	いいえ	"c46c3f5e-6b32-4b5c-8aac-59a319941248"

item_list

事前取得したアイテムのバッチがある場合は、item_list パラメーターで渡すことができます。 item_list パラメーターは、マップオブジェクトの配列です。 配列内の各オブジェクトには、アイテム ID を指定する item_id フィールドが含まれている必要があります。 他のすべてのフィールドはオプションです。 オブジェクトに score フィールドが含まれている場合、その値は取得スコアとして使用されます。 他のすべてのフィールドは、アイテムプロパティとして扱われます。

complex_type_features

複雑なコンテキスト特徴は、各要素が次のフィールドを含む配列として渡します。

パラメーター	説明	例
name	コンテキスト特徴の名前。	age
type	コンテキスト特徴の型。	int
values	コンテキスト特徴の値。 単一の値、配列、またはマップを指定できます。	20

例：

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. マップを渡す [{"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	API 固有の状態コード。	int	200
msg	対応するステータスメッセージ。	string	success
request_id	一意のリクエスト ID。	string	e332fe9c-7d99-45a8-a047-bc7ec33d07f6
size	返されたレコメンデーションアイテムの数。	int	10
experiment_id	実験 ID。 A/B テストが設定されていない場合、このパラメーターは空になります。	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

エラーコード

エラーコード	説明	msg
200	API 呼び出しは成功しました。	success
299	リクエストされた数よりも少ないアイテムが返されました。	items size not enough
400	無効なパラメーターが指定されました。 msg フィールドにエラーの詳細が含まれます。	uid not empty or unexpected end of JSON input
500	サーバーエラーが発生しました。 これは JSON ボディではなく、HTTP ステータスコードとして返されます。

設定と呼び出し例

このセクションでは、API 呼び出しで取得リストを渡すコンテキスト取得の例を示します。 以下は、home_feed レコメンデーションシナリオを使用したエンジン設定のサンプルです。

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

リクエストボディ：

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

API 呼び出し

cURL での呼び出し

ローカルマシンから cURL でエンジンサービスを呼び出すには、まず EAS コンソールからリクエスト URL とトークンを取得します。

サービス詳細ページで、[エンドポイント情報の表示] をクリックして、呼び出し情報ダイアログボックスを開きます。

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}]
}'

レスポンスデータ

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

PAI-Rec 診断ツールでの呼び出し

PAI-Rec コンソールの [サービス管理] ページからサービスをデプロイした場合、診断ツールを使用してレコメンデーション結果をデバッグできます。

対応するサービスと環境を選択し、ルーティング情報には /api/rec/feed を選択します。

アイテムテーブル： アイテム詳細テーブルがある場合は、それを選択してアイテム詳細を返されたデータと結合します。

リクエストデータ： 最近のリクエストパラメーターが表示されます。 パラメーターを手動で入力することもできます。

パラメーターを選択して入力した後、[診断] をクリックしてレコメンデーション結果を取得します。

レスポンス JSON では、code が 200 の場合はリクエストが成功したことを示します。 レスポンスには、request_id や experiment_id などのフィールドも含まれます。 items 配列はレコメンデーション結果のリストです。 各レコメンデーションアイテムには、item_id (アイテム ID) と score (レコメンデーションスコア) が含まれます。