Kurz: Přidání personalizace do webové aplikace .NET

  • Článek

Důležité

Od 20. září 2023 nebudete moct vytvářet nové prostředky personalizace. Služba Personalizace se vyřadí z provozu 1. října 2026.

Přizpůsobte si webovou aplikaci C# .NET smyčkou Personalizace, která uživateli poskytne správný obsah na základě akcí (s funkcemi) a kontextových funkcí.

V tomto kurzu se naučíte:

  • Nastavení klíče a koncového bodu Personalizace
  • Shromažďování funkcí
  • Volání rozhraní API pro pořadí a odměny
  • Zobrazení hlavní akce označené jako rewardsActionId

Výběr nejlepšího obsahu pro webovou aplikaci

Webová aplikace by měla používat personalizaci, pokud je na webové stránce seznam akcí (nějaký typ obsahu), které je potřeba přizpůsobit jedné nejvyšší položce (rewardsActionId), aby se zobrazila. Mezi příkladyseznamůch

Seznam akcí spolu s kontextovými funkcemi odešlete do smyčky Personalizace. Personalizace vybere jednu nejlepší akci a pak webová aplikace tuto akci zobrazí.

V tomto kurzu jsou akce typy potravin:

  • Těstoviny
  • Zmrzlina
  • Šťávy
  • Salát
  • Popcorn
  • Kávy
  • Polévka

Chcete-li pomoct přizpůsobit informace o vašich akcích, odešlete obě akce s funkcemi a kontextovými funkcemi s každou žádostí rozhraní API pro hodnocení.

Funkce modelu je informace o akci nebo kontextu, které je možné agregovat (seskupit) mezi členy uživatelské základny vaší webové aplikace. Funkce není specifická jednotlivě (například ID uživatele) nebo vysoce specifická (například přesná denní doba).

Akce s funkcemi

Každá akce (položka obsahu) má funkce, které pomáhají odlišit položku jídla.

Funkce nejsou nakonfigurované jako součást konfigurace smyčky na webu Azure Portal. Místo toho se posílají jako objekt JSON s každým voláním rozhraní Rank API. To umožňuje flexibilitu pro akce a jejich funkce, aby se v průběhu času zvětšovaly, měnily a zmenšovaly, což umožňuje personalizaci sledovat trendy.

 /// <summary>
  /// Creates personalizer actions feature list.
  /// </summary>
  /// <returns>List of actions for personalizer.</returns>
  private IList<RankableAction> GetActions()
  {
      IList<RankableAction> actions = new List<RankableAction>
      {
          new RankableAction
          {
              Id = "pasta",
              Features =
              new List<object>() { new { taste = "savory", 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 = "sour", spiceLevel = "low" }, new { nutritionLevel = 8 } }
          },

          new RankableAction
          {
              Id = "popcorn",
              Features =
              new List<object>() { new { taste = "salty", spiceLevel = "none" }, new { nutritionLevel = 3 } }
          },

          new RankableAction
          {
              Id = "coffee",
              Features =
              new List<object>() { new { taste = "bitter", spiceLevel = "none" }, new { nutritionLevel = 3 }, new { drink = true } }
          },

          new RankableAction
          {
              Id = "soup",
              Features =
              new List<object>() { new { taste = "sour", spiceLevel = "high" }, new { nutritionLevel =  7} }
          }
      };

      return actions;
  }

Kontextové funkce

Kontextové funkce pomáhají personalizaci porozumět kontextu akcí. Kontext pro tuto ukázkovou aplikaci zahrnuje:

  • denní čas - ráno, odpoledne, večer, noc
  • preference uživatele pro chuť - slané, sladké, sladké, kyselé, kyselé nebo slané
  • kontext prohlížeče – uživatelský agent, zeměpisné umístění, referrer
