Azure AI Personalizer용 로컬 유추 SDK 시작
Important
2023년 9월 20일부터 새로운 Personalizer 리소스를 만들 수 없습니다. Personalizer 서비스는 2026년 10월 1일에 사용 중지됩니다.
Personalizer 로컬 유추 SDK(미리 보기)는 Personalizer 모델을 로컬로 다운로드하므로 네트워크 호출을 제거하여 순위 호출의 대기 시간을 크게 줄입니다. 1분마다 클라이언트는 백그라운드에서 최신 모델을 다운로드하고 유추에 사용합니다.
이 가이드에서는 Personalizer 로컬 유추 SDK를 사용하는 방법에 대해 알아봅니다.
다음을 수행하려면 .NET용 Personalizer 클라이언트 라이브러리를 설치해야 합니다.
- Azure의 Personalizer 리소스를 사용하여 빠른 시작 예 클라이언트를 인증합니다.
- 컨텍스트 및 작업 기능을 보상 API로 전송하면 Personalizer 모델에서 최상의 작업을 반환합니다.
- Rank API에 보상 점수를 보내고 Personalizer 모델을 학습시킵니다.
참조 설명서 | 라이브러리 소스 코드 | 패키지(NuGet)
필수 조건
- Azure 구독 - 체험 구독 만들기
- 최신 버전의 .NET Core
- Azure 구독이 있으면 Azure Portal에서 Personalizer 리소스를 만들어 키와 엔드포인트를 가져옵니다. 배포 후 리소스로 이동을 선택합니다.
- 애플리케이션을 Personalizer API에 연결하려면 만든 리소스의 키와 엔드포인트가 필요합니다. 이 빠른 시작의 뒷부분에 나오는 코드에 키와 엔드포인트를 붙여넣습니다.
- 평가판 가격 책정 계층(
F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.
설정
모델 업데이트 빈도 변경
Azure Portal에서 Personalizer 리소스의 구성 페이지로 이동하고 모델 업데이트 빈도를 30초로 변경합니다. 이 짧은 기간은 모델을 빠르게 학습시켜 각 반복에 대해 권장 작업이 어떻게 변경되는지 확인할 수 있습니다.
보상 대기 시간 변경
Azure Portal에서 Personalizer 리소스의 구성 페이지로 이동하고 보상 대기 시간을 10분으로 변경합니다. 이는 모델이 권장 사항을 보낸 후 해당 권장 사항에서 보상 피드백을 받기 위해 대기하는 시간을 결정합니다. 보상 대기 시간이 지날 때까지 학습이 발생하지 않습니다.
새 C# 애플리케이션 만들기
선호하는 편집기 또는 IDE에서 .NET Core 애플리케이션을 새로 만듭니다.
콘솔 창(예: cmd, PowerShell 또는 Bash)에서 dotnet new 명령을 사용하여 personalizer-quickstart라는 새 콘솔 앱을 만듭니다. 이 명령은 Program.cs라는 단일 소스 파일을 사용하여 간단한 "Hello World" C# 프로젝트를 만듭니다.
dotnet new console -n personalizer-quickstart
새로 만든 앱 폴더로 디렉터리를 변경합니다. 다음을 통해 애플리케이션을 빌드할 수 있습니다.
dotnet build
빌드 출력에 경고나 오류가 포함되지 않아야 합니다.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
클라이언트 라이브러리 설치
애플리케이션 디렉터리 내에서 다음 명령을 사용하여 .NET용 Personalizer 클라이언트 라이브러리를 설치합니다.
dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2
팁
Visual Studio IDE를 사용하는 경우 클라이언트 라이브러리는 다운로드 가능한 NuGet 패키지로 제공됩니다.
프로젝트 디렉터리의 원하는 편집기나 IDE에서 Program.cs 파일을 엽니다. 다음 using 지시문을 추가합니다.
using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;
개체 모델
Personalizer 클라이언트는 키가 포함된 Azure.AzureKeyCredential을 사용하여 Azure에 인증하는 PersonalizerClient 개체입니다.
사용자에게 표시할 최상의 단일 항목을 요청하려면 PersonalizerRankOptions를 만든 다음, PersonalizerClient.Rank 메서드에 전달합니다. Rank 메서드는 PersonalizerRankResult를 반환합니다.
Personalizer에 보상 점수를 보내려면 이벤트 ID와 보상 점수를 PersonalizerClient.Reward 메서드에 전달합니다.
이 빠른 시작에서 보상 점수를 결정하는 방법은 간단합니다. 프로덕션 시스템에서 보상 점수에 영향을 주는 요소와 크기를 결정하는 것은 복잡한 프로세스일 수 있으며, 시간이 지남에 따라 변경될 수 있습니다. 이 설계 결정은 Personalizer 아키텍처에서 기본 설계 결정 중 하나여야 합니다.
코드 예제
여기에 나와 있는 코드 조각에서는 .NET용 Personalizer 클라이언트 라이브러리를 사용하여 다음 작업을 수행하는 방법을 보여 줍니다.
- Personalizer 클라이언트 만들기
- 다중 슬롯 순위 API
- 다중 슬롯 보상 API
클라이언트 인증
이 섹션에서는 다음과 같은 두 가지 작업을 수행합니다.
- 키 및 엔드포인트 지정
- Personalizer 클라이언트 만들기
프로그램 클래스에 다음 줄을 추가하여 시작합니다. Personalizer 리소스에서 키와 엔드포인트를 추가해야 합니다.
Important
Azure Portal로 이동합니다. 필수 구성 요소 섹션에서 만든 Personalizer 리소스가 성공적으로 배포된 경우 다음 단계 아래에서 리소스로 이동 단추를 클릭합니다. 리소스 관리 아래에 있는 리소스의 키 및 엔드포인트 페이지에서 키 및 엔드포인트를 찾을 수 있습니다.
완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용하는 것이 좋습니다. 예를 들어 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>";
다음으로, 순위 및 보상 URL을 생성합니다. 로컬 유추를 사용하도록 설정하려면 useLocalInference: true를 PersonalizerClientOptions의 매개 변수로 설정해야 합니다.
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));
}
작업으로 표현되는 콘텐츠 선택 항목 가져오기
작업은 Personalizer에서 최상의 콘텐츠 항목을 선택할 수 있는 콘텐츠 선택 항목을 나타냅니다. Program 클래스에 다음 메서드를 추가하여 작업 세트와 해당 기능을 표시합니다.
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;
}
컨텍스트에 대한 사용자 기본 설정 검색
다음 메서드를 Program 클래스에 추가하여 시간 및 사용자 취향 기본 설정에 대한 명령줄에서 사용자의 입력을 가져옵니다. 이러한 메서드는 컨텍스트 기능으로 사용됩니다.
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];
}
두 메서드는 모두 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 }
};
}
학습 루프 만들기
Personalizer 학습 루프는 순위 및 보상 호출의 주기입니다. 이 빠른 시작에서는 각 순위 호출을 수행하여 콘텐츠를 맞춤 설정한 다음, 보상 호출을 수행하여 서비스에서 얼마나 잘 수행되었는지 Personalizer에 알려줍니다.
다음 코드는 명령줄을 통해 사용자에게 해당 기본 설정을 요청하고, 해당 정보를 Personalizer로 보내어 각 슬롯에 대한 최상의 작업을 선택하고, 고객에게 해당 선택 항목을 제시하여 목록에서 선택한 다음, 보상 점수를 Personalizer에 전달하여 서비스에서 얼마나 잘 지정했는지 알려주는 주기를 반복합니다.
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);
}
프로그램 실행
애플리케이션 디렉터리에서 dotnet run 명령을 사용하여 애플리케이션을 실행합니다.
dotnet run
