Öğretici: .NET web uygulamasına Kişiselleştirme ekleme

Bir kullanıcıya eylemlere (özelliklere sahip) ve bağlam özelliklerine göre doğru içeriği sağlamak için C# .NET web uygulamasını Kişiselleştirici döngüsüyle özelleştirin.

Bu öğreticide şunların nasıl yapıldığını öğrenirsiniz:

Web uygulaması için en iyi içeriği seçme

Web sayfasında görüntülenecek tek bir üst öğeye (rewardActionId) göre kişiselleştirilmiş bir eylem listesi (bir tür içerik) olduğunda web uygulaması Kişiselleştirme'yi kullanmalıdır. Eylem listelerine örnek olarak haber makaleleri, düğme yerleştirme konumları ve ürün adları için sözcük seçenekleri verilebilir.

Bağlam özellikleriyle birlikte eylemlerin listesini Kişiselleştirme döngüsüne gönderirsiniz. Kişiselleştirme en iyi tek eylemi seçer, ardından web uygulamanız bu eylemi görüntüler.

Bu öğreticide eylemler yiyecek türleridir:

• makarna
• dondurma
• su
• salata
• patlamış mısır
• kahve
• çorba

Kişiselleştirme'nin eylemleriniz hakkında bilgi edinebilmesine yardımcı olmak için her sıralama API'si isteğiyle hem özellikleri hem de bağlam özelliklerini içeren eylemleri gönderin.

Modelin bir özelliği, web uygulaması kullanıcı tabanınızın üyeleri arasında toplanabilir (gruplandırılabilir) eylem veya bağlam hakkındaki bilgilerdir. Bir özellik ayrı ayrı (kullanıcı kimliği gibi) veya yüksek oranda özel değildir (örneğin, günün tam saati).

Özelliklere sahip eylemler

Her eylemin (içerik öğesi) yiyecek öğesini ayırt etmeye yardımcı olacak özellikleri vardır.

Özellikler Azure portalında döngü yapılandırmasının bir parçası olarak yapılandırılmaz. Bunun yerine, her Rank API çağrısıyla bir JSON nesnesi olarak gönderilirler. Bu, eylemlerin ve özelliklerinin zaman içinde büyümesi, değişmesi ve küçülmesi için esneklik sağlayarak Kişiselleştirme'nin eğilimleri takip etmesini sağlar.

 /// <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;
  }

Bağlam özellikleri

Bağlam özellikleri Kişiselleştirme'nin eylemlerin bağlamını anlamasına yardımcı olur. Bu örnek uygulamanın bağlamı şunları içerir:

• günün saati - sabah, öğleden sonra, akşam, gece
• kullanıcının tadı tercihi - tuzlu, tatlı, acı, ekşi veya tuzlu
• tarayıcı bağlamı - kullanıcı aracısı, coğrafi konum, başvuran

/// <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];
}

Web uygulaması Kişiselleştirme'yi nasıl kullanır?

Web uygulaması, yiyecek seçenekleri listesinden en iyi eylemi seçmek için Kişiselleştirici'yi kullanır. Bunu, her Rank API çağrısıyla aşağıdaki bilgileri göndererek yapar:

• ve gibi taste özelliklerine sahip eylemlerspiceLevel
• gün gibi time bağlam özellikleri, kullanıcının taste tercihi, tarayıcının kullanıcı aracısı bilgileri ve bağlam özellikleri
• meyve suyu gibi dışlanması gereken eylemler
• Rank API'sine yapılan her çağrı için farklı olan eventId.

Web uygulamasında kişiselleştirme modeli özellikleri

Kişiselleştirme, eylemler (içerik) ve geçerli bağlam (kullanıcı ve ortam) için özelliklere ihtiyaç duyar. Özellikler, eylemleri modeldeki geçerli bağlama hizalamak için kullanılır. Model, Kişiselleştirici'nin eğitilmiş kararlar vermesine olanak tanıyan eylemler, bağlam ve özellikleri hakkındaki geçmiş bilgilerinin bir gösterimidir.

Özellikler de dahil olmak üzere model, Azure portalındaki Model güncelleştirme sıklığı ayarınıza göre bir zamanlamaya göre güncelleştirilir.

Özellikleri ve değerlerini planlama

Özellikler, teknik mimarinizdeki herhangi bir şemaya veya modele uygulayacağınız planlama ve tasarımla seçilmelidir. Özellik değerleri iş mantığı veya üçüncü taraf sistemlerle ayarlanabilir. Özellik değerleri, bir grup veya özellik sınıfına uygulanmayacak kadar belirgin olmamalıdır.

Özellik değerlerini genelleştirme

Kategoriler halinde genelleştirin

Bu uygulama özellik olarak kullanır time ancak zamanı , , afternooneveningve nightgibi morningkategoriler halinde gruplandırr. Bu, zaman bilgilerini kullanma örneğidir, ancak gibi 10:05:01 UTC+2son derece belirli bir şekilde kullanmaz.

