Azure AI Kişiselleştirme için yerel çıkarım SDK'sını kullanmaya başlama

Önemli

20 Eylül 2023 tarihinden itibaren yeni Kişiselleştirme kaynakları oluşturamayacaksınız. Kişiselleştirme hizmeti 1 Ekim 2026'da kullanımdan kaldırılıyor.

Kişiselleştirme yerel çıkarım SDK'sı (Önizleme) Kişiselleştirme modelini yerel olarak indirir ve bu nedenle ağ çağrılarını ortadan kaldırarak Sıralama çağrılarının gecikme süresini önemli ölçüde azaltır. İstemci her dakika arka planda en son modeli indirir ve çıkarım için kullanır.

Bu kılavuzda Kişiselleştirme yerel çıkarım SDK'sını kullanmayı öğreneceksiniz.

.NET için Kişiselleştirme istemci kitaplığını şu şekilde yüklemeniz gerekir:

• Azure'da bir Kişiselleştirme kaynağıyla hızlı başlangıç örnek istemcisinin kimliğini doğrulama.
• Bağlam ve eylem özelliklerini Reward API'sine göndererek Kişiselleştirme modelinden en iyi eylemi döndürecek
• Derece API'sine bir ödül puanı gönderin ve Kişiselleştirici modelini eğitin.

Başvuru belgeleri | Kitaplık kaynak kodu | Paketi (NuGet)

Ön koşullar

• Azure aboneliği - Ücretsiz olarak oluşturun
• .NET Core'un geçerli sürümü.
• Azure aboneliğinizi aldıktan sonra anahtarınızı ve uç noktanızı almak için Azure portalında bir Kişiselleştirme kaynağı oluşturun. Dağıtıldıktan sonra Kaynağa git'i seçin.
  • Uygulamanızı Kişiselleştirme API'sine bağlamak için oluşturduğunuz kaynaktan anahtara ve uç noktaya ihtiyacınız olacaktır. Anahtarınızı ve uç noktanızı hızlı başlangıcın ilerleyen bölümlerinde aşağıdaki koda yapıştıracaksınız.
  • Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek için ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

Ayarlama

Model güncelleştirme sıklığını değiştirme

Azure portalında Kişiselleştirme kaynağınızın Yapılandırma sayfasına gidin ve Model güncelleştirme sıklığını 30 saniye olarak değiştirin. Bu kısa süre modeli hızla eğiterek önerilen eylemin her yineleme için nasıl değiştiğini görmenizi sağlar.

Ödül bekleme süresini değiştirme

Azure portalında Kişiselleştirme kaynağınızın Yapılandırma sayfasına gidin ve Ödül bekleme süresini 10 dakika olarak değiştirin. Bu, bir öneri gönderdikten sonra modelin öneriden ödül geri bildirimi almak için ne kadar bekleyeceğini belirler. Ödül bekleme süresi geçene kadar eğitim gerçekleşmez.

Yeni bir C# uygulaması oluşturma

Tercih ettiğiniz düzenleyicide veya IDE'de yeni bir .NET Core uygulaması oluşturun.

Bir konsol penceresinde (cmd, PowerShell veya Bash gibi), adlı personalizer-quickstartyeni bir konsol uygulaması oluşturmak için dotnet new komutunu kullanın. Bu komut, tek bir kaynak dosyasıyla basit bir "Merhaba Dünya" C# projesi oluşturur: Program.cs.

dotnet new console -n personalizer-quickstart

Dizininizi yeni oluşturulan uygulama klasörüyle değiştirin. Uygulamayı şu şekilde oluşturabilirsiniz:

dotnet build

Derleme çıkışı hiçbir uyarı veya hata içermemelidir.

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

İstemci kitaplığını yükleme

Uygulama dizininde, .NET için Kişiselleştirme istemci kitaplığını aşağıdaki komutla yükleyin:

dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2

Bahşiş

Visual Studio IDE kullanıyorsanız, istemci kitaplığı indirilebilir bir NuGet paketi olarak kullanılabilir.

Proje dizininden dosyayı tercih ettiğiniz düzenleyicide veya IDE'de açın Program.cs . Aşağıdaki kullanım yönergelerini ekleyin:

using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;

Nesne modeli

Kişiselleştirme istemcisi, anahtarınızı içeren Azure.AzureKeyCredential kullanarak Azure'da kimlik doğrulaması yapan bir PersonalizerClient nesnesidir.

Kullanıcıya gösterilecek en iyi tek öğeyi istemek için bir PersonalizerRankOptions oluşturun ve bunu PersonalizerClient.Rank yöntemine geçirin. Rank yöntemi bir PersonalizerRankResult döndürür.

Personalizer'a ödül puanı göndermek için olay kimliğini ve ödül puanını PersonalizerClient.Reward yöntemine geçirin.

Ödül puanını belirlemek, bu hızlı başlangıçta önemsizdir. Bir üretim sisteminde, ödül puanını neyin etkilediğinin belirlenmesi ve zaman içinde değişmeye karar verebileceğiniz karmaşık bir sürecin ne kadar olabileceği. Bu tasarım kararı, Kişiselleştirme mimarinizdeki birincil kararlardan biri olmalıdır.

Kod örnekleri

Bu kod parçacıkları, .NET için Kişiselleştirme istemci kitaplığıyla aşağıdaki görevlerin nasıl yapılacağını gösterir:

• Kişiselleştirme istemcisi oluşturma
• Çok Yuvalı Sıralama API'si
• Çok Yuvalı Ödül API'si

İstemcinin kimliğini doğrulama