/// <summary>
/// Get users time of the day context.
/// </summary>
/// <returns>Time of day feature selected by the user.</returns>
private string GetUsersTimeOfDay()
{
    Random rnd = new Random();
    string[] timeOfDayFeatures = new string[] { "morning", "noon", "afternoon", "evening", "night", "midnight" };
    int timeIndex = rnd.Next(timeOfDayFeatures.Length);
    return timeOfDayFeatures[timeIndex];
}

/// <summary>
/// Gets user food preference.
/// </summary>
/// <returns>Food taste feature selected by the user.</returns>
private string GetUsersTastePreference()
{
    Random rnd = new Random();
    string[] tasteFeatures = new string[] { "salty", "bitter", "sour", "savory", "sweet" };
    int tasteIndex = rnd.Next(tasteFeatures.Length);
    return tasteFeatures[tasteIndex];
}

Jak webová aplikace používá personalizaci?

Webová aplikace používá personalizaci k výběru nejlepší akce ze seznamu voleb potravin. To provede odesláním následujících informací s každým voláním rozhraní Rank API:

  • akce s jejich funkcemi, jako taste jsou a spiceLevel
  • kontextové funkce, jako time jsou dny, předvolby uživatele taste a informace o uživatelském agentovi prohlížeče a kontextové funkce
  • opatření k vyloučení , jako je šťáva
  • eventId, který se pro každé volání rozhraní Rank API liší.

Funkce modelu přizpůsobení ve webové aplikaci

Personalizace potřebuje funkce pro akce (obsah) a aktuální kontext (uživatele a prostředí). Funkce se používají ke sladění akcí s aktuálním kontextem modelu. Model je reprezentace minulých znalostí personalizace o akcích, kontextu a jejich funkcích, které mu umožňují provádět kvalifikovaná rozhodnutí.

Model, včetně funkcí, se aktualizuje podle plánu na základě nastavení frekvence aktualizace modelu na webu Azure Portal.

Upozornění

Funkce v této aplikaci jsou určené k ilustraci funkcí a hodnot funkcí, ale ne nutně k nejlepším funkcím, které se mají použít ve webové aplikaci.

Plánování funkcí a jejich hodnot

Funkce by měly být vybrány se stejným plánováním a návrhem, které byste použili u jakéhokoli schématu nebo modelu ve vaší technické architektuře. Hodnoty funkcí je možné nastavit pomocí obchodní logiky nebo systémů třetích stran. Hodnoty funkcí by neměly být tak vysoce specifické, že se nevztahují na skupinu nebo třídu funkcí.

Generalizace hodnot funkcí

Zobecnit do kategorií

Tato aplikace používá time jako funkci, ale seskupuje čas do kategorií, jako morningjsou , afternoonevening, a night. To je příklad použití informací o čase, ale ne velmi specifickým způsobem, například 10:05:01 UTC+2.

Zobecnění částí

Tato aplikace používá funkce požadavku HTTP z prohlížeče. Začíná to velmi konkrétním řetězcem se všemi daty, například:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/530.99 (KHTML, like Gecko) Chrome/80.0.3900.140 Safari/537.36

Knihovna tříd HttpRequestFeatures generalizuje tento řetězec do userAgentInfo objektu s jednotlivými hodnotami. Všechny hodnoty, které jsou příliš specifické, jsou nastaveny na prázdný řetězec. Po odeslání kontextových funkcí požadavku má následující formát JSON:

{
  "httpRequestFeatures": {
    "_synthetic": false,
    "OUserAgent": {
      "_ua": "",
      "_DeviceBrand": "",
      "_DeviceFamily": "Other",
      "_DeviceIsSpider": false,
      "_DeviceModel": "",
      "_OSFamily": "Windows",
      "_OSMajor": "10",
      "DeviceType": "Desktop"
    }
  }
}

Použití ukázkové webové aplikace

Ukázková webová aplikace založená na prohlížeči (je k dispozici veškerý kód) potřebuje k spuštění aplikace nainstalované následující aplikace.

