快速入門:個人化工具用戶端程式庫

使用個人化工具服務顯示此快速入門中的個人化內容。

開始使用個人化工具用戶端程式庫。 請遵循下列步驟來安裝套件,並試用基本工作的程式碼範例。

  • 排名 API - 根據您就內容和上下文提供的相關即時資訊,從動作中選取最佳項目。
  • 獎勵 API - 您可以根據您的業務需求決定獎勵分數,然後使用此 API 將其傳送到個人化工具。 該分數可以是單一值,例如 1 表示良好、0 表示不良,或根據您的業務需求建立的演算法。

參考文件 | 程式庫來源程式碼 | 套件 (NuGet) | 範例

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 最新版 .NET Core
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立個人化工具資源,以取得您的金鑰和端點。 在其部署後,按一下 [前往資源]。
    • 您需要來自所建立資源的金鑰和端點,以將應用程式連線至個人化工具 API。 您稍後會在快速入門中將金鑰和端點貼到下列程式碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

變更模型更新頻率

在 Azure 入口網站中,於個人化工具資源的 [設定] 頁面上,將 [模型更新頻率] 變更為 30 秒。 這個較短的時間將會快速定型服務,讓您可以查看名次最高的動作會如何針對每個反覆項目變更。

Change model update frequency

第一次具現化個人化工具迴圈時,因為已經沒有可進行訓練的獎勵 API 呼叫,所以沒有模型。 排名呼叫會針對每個項目傳回相等的機率。 您的應用程式應該仍會一直使用 RewardActionId 的輸出來排名內容。

變更奬勵等待時間

在 Azure 入口網站中,於個人化工具資源的 [設定] 頁面上,將 [奬勵等待時間] 變更為 30 秒。 這個較短的時間將會快速定型服務,讓您可以查看名次最高的動作會如何針對每個反覆項目變更。

Change reward wait time

建立新的 C# 應用程式

在您慣用的編輯器或 IDE 中,建立新的 .NET Core 應用程式。

在主控台視窗中 (例如 cmd、PowerShell 或 Bash),使用 dotnet new 命令建立名為 personalizer-quickstart 的新主控台應用程式。 此命令會建立簡單的 "Hello World" C# 專案,內含單一原始程式檔:Program.cs

dotnet new console -n personalizer-quickstart

將目錄變更為新建立的應用程式資料夾。 您可以使用下列命令來建置應用程式:

dotnet build

建置輸出應該不會有警告或錯誤。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

安裝用戶端程式庫

在應用程式目錄中,使用下列命令安裝適用於 .NET 的個人化工具用戶端程式庫:

dotnet add package Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0

提示

如果您使用 Visual Studio IDE,則可以取得可下載 NuGet 套件形式的用戶端程式庫。

從專案目錄,在慣用的編輯器或 IDE 中開啟 Program.cs 檔案。 加入以下 using 指示詞:

using Microsoft.Azure.CognitiveServices.Personalizer;
using Microsoft.Azure.CognitiveServices.Personalizer.Models;
using System;
using System.Collections.Generic;
using System.Linq;

物件模型

個人化工具用戶端是一種 PersonalizerClient 物件,會使用含有金鑰的 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證。

若要要求內容的單一最佳時間,請建立 RankRequest,然後將其傳至 client.Rank 方法。 Rank 方法會傳回 RankResponse。

若要將獎勵分數傳送至個人化工具,請建立 RewardRequest,然後將其傳至 client.Reward 方法。

在本快速入門中,決定獎勵分數是很簡單的。 在生產系統中,判斷影響獎勵分數的因素及影響程度可能是複雜的程序,您可能會隨著時間做出變更決定。 此設計決策應該是您個人化工具架構中的其中一個主要決策。

程式碼範例

這些程式碼片段會示範如何使用適用於 .NET 的個人化工具用戶端程式庫來執行下列工作:

驗證用戶端

在本節中,您將執行兩個動作:

  • 指定您的金鑰和端點
  • 建立個人化工具用戶端

首先,將下列幾行新增至您的 Program 類別。 務必從您的個人化工具資源新增金鑰和端點。

重要

