Snabb start: klient bibliotek för PersonanpassareQuickstart: Personalizer client library

Visa personligt innehåll i den här snabb starten med tjänsten personanpassa.Display personalized content in this quickstart with the Personalizer service.

Kom igång med personanpassa klient biblioteket.Get started with the Personalizer client library. Följ de här stegen för att installera paketet och prova exempel koden för grundläggande uppgifter.Follow these steps to install the package and try out the example code for basic tasks.

  • Rang-API – väljer det bästa objektet, från åtgärder, baserat på information i real tid som du anger om innehåll och kontext.Rank API - Selects the best item, from actions, based on real-time information you provide about content and context.
  • Belönings-API – du fastställer belönings poängen utifrån dina affärs behov och skickar det sedan till en Personligre med detta API.Reward API - You determine the reward score based on your business needs, then send it to Personalizer with this API. Poängen kan vara ett enda värde, till exempel 1 för bra, och 0 för dåligt eller en algoritm som du skapar utifrån dina affärs behov.That score can be a single value such as 1 for good, and 0 for bad, or an algorithm you create based on your business needs.

Referens dokumentation | bibliotek käll kods | paket (NuGet) | exempelReference documentation | Library source code | Package (NuGet) | Samples

KravPrerequisites

Använd den här snabb startenUsing this quickstart

Det finns flera steg för att använda den här snabb starten:There are several steps to use this quickstart:

  • I Azure Portal skapar du en personanpassar-resursIn the Azure portal, create a Personalizer resource
  • I Azure Portal för personanpassa resursen, på sidan konfiguration , ändrar du modell uppdaterings frekvensen till ett mycket kort intervallIn the Azure portal, for the Personalizer resource, on the Configuration page, change the model update frequency to a very short interval
  • Skapa en kod fil i en kod redigerare och redigera kod filenIn a code editor, create a code file and edit the code file
  • På kommando raden eller terminalen installerar du SDK från kommando radenIn the command line or terminal, install the SDK from the command line
  • Kör kod filen i kommando raden eller terminalenIn the command line or terminal, run the code file

Skapa en personanpassa Azure-resursCreate a Personalizer Azure resource

Skapa en resurs för Personanpassare med hjälp av Azure Portal eller Azure CLI på den lokala datorn.Create a resource for Personalizer using the Azure portal or Azure CLI on your local machine.

När du har skaffat en nyckel från din resurs skapar du två miljö variabel:After you get a key from your resource, create two environment variable:

  • PERSONALIZER_RESOURCE_KEYför resurs nyckeln.PERSONALIZER_RESOURCE_KEY for the resource key.
  • PERSONALIZER_RESOURCE_ENDPOINTför resurs slut punkten.PERSONALIZER_RESOURCE_ENDPOINT for the resource endpoint.

I Azure Portal är både nyckel-och slut punkts värden tillgängliga från snabb starts sidan.In the Azure portal, both the key and endpoint values are available from the quickstart page.

Ändra modell uppdaterings frekvensenChange the model update frequency

I Azure Portal i gruppen personanpassa på sidan konfiguration ändrar du modell uppdaterings frekvensen till 10 sekunder.In the Azure portal, in the Personalizer resource on the Configuration page, change the Model update frequency to 10 seconds. Den här korta varaktigheten kommer att träna tjänsten snabbt, så att du kan se hur de viktigaste åtgärderna ändras för varje iteration.This short duration will train the service rapidly, allowing you to see how the top action changes for each iteration.

Ändra modell uppdaterings frekvens

När en säkerhetsslinga först instansieras finns det ingen modell eftersom det inte har skett några belönings-API-anrop att träna från.When a Personalizer loop is first instantiated, there is no model since there has been no Reward API calls to train from. Ranknings anrop returnerar lika många sannolikheter för varje objekt.Rank calls will return equal probabilities for each item. Ditt program borde fortfarande alltid rangordna innehåll med hjälp av utdata från RewardActionId.Your application should still always rank content using the output of RewardActionId.

Skapa ett nytt C#-programCreate a new C# application

Skapa ett nytt .NET Core-program i önskat redigerings program eller IDE.Create a new .NET Core application in your preferred editor or IDE.

I ett konsol fönster (till exempel cmd, PowerShell eller bash) använder du kommandot dotNet new för att skapa en ny konsol app med namnet. personalizer-quickstartIn a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name personalizer-quickstart. Det här kommandot skapar ett enkelt "Hello World" C#-projekt med en enda käll Program.csfil:.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

dotnet new console -n personalizer-quickstart

Ändra katalogen till mappen nyligen skapade appar.Change your directory to the newly created app folder. Du kan bygga programmet med:You can build the application with:

dotnet build

Build-utdata får inte innehålla varningar eller fel.The build output should contain no warnings or errors.

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

