Microsoft Recommendations API (1)

# 概要

Microsoft Azure の Cognitive Services のひとつ、
 [Recommendations API](https://www.microsoft.com/cognitive-services/en-us/recommendations-api) がどういうものか調べた。

# ドキュメント
- [Recommendations API Overview](https://www.microsoft.com/cognitive-services/en-us/recommendations/documentation)
- [Recommendations API Reference](https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0/operations/56f30d77eda5650db055a3db)

# Recommendations APIの機能
### できること
『**商品の一覧**』と『**ユーザの購買/クリックの履歴**』を入力として

* User-to-Item Recommendations
    * ユーザに対して適切な商品を勧める
    * 「*あなたにおすすめ*」
* Item-to-Item Recommendations
    * ある商品と関連する商品を勧める
    * 「*この商品を見た人はこんな商品も見ています*」
* Frequently Bought Together Recommendations (FBT)
    * ある商品と同時に購入された商品を勧める
    * 「*合わせて買いたい*」
* ユーザの行動データを逐次的に追加してモデルを更新
* 手持ちのデータを使って、作ったモデルを評価する

### できないこと
* ユーザによる商品のレーティングを予測 （「この映画を高評価した人はこれらの映画も高評価しています」）
    * Recommendations API は、あくまで「買った」「クリックした」といったタイムスタンプ付きの**行動履歴**を情報源とする。
* ユーザに対してユーザを勧める（おすすめユーザ）
* ユーザの特徴を使って推薦する（性別、年齢、・・・）

## データのフォーマット
recommendations APIを利用するために与える必要のあるデータは、下記の2種類。

### (1) 商品カタログ (catalog)

```
商品ID, 商品名, 商品カテゴリ [,説明] [,特徴量1=値, 特徴量2=値,...]
```

推薦の対象となる商品のマスタとなるデータ。
最低限必要なのが 商品ID,商品名,カテゴリ の3カラムで、それに加えて任意の特徴量(最大4000個)を付与することができる。
→ [document](https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0/operations/56f316efeda5650db055a3e1)

### (2) ユーザの利用履歴 (usage)

各ユーザの商品に対する行動の履歴を表すデータ。

```
ユーザID, 商品ID ,タイムスタンプ [,Event]
```
"Event" には"Click", "Purchase" といった行動タイプが入る。

タイムスタンプ[^1]はユーザが行動を起こした時刻で、

- 評価の際に学習データと評価データを期間で分割する
- FBT(Frequently Bought Together)モデルにおいて、「同時に買った」ケースを識別する

といった用途で使われる。[^2]

→ [document](https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0/operations/56f316efeda5650db055a3e2)

[^1]: APIドキュメントにおいてTimeは必須カラムとなっているが、実際にはTimeカラムが無いデータでも動作はする。MSが配布しているサンプルデータのうち"Books.zip" のusageデータにはタイムスタンプが存在せず、そのデータで学習してモデルを作ることもできるので、タイムスタンプを含まないデータでの利用も想定されていると思われる。

[^2]: https://azure.microsoft.com/en-us/documentation/articles/cognitive-services-recommendations-buildtypes/

---


# 使ってみる

では、Microsoft が提供しているデータセットを使って実際に試してみる。

## 1. APIキーを取得
[Quick start guide](https://azure.microsoft.com/en-us/documentation/articles/cognitive-services-recommendations-quick-start/) の Task 1 の部分を見てRecommendations APIをサブスクライブし、APIキーを取得する。
(MS Azureのアカウントは前もって取得しておきましょう。)

## 2. サンプルデータのダウンロード

[こちら](https://onedrive.live.com/?authkey=%21AA_mnOjIeHFSRO4&id=8536718B52F71725%21138&cid=8536718B52F71725)から**MsStoreData.zip**をダウンロードし、展開。

下記のように、catalog,usageのデータファイルが入っている。
(usageデータはサイズが大きいので、3つに分割されている。)

```
MsStoreData.zip
└── withTimestamps
    ├── catalog.csv
    ├── usage1.csv
    ├── usage2.csv
    └── usage3.csv
```

## 3. Projectを作る
[Recommendations UI](http://recommendations-portal.azurewebsites.net/)を開き、"Account Key"の部分に1.で取得したAPIキーを入力。
適当なプロジェクト名を入力して[Add Project]でプロジェクトを作成。

## 4. catalog ファイルをアップロード

"Step 1: Add a catalog file" の [BROWSE FOR FILE...] から、 `catalog.csv`をアップロード

## 5. usage ファイルをアップロード

"Step 2: Add a usage files" の [BROWSE FOR FILE...] から、 `usage1.csv`をアップロードする。(usage2,3はアップロードしてもしなくてもよい。)

このように、ひとつのプロジェクトに対して**catalogファイルは1個だけ**、**usageファイルは複数個**アップロードすることができる。

## 6. モデルをBuildする

Buildとは、すなわちモデルの学習を行うこと。

[New Build]ボタンを押すと、モデルのビルドを行うダイアログボックスが出てくる。
ここで **モデルの種類**(Build Type) と **ビルドパラメータ** を指定することになる。
ここで適切なモデルとパラメータを選ぶことが重要になるが、それは後で詳しく見るとして、ここでは一旦下記のように設定してしまう。

Build Type = ***"Recommendation"***

|パラメータ|値|
|:--|:--|
|Number of model Iterations|20|
|Number of Model Dimension|20|
|Item Cuf-off Lower Bound|2|
|Item Cuf-off Upper Bound||
|User Cut-off Lower Bound|2|
|User Cut-off Upper Bound||
|Enable Modeling Insights|True|
|Splitter Strategy|Last Event|
|Enable U2I|True|

注意点として、Enable Modeling Insights = True にしないと、モデルの評価値を得られない。

[BUILD]ボタンを押すと、モデルのビルドが開始される。
今回のセッティングの場合、だいたい10〜20分くらいでビルドが完了する。

## 7. モデルの評価

ビルドが完了すると、Statusが"SUCCESS"に変わり、[SCORE]ボタンが押せるようになる。

![ｓｃｏｒｅ](https://qiita-image-store.s3.amazonaws.com/0/41617/d2fa9cf3-5b85-af05-1372-34c4d08f4a99.png)

[SCORE]ボタンを押すとモデルの評価画面が開き、実際に"カート"に商品を入れてみて、何が推薦されるか(Item-to-Item Recommendation)をシミュレーションで確認することができる。

![score](https://qiita-image-store.s3.amazonaws.com/0/41617/51852991-4a8c-e31f-f627-7f0633fa9191.png)

また、OFFLINE METRICS のページでは、モデルの評価指標として **Diversity** と **Precision at K** を表示できる。
(今回はUser-to-ItemとItem-to-Itemがどちらも有効になる設定でビルドしたので、それぞれについてDiversityとPrecision at Kが出力される。)

![評価値](https://qiita-image-store.s3.amazonaws.com/0/41617/98ab12f0-a172-7b2b-72e1-476d1579b69e.png)

## 8. APIとしてモデルを利用する

モデルを自分のアプリケーションに組み込む場合は、APIから呼ぶことになる。

- [Item-to-Item (API Reference)](https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0/operations/56f30d77eda5650db055a3d4)
- [User-to-Item (API Reference)](https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0/operations/56f30d77eda5650db055a3dd)

たとえば、Item-to-Item Recommendation であれば、modelId, userId, などを指定してリクエストを送ることで、下のような結果が返ってくる。
この結果をパースしてアプリケーションで利用すればよい。

リクエスト

```
https://westus.api.cognitive.microsoft.com/recommendations/v4.0/models/d4f86d2d-7a67-4ca3-9ade-72d0578bdb43/recommend/user?userId=00030000CF41798F&numberOfResults=3&buildId=1581037
```

レスポンス

```
{
  "recommendedItems": [
    {
      "items": [
        {
          "id": "DHF-00285",
          "name": "Microsoft Online Coupon SKU"
        }
      ],
      "rating": 0.574363877955354,
      "reasoning": [
        "People who like 'O365 Personal 1Mo 32/64 Alng SubPKL Onln MSStore DwnLdC2R NR RtlSyndctn' also like 'Microsoft Online Coupon SKU'"
      ]
    },
    {
      "items": [
        {
          "id": "P2W-00004",
          "name": "O365 Home 1Mo 32/64 Alng SubPKL 1Mo Onln MSStore DwnLdC2R NR RtlSyndctn"
        }
      ],
      "rating": 0.572219506909306,
      "reasoning": [
        "People who like 'O365 Personal 1Mo 32/64 Alng SubPKL Onln MSStore DwnLdC2R NR RtlSyndctn' also like 'O365 Home 1Mo 32/64 Alng SubPKL 1Mo Onln MSStore DwnLdC2R NR RtlSyndctn'"
      ]
    },
    {
      "items": [
        {
          "id": "QQ2-00031",
          "name": "Off365 Personal 32/64 Alng SubsPKL 1YR Onln MSStore DwnLd C2R NR RtlSynd"
        }
      ],
      "rating": 0.555740308646459,
      "reasoning": [
        "People who like 'O365 Personal 1Mo 32/64 Alng SubPKL Onln MSStore DwnLdC2R NR RtlSyndctn' also like 'Off365 Personal 32/64 Alng SubsPKL 1YR Onln MSStore DwnLd C2R NR RtlSynd'"
      ]
    }
  ]
}
```

# 最後に
今回は、細かい理屈は飛ばしてRecommendations APIの使い方をざっとさらった。
次回は、評価値の見方、ビルドタイプの選択方法などを詳しく見ていく予定。