Nainstalujte následující software:

  • .NET Core 2.1 – ukázkový back-endový server používá .NET Core
  • Node.js – klient/front-end závisí na této aplikaci.
  • Visual Studio 2019 nebo .NET Core CLI – k sestavení a spuštění aplikace použijte vývojářské prostředí sady Visual Studio 2019 nebo .NET Core CLI.

Nastavení ukázky

  1. Naklonujte úložiště Ukázek personalizace Azure AI.

    git clone https://github.com/Azure-Samples/cognitive-services-personalizer-samples.git

  2. Přejděte na ukázky /HttpRequestFeatures a otevřete řešení HttpRequestFeaturesExample.sln.

    Pokud je to požadováno, povolte sadě Visual Studio aktualizovat balíček .NET pro personalizaci.

Nastavení služby Personalizace Azure AI

  1. Vytvořte prostředek Personalizace na webu Azure Portal.

  2. Na webu Azure Portal najděte Endpoint na kartě Klíče a koncové body buď a Key1Key2 nebo (buď bude fungovat). To jsou vaše PersonalizerServiceEndpoint a vaše PersonalizerApiKey.

  3. PersonalizerServiceEndpoint Vyplňte soubor appsettings.json.

  4. Nakonfigurujte tajné kódy PersonalizerApiKey aplikace jedním z následujících způsobů:

    • Pokud používáte rozhraní příkazového řádku .NET Core, můžete použít dotnet user-secrets set "PersonalizerApiKey" "<API Key>" tento příkaz.
    • Pokud používáte Sadu Visual Studio, můžete na projekt kliknout pravým tlačítkem myši a vybrat možnost nabídky Spravovat tajné kódy uživatelů a nakonfigurovat klíče Personalizace. Tímto způsobem visual Studio otevře secrets.json soubor, ve kterém můžete klíče přidat následujícím způsobem:
    {
  "PersonalizerApiKey": "<your personalizer key here>",
}

Spuštění ukázky

Sestavte a spusťte HttpRequestFeaturesExample pomocí jedné z následujících metod:

  • Visual Studio 2019: Stiskněte klávesu F5
  • .NET Core CLI: dotnet build pak dotnet run

Prostřednictvím webového prohlížeče můžete odeslat žádost o pořadí a žádost o odměnu a zobrazit jejich odpovědi a také funkce požadavku HTTP extrahované z vašeho prostředí.

Screenshot shows an example of the Http Request Feature in a web browser.

Předvedení smyčky Personalizace

  1. Výběrem tlačítka Vygenerovat novou žádost o pořadí vytvořte nový objekt JSON pro volání rozhraní API pořadí. Tím se vytvoří akce (s funkcemi) a kontextové funkce a zobrazí se hodnoty, abyste viděli, jak JSON vypadá.

    U vaší vlastní budoucí aplikace může na klientovi, na serveru, na serveru nebo při volání jiných služeb dojít ke generování akcí a funkcí.

  2. Výběrem možnosti Odeslat požadavek na pořadí odešlete objekt JSON na server. Server volá rozhraní API personalizace pořadí. Server obdrží odpověď a vrátí nejlépe seřazenou akci klientovi, která se má zobrazit.

  3. Nastavte hodnotu odměny a pak vyberte tlačítko Odeslat žádost o odměnu. Pokud hodnotu odměny nezměníte, klientská aplikace vždy odešle hodnotu 1 personalizaci.

    Screenshot shows the Reward Request section.

    Pro vlastní budoucí aplikaci může dojít k generování skóre odměny po shromáždění informací z chování uživatele na klientovi spolu s obchodní logikou na serveru.

Vysvětlení ukázkové webové aplikace

Ukázková webová aplikace má server C# .NET , který spravuje kolekci funkcí a posílá a přijímá volání HTTP do koncového bodu Personalizace.

Ukázková webová aplikace používá front-endovou klientskou aplikaci k zachycení funkcí a zpracování akcí uživatelského rozhraní, jako je kliknutí na tlačítka a odesílání dat na server .NET.