Installera SDK:nInstall the SDK

I program katalogen installerar du ett installations program för personanpassa klient bibliotek för .NET med följande kommando:Within the application directory, install the Personalizer client library for .NET with the following command:

dotnet add package Microsoft.Azure.CognitiveServices.Personalizer --version 0.8.0-preview

Om du använder Visual Studio IDE är klient biblioteket tillgängligt som ett nedladdnings Bart NuGet-paket.If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

Objekt modellObject model

Personanpassa klienten är ett PersonalizerClient -objekt som autentiserar till Azure med hjälp av Microsoft. rest. ServiceClientCredentials, som innehåller din nyckel.The Personalizer client is a PersonalizerClient object that authenticates to Azure using Microsoft.Rest.ServiceClientCredentials, which contains your key.

Om du vill be om det enda bästa objektet i innehållet skapar du en RankRequestoch skickar det sedan till klienten. Rangordnings metod.To ask for the single best item of the content, create a RankRequest, then pass it to client.Rank method. Rangordnings metoden returnerar en RankResponse.The Rank method returns a RankResponse.

Om du vill skicka en belönings poäng till Personanpassaren skapar du en RewardRequestoch skickar den till klienten. Belönings metod.To send a reward score to Personalizer, create a RewardRequest, then pass it to the client.Reward method.

Att fastställa belönings poängen i den här snabb starten är trivial.Determining the reward score, in this quickstart is trivial. I ett produktions system kan du bestämma vad som påverkar belönings poängen och hur mycket som kan vara en komplicerad process som du kan välja att ändra med tiden.In a production system, the determination of what impacts the reward score and by how much can be a complex process, that you may decide to change over time. Det här design beslutet bör vara ett av de viktigaste besluten i din personanpassa arkitektur.This design decision should be one of the primary decisions in your Personalizer architecture.

KodexempelCode examples

De här kodfragmenten visar hur du utför följande uppgifter med personanpassa klient biblioteket för .NET:These code snippets show you how to do the following tasks with the Personalizer client library for .NET:

Lägg till beroendenAdd the dependencies

Från projekt katalogen öppnar du program.cs -filen i önskat redigerings program eller IDE.From the project directory, open the Program.cs file in your preferred editor or IDE. Ersätt den befintliga using koden med följande using direktiv:Replace the existing using code with the following using directives:

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

Lägg till information om personanpassa resurserAdd Personalizer resource information

I program -klassen skapar du variabler för din resurs Azure-nyckel och slut punkt från miljövariablerna, med PERSONALIZER_RESOURCE_KEY namnet PERSONALIZER_RESOURCE_ENDPOINToch.In the Program class, create variables for your resource's Azure key and endpoint pulled from the environment variables, named PERSONALIZER_RESOURCE_KEY and PERSONALIZER_RESOURCE_ENDPOINT. Om du har skapat miljövariablerna när programmet har startats måste redigeraren, IDE eller gränssnittet som kör det stängas och läsas in igen för att få åtkomst till variabeln.If you created the environment variables after the application is launched, the editor, IDE, or shell running it will need to be closed and reloaded to access the variable. Metoderna kommer att skapas senare i den här snabb starten.The methods will be created later in this quickstart.

// The key specific to your personalizer resource instance; e.g. "0123456789abcdef0123456789ABCDEF"
private static readonly string ApiKey = Environment.GetEnvironmentVariable("PERSONALIZER_RESOURCE_KEY");

// The endpoint specific to your personalizer resource instance; e.g. https://westus2.api.cognitive.microsoft.com/
private static readonly string ServiceEndpoint = Environment.GetEnvironmentVariable("PERSONALIZER_RESOURCE_ENDPOINT");

Skapa en personanpassa klientCreate a Personalizer client

Skapa sedan en metod för att returnera en personanpassa klient.Next, create a method to return a Personalizer client. Parametern till-metoden är PERSONALIZER_RESOURCE_ENDPOINT och ApiKey är. PERSONALIZER_RESOURCE_KEYThe parameter to the method is the PERSONALIZER_RESOURCE_ENDPOINT and the ApiKey is the PERSONALIZER_RESOURCE_KEY.

/// <summary>
/// Initializes the personalizer client.
/// </summary>
/// <param name="url">Azure endpoint</param>
/// <returns>Personalizer client instance</returns>
static PersonalizerClient InitializePersonalizerClient(string url)
{
    PersonalizerClient client = new PersonalizerClient(
        new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url };

    return client;
}

Hämta mat objekt som ranknings bara åtgärderGet food items as rankable actions

Åtgärder representerar de innehålls val som du vill att en Personanpassare ska välja det bästa innehålls objektet från.Actions represent the content choices from which you want Personalizer to select the best content item. Lägg till följande metoder i program-klassen för att representera uppsättningen med åtgärder och deras funktioner.Add the following methods to the Program class to represent the set of actions and their features.