Parçalar halinde genelleştirme

Bu uygulama, tarayıcıdan HTTP İsteği özelliklerini kullanır. Bu, tüm verileri içeren çok belirli bir dizeyle başlar, örneğin:

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

HttpRequestFeatures sınıf kitaplığı, bu dizeyi tek tek değerlerle bir userAgentInfo nesnesine genelleştirir. Çok özel olan tüm değerler boş bir dizeye ayarlanır. İsteğin bağlam özellikleri gönderildiğinde aşağıdaki JSON biçimine sahiptir:

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

Örnek web uygulamasını kullanma

Tarayıcı tabanlı örnek web uygulamasının (tüm kodlar sağlanır) uygulamayı çalıştırmak için aşağıdaki uygulamaların yüklü olması gerekir.

Aşağıdaki yazılımı yükleyin:

• .NET Core 2.1 - örnek arka uç sunucusu .NET core kullanır
• Node.js - istemci/ön uç bu uygulamaya bağlıdır
• Visual Studio 2019 veya .NET Core CLI - Uygulamayı derlemek ve çalıştırmak için Visual Studio 2019'un geliştirici ortamını veya .NET Core CLI'yı kullanın

Örneği ayarlama

1. Azure AI Kişiselleştirme Örnekleri depoyu kopyalayın.

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

2. çözümü HttpRequestFeaturesExample.slnaçmak için samples/HttpRequestFeatures adresine gidin.

   İstenirse Visual Studio'nın Kişiselleştirme için .NET paketini güncelleştirmesine izin verin.

Azure AI Kişiselleştirme Hizmetini ayarlama

1. Azure portalında bir Kişiselleştirme kaynağı oluşturun.

2. Azure portalında Anahtarlar ve Uç Noktalar sekmesinde ve Key2 Key1 veya (ya da çalışacaktır) öğesini bulunEndpoint. Bunlar sizin PersonalizerServiceEndpoint ve sizindirPersonalizerApiKey.

3. PersonalizerServiceEndpoint appsettings.json doldurun.

4. uygulamasını PersonalizerApiKey aşağıdaki yollardan biriyle uygulama gizli dizileri olarak yapılandırın:

   • .NET Core CLI kullanıyorsanız komutunu kullanabilirsiniz dotnet user-secrets set "PersonalizerApiKey" "<API Key>" .
   • Visual Studio kullanıyorsanız projeye sağ tıklayıp Kullanıcı Gizli Dizilerini Yönet menü seçeneğini belirleyerek Kişiselleştirme anahtarlarını yapılandırabilirsiniz. Bunu yaptığınızda Visual Studio, anahtarları aşağıdaki gibi ekleyebileceğiniz bir secrets.json dosya açar:

   {
     "PersonalizerApiKey": "<your personalizer key here>",
   }
   

Örneği çalıştırma

Aşağıdaki yöntemlerden biriyle HttpRequestFeaturesExample derleme ve çalıştırma:

• Visual Studio 2019: F5 tuşuna basın
• .NET Core CLI: dotnet build sonra dotnet run

Bir web tarayıcısı aracılığıyla Bir Derece isteği ve Ödül isteği gönderebilir, yanıtlarını ve ortamınızdan ayıklanan http isteği özelliklerini görebilirsiniz.

Kişiselleştirme döngüsünü gösterme

1. Rank API çağrısı için yeni bir JSON nesnesi oluşturmak için Yeni Sıralama İsteği Oluştur düğmesini seçin. Bu işlem eylemleri (özelliklerle) ve bağlam özelliklerini oluşturur ve değerleri görüntüler; böylece JSON'un nasıl göründüğünü görebilirsiniz.

   Kendi gelecekteki uygulamanız için, istemcide, sunucuda, ikisinin bir karışımında veya diğer hizmetlere yapılan çağrılarla eylem ve özellik oluşturma işlemi gerçekleşebilir.

2. JSON nesnesini sunucuya göndermek için Derece İsteği Gönder'i seçin. Sunucu Kişiselleştirme Derecelendirme API'sini çağırır. Sunucu yanıtı alır ve görüntülenecek istemciye en yüksek dereceli eylemi döndürür.

3. Ödül değerini ayarlayın, ardından Ödül İsteği Gönder düğmesini seçin. Ödül değerini değiştirmezseniz istemci uygulaması değerini her zaman Kişiselleştirici'ye gönderir 1 .

   

   Gelecekteki uygulamanız için, kullanıcının istemcideki davranışından ve sunucudaki iş mantığından bilgi topladıktan sonra ödül puanının oluşturulması gerçekleşebilir.

Örnek web uygulamasını anlama

Örnek web uygulaması, özellik koleksiyonunu yöneten ve Kişiselleştirme uç noktanıza HTTP çağrıları gönderen ve alan bir C# .NET sunucusuna sahiptir.

