Oktatóanyag: Personalizer hozzáadása .NET-webalkalmazáshoz
Fontos
2023. szeptember 20-tól nem hozhat létre új Personalizer-erőforrásokat. A Personalizer szolgáltatás 2026. október 1-jén megszűnik.
Testre szabhat egy C# .NET-webalkalmazást egy Personalizer-hurokkal, hogy a műveletek (funkciók) és a környezeti funkciók alapján a megfelelő tartalmat biztosítsa a felhasználónak.
Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:
- A Personalizer-kulcs és a végpont beállítása
- Szolgáltatások összegyűjtése
- Rang és jutalom API-k meghívása
- A rewardActionId azonosítóként megjelölt felső művelet megjelenítése
A webalkalmazások legjobb tartalmának kiválasztása
A webalkalmazásoknak a Personalizert kell használniuk, ha a weblapon olyan műveletek listája (valamilyen tartalomtípus) található, amelyeket egyetlen legfelső elemre (rewardActionId) kell testre szabni a megjelenítéshez. A műveletlisták közé tartoznak például a hírcikkek, a gombelhelyezési helyek és a terméknevek szóválasztása.
A műveletek listáját a környezeti funkciókkal együtt a Personalizer hurokba kell küldenie. A Personalizer kiválasztja az egyetlen legjobb műveletet, majd a webalkalmazás megjeleníti ezt a műveletet.
Ebben az oktatóanyagban a műveletek az élelmiszerek típusai:
- Tészta
- Fagylalt
- Juice
- Saláta
- Popcorn
- Kávé
- Leves
Ha szeretné, hogy a Personalizer megismerje a műveleteket, küldje el a szolgáltatásokat és a környezetfunkciókat tartalmazó műveleteket az egyes Rank API-kérésekkel.
A modell egyik funkciója az a művelet vagy környezet információja, amely összesíthető (csoportosítható) a webalkalmazás felhasználói bázisának tagjai között. A funkció nem egyedi (például felhasználói azonosító) vagy nagyon specifikus (például pontos napidő).
Funkciókkal rendelkező műveletek
Minden művelet (tartalomelem) olyan funkciókkal rendelkezik, amelyek segítenek megkülönböztetni az élelmiszer-elemet.
A funkciók nincsenek konfigurálva az Azure Portal hurokkonfigurációjának részeként. Ehelyett JSON-objektumként küldik őket minden Rank API-hívással. Ez lehetővé teszi a műveletek és azok funkcióinak rugalmasságát, hogy idővel növekedjenek, változhassanak és zsugorodjanak, ami lehetővé teszi a Personalizer számára a trendek követését.
/// <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;
}
Környezeti funkciók
A környezeti funkciók segítenek a Personalizernek megérteni a műveletek kontextusát. A mintaalkalmazás környezete a következőket tartalmazza:
- napszak - reggel, délután, este, éjszaka
- a felhasználó ízlésének preferencia - sós, édes, keserű, savanyú vagy sós
- böngésző környezete – felhasználói ügynök, földrajzi hely, hivatkozó
/// <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];
}
Hogyan használja a webalkalmazás a Personalizert?
A webalkalmazás a Personalizer használatával választja ki a legjobb műveletet az élelmiszerek listájából. Ezt úgy teszi, hogy elküldi a következő információkat minden Rank API-hívással:
- olyan funkciókkal rendelkező műveletek , mint például
tasteaspiceLevel - környezeti funkciók, például
timea nap, a felhasználó preferenciájataste, a böngésző felhasználói ügynökének adatai és a környezeti funkciók - olyan műveletek kizárására , mint a gyümölcslé
- eventId, amely a Rank API minden egyes hívásához eltérő.
A személyre szabható modell funkciói egy webalkalmazásban
A Personalizernek szüksége van a műveletek (tartalom) és az aktuális környezet (felhasználó és környezet) funkcióira. A funkciók a modell aktuális környezetéhez igazítják a műveleteket. A modell a Personalizer korábbi, a műveletekre, a környezetre és azok funkcióira vonatkozó ismereteit jeleníti meg, amelyek lehetővé teszik, hogy megalapozott döntéseket hozzon.
A modell, beleértve a funkciókat is, ütemezés szerint frissül az Azure Portal modellfrissítési gyakorisági beállítása alapján.
Figyelmeztetés
Az alkalmazás funkciói a funkciók és a funkcióértékek szemléltetésére szolgálnak, de nem feltétlenül a webalkalmazások legjobb funkcióira.
Funkciók és értékük tervezése
A szolgáltatásokat ugyanazzal a tervezéssel és kialakítással kell kiválasztani, mint amelyet a műszaki architektúra bármely sémájához vagy modelljéhez alkalmazna. A funkcióértékek beállíthatók üzleti logikával vagy külső rendszerekkel. A funkcióértékek nem lehetnek annyira specifikusak, hogy nem alkalmazhatók egy adott csoportra vagy szolgáltatásosztályra.
Funkcióértékek általánosítása
Általánosítás kategóriákba
Ez az alkalmazás funkcióként használja time , de az időt olyan kategóriákba csoportosítja, mint morninga , afternoon, eveningés night. Ez egy példa az idő információinak használatára, de nem kifejezetten meghatározott módon, például 10:05:01 UTC+2.
Általánosítás részekre
Ez az alkalmazás a böngésző HTTP-kérési funkcióit használja. Ez egy nagyon konkrét sztringgel kezdődik, amely az összes adatot tartalmazza, például:
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/530.99 (KHTML, like Gecko) Chrome/80.0.3900.140 Safari/537.36
A HttpRequestFeatures osztálykódtár ezt a sztringet egy userAgentInfo objektummá általánosítja egyéni értékekkel. A túl specifikus értékek üres sztringre vannak állítva. A kérés környezeti funkcióinak elküldésekor a következő JSON-formátumot kapja:
{
"httpRequestFeatures": {
"_synthetic": false,
"OUserAgent": {
"_ua": "",
"_DeviceBrand": "",
"_DeviceFamily": "Other",
"_DeviceIsSpider": false,
"_DeviceModel": "",
"_OSFamily": "Windows",
"_OSMajor": "10",
"DeviceType": "Desktop"
}
}
}
Minta webalkalmazás használata
A böngészőalapú mintaalkalmazásnak (minden kód meg van adva) az alábbi alkalmazásokra van szüksége az alkalmazás futtatásához.
Telepítse a következő szoftvert:
- .NET Core 2.1 – a minta háttérkiszolgáló .NET Core-t használ
- Node.js – az ügyfél/előtér az alkalmazástól függ
- Visual Studio 2019 vagy .NET Core CLI – az alkalmazás létrehozásához és futtatásához használja a Visual Studio 2019 fejlesztői környezetét vagy a .NET Core CLI-t
A minta beállítása
Klónozza az Azure AI Personalizer-minták adattárát.
git clone https://github.com/Azure-Samples/cognitive-services-personalizer-samples.gitLépjen a minták/HttpRequestFeatures webhelyre a megoldás megnyitásához.
HttpRequestFeaturesExample.slnHa szükséges, engedélyezze a Visual Studio számára a Personalizer .NET-csomagjának frissítését.
Az Azure AI Personalizer szolgáltatás beállítása
Hozzon létre egy Personalizer-erőforrást az Azure Portalon.
Az Azure Portalon keresse meg a
Endpointkulcsokat ésKey2Key1végpontokat a Kulcsok és végpontok lapon. Ezek a tePersonalizerServiceEndpointés a tePersonalizerApiKey.Töltse ki az
PersonalizerServiceEndpointappsettings.json fájlt.Az alábbi módok egyikével konfigurálhatja az
PersonalizerApiKeyalkalmazás titkos kulcsait:- Ha a .NET Core parancssori felületet használja, használhatja a
dotnet user-secrets set "PersonalizerApiKey" "<API Key>"parancsot. - Ha Visual Studiót használ, kattintson a jobb gombbal a projektre, és válassza a Felhasználói titkos kódok kezelése menüt a Személyre szabó kulcsok konfigurálásához. Ezzel a Visual Studio megnyit egy
secrets.jsonfájlt, amelyben a következő módon adhat hozzá kulcsokat:
{ "PersonalizerApiKey": "<your personalizer key here>", }- Ha a .NET Core parancssori felületet használja, használhatja a
Minta futtatása
A HttpRequestFeaturesExample létrehozása és futtatása az alábbi módszerek egyikével:
- Visual Studio 2019: Nyomja le az F5 billentyűt
- .NET Core parancssori felület:
dotnet buildmajddotnet run
Egy webböngészőn keresztül elküldhet egy Rangsor kérést és egy Reward-kérést, és megtekintheti azok válaszait, valamint a környezetből kinyert HTTP-kérési funkciókat.
A Personalizer-ciklus bemutatása
Válassza az Új rangsor kérés létrehozása gombot egy új JSON-objektum létrehozásához a Rank API-híváshoz. Ez létrehozza a műveleteket (funkciókkal) és a környezeti szolgáltatásokat, és megjeleníti az értékeket, így láthatja, hogyan néz ki a JSON.
Saját jövőbeli alkalmazása esetén a műveletek és szolgáltatások létrehozása történhet az ügyfélen, a kiszolgálón, a kettő kombinációján vagy más szolgáltatások hívásaival.
Válassza a Rangsor kérés küldése lehetőséget a JSON-objektum kiszolgálóra való küldéséhez. A kiszolgáló meghívja a Personalizer Rank API-t. A kiszolgáló megkapja a választ, és visszaadja a legjobban rangsorolt műveletet a megjelenítendő ügyfélnek.
Állítsa be a jutalomértéket, majd válassza a Jutalomkérés küldése gombot. Ha nem módosítja a jutalomértéket, az ügyfélalkalmazás mindig elküldi az értéket
1a Personalizernek.
A saját jövőbeli alkalmazása esetén a jutalompont létrehozása akkor fordulhat elő, ha adatokat gyűjt a felhasználó viselkedéséből az ügyfélen, valamint az üzleti logikát a kiszolgálón.
A minta webalkalmazás ismertetése
A minta webalkalmazás egy C# .NET-kiszolgálóval rendelkezik, amely kezeli a szolgáltatások gyűjteményét, valamint HTTP-hívások küldését és fogadását a Personalizer-végpontra.
A minta webalkalmazás egy kiugró előtér-ügyfélalkalmazást használ a funkciók rögzítéséhez és a felhasználói felület műveleteinek feldolgozásához, például a gombokra való kattintáshoz és az adatok .NET-kiszolgálóra való küldéséhez.
Az alábbi szakaszok ismertetik a kiszolgáló és az ügyfél azon részeit, amelyeket a fejlesztőknek meg kell érteniük a Personalizer használatához.
Rank API: Az ügyfélalkalmazás kontextust küld a kiszolgálónak
Az ügyfélalkalmazás összegyűjti a felhasználó böngészőbeli felhasználói ügynökét.
Rank API: A kiszolgálóalkalmazás meghívja a Personalizert
Ez egy tipikus .NET-webalkalmazás egy ügyfélalkalmazással, a kazánlemez-kód nagy része az Ön számára van megadva. A Personalizerre nem jellemző kódokat a program eltávolítja a következő kódrészletekből, így a Personalizer-specifikus kódra összpontosíthat.
Personalizer-ügyfél létrehozása
A kiszolgáló Startup.cs fájljában a Personalizer-végpont és a kulcs használatával hozza létre a Personalizer-ügyfelet. Az ügyfélalkalmazásnak nem kell kommunikálnia a Personalizerrel ebben az alkalmazásban, ehelyett a kiszolgálóra támaszkodva kezdeményezi ezeket az SDK-hívásokat.
A webkiszolgáló .NET indítási kódja a következő:
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
}
}
A legjobb művelet kiválasztása
A kiszolgáló PersonalizerController.cs fájljában a GenerateRank kiszolgálói API összefoglalja a Rank API meghívásának előkészítését
- Új
eventIdlétrehozása a ranghíváshoz - A műveletek listájának lekérése
- A szolgáltatások listájának lekérése a felhasználótól, és környezetfunkciók létrehozása
- Opcionálisan állítsa be a kizárt műveleteket
- Rang API meghívása, eredmények visszaadva az ügyfélnek
/// <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);
}
A Personalizernek küldött JSON, amely mindkét műveletet (funkciókkal) és az aktuális környezeti funkciókat tartalmazza, a következőképpen néz ki:
{
"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
}
Personalizer rewardActionId visszaadása az ügyfélnek
A Rank API a kiválasztott legjobb művelet rewardActionId azonosítóját adja vissza a kiszolgálónak.
A rewardActionId azonosítóban visszaadott művelet megjelenítése.
{
"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"
}
Az ügyfél megjeleníti a rewardActionId műveletet
Ebben az oktatóanyagban az rewardActionId érték jelenik meg.
A saját jövőbeli alkalmazásában ez lehet egy pontos szöveg, egy gomb vagy a weblap kiemelt szakasza. A lista a pontszámok utólagos elemzésére, nem pedig a tartalom sorrendjére lesz visszaadva. Csak a rewardActionId tartalom jelenjen meg.
Reward API: információk gyűjtése jutalomért
A jutalom pontszámot gondosan kell megtervezni, ugyanúgy, ahogy a funkciókat tervezik. A jutalompontszámnak általában 0 és 1 közötti értéknek kell lennie. Az érték részben az ügyfélalkalmazásban, a felhasználói viselkedés alapján, részben a kiszolgálón, üzleti logika és célok alapján számítható ki.
Ha a kiszolgáló nem hívja meg a Reward API-t az Azure Portalon a Personalizer-erőforráshoz konfigurált Reward várakozási időn belül, akkor az alapértelmezett jutalom (az Azure Portalon is konfigurálva) lesz használva az eseményhez.
Ebben a mintaalkalmazásban kiválaszthat egy értéket, amelyből megtudhatja, hogy a jutalom milyen hatással van a kiválasztásokra.
További módszerek a mintából való tanulásra
A minta az Azure Portalon konfigurált több időalapú eseményt használ a Personalizer-erőforráshoz. Játsszon ezekkel az értékekkel, majd térjen vissza ehhez a minta webalkalmazáshoz, és nézze meg, hogy a változások milyen hatással vannak a Rang- és Reward-hívásokra:
- Jutalom várakozási ideje
- Modellfrissítés gyakorisága
További játékbeállítások a következők:
- Alapértelmezett jutalom
- Feltárási százalék
Clean up resources
Ha végzett ezzel az oktatóanyaggal, törölje a következő erőforrásokat:
- Törölje a mintaprojekt könyvtárát.
- Törölje a Personalizer-erőforrást – gondoljon egy személyre szabható erőforrásra, amely a műveletekhez és a környezethez tartozik – csak akkor használja újra az erőforrást, ha továbbra is a műveletek tárgyát képező tartományként használja az élelmiszereket.
Következő lépések
- A Personalizer működése
- Szolgáltatások: a műveletek és környezetek használatával használt funkciókkal kapcsolatos fogalmak megismerése
- Jutalmak: tudnivalók a jutalmak kiszámításáról