/// <summary>
/// Creates personalizer actions feature list.
/// </summary>
/// <returns>List of actions for personalizer.</returns>
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;
}

Hämta användar inställningar för kontextGet user preferences for context

Lägg till följande metoder i program-klassen för att få en användares indata från kommando raden för tid på dag och aktuell kost preferens.Add the following methods to the Program class to get a user's input from the command line for the time of day and current food preference. Dessa kommer att användas som Sammanhangs beroende funktioner.These will be used as context features.

/// <summary>
/// Get users time of the day context.
/// </summary>
/// <returns>Time of day feature selected by the user.</returns>
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];
}
/// <summary>
/// Gets user food preference.
/// </summary>
/// <returns>Food taste feature selected by the user.</returns>
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];
}

Båda metoderna använder GetKey metoden för att läsa användarens val från kommando raden.Both methods use the GetKey method to read the user's selection from the command line.

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

Skapa inlärnings slinganCreate the learning loop

Inlärnings-loopen för inlärning är en cykel av rang -och belönings samtal.The Personalizer learning loop is a cycle of Rank and Reward calls. I den här snabb starten, som varje rang anrop, för att anpassa innehållet, följs av ett belönings samtal för att berätta för personanpassa hur väl tjänsten utförs.In this quickstart, each Rank call, to personalize the content, is followed by a Reward call to tell Personalizer how well the service performed.

Följande kod går igenom en cykel som ber användaren att ange sina inställningar på kommando raden, vilket innebär att informationen skickas till Personanpassare för att välja den bästa åtgärden, vilket innebär att valet av kund kan välja bland listan och sedan skicka en belönings poäng till en personlig signalering av hur väl tjänsten gjorde sitt val.The following code loops through a cycle of asking the user their preferences at the command line, sending that information to Personalizer to select the best action, presenting the selection to the customer to choose from among the list, then sending a reward score to Personalizer signaling how well the service did in its selection.

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

    // Get the actions list to choose from personalizer with their features.
    IList<RankableAction> actions = GetActions();

    // Initialize Personalizer client.
    PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);

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

        // Get context information from the user.
        string timeOfDayFeature = GetUsersTimeOfDay();
        string tasteFeature = GetUsersTastePreference();

        // Create current context from user specified data.
        IList<object> currentContext = new List<object>() {
            new { time = timeOfDayFeature },
            new { taste = tasteFeature }
        };

        // Exclude an action for personalizer ranking. This action will be held at its current position.
        // This simulates a business rule to force the action "juice" to be ignored in the ranking.
        // As juice is excluded, the return of the API will always be with a probability of 0.
        IList<string> excludeActions = new List<string> { "juice" };

        // Generate an ID to associate with the request.
        string eventId = Guid.NewGuid().ToString();

        // Rank the actions
        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);
        }

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

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

    } while (runLoop);
}

Lägg till följande metoder, som hämtar innehålls valen, innan du kör kod filen:Add the following methods, which get the content choices, before running the code file:

  • GetActions
  • GetUsersTimeOfDay
  • GetUsersTastePreference
  • GetKey

Begär den bästa åtgärdenRequest the best action

För att slutföra ranknings förfrågan ställer programmet till användarens inställningar för att skapa ett currentContent av innehålls valen.To complete the Rank request, the program asks the user's preferences to create a currentContent of the content choices. Processen kan skapa innehåll som ska undantas från åtgärder, som visas excludeActionssom.The process can create content to exclude from the actions, shown as excludeActions. Ranknings förfrågan behöver åtgärder och deras funktioner, currentContext-funktioner, excludeActions och ett unikt händelse-ID för att få svaret.The Rank request needs the actions and their features, currentContext features, excludeActions, and a unique event ID, to receive the response.

Den här snabb starten har enkla Sammanhangs funktioner i tid på dygnet och användarens mat preferenser.This quickstart has simple context features of time of day and user food preference. I produktions system kan det vara en icke-trivial sak att fastställa och utvärdera åtgärder och funktioner .In production systems, determining and evaluating actions and features can be a non-trivial matter.

// Get context information from the user.
string timeOfDayFeature = GetUsersTimeOfDay();
string tasteFeature = GetUsersTastePreference();

// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
    new { time = timeOfDayFeature },
    new { taste = tasteFeature }
};

// Exclude an action for personalizer ranking. This action will be held at its current position.
// This simulates a business rule to force the action "juice" to be ignored in the ranking.
// As juice is excluded, the return of the API will always be with a probability of 0.
IList<string> excludeActions = new List<string> { "juice" };

// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();

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

Skicka en belöningSend a reward