前往 Azure 入口網站。 如果您在 [必要條件] 區段中建立的個人化工具資源成功部署,請按一下 [後續步驟] 底下的 [前往資源] 按鈕。 您可以在 [資源管理] 底下的 [金鑰和端點] 頁面中找到金鑰和端點。

完成時,請記得從程式碼中移除金鑰,且不要公開張貼金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 例如,Azure金鑰保存庫

private static readonly string ApiKey = "REPLACE-WITH-YOUR-PERSONALIZER-KEY";
private static readonly string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";

接下來,將方法新增至您的程式,以建立新的個人化工具用戶端。

static PersonalizerClient InitializePersonalizerClient(string url)
{
    PersonalizerClient client = new PersonalizerClient(
        new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url };

    return client;
}

取得食物項目作為可排名的動作

動作代表您要個人化工具從中選取最佳內容項目的內容選擇。 將下列方法新增至 Program 類別,以代表動作及其特性的組合。

static IList<RankableAction> GetActions()
{
    IList<RankableAction> actions = new List<RankableAction>
    {
        new RankableAction
        {
            Id = "pasta",
            Features =
            new List<object>() { new { taste = "salty", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
        },

        new RankableAction
        {
            Id = "ice cream",
            Features =
            new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
        },

        new RankableAction
        {
            Id = "juice",
            Features =
            new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
        },

        new RankableAction
        {
            Id = "salad",
            Features =
            new List<object>() { new { taste = "salty", spiceLevel = "low" }, new { nutritionLevel = 8 } }
        }
    };

    return actions;
}

取得內容的使用者喜好設定

將下列方法新增至 [程式] 類別,以從命令列取得一天時間和目前食物喜好的使用者輸入。 這些會作為關係特性使用。

static string GetUsersTimeOfDay()
{
    string[] timeOfDayFeatures = new string[] { "morning", "afternoon", "evening", "night" };

    Console.WriteLine("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night");
    if (!int.TryParse(GetKey(), out int timeIndex) || timeIndex < 1 || timeIndex > timeOfDayFeatures.Length)
    {
        Console.WriteLine("\nEntered value is invalid. Setting feature value to " + timeOfDayFeatures[0] + ".");
        timeIndex = 1;
    }

    return timeOfDayFeatures[timeIndex - 1];
}
static string GetUsersTastePreference()
{
    string[] tasteFeatures = new string[] { "salty", "sweet" };

    Console.WriteLine("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet");
    if (!int.TryParse(GetKey(), out int tasteIndex) || tasteIndex < 1 || tasteIndex > tasteFeatures.Length)
    {
        Console.WriteLine("\nEntered value is invalid. Setting feature value to " + tasteFeatures[0] + ".");
        tasteIndex = 1;
    }

    return tasteFeatures[tasteIndex - 1];
}

這兩個方法都會使用 GetKey 方法從命令列讀取使用者的選取。

private static string GetKey()
{
    return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}

建立學習迴圈

個人化工具學習迴圈是排名獎勵呼叫的循環。 在本快速入門中,用於個人化內容的每個排名呼叫後面都會接著獎勵呼叫,以告訴個人化工具該服務的成效為何。

下列程式碼會在命令列上進行詢問使用者喜好的循環迴圈,並將該資訊傳送至個人化工具以選取最佳動作,然後向客戶顯示選取項目,讓他們從清單中選擇,接著將獎勵分數傳送至個人化工具,告知服務的成效為何。

static void Main(string[] args)
{
    int iteration = 1;
    bool runLoop = true;

    IList<RankableAction> actions = GetActions();

    PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);

    do
    {
        Console.WriteLine("\nIteration: " + iteration++);

        string timeOfDayFeature = GetUsersTimeOfDay();
        string tasteFeature = GetUsersTastePreference();

        IList<object> currentContext = new List<object>() {
            new { time = timeOfDayFeature },
            new { taste = tasteFeature }
        };

        IList<string> excludeActions = new List<string> { "juice" };

        string eventId = Guid.NewGuid().ToString();

        var request = new RankRequest(actions, currentContext, excludeActions, eventId);
        RankResponse response = client.Rank(request);

        Console.WriteLine("\nPersonalizer service thinks you would like to have: " + response.RewardActionId + ". Is this correct? (y/n)");

        float reward = 0.0f;
        string answer = GetKey();

        if (answer == "Y")
        {
            reward = 1;
            Console.WriteLine("\nGreat! Enjoy your food.");
        }
        else if (answer == "N")
        {
            reward = 0;
            Console.WriteLine("\nYou didn't like the recommended food choice.");
        }
        else
        {
            Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended food choice.");
        }

        Console.WriteLine("\nPersonalizer service ranked the actions with the probabilities as below:");
        foreach (var rankedResponse in response.Ranking)
        {
            Console.WriteLine(rankedResponse.Id + " " + rankedResponse.Probability);
        }

        client.Reward(response.EventId, new RewardRequest(reward));

        Console.WriteLine("\nPress q to break, any other key to continue:");
        runLoop = !(GetKey() == "Q");

    } while (runLoop);
}

新增下列方法,以在執行程式碼檔案之前,取得內容選項

  • GetActions
  • GetUsersTimeOfDay
  • GetUsersTastePreference
  • GetKey

要求最佳動作

為了完成排名要求,程式會詢問使用者的喜好,以建立內容選擇的 currentContext。 程式可以建立從動作中排除的內容,如 excludeActions 所示。 排名要求需要動作及其特性、currentContext 特性、excludeActions 和唯一排名事件識別碼,才能接收回應。

本快速入門有一天時間和使用者食物喜好的簡單關係特性。 在生產系統中,判斷和評估動作和特性可能不是簡單的事。

string timeOfDayFeature = GetUsersTimeOfDay();
string tasteFeature = GetUsersTastePreference();

IList<object> currentContext = new List<object>() {
    new { time = timeOfDayFeature },
    new { taste = tasteFeature }
};

IList<string> excludeActions = new List<string> { "juice" };

string eventId = Guid.NewGuid().ToString();

var request = new RankRequest(actions, currentContext, excludeActions, eventId);
RankResponse response = client.Rank(request);

傳送獎勵

若要取得獎勵分數以在獎勵要求中傳送,程式會從命令列取得使用者的選取項目,將數值指派給選取項目,然後將唯一的事件識別碼和獎勵分數當作數值傳送至獎勵 API。

本快速入門會指派簡單的數字作為獎勵分數,也就是零或 1。 在生產系統中,視您的特定需求而定,判斷要傳送給獎勵呼叫的時機和內容可能不是簡單的事。

float reward = 0.0f;
string answer = GetKey();

if (answer == "Y")
{
    reward = 1;
    Console.WriteLine("\nGreat! Enjoy your food.");
}
else if (answer == "N")
{
    reward = 0;
    Console.WriteLine("\nYou didn't like the recommended food choice.");
}
else
{
    Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended food choice.");
}

Console.WriteLine("\nPersonalizer service ranked the actions with the probabilities as below:");
foreach (var rankedResponse in response.Ranking)
{
    Console.WriteLine(rankedResponse.Id + " " + rankedResponse.Probability);
}

// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));

執行程式

從應用程式目錄使用 dotnet run 命令來執行應用程式。

dotnet run

The quickstart program asks a couple of questions to gather user preferences, known as features, then provides the top action.

這裡可取得適用於此快速入門的原始程式碼

參考文件 |程式庫來源程式碼 | 套件 (NPM) | 範例

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 安裝 Node.js \(英文\) 和 NPM (已使用 Node.js v14.16.0 和 NPM 6.14.11 進行驗證)。
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立個人化工具資源,以取得您的金鑰和端點。 在其部署後,按一下 [前往資源]。
    • 您需要來自所建立資源的金鑰和端點,以將應用程式連線至個人化工具 API。 您稍後會在快速入門中將金鑰和端點貼到下列程式碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

變更模型更新頻率

在 Azure 入口網站中,於個人化工具資源的 [設定] 頁面上,將 [模型更新頻率] 變更為 30 秒。 這個較短的時間將會快速定型服務,讓您可以查看名次最高的動作會如何針對每個反覆項目變更。

Change model update frequency

第一次具現化個人化工具迴圈時,因為已經沒有可進行訓練的獎勵 API 呼叫,所以沒有模型。 排名呼叫會針對每個項目傳回相等的機率。 您的應用程式應該仍會一直使用 RewardActionId 的輸出來排名內容。

變更奬勵等待時間

在 Azure 入口網站中,於個人化工具資源的 [設定] 頁面上,將 [奬勵等待時間] 變更為 30 秒。 這個較短的時間將會快速定型服務,讓您可以查看名次最高的動作會如何針對每個反覆項目變更。

Change reward wait time

建立新的 Node.js 應用程式

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中,為您的應用程式建立新的目錄,並瀏覽至該目錄。

mkdir myapp && cd myapp

執行 npm init -y 命令以建立 package.json 檔案。

npm init -y

在您慣用的編輯器或 IDE 中,建立名為 sample.js 的新 Node.js 應用程式,並為您的資源端點和訂用帳戶金鑰建立變數。

重要

前往 Azure 入口網站。 如果您在 [必要條件] 區段中建立的個人化工具資源成功部署,請按一下 [後續步驟] 底下的 [前往資源] 按鈕。 您可以在 [資源管理] 底下的 [金鑰和端點] 頁面中找到金鑰和端點。

完成時,請記得從程式碼中移除金鑰,且不要公開張貼金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 例如,Azure金鑰保存庫

const uuidv1 = require('uuid/v1');
const Personalizer = require('@azure/cognitiveservices-personalizer');
const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const readline = require('readline-sync');

// The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
const serviceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";

// The endpoint specific to your personalization service instance; 
// e.g. https://<your-resource-name>.cognitiveservices.azure.com
const baseUri = "https://<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>.cognitiveservices.azure.com";

安裝 Node.js 個人化工具程式庫

使用下列命令安裝適用於 Node.js 的個人化工具用戶端程式庫:

npm install @azure/cognitiveservices-personalizer --save

安裝本快速入門的其餘 NPM 套件:

npm install @azure/ms-rest-azure-js @azure/ms-rest-js readline-sync uuid --save

物件模型

個人化工具用戶端是一種 PersonalizerClient 物件,會使用含有金鑰的 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證。

若要要求內容的單一最佳時間,請建立 RankRequest,然後將其傳至 client.Rank 方法。 Rank 方法會傳回 RankResponse。

若要將獎勵傳送至個人化工具,請建立 RewardRequest,然後將其傳遞至 Events 類別上的 Reward 方法。

在本快速入門中,決定獎勵是很簡單的。 在生產系統中,判斷影響獎勵分數的因素及影響程度可能是複雜的程序,您可能會隨著時間做出變更決定。 這應該是個人化工具架構中的一個主要設計決策。

程式碼範例

這些程式碼片段會示範如何使用適用於 Node.js 的個人化工具用戶端程式庫來執行下列動作:

驗證用戶端

使用您稍早建立的 serviceKeybaseUri 來具現化 PersonalizerClient

const credentials = new CognitiveServicesCredentials(serviceKey);

// Initialize Personalization client.
const personalizerClient = new Personalizer.PersonalizerClient(credentials, baseUri);

取得以動作表示的內容選擇

動作代表您要個人化工具從中選取最佳內容項目的內容選擇。 將下列方法新增至 Program 類別,以代表動作及其特性的組合。

function getContextFeaturesList() {
  const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
  const tasteFeatures = ['salty', 'sweet'];

  let answer = readline.question("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n");
  let selection = parseInt(answer);
  const timeOfDay = selection >= 1 && selection <= 4 ? timeOfDayFeatures[selection - 1] : timeOfDayFeatures[0];

  answer = readline.question("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet\n");
  selection = parseInt(answer);
  const taste = selection >= 1 && selection <= 2 ? tasteFeatures[selection - 1] : tasteFeatures[0];

  console.log("Selected features:\n");
  console.log("Time of day: " + timeOfDay + "\n");
  console.log("Taste: " + taste + "\n");

  return [
    {
      "time": timeOfDay
    },
    {
      "taste": taste
    }
  ];
}
function getActionsList() {
  return [
    {
      "id": "pasta",
      "features": [
        {
          "taste": "salty",
          "spiceLevel": "medium"
        },
        {
          "nutritionLevel": 5,
          "cuisine": "italian"
        }
      ]
    },
    {
      "id": "ice cream",
      "features": [
        {
          "taste": "sweet",
          "spiceLevel": "none"
        },
        {
          "nutritionalLevel": 2
        }
      ]
    },
    {
      "id": "juice",
      "features": [
        {
          "taste": "sweet",
          "spiceLevel": "none"
        },
        {
          "nutritionLevel": 5
        },
        {
          "drink": true
        }
      ]
    },
    {
      "id": "salad",
      "features": [
        {
          "taste": "salty",
          "spiceLevel": "low"
        },
        {
          "nutritionLevel": 8
        }
      ]
    }
  ];
}

建立學習迴圈

個人化工具學習迴圈是排名獎勵呼叫的循環。 在本快速入門中,用於個人化內容的每個排名呼叫後面都會接著獎勵呼叫,以告訴個人化工具該服務的成效為何。

下列程式碼會在命令列上進行詢問使用者喜好的循環迴圈,並將該資訊傳送至個人化工具以選取最佳動作,然後向客戶顯示選取項目,讓他們從清單中選擇,接著將獎勵傳送至個人化工具,告知服務的成效為何。

let runLoop = true;

do {

  let rankRequest = {}

  // Generate an ID to associate with the request.
  rankRequest.eventId = uuidv1();

  // Get context information from the user.
  rankRequest.contextFeatures = getContextFeaturesList();

  // Get the actions list to choose from personalization with their features.
  rankRequest.actions = getActionsList();

  // Exclude an action for personalization ranking. This action will be held at its current position.
  rankRequest.excludedActions = getExcludedActionsList();

  rankRequest.deferActivation = false;

  // Rank the actions
  const rankResponse = await personalizerClient.rank(rankRequest);

  console.log("\nPersonalization service thinks you would like to have:\n")
  console.log(rankResponse.rewardActionId);

  // Display top choice to user, user agrees or disagrees with top choice
  const reward = getReward();

  console.log("\nPersonalization service ranked the actions with the probabilities as below:\n");
  for (let i = 0; i < rankResponse.ranking.length; i++) {
    console.log(JSON.stringify(rankResponse.ranking[i]) + "\n");
  }

  // Send the reward for the action based on user response.

  const rewardRequest = {
    value: reward
  }

  await personalizerClient.events.reward(rankRequest.eventId, rewardRequest);

  runLoop = continueLoop();

} while (runLoop);

請仔細查看下列各節中的排名和報酬呼叫。

新增下列方法,以在執行程式碼檔案之前,取得內容選項

  • getActionsList
  • getContextFeaturesList

要求最佳動作

為了完成排名要求,程式會詢問使用者的喜好來建立內容選擇。 程式可以建立從動作中排除的內容,如 excludeActions 所示。 排名要求需要動作及其特性、currentContext 特性、excludeActions 和唯一排名事件識別碼,才能接收已排名的回應。

本快速入門有一天時間和使用者食物喜好的簡單關係特性。 在生產系統中,判斷和評估動作和特性可能不是簡單的事。

let rankRequest = {}

// Generate an ID to associate with the request.
rankRequest.eventId = uuidv1();

// Get context information from the user.
rankRequest.contextFeatures = getContextFeaturesList();

// Get the actions list to choose from personalization with their features.
rankRequest.actions = getActionsList();

// Exclude an action for personalization ranking. This action will be held at its current position.
rankRequest.excludedActions = getExcludedActionsList();

rankRequest.deferActivation = false;

// Rank the actions
const rankResponse = await personalizerClient.rank(rankRequest);

傳送獎勵

若要取得獎勵分數以在獎勵要求中傳送,程式會從命令列取得使用者的選取項目,將數值指派給選取項目,然後將唯一的事件識別碼和獎勵分數當作數值傳送至獎勵 API。

本快速入門會指派簡單的數字作為獎勵分數,也就是零或 1。 在生產系統中,視您的特定需求而定,判斷要傳送給獎勵呼叫的時機和內容可能不是簡單的事。

const rewardRequest = {
  value: reward
}

await personalizerClient.events.reward(rankRequest.eventId, rewardRequest);

執行程式

使用 Node.js 從您的應用程式目錄執行應用程式。

node sample.js

The quickstart program asks a couple of questions to gather user preferences, known as features, then provides the top action.

參考文件 | 程式庫來源程式碼 | 套件 (pypi) | 範例

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • Python 3.x
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立個人化工具資源,以取得您的金鑰和端點。 在其部署後,按一下 [前往資源]。
    • 您需要來自所建立資源的金鑰和端點,以將應用程式連線至個人化工具 API。 您稍後會在快速入門中將金鑰和端點貼到下列程式碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

變更模型更新頻率

在 Azure 入口網站中,於個人化工具資源的 [設定] 頁面上,將 [模型更新頻率] 變更為 30 秒。 這個較短的時間將會快速定型服務,讓您可以查看名次最高的動作會如何針對每個反覆項目變更。

Change model update frequency

第一次具現化個人化工具迴圈時,因為已經沒有可進行訓練的獎勵 API 呼叫,所以沒有模型。 排名呼叫會針對每個項目傳回相等的機率。 您的應用程式應該仍會一直使用 RewardActionId 的輸出來排名內容。

變更奬勵等待時間

在 Azure 入口網站中,於個人化工具資源的 [設定] 頁面上,將 [奬勵等待時間] 變更為 30 秒。 這個較短的時間將會快速定型服務,讓您可以查看名次最高的動作會如何針對每個反覆項目變更。

Change reward wait time

安裝用戶端程式庫

安裝 Python 之後,您可以透過以下項目安裝用戶端程式庫:

pip install azure-cognitiveservices-personalizer

建立新的 Python 應用程式

建立新的 Python 檔案,並為資源的端點和訂用帳戶金鑰建立變數。

重要

前往 Azure 入口網站。 如果您在 [必要條件] 區段中建立的個人化工具資源成功部署,請按一下 [後續步驟] 底下的 [前往資源] 按鈕。 您可以在 [資源管理] 底下的 [金鑰和端點] 頁面中找到金鑰和端點。

完成時,請記得從程式碼中移除金鑰,且不要公開張貼金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 例如,Azure金鑰保存庫

from azure.cognitiveservices.personalizer import PersonalizerClient
from azure.cognitiveservices.personalizer.models import RankableAction, RewardRequest, RankRequest
from msrest.authentication import CognitiveServicesCredentials

import datetime, json, os, time, uuid

key = "<paste-your-personalizer-key-here>"
endpoint = "<paste-your-personalizer-endpoint-here>"

物件模型

個人化工具用戶端是一種 PersonalizerClient 物件,會使用含有金鑰的 Microsoft.Rest.ServiceClientCredentials 向 Azure 進行驗證。

若要要求內容的單一最佳時間,請建立 RankRequest,然後將其傳至 client.Rank 方法。 Rank 方法會傳回 RankResponse。

若要將獎勵分數傳送至個人化工具,請將事件識別碼和獎勵分數 (值) 設定為傳送至 EventOperations 類別上的 Reward 方法。

在本快速入門中,決定獎勵是很簡單的。 在生產系統中,判斷影響獎勵分數的因素及影響程度可能是複雜的程序,您可能會隨著時間做出變更決定。 這應該是個人化工具架構中的一個主要設計決策。

程式碼範例

這些程式碼片段會說明如何使用適用於 Python 的個人化工具用戶端程式庫執行下列動作:

驗證用戶端

使用您稍早建立的 keyendpoint 來具現化 PersonalizerClient

# Instantiate a Personalizer client
client = PersonalizerClient(endpoint, CognitiveServicesCredentials(key))

取得以動作表示的內容選擇

動作代表您要個人化工具從中選取最佳內容項目的內容選擇。 將下列方法新增至 Program 類別,以代表動作及其特性的組合。

def get_actions():
    action1 = RankableAction(id='pasta', features=[{"taste":"salty", "spice_level":"medium"},{"nutrition_level":5,"cuisine":"italian"}])
    action2 = RankableAction(id='ice cream', features=[{"taste":"sweet", "spice_level":"none"}, { "nutritional_level": 2 }])
    action3 = RankableAction(id='juice', features=[{"taste":"sweet", 'spice_level':'none'}, {'nutritional_level': 5}, {'drink':True}])
    action4 = RankableAction(id='salad', features=[{'taste':'salty', 'spice_level':'none'},{'nutritional_level': 2}])
    return [action1, action2, action3, action4]
def get_user_timeofday():
    res={}
    time_features = ["morning", "afternoon", "evening", "night"]
    time = input("What time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n")
    try:
        ptime = int(time)
        if(ptime<=0 or ptime>len(time_features)):
            raise IndexError
        res['time_of_day'] = time_features[ptime-1]
    except (ValueError, IndexError):
        print("Entered value is invalid. Setting feature value to", time_features[0] + ".")
        res['time_of_day'] = time_features[0]
    return res
def get_user_preference():
    res = {}
    taste_features = ['salty','sweet']
    pref = input("What type of food would you prefer? Enter number 1.salty 2.sweet\n")
    
    try:
        ppref = int(pref)
        if(ppref<=0 or ppref>len(taste_features)):
            raise IndexError
        res['taste_preference'] = taste_features[ppref-1]
    except (ValueError, IndexError):
        print("Entered value is invalid. Setting feature value to", taste_features[0]+ ".")
        res['taste_preference'] = taste_features[0]
    return res

建立學習迴圈

個人化工具學習迴圈是排名獎勵呼叫的循環。 在本快速入門中,用於個人化內容的每個排名呼叫後面都會接著獎勵呼叫,以告訴個人化工具該服務的成效為何。

下列程式碼會在命令列上進行詢問使用者喜好的循環迴圈,並將該資訊傳送至個人化工具以選取最佳動作,然後向客戶顯示選取項目,讓他們從清單中選擇,接著將獎勵傳送至個人化工具,告知服務的成效為何。

keep_going = True
while keep_going:

    eventid = str(uuid.uuid4())

    context = [get_user_preference(), get_user_timeofday()]
    actions = get_actions()

    rank_request = RankRequest( actions=actions, context_features=context, excluded_actions=['juice'], event_id=eventid)
    response = client.rank(rank_request=rank_request)
    
    print("Personalizer service ranked the actions with the probabilities listed below:")
    
    rankedList = response.ranking
    for ranked in rankedList:
        print(ranked.id, ':',ranked.probability)

    print("Personalizer thinks you would like to have", response.reward_action_id+".")
    answer = input("Is this correct?(y/n)\n")[0]

    reward_val = "0.0"
    if(answer.lower()=='y'):
        reward_val = "1.0"
    elif(answer.lower()=='n'):
        reward_val = "0.0"
    else:
        print("Entered choice is invalid. Service assumes that you didn't like the recommended food choice.")

    client.events.reward(event_id=eventid, value=reward_val)

    br = input("Press Q to exit, any other key to continue: ")
    if(br.lower()=='q'):
        keep_going = False

新增下列方法,以在執行程式碼檔案之前,取得內容選項

  • get_user_preference
  • get_user_timeofday
  • get_actions

要求最佳動作

為了完成排名要求,程式會詢問使用者的喜好,以建立內容選擇的 currentContent。 程式可以建立從動作中排除的內容,如 excludeActions 所示。 排名要求需要動作及其特性、currentContext 特性、excludeActions 和唯一排名事件識別碼,才能接收回應。

本快速入門有一天時間和使用者食物喜好的簡單關係特性。 在生產系統中,判斷和評估動作和特性可能不是簡單的事。

rank_request = RankRequest( actions=actions, context_features=context, excluded_actions=['juice'], event_id=eventid)
response = client.rank(rank_request=rank_request)

傳送獎勵

若要取得獎勵分數以在獎勵要求中傳送,程式會從命令列取得使用者的選取項目,將數值指派給選取項目,然後將唯一的事件識別碼和獎勵分數當作數值傳送至獎勵 API。

本快速入門會指派簡單的數字作為獎勵分數,也就是零或 1。 在生產系統中,視您的特定需求而定,判斷要傳送給獎勵呼叫的時機和內容可能不是簡單的事。

reward_val = "0.0"
if(answer.lower()=='y'):
    reward_val = "1.0"
elif(answer.lower()=='n'):
    reward_val = "0.0"
else:
    print("Entered choice is invalid. Service assumes that you didn't like the recommended food choice.")

client.events.reward(event_id=eventid, value=reward_val)

執行程式

從應用程式目錄使用 Python 執行應用程式。

python sample.py

The quickstart program asks a couple of questions to gather user preferences, known as features, then provides the top action.

清除資源

如果您想要清除和移除認知服務訂用帳戶,則可以刪除資源或資源群組。 刪除資源群組也會刪除其關聯的任何其他資源。

後續步驟