Bu bölümde iki şey yapacaksınız:

• Anahtarınızı ve uç noktanızı belirtin
• Kişiselleştirme istemcisi oluşturma

Program sınıfınıza aşağıdaki satırları ekleyerek başlayın. Kişiselleştirme kaynağınızdan anahtarınızı ve uç noktanızı eklediğinizden emin olun.

Önemli

Azure portalına gidin. Önkoşullar bölümünde oluşturduğunuz Kişiselleştirme kaynağı başarıyla dağıtıldıysa, Sonraki Adımlar'ın altındaki Kaynağa Git düğmesine tıklayın. Anahtarınızı ve uç noktanızı kaynağın anahtar ve uç nokta sayfasında, kaynak yönetimi altında bulabilirsiniz.

İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için kimlik bilgilerinizi depolamak ve bunlara erişmek için güvenli bir yol kullanmayı göz önünde bulundurun. Örneğin, Azure anahtar kasası.

private const string ServiceEndpoint  = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";

Ardından Derece ve Ödül URL'lerini oluştur. Yerel çıkarımı etkinleştirmek için PersonalizerClientOptions parametresi olarak ayarın useLocalInference: true gerekli olduğunu unutmayın.

static PersonalizerClient InitializePersonalizerClient(Uri url)
{
    // Set the local inference flag to true when initializing the client.
    return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey), new PersonalizerClientOptions(useLocalInference: true));
}

Eylem olarak temsil edilen içerik seçeneklerini alma

Eylemler, Kişiselleştirme'nin en iyi içerik öğesini seçmesini istediğiniz içerik seçimlerini gösterir. Eylem kümesini ve özelliklerini göstermek için Program sınıfına aşağıdaki yöntemleri ekleyin.

static IList<PersonalizerRankableAction> GetActions()
{
    IList<PersonalizerRankableAction> actions = new List<PersonalizerRankableAction>
    {
        new PersonalizerRankableAction(
            id: "pasta",
            features: new List<object>() { new { taste = "salty", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
        ),

        new PersonalizerRankableAction(
            id: "ice cream",
            features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
        ),

        new PersonalizerRankableAction(
            id: "juice",
            features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
        ),

        new PersonalizerRankableAction(
            id: "salad",
            features: new List<object>() { new { taste = "salty", spiceLevel = "low" }, new { nutritionLevel = 8 } }
        )
    };

    return actions;
}

Bağlam için kullanıcı tercihlerini alma

Günün saati ve kullanıcı tadı tercihi için komut satırından kullanıcının girişini almak için Program sınıfına aşağıdaki yöntemleri ekleyin. Bunlar bağlam özellikleri olarak kullanılır.

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

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

    return timeOfDayFeatures[timeIndex - 1];
}

static string GetUsersTastePreference()
{
    string[] tasteFeatures = new string[] { "salty", "sweet" };
    var random = new Random();
    var taste = random.Next(1, 2);

    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[taste - 1];
}

Her iki yöntem de komut satırından kullanıcının seçimini okumak için yöntemini kullanır GetKey .

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

private static IList<object> GetContext(string time, string taste)
{
    return new List<object>()
    {
        new { time = time },
        new { taste = taste }
    };
}

Öğrenme döngüsünü oluşturma

Kişiselleştirme öğrenme döngüsü, Rank ve Reward çağrılarının bir döngüsüdür. Bu hızlı başlangıçta, içeriği kişiselleştirmek için yapılan her Sıralama çağrısının ardından Hizmetin ne kadar iyi performans sergilediğini kişiselleştirmek için bir Reward çağrısı yapılır.

Aşağıdaki kod, kullanıcıya komut satırı üzerinden tercihlerini sorma döngüsü boyunca döngü yapar, bu bilgileri Her yuva için en iyi eylemi seçmesi için Kişiselleştirme'ye gönderir, listeden seçim yapmak üzere müşteriye seçimi sunar ve ardından hizmetin seçiminde ne kadar iyi olduğunu gösteren bir ödül puanı Kişiselleştirme'ye gönderir.

static void Main(string[] args)
{
    Console.WriteLine($"Welcome to this Personalizer Quickstart!\n" +
    $"This code will help you understand how to use the Personalizer APIs (rank and reward).\n" +
    $"Each iteration represents a user interaction and will demonstrate how context, actions, and rewards work.\n" +
    $"Note: Personalizer AI models learn from a large number of user interactions:\n" +
    $"You won't be able to tell the difference in what Personalizer returns by simulating a few events by hand.\n" +
    $"If you want a sample that focuses on seeing how Personalizer learns, see the Python Notebook sample.");

    int iteration = 1;
    bool runLoop = true;

    IList<PersonalizerRankableAction> actions = GetActions();
    PersonalizerClient client = InitializePersonalizerClient(new Uri(ServiceEndpoint));

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

        string timeOfDayFeature = GetTimeOfDayForContext();
        string deviceFeature = GetUsersTastePreference();

        IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);

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

        var rankOptions = new PersonalizerRankOptions(actions: actions, contextFeatures: currentContext, eventId: eventId);
        PersonalizerRankResult rankResult = client.Rank(rankOptions);

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

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

        if (answer == "Y")
        {
            reward = 1.0f;
            Console.WriteLine("\nGreat! Enjoy your food.");
        }
        else if (answer == "N")
        {
            reward = 0.0f;
            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.");
        }

        client.Reward(rankResult.EventId, reward);

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

    } while (runLoop);
}

Programı çalıştırma

Uygulamayı uygulama dizininizdeki dotnet run komutuyla çalıştırın.

dotnet run