För att få belönings poängen att skicka i belönings förfrågan får programmet användarens val från kommando raden, tilldelar ett numeriskt värde till markeringen och skickar sedan det unika händelse-ID: t och belönings poängen som det numeriska värdet till belönings-API: et.To get the reward score to send in the Reward request, the program gets the user's selection from the command line, assigns a numeric value to the selection, then sends the unique event ID and the reward score as the numeric value to the Reward API.

Den här snabb starten tilldelar ett enkelt tal som en belönings poäng, antingen noll eller 1.This quickstart assigns a simple number as a reward score, either a zero or a 1. I produktions system kan du fastställa när och vad som ska skickas till belönings anropet som en icke-trivial fråga, beroende på dina behov.In production systems, determining when and what to send to the Reward call can be a non-trivial matter, depending on your specific needs.

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));

Köra programmetRun the program

Kör programmet med kommandot dotNet run från program katalogen.Run the application with the dotnet run command from your application directory.

dotnet run

Snabb start programmet ber några frågor om att samla in användar inställningar, kallas funktioner, och ger sedan den främsta åtgärden.

Käll koden för den här snabb starten är tillgänglig i GitHub-lagringsplatsen för personanpassa exempel.The source code for this quickstart is available in the Personalizer samples GitHub repository.

Referens dokumentation |bibliotek käll kods | paket (NPM) | exempelReference documentation |Library source code | Package (NPM) | Samples

KravPrerequisites

Använd den här snabb startenUsing this quickstart

Det finns flera steg för att använda den här snabb starten:There are several steps to use this quickstart:

  • I Azure Portal skapar du en personanpassar-resursIn the Azure portal, create a Personalizer resource
  • I Azure Portal för personanpassa resursen, på sidan konfiguration , ändrar du modell uppdaterings frekvensen till ett mycket kort intervallIn the Azure portal, for the Personalizer resource, on the Configuration page, change the model update frequency to a very short interval
  • Skapa en kod fil i en kod redigerare och redigera kod filenIn a code editor, create a code file and edit the code file
  • På kommando raden eller terminalen installerar du SDK från kommando radenIn the command line or terminal, install the SDK from the command line
  • Kör kod filen i kommando raden eller terminalenIn the command line or terminal, run the code file

Skapa en personanpassa Azure-resursCreate a Personalizer Azure resource

Skapa en resurs för Personanpassare med hjälp av Azure Portal eller Azure CLI på den lokala datorn.Create a resource for Personalizer using the Azure portal or Azure CLI on your local machine.

När du har skaffat en nyckel från din resurs skapar du två miljö variabel:After you get a key from your resource, create two environment variable:

  • PERSONALIZER_RESOURCE_KEYför resurs nyckeln.PERSONALIZER_RESOURCE_KEY for the resource key.
  • PERSONALIZER_RESOURCE_ENDPOINTför resurs slut punkten.PERSONALIZER_RESOURCE_ENDPOINT for the resource endpoint.

I Azure Portal är både nyckel-och slut punkts värden tillgängliga från snabb starts sidan.In the Azure portal, both the key and endpoint values are available from the quickstart page.

Ändra modell uppdaterings frekvensenChange the model update frequency

I Azure Portal i gruppen personanpassa på sidan konfiguration ändrar du modell uppdaterings frekvensen till 10 sekunder.In the Azure portal, in the Personalizer resource on the Configuration page, change the Model update frequency to 10 seconds. Den här korta varaktigheten kommer att träna tjänsten snabbt, så att du kan se hur de viktigaste åtgärderna ändras för varje iteration.This short duration will train the service rapidly, allowing you to see how the top action changes for each iteration.

Ändra modell uppdaterings frekvens

När en säkerhetsslinga först instansieras finns det ingen modell eftersom det inte har skett några belönings-API-anrop att träna från.When a Personalizer loop is first instantiated, there is no model since there has been no Reward API calls to train from. Ranknings anrop returnerar lika många sannolikheter för varje objekt.Rank calls will return equal probabilities for each item. Ditt program borde fortfarande alltid rangordna innehåll med hjälp av utdata från RewardActionId.Your application should still always rank content using the output of RewardActionId.

Skapa ett nytt Node.js-programCreate a new Node.js application

I ett konsol fönster (till exempel cmd, PowerShell eller bash) skapar du en ny katalog för din app och navigerar till den.In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.

mkdir myapp && cd myapp

Kör npm init -y kommandot för att skapa en package.json fil.Run the npm init -y command to create a package.json file.

npm init -y

Installera Node. js-biblioteket för PersonanpassareInstall the Node.js library for Personalizer

Installera det personliga klient biblioteket för Node. js med följande kommando:Install the Personalizer client library for Node.js with the following command:

npm install @azure/cognitiveservices-personalizer --save

Installera de återstående NPM-paketen för den här snabb starten:Install the remaining NPM packages for this quickstart:

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

Objekt modellObject model