Následující části popisují části serveru a klienta, kterým vývojář musí rozumět, aby mohli personalizaci používat.

Rozhraní API pro hodnocení: Klientská aplikace odesílá kontext na server

Klientská aplikace shromažďuje uživatelského agenta prohlížeče uživatele.

Build and run the HTTPRequestFeaturesExample project. A browser window opens to display the single page application.

Rozhraní API pro hodnocení: Serverová aplikace volá Personalizace

Jedná se o typickou webovou aplikaci .NET s klientskou aplikací. Většina kódu kotlového štítku je k dispozici za vás. Z následujících fragmentů kódu se odebere jakýkoli kód, který není specifický pro personalizaci, takže se můžete zaměřit na kód specifický pro personalizaci.

Vytvoření klienta Personalizace

V souboru Startup.cs serveru se koncový bod a klíč personalizace používají k vytvoření klienta Personalizace. Klientská aplikace nemusí komunikovat s personalizátorem v této aplikaci, místo toho se spoléhá na server, aby tato volání sady SDK byla provedena.

Spouštěcí kód .NET webového serveru je:

using Microsoft.Azure.CognitiveServices.Personalizer;
// ... other using statements removed for brevity

namespace HttpRequestFeaturesExample
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            string personalizerApiKey = Configuration.GetSection("PersonalizerApiKey").Value;
            string personalizerEndpoint = Configuration.GetSection("PersonalizerConfiguration:ServiceEndpoint").Value;
            if (string.IsNullOrEmpty(personalizerEndpoint) || string.IsNullOrEmpty(personalizerApiKey))
            {
                throw new ArgumentException("Missing Azure AI Personalizer endpoint and/or api key.");
            }
            services.AddSingleton(client =>
            {
                return new PersonalizerClient(new ApiKeyServiceClientCredentials(personalizerApiKey))
                {
                    Endpoint = personalizerEndpoint
                };
            });

            services.AddMvc();
        }

        // ... code removed for brevity
    }
}

Výběr nejlepší akce

V souboru PersonalrController.cs serveru generateRank shrnuje rozhraní API serveru GenerateRank přípravu k volání rozhraní Rank API.

  • Vytvoření nového eventId pro volání pořadí
  • Získání seznamu akcí
  • Získání seznamu funkcí od uživatele a vytvoření kontextových funkcí
  • Volitelně můžete nastavit všechny vyloučené akce.
  • Volání rozhraní API pro pořadí volání, vrácení výsledků klientovi
/// <summary>
/// Creates a RankRequest with user time of day, HTTP request features,
/// and taste as the context and several different foods as the actions
/// </summary>
/// <returns>RankRequest with user info</returns>
[HttpGet("GenerateRank")]
public RankRequest GenerateRank()
{
    string eventId = Guid.NewGuid().ToString();

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

    // Get context information from the user.
    HttpRequestFeatures httpRequestFeatures = GetHttpRequestFeaturesFromRequest(Request);
    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 },
            new { httpRequestFeatures }
    };

    // Exclude an action for personalizer ranking. This action will be held at its current position.
    IList<string> excludeActions = new List<string> { "juice" };

    // Rank the actions
    return new RankRequest(actions, currentContext, excludeActions, eventId);
}

Json odeslaný do personalizace, který obsahuje obě akce (s funkcemi) i aktuální kontextové funkce, vypadá takto:

{
    "contextFeatures": [
        {
            "time": "morning"
        },
        {
            "taste": "savory"
        },
        {
            "httpRequestFeatures": {
                "_synthetic": false,
                "MRefer": {
                    "referer": "http://localhost:51840/"
                },
                "OUserAgent": {
                    "_ua": "",
                    "_DeviceBrand": "",
                    "_DeviceFamily": "Other",
                    "_DeviceIsSpider": false,
                    "_DeviceModel": "",
                    "_OSFamily": "Windows",
                    "_OSMajor": "10",
                    "DeviceType": "Desktop"
                }
            }
        }
    ],
    "actions": [
        {
            "id": "pasta",
            "features": [
                {
                    "taste": "savory",
                    "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": "sour",
                    "spiceLevel": "low"
                },
                {
                    "nutritionLevel": 8
                }
            ]
        },
        {
            "id": "popcorn",
            "features": [
                {
                    "taste": "salty",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 3
                }
            ]
        },
        {
            "id": "coffee",
            "features": [
                {
                    "taste": "bitter",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 3
                },
                {
                    "drink": true
                }
            ]
        },
        {
            "id": "soup",
            "features": [
                {
                    "taste": "sour",
                    "spiceLevel": "high"
                },
                {
                    "nutritionLevel": 7
                }
            ]
        }
    ],
    "excludedActions": [
        "juice"
    ],
    "eventId": "82ac52da-4077-4c7d-b14e-190530578e75",
    "deferActivation": null
}

Vrácení personalizace rewardsActionId klientovi

Rozhraní Rank API vrátí vybrané nejlepší akce rewardsActionId na server.

Zobrazí akci vrácenou v hodnotě rewardsActionId.

{
    "ranking": [
        {
            "id": "popcorn",
            "probability": 0.833333254
        },
        {
            "id": "salad",
            "probability": 0.03333333
        },
        {
            "id": "juice",
            "probability": 0
        },
        {
            "id": "soup",
            "probability": 0.03333333
        },
        {
            "id": "coffee",
            "probability": 0.03333333
        },
        {
            "id": "pasta",
            "probability": 0.03333333
        },
        {
            "id": "ice cream",
            "probability": 0.03333333
        }
    ],
    "eventId": "82ac52da-4077-4c7d-b14e-190530578e75",
    "rewardActionId": "popcorn"
}

Klient zobrazí akci rewardsActionId.

V tomto kurzu rewardActionId se zobrazí hodnota.

Ve vlastní budoucí aplikaci to může být určitý přesný text, tlačítko nebo oddíl webové stránky zvýrazněné. Seznam se vrátí pro všechny následné analýzy skóre, nikoli řazení obsahu. rewardActionId Měl by se zobrazit jenom obsah.

Rozhraní API odměny: Shromáždění informací o odměně

Skóre odměny by mělo být pečlivě naplánováno, stejně jako jsou plánované funkce. Skóre odměny by obvykle mělo být hodnota od 0 do 1. Hodnotu lze vypočítat částečně v klientské aplikaci na základě chování uživatelů a částečně na serveru na základě obchodní logiky a cílů.

Pokud server nevolá rozhraní API odměny v době čekání na odměnu nakonfigurovanou na webu Azure Portal pro váš prostředek Personalizace, použije se pro tuto událost výchozí odměna (nakonfigurovaná také na webu Azure Portal).

V této ukázkové aplikaci můžete vybrat hodnotu, abyste viděli, jak odměna ovlivňuje výběry.

Další způsoby, jak se z této ukázky naučit

Ukázka používá několik událostí založených na čase nakonfigurovaných na webu Azure Portal pro prostředek Personalizace. S těmito hodnotami se pak vraťte do této ukázkové webové aplikace a podívejte se, jak změny ovlivňují volání Rank a Rewards:

  • Doba čekání na odměnu
  • Frekvence aktualizace modelu

Mezi další nastavení, která se mají hrát, patří:

  • Výchozí odměna
  • Procento průzkumu

Vyčištění prostředků

Po dokončení tohoto kurzu vyčistěte následující prostředky:

  • Odstraňte svůj ukázkový adresář projektu.
  • Odstraňte prostředek Personalizace – představte si prostředek Personalizace jako vyhrazený pro akce a kontext – prostředek znovu použijte pouze v případě, že stále používáte potraviny jako doménu předmětu akcí.

Další kroky