Kom igång med den lokala slutsatsdragnings-SDK:n för Azure AI Personalizer
Viktigt!
Från och med den 20 september 2023 kommer du inte att kunna skapa nya personaliseringsresurser. Personanpassningstjänsten dras tillbaka den 1 oktober 2026.
SDK för lokal slutsatsdragning för personanpassning (förhandsversion) laddar ned Personanpassningsmodellen lokalt och minskar därmed svarstiden för Rank-anrop avsevärt genom att eliminera nätverksanrop. Varje minut laddar klienten ned den senaste modellen i bakgrunden och använder den för slutsatsdragning.
I den här guiden får du lära dig hur du använder SDK:et för lokal härledning för personanpassning.
Du måste installera Personalizer-klientbiblioteket för .NET för att:
- Autentisera snabbstartsexempleklienten med en Personalizer-resurs i Azure.
- Skicka kontext- och åtgärdsfunktioner till Reward-API:et, som returnerar den bästa åtgärden från Personanpassningsmodellen
- Skicka en belöningspoäng till ranknings-API:et och träna personanpassningsmodellen.
ReferensdokumentationEns källkodspaket | för bibliotek (NuGet) |
Förutsättningar
- Azure-prenumeration – Skapa en kostnadsfritt
- Den aktuella versionen av .NET Core.
- När du har din Azure-prenumeration skapar du en Personalizer-resurs i Azure-portalen för att hämta din nyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
- Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till Personanpassnings-API:et. Du klistrar in nyckeln och slutpunkten i koden nedan senare i snabbstarten.
- Du kan använda den kostnadsfria prisnivån (
F0) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.
Konfigurera
Ändra uppdateringsfrekvensen för modellen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar uppdateringsfrekvensen för modell till 30 sekunder. Den här korta varaktigheten tränar modellen snabbt, så att du kan se hur den rekommenderade åtgärden ändras för varje iteration.
Ändra väntetiden för belöningen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar väntetiden för belöningen till 10 minuter. Detta avgör hur länge modellen väntar efter att ha skickat en rekommendation för att få belöningsfeedback från den rekommendationen. Träningen sker inte förrän belöningens väntetid har passerat.
Skapa ett nytt C#-program
Skapa ett nytt .NET Core-program i önskad redigerare eller IDE.
I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet-kommandot new för att skapa en ny konsolapp med namnet personalizer-quickstart. Det här kommandot skapar ett enkelt "Hello World"-C#-projekt med en enda källfil: Program.cs.
dotnet new console -n personalizer-quickstart
Ändra katalogen till den nyligen skapade appmappen. Du kan skapa programmet med:
dotnet build
Kompileringsutdata får inte innehålla några varningar eller fel.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Installera klientbiblioteket
I programkatalogen installerar du Personalizer-klientbiblioteket för .NET med följande kommando:
dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2
Dricks
Om du använder Visual Studio IDE är klientbiblioteket tillgängligt som ett nedladdningsbart NuGet-paket.
Öppna filen i önskad redigerare eller IDE från projektkatalogen Program.cs . Lägg till följande med hjälp av direktiv:
using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;
Objektmodell
Personanpassningsklienten är ett PersonalizerClient-objekt som autentiserar till Azure med hjälp av Azure.AzureKeyCredential, som innehåller din nyckel.
Om du vill be om det enskilt bästa objektet för att visa användaren skapar du en PersonalizerRankOptions och skickar den sedan till metoden PersonalizerClient.Rank . Metoden Rank returnerar en PersonalizerRankResult.
Skicka en belöningspoäng till Personanpassning genom att skicka händelse-ID:t och belöningspoängen till metoden PersonalizerClient.Reward .
Att fastställa belöningspoängen i den här snabbstarten är trivialt. I ett produktionssystem kan du bestämma vad som påverkar belöningspoängen och hur mycket som kan vara en komplex process, som du kan besluta att ändra över tid. Det här designbeslutet bör vara ett av de viktigaste besluten i din personanpassningsarkitektur.
Kodexempel
De här kodfragmenten visar hur du utför följande uppgifter med Personalizer-klientbiblioteket för .NET:
- Skapa en personanpassningsklient
- Ranknings-API för flera platser
- Belönings-API för flera platser
Autentisera klienten
I det här avsnittet gör du två saker:
- Ange din nyckel och slutpunkt
- Skapa en personanpassningsklient
Börja med att lägga till följande rader i klassen Program. Se till att lägga till din nyckel och slutpunkt från personaliserarresursen.
Viktigt!
Gå till Azure-portalen. Om personanpassningsresursen som du skapade i avsnittet Förutsättningar har distribuerats klickar du på knappen Gå till resurs under Nästa steg. Du hittar din nyckel och slutpunkt på resursens nyckel- och slutpunktssida under resurshantering.
Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion bör du överväga att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter. Till exempel Azure Key Vault.
private const string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";
Skapa sedan URL:erna Rank och Reward. Observera att det krävs en inställning useLocalInference: true som parameter för för PersonalizerClientOptions att aktivera lokal slutsatsdragning.
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));
}
Hämta innehållsval som representeras som åtgärder
Åtgärder representerar de innehållsval som du vill att Personanpassning ska välja det bästa innehållsobjektet från. Lägg till följande metoder i klassen Program för att representera uppsättningen med åtgärder och deras funktioner.
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;
}
Hämta användarinställningar för kontext
Lägg till följande metoder i klassen Program för att hämta en användares indata från kommandoraden för tid på dagen och användarens smakinställningar. Dessa används som kontextfunktioner.
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];
}
Båda metoderna använder GetKey metoden för att läsa användarens val från kommandoraden.
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 }
};
}
Skapa inlärningsloopen
Personalizer-inlärningsloopen är en cykel med ranknings- och belöningsanrop. I den här snabbstarten följs varje Rank-anrop, för att anpassa innehållet, av ett Reward-anrop för att berätta för Personanpassning hur väl tjänsten har utförts.
Följande kod loopar igenom en cykel där användaren uppmanas sina inställningar via kommandoraden, skickar informationen till Personanpassning för att välja den bästa åtgärden för varje fack, presenterar valet för kunden att välja bland listan och skickar sedan en belöningspoäng till Personanpassning som signalerar hur bra tjänsten gjorde i sitt val.
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);
}
Köra programmet
Kör programmet med dotnet-kommandot run från programkatalogen.
dotnet run