Personanpassa klienten är ett PersonalizerClient -objekt som autentiserar till Azure med hjälp av Microsoft. rest. ServiceClientCredentials, som innehåller din nyckel.The Personalizer client is a PersonalizerClient object that authenticates to Azure using Microsoft.Rest.ServiceClientCredentials, which contains your key.

Om du vill be om det enda bästa objektet i innehållet skapar du en RankRequestoch skickar det sedan till klienten. Rangordnings metod.To ask for the single best item of the content, create a RankRequest, then pass it to client.Rank method. Rangordnings metoden returnerar en RankResponse.The Rank method returns a RankResponse.

Om du vill skicka en belöning till Personanpassan skapar du en RewardRequestoch skickar den sedan till belönings metoden i händelse klassen.To send a reward to Personalizer, create a RewardRequest, then pass it to the Reward method on the Events class.

Att fastställa belöningen i den här snabb starten är trivial.Determining the reward, in this quickstart is trivial. I ett produktions system kan du bestämma vad som påverkar belönings poängen och hur mycket som kan vara en komplicerad process som du kan välja att ändra med tiden.In a production system, the determination of what impacts the reward score and by how much can be a complex process, that you may decide to change over time. Detta bör vara ett av de primära design besluten i din anpassnings arkitektur.This should be one of the primary design decisions in your Personalizer architecture.

KodexempelCode examples

De här kodfragmenten visar hur du gör följande med det anpassade klient biblioteket för Node. js:These code snippets show you how to do the following with the Personalizer client library for Node.js:

Skapa ett nytt Node.js-programCreate a new Node.js application

Skapa ett nytt Node. js-program i önskat redigerings program eller IDE sample.js-namn.Create a new Node.js application in your preferred editor or IDE named sample.js.

Lägg till beroendenAdd the dependencies

Öppna Sample. js -filen i önskat redigerings program eller IDE.Open the sample.js file in your preferred editor or IDE. Lägg till följande requires för att lägga till NPM-paketen:Add the following requires to add the NPM packages:

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');

Lägg till information om personanpassa resurserAdd Personalizer resource information

Skapa variabler för resursens Azure-nyckel och slut punkt från miljövariablerna, med PERSONALIZER_KEY namnet PERSONALIZER_ENDPOINToch.Create variables for your resource's Azure key and endpoint pulled from the environment variables, named PERSONALIZER_KEY and PERSONALIZER_ENDPOINT. Om du har skapat miljövariablerna när programmet har startats måste redigeraren, IDE eller gränssnittet som kör det stängas och läsas in igen för att få åtkomst till variabeln.If you created the environment variables after the application is launched, the editor, IDE, or shell running it will need to be closed and reloaded to access the variable. Metoderna kommer att skapas senare i den här snabb starten.The methods will be created later in this quickstart.

// The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
let serviceKey = process.env.PERSONALIZER_KEY;

// The endpoint specific to your personalization service instance; 
// e.g. https://westus2.api.cognitive.microsoft.com
let baseUri = process.env.PERSONALIZER_ENDPOINT;

Skapa en personanpassa klientCreate a Personalizer client

Skapa sedan en metod för att returnera en personanpassa klient.Next, create a method to return a Personalizer client. Parametern till-metoden är PERSONALIZER_RESOURCE_ENDPOINT och ApiKey är. PERSONALIZER_RESOURCE_KEYThe parameter to the method is the PERSONALIZER_RESOURCE_ENDPOINT and the ApiKey is the PERSONALIZER_RESOURCE_KEY.

let credentials = new CognitiveServicesCredentials(serviceKey);

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

Hämta innehålls val som visas som åtgärderGet content choices represented as actions

Åtgärder representerar de innehålls val som du vill att en Personanpassare ska välja det bästa innehålls objektet från.Actions represent the content choices from which you want Personalizer to select the best content item. Lägg till följande metoder i program-klassen för att representera uppsättningen med åtgärder och deras funktioner.Add the following methods to the Program class to represent the set of actions and their features.

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

  var answer = readline.question("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n");
  var selection = parseInt(answer);
  var 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);
  var 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
        }
      ]
    }
  ];
}

Skapa inlärnings slinganCreate the learning loop

Inlärnings-loopen för inlärning är en cykel av rang -och belönings samtal.The Personalizer learning loop is a cycle of Rank and Reward calls. I den här snabb starten, som varje rang anrop, för att anpassa innehållet, följs av ett belönings samtal för att berätta för personanpassa hur väl tjänsten utförs.In this quickstart, each Rank call, to personalize the content, is followed by a Reward call to tell Personalizer how well the service performed.