Örnek web uygulaması, özellikleri yakalamak ve düğmelere tıklama ve .NET sunucusuna veri gönderme gibi kullanıcı arabirimi eylemlerini işlemek için bir nakavt ön uç istemci uygulaması kullanır.

Aşağıdaki bölümlerde, bir geliştiricinin Kişiselleştirme'yi kullanmak için anlaması gereken sunucu ve istemci bölümleri açıklanmaktadır.

Sıralama API'si: İstemci uygulaması sunucuya bağlam gönderir

İstemci uygulaması kullanıcının tarayıcı kullanıcı aracısını toplar.

Sıralama API'si: Sunucu uygulaması Kişiselleştirmeyi çağırır

Bu, istemci uygulamasına sahip tipik bir .NET web uygulamasıdır, kazan plaka kodunun büyük bölümü sizin için sağlanır. Kişiselleştirici'ye özgü olmayan tüm kodlar, Kişiselleştirmeye özgü koda odaklanabilmeniz için aşağıdaki kod parçacıklarından kaldırılır.

Kişiselleştirme istemcisi oluşturma

Sunucunun Startup.cs Kişiselleştirici uç noktası ve anahtarı, Kişiselleştirici istemcisini oluşturmak için kullanılır. İstemci uygulamasının bu uygulamada Kişiselleştirme ile iletişim kurması gerekmez, bunun yerine söz konusu SDK çağrılarını yapmak için sunucuya bağımlıdır.

Web sunucusunun .NET başlangıç kodu:

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
    }
}

En iyi eylemi seçin

Sunucunun PersonalizerController.cs GenerateRank sunucu API'sinde Rank API'sini çağırma hazırlığı özetlenmiştir

• Rank çağrısı için yeni eventId oluşturma
• Eylem listesini alma
• Kullanıcıdan özellik listesini alma ve bağlam özellikleri oluşturma
• İsteğe bağlı olarak, dışlanan eylemleri ayarlayın
• Rank API'sini çağır, sonuçları istemciye döndür

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

Kişiselleştirme'ye gönderilen ve hem eylemleri (özelliklerle) hem de geçerli bağlam özelliklerini içeren JSON şöyle görünür:

{
    "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 değerini istemciye iade etme

Derece API'si, seçilen en iyi eylem rewardActionId değerini sunucuya döndürür.

rewardActionId içinde döndürülen eylemi görüntüleyin.

{
    "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"
}

İstemci rewardActionId eylemini görüntüler

Bu öğreticide rewardActionId değer görüntülenir.

Gelecekteki uygulamanızda, bu tam metin, düğme veya web sayfasının vurgulanmış bir bölümü olabilir. Liste, içeriğin sıralanması için değil, puanların son analizi için döndürülür. rewardActionId Yalnızca içerik görüntülenmelidir.

Ödül API'si: ödül için bilgi toplama

Ödül puanı , özellikler planlandığı gibi dikkatle planlanmalıdır. Ödül puanı genellikle 0 ile 1 arasında bir değer olmalıdır. Değer , kullanıcı davranışlarına göre istemci uygulamasında kısmen, iş mantığına ve hedeflerine göre kısmen sunucuda hesaplanabilir .

Sunucu, Kişiselleştirme kaynağınız için Azure portalında yapılandırılan Ödül bekleme süresi içinde Ödül API'sini çağırmazsa, bu olay için Varsayılan ödül (Azure portalında da yapılandırılır) kullanılır.

Bu örnek uygulamada, ödülün seçimleri nasıl etkilediğini görmek için bir değer seçebilirsiniz.

Bu örnekten öğrenmenin ek yolları

Örnek, Kişiselleştirme kaynağınız için Azure portalında yapılandırılmış birkaç zaman tabanlı olay kullanır. Bu değerlerle oynayın ve değişikliklerin Derece ve Ödül çağrılarını nasıl etkilediğini görmek için bu örnek web uygulamasına dönün:

• Ödül bekleme süresi
• Model güncelleştirme sıklığı

Yürütülecek ek ayarlar şunlardır:

• Varsayılan ödül
• Araştırma yüzdesi

Kaynakları temizleme

Bu öğreticiyi tamamladığınızda aşağıdaki kaynakları temizleyin:

• Örnek proje dizininizi silin.
• Kişiselleştirici kaynağınızı silin ( Kişiselleştirici kaynağını eylemlere ve bağlama ayrılmış olarak düşünebilirsiniz) yalnızca eylemlerin konu etki alanı olarak gıdaları kullanmaya devam ediyorsanız kaynağı yeniden kullanın.

Sonraki adımlar

• Kişiselleştirme nasıl çalışır?
• Özellikler: Eylemleri ve bağlamı kullanarak özelliklerin kavramlarını öğrenin
• Ödüller: Ödülleri hesaplama hakkında bilgi edinin