Följande kod går igenom en cykel som ber användaren att ange sina inställningar på kommando raden, vilket innebär att informationen skickas till Personanpassare för att välja den bästa åtgärden, vilket innebär att valet av kund kan välja bland listan och sedan skicka en belöning till en person som ska signalera hur väl tjänsten gjorde sitt val.The following code loops through a cycle of asking the user their preferences at the command line, sending that information to Personalizer to select the best action, presenting the selection to the customer to choose from among the list, then sending a reward to Personalizer signaling how well the service did in its selection.

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
  let 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
  let reward = getReward();

  console.log("\nPersonalization service ranked the actions with the probabilities as below:\n");
  for (var 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.

  let rewardRequest = {
    value: reward
  }

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

  runLoop = continueLoop();

} while (runLoop);

Ta en närmare titt på rang-och belönings anropen i följande avsnitt.Take a closer look at the rank and reward calls in the following sections.

Lägg till följande metoder, som hämtar innehålls valen, innan du kör kod filen:Add the following methods, which get the content choices, before running the code file:

  • getActionsListgetActionsList
  • getContextFeaturesListgetContextFeaturesList

Begär den bästa åtgärdenRequest the best action

För att slutföra ranknings förfrågan ber programmet användarens inställningar att skapa innehålls val.To complete the Rank request, the program asks the user's preferences to create content choices. Processen kan skapa innehåll som ska undantas från åtgärder, som visas excludeActionssom.The process can create content to exclude from the actions, shown as excludeActions. Ranknings förfrågan behöver åtgärder och deras funktioner, currentContext-funktioner, excludeActions och ett unikt ID för ranknings händelse för att ta emot det rankade svaret.The Rank request needs the actions and their features, currentContext features, excludeActions, and a unique rank event ID, to receive the ranked response.

Den här snabb starten har enkla Sammanhangs funktioner i tid på dygnet och användarens mat preferenser.This quickstart has simple context features of time of day and user food preference. I produktions system kan det vara en icke-trivial sak att fastställa och utvärdera åtgärder och funktioner .In production systems, determining and evaluating actions and features can be a non-trivial matter.

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
let rankResponse = await personalizerClient.rank(rankRequest);

Skicka en belöningSend a reward

För att få belönings poängen att skicka i belönings förfrågan får programmet användarens val från kommando raden, tilldelar ett numeriskt värde till markeringen och skickar sedan det unika händelse-ID: t och belönings poängen som det numeriska värdet till belönings-API: et.To get the reward score to send in the Reward request, the program gets the user's selection from the command line, assigns a numeric value to the selection, then sends the unique event ID and the reward score as the numeric value to the Reward API.

Den här snabb starten tilldelar ett enkelt tal som en belönings poäng, antingen noll eller 1.This quickstart assigns a simple number as a reward score, either a zero or a 1. I produktions system kan du fastställa när och vad som ska skickas till belönings anropet som en icke-trivial fråga, beroende på dina behov.In production systems, determining when and what to send to the Reward call can be a non-trivial matter, depending on your specific needs.

let rewardRequest = {
  value: reward
}

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

Köra programmetRun the program

Kör programmet med Node. js från program katalogen.Run the application with the Node.js from your application directory.

node sample.js

Snabb start programmet ber några frågor om att samla in användar inställningar, kallas funktioner, och ger sedan den främsta åtgärden.

Referens dokumentation | bibliotek käll kods | paket (pypi) | exempelReference documentation | Library source code | Package (pypi) | Samples

KravPrerequisites

Använd den här snabb startenUsing this quickstart

Det finns flera steg för att använda den här snabb starten:There are several steps to use this quickstart:

  • I Azure Portal skapar du en personanpassar-resursIn the Azure portal, create a Personalizer resource
  • I Azure Portal för personanpassa resursen, på sidan konfiguration , ändrar du modell uppdaterings frekvensen till ett mycket kort intervallIn the Azure portal, for the Personalizer resource, on the Configuration page, change the model update frequency to a very short interval
  • Skapa en kod fil i en kod redigerare och redigera kod filenIn a code editor, create a code file and edit the code file
  • På kommando raden eller terminalen installerar du SDK från kommando radenIn the command line or terminal, install the SDK from the command line
  • Kör kod filen i kommando raden eller terminalenIn the command line or terminal, run the code file

Skapa en personanpassa Azure-resursCreate a Personalizer Azure resource

Skapa en resurs för Personanpassare med hjälp av Azure Portal eller Azure CLI på den lokala datorn.Create a resource for Personalizer using the Azure portal or Azure CLI on your local machine.

När du har skaffat en nyckel från din resurs skapar du två miljö variabel:After you get a key from your resource, create two environment variable:

  • PERSONALIZER_RESOURCE_KEYför resurs nyckeln.PERSONALIZER_RESOURCE_KEY for the resource key.
  • PERSONALIZER_RESOURCE_ENDPOINTför resurs slut punkten.PERSONALIZER_RESOURCE_ENDPOINT for the resource endpoint.

I Azure Portal är både nyckel-och slut punkts värden tillgängliga från snabb starts sidan.In the Azure portal, both the key and endpoint values are available from the quickstart page.

Ändra modell uppdaterings frekvensenChange the model update frequency

I Azure Portal i gruppen personanpassa på sidan konfiguration ändrar du modell uppdaterings frekvensen till 10 sekunder.In the Azure portal, in the Personalizer resource on the Configuration page, change the Model update frequency to 10 seconds. Den här korta varaktigheten kommer att träna tjänsten snabbt, så att du kan se hur de viktigaste åtgärderna ändras för varje iteration.This short duration will train the service rapidly, allowing you to see how the top action changes for each iteration.

Ändra modell uppdaterings frekvens

När en säkerhetsslinga först instansieras finns det ingen modell eftersom det inte har skett några belönings-API-anrop att träna från.When a Personalizer loop is first instantiated, there is no model since there has been no Reward API calls to train from. Ranknings anrop returnerar lika många sannolikheter för varje objekt.Rank calls will return equal probabilities for each item. Ditt program borde fortfarande alltid rangordna innehåll med hjälp av utdata från RewardActionId.Your application should still always rank content using the output of RewardActionId.

Installera python-biblioteket för PersonanpassareInstall the Python library for Personalizer

Installera det personliga klient biblioteket för python med följande kommando:Install the Personalizer client library for Python with the following command:

pip install azure-cognitiveservices-personalizer

Objekt modellObject model

Personanpassa klienten är ett PersonalizerClient -objekt som autentiserar till Azure med hjälp av Microsoft. rest. ServiceClientCredentials, som innehåller din nyckel.The Personalizer client is a PersonalizerClient object that authenticates to Azure using Microsoft.Rest.ServiceClientCredentials, which contains your key.

Om du vill be om det enda bästa objektet i innehållet skapar du en RankRequestoch skickar det sedan till klienten. Rangordnings metod.To ask for the single best item of the content, create a RankRequest, then pass it to client.Rank method. Rangordnings metoden returnerar en RankResponse.The Rank method returns a RankResponse.

Om du vill skicka en belönings poäng till Personanpassan ställer du in händelse-ID och belönings poängen (värdet) som ska skickas till belönings metoden i EventOperations-klassen.To send a reward score to Personalizer, set the event ID and the reward score (value) to send to the Reward method on the EventOperations class.

Att fastställa belöningen i den här snabb starten är trivial.Determining the reward, in this quickstart is trivial. I ett produktions system kan du bestämma vad som påverkar belönings poängen och hur mycket som kan vara en komplicerad process som du kan välja att ändra med tiden.In a production system, the determination of what impacts the reward score and by how much can be a complex process, that you may decide to change over time. Detta bör vara ett av de primära design besluten i din anpassnings arkitektur.This should be one of the primary design decisions in your Personalizer architecture.

KodexempelCode examples

De här kodfragmenten visar hur du gör följande med personanpassa klient biblioteket för python:These code snippets show you how to do the following with the Personalizer client library for Python:

Skapa ett nytt python-programCreate a new python application

Skapa ett nytt python-program i önskat redigerings program eller IDE sample.py-namn.Create a new Python application in your preferred editor or IDE named sample.py.

Lägg till beroendenAdd the dependencies

Från projekt katalogen öppnar du Sample.py -filen i önskat redigerings program eller IDE.From the project directory, open the sample.py file in your preferred editor or IDE. Lägg till följande:Add the following:

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

Lägg till information om personanpassa resurserAdd Personalizer resource information

Skapa variabler för resursens Azure-nyckel och slut punkt från miljövariablerna, med PERSONALIZER_RESOURCE_KEY namnet PERSONALIZER_RESOURCE_ENDPOINToch.Create variables for your resource's Azure key and endpoint pulled from the environment variables, named PERSONALIZER_RESOURCE_KEY and PERSONALIZER_RESOURCE_ENDPOINT. Om du har skapat miljövariablerna när programmet har startats måste redigeraren, IDE eller gränssnittet som kör det stängas och läsas in igen för att få åtkomst till variabeln.If you created the environment variables after the application is launched, the editor, IDE, or shell running it will need to be closed and reloaded to access the variable. Metoderna kommer att skapas senare i den här snabb starten.The methods will be created later in this quickstart.

Resurs namnet är en del av slut punkts- https://<your-resource-name>.api.cognitive.microsoft.com/URL: en:.The resource name is part of the endpoint URL: https://<your-resource-name>.api.cognitive.microsoft.com/.

key_var_name = 'PERSONALIZER_KEY'
if not key_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(key_var_name))
personalizer_key = os.environ[key_var_name]

# Replace <your-resource-name>: https://<your-resource-name>.api.cognitive.microsoft.com/
endpoint_var_name = 'PERSONALIZER_ENDPOINT'
if not endpoint_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(endpoint_var_name))
personalizer_endpoint = os.environ[endpoint_var_name]

Skapa en personanpassa klientCreate a Personalizer client

Skapa sedan en metod för att returnera en personanpassa klient.Next, create a method to return a Personalizer client. Parametern till-metoden är PERSONALIZER_RESOURCE_ENDPOINT och ApiKey är. PERSONALIZER_RESOURCE_KEYThe parameter to the method is the PERSONALIZER_RESOURCE_ENDPOINT and the ApiKey is the PERSONALIZER_RESOURCE_KEY.

# Instantiate a Personalizer client
client = PersonalizerClient(personalizer_endpoint, CognitiveServicesCredentials(personalizer_key))

Hämta innehålls val som visas som åtgärderGet content choices represented as actions

Åtgärder representerar de innehålls val som du vill att en Personanpassare ska välja det bästa innehålls objektet från.Actions represent the content choices from which you want Personalizer to select the best content item. Lägg till följande metoder i program-klassen för att representera uppsättningen med åtgärder och deras funktioner.Add the following methods to the Program class to represent the set of actions and their features.

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

Skapa inlärnings slinganCreate the learning loop

Inlärnings-loopen för inlärning är en cykel av rang -och belönings samtal.The Personalizer learning loop is a cycle of Rank and Reward calls. I den här snabb starten, som varje rang anrop, för att anpassa innehållet, följs av ett belönings samtal för att berätta för personanpassa hur väl tjänsten utförs.In this quickstart, each rank call, to personalize the content, is followed by a reward call to tell Personalizer how well the service performed.

Följande kod går igenom en cykel som ber användaren att ange sina inställningar på kommando raden, vilket innebär att informationen skickas till Personanpassare för att välja den bästa åtgärden, vilket innebär att valet av kund kan välja bland listan och sedan skicka en belöning till en person som ska signalera hur väl tjänsten gjorde sitt val.The following code loops through a cycle of asking the user their preferences at the command line, sending that information to Personalizer to select the best action, presenting the selection to the customer to choose from among the list, then sending a reward to Personalizer signaling how well the service did in its selection.

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

Lägg till följande metoder, som hämtar innehålls valen, innan du kör kod filen:Add the following methods, which get the content choices, before running the code file:

  • get_user_preference
  • get_user_timeofday
  • get_actions

Begär den bästa åtgärdenRequest the best action

För att slutföra ranknings förfrågan ställer programmet till användarens inställningar för att skapa ett currentContent av innehålls valen.To complete the Rank request, the program asks the user's preferences to create a currentContent of the content choices. Processen kan skapa innehåll som ska undantas från åtgärder, som visas excludeActionssom.The process can create content to exclude from the actions, shown as excludeActions. Ranknings förfrågan behöver åtgärder och deras funktioner, currentContext-funktioner, excludeActions och ett unikt händelse-ID för att få svaret.The Rank request needs the actions and their features, currentContext features, excludeActions, and a unique event ID, to receive the response.

Den här snabb starten har enkla Sammanhangs funktioner i tid på dygnet och användarens mat preferenser.This quickstart has simple context features of time of day and user food preference. I produktions system kan det vara en icke-trivial sak att fastställa och utvärdera åtgärder och funktioner .In production systems, determining and evaluating actions and features can be a non-trivial matter.

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

Skicka en belöningSend a reward

För att få belönings poängen att skicka i belönings förfrågan får programmet användarens val från kommando raden, tilldelar ett numeriskt värde till markeringen och skickar sedan det unika händelse-ID: t och belönings poängen som det numeriska värdet till belönings-API: et.To get the reward score to send in the Reward request, the program gets the user's selection from the command line, assigns a numeric value to the selection, then sends the unique event ID and the reward score as the numeric value to the Reward API.

Den här snabb starten tilldelar ett enkelt tal som en belönings poäng, antingen noll eller 1.This quickstart assigns a simple number as a reward score, either a zero or a 1. I produktions system kan du fastställa när och vad som ska skickas till belönings anropet som en icke-trivial fråga, beroende på dina behov.In production systems, determining when and what to send to the Reward call can be a non-trivial matter, depending on your specific needs.

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)

Köra programmetRun the program

Kör programmet med python från program katalogen.Run the application with the python from your application directory.

python sample.py

Snabb start programmet ber några frågor om att samla in användar inställningar, kallas funktioner, och ger sedan den främsta åtgärden.

Rensa resurserClean up resources

Om du vill rensa och ta bort en Cognitive Services prenumeration kan du ta bort resursen eller resurs gruppen.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Om du tar bort resurs gruppen raderas även andra resurser som är kopplade till den.Deleting the resource group also deletes any other resources associated with it.

Nästa stegNext steps