Merge pull request #100627 from diberry/diberry/0109-personalizer-troubleshooting-2

[Cogsvcs] Personalizer - import learning policy

Author: GitHubber17

articles/cognitive-services/personalizer/concept-active-learning.md

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: personalizer
 ms.topic: conceptual
-ms.date: 05/30/2019
+ms.date: 01/09/2019
 ms.author: diberry
 ---
 
@@ -20,10 +20,10 @@ In some scenarios, the application might need to call Rank before it even knows
 
 Typically, these scenarios happen when:
 
-* You're prerendering UI that the user might or might not get to see. 
-* Your application is doing predictive personalization in which Rank calls are made with little real-time context and the application might or might not use the output. 
+* You're prerendering UI that the user might or might not get to see.
+* Your application is doing predictive personalization in which Rank calls are made with little real-time context and the application might or might not use the output.
 
-In these cases, use Personalizer to call Rank, requesting the event to be _inactive_. Personalizer won't expect a reward for this event, and it won't apply a default reward. 
+In these cases, use Personalizer to call Rank, requesting the event to be _inactive_. Personalizer won't expect a reward for this event, and it won't apply a default reward.
 Later in your business logic, if the application uses the information from the Rank call, just _activate_ the event. As soon as the event is active, Personalizer expects an event reward. If no explicit call is made to the Reward API, Personalizer applies a default reward.
 
 ## Inactive events
@@ -38,15 +38,28 @@ Learning settings determine the *hyperparameters* of the model training. Two mod
 
 You can import and export learning-policy files from the Azure portal. Use this method to save existing policies, test them, replace them, and archive them in your source code control as artifacts for future reference and audit.
 
+Learn [how to](how-to-learning-policy.md) import and export a learning policy.
+
 ### Understand learning policy settings
 
 The settings in the learning policy aren't intended to be changed. Change settings only if you understand how they affect Personalizer. Without this knowledge, you could cause problems, including invalidating Personalizer models.
 
+Personalizer uses [vowpalwabbit](https://github.com/VowpalWabbit) to train and score the events. Refer to the [vowpalwabbit documentation](https://github.com/VowpalWabbit/vowpal_wabbit/wiki/Command-line-arguments) on how to edit the learning settings using vowpalwabbit. Once you have the correct command line arguments, save the command to a file with the following format (replace the arguments property value with the desired command) and upload the file to import learning settings in the **Model and Learning Settings** pane in the Azure portal for your Personalizer resource.
+
+The following `.json` is an example of a learning policy.
+
+```json
+{
+  "name": "new learning settings",
+  "arguments": " --cb_explore_adf --epsilon 0.2 --power_t 0 -l 0.001 --cb_type mtr -q ::"
+}
+```
+
 ### Compare learning policies
 
 You can compare how different learning policies perform against past data in Personalizer logs by doing [offline evaluations](concepts-offline-evaluation.md).
 
-[Upload your own learning policies](how-to-offline-evaluation.md) to compare them with the current learning policy.
+[Upload your own learning policies](how-to-learning-policy.md) to compare them with the current learning policy.
 
 ### Optimize learning policies
 

articles/cognitive-services/personalizer/how-to-learning-policy.md

@@ -0,0 +1,30 @@
+---
+title: Manage learning policy - Personalizer
+description: This article contains answers to frequently asked troubleshooting questions about Personalizer.
+ms.topic: conceptual
+ms.date: 01/08/2019
+---
+
+# Manage learning policy
+
+Learning policy settings determine the _hyperparameters_ of the model training. The learning policy is defined in a `.json` file.
+
+## Import a new learning policy
+
+1. Open the [Azure portal](https://portal.azure.com), and select your Personalizer resource.
+1. Select **Model and learning settings** in the **Resource Management** section.
+1. For the **Import learning settings** select the file you created with the JSON format specified above, then select the **Upload** button.
+
+    Wait for the notification that the learning policy was uploaded successfully.
+
+## Export a learning policy
+
+1. Open the [Azure portal](https://portal.azure.com), and select your Personalizer resource.
+1. Select **Model and learning settings** in the **Resource Management** section.
+1. For the **Import learning settings** select the **Export learning settings** button. This saves the `json` file to your local computer.
+
+## Next steps
+
+Learn about learning policy [concepts](concept-active-learning.md#learning-settings)
+
+[Learn about region availability](https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services)

articles/cognitive-services/personalizer/how-to-settings.md

@@ -10,7 +10,7 @@ ms.subservice: personalizer
 ms.topic: conceptual
 ms.date: 10/23/2019
 ms.author: diberry
-#Customer intent: 
+#Customer intent:
 ---
 
 # Configure Personalizer
@@ -19,9 +19,9 @@ Service configuration includes how the service treats rewards, how often the ser
 
 ## Create Personalizer resource
 
-Create a Personalizer resource for each feedback loop. 
+Create a Personalizer resource for each feedback loop.
 
-1. Sign in to [Azure portal](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesPersonalizer). The previous link takes you to the **Create** page for the Personalizer service. 
+1. Sign in to [Azure portal](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesPersonalizer). The previous link takes you to the **Create** page for the Personalizer service.
 1. Enter your service name, select a subscription, location, pricing tier, and resource group.
 1. Select the confirmation and select **Create**.
 
@@ -30,7 +30,7 @@ Create a Personalizer resource for each feedback loop.
 ## Configure service in the Azure portal
 
 1. Sign in to the [Azure portal](https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesPersonalizer).
-1. Find your Personalizer resource. 
+1. Find your Personalizer resource.
 1. In the **Resource management** section, select **Configuration**.
 
     Before leaving the Azure portal, copy one of your resource keys from the **Keys** page. You will need this to use the [Personalizer SDK](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.personalizer).
@@ -51,9 +51,9 @@ Configure the service for your feedback loop's use of rewards. Changes to the fo
 
 After changing these values, make sure to select **Save**.
 
-### Configure exploration 
+### Configure exploration
 
-Personalization is able to discover new patterns and adapt to user behavior changes over time by exploring alternatives. The **Exploration** value determines what percentage of Rank calls are answered with exploration. 
+Personalization is able to discover new patterns and adapt to user behavior changes over time by exploring alternatives. The **Exploration** value determines what percentage of Rank calls are answered with exploration.
 
 Changes to this value will reset the current Personalizer model and retrain it with the last 2 days of data.
 
@@ -63,7 +63,7 @@ After changing this value, make sure to select **Save**.
 
 ### Model update frequency
 
-The latest model, trained from Reward API calls from every active event, isn't automatically used by Personalizer Rank call. The **Model update frequency** sets how often the model used by the Rank call up updated. 
+The latest model, trained from Reward API calls from every active event, isn't automatically used by Personalizer Rank call. The **Model update frequency** sets how often the model used by the Rank call up updated.
 
 High model update frequencies are useful for situations where you want to closely track changes in user behaviors. Examples include sites that run on live news, viral content, or live product bidding. You could use a 15-minute frequency in these scenarios. For most use cases, a lower update frequency is effective. One-minute update frequencies are useful when debugging an application's code using Personalizer, doing demos, or interactively testing machine learning aspects.
 
@@ -79,15 +79,10 @@ After changing this value, make sure to select **Save**.
 
 ## Export the Personalizer model
 
-From the Resource management's section for **Model and learning settings**, review model creation and last updated date and export the current model. You can use the Azure portal or the Personalizer APIs to export a model file for archival purposes. 
+From the Resource management's section for **Model and learning settings**, review model creation and last updated date and export the current model. You can use the Azure portal or the Personalizer APIs to export a model file for archival purposes.
 
 ![Export current Personalizer model](media/settings/export-current-personalizer-model.png)
 
-## Import and export learning policy
-
-From the Resource management's section for **Model and learning settings**, import a new learning policy or export the current learning policy.
-You can get learning policy files from previous exports, or downloading the optimized policies discovered during Offline Evaluations. Making manual changes to these files will affect machine learning performance and accuracy of offline evaluations, and Microsoft cannot vouch for the accuracy of machine learning and evaluations, or service exceptions resulting from manually edited policies.
-
 ## Clear data for your learning loop
 
 1. In the Azure portal, for your Personalizer resource, on the **Model and learning settings** page, select **Clear data**.
@@ -101,9 +96,8 @@ You can get learning policy files from previous exports, or downloading the opti
     |Reset the Personalizer model.|This model changes on every retraining. This frequency of training is specified in **upload model frequency** on the **Configuration** page. |
     |Set the learning policy to default.|If you have changed the learning policy as part of an offline evaluation, this resets to the original learning policy.|
 
-1. Select **Clear selected data** to begin the clearing process. Status is reported in Azure notifications, in the top-right navigation. 
+1. Select **Clear selected data** to begin the clearing process. Status is reported in Azure notifications, in the top-right navigation.
 
 ## Next steps
 
-
-[Learn about region availability](https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services)
+[Learn how to manage a learning policy](how-to-learning-policy.md)

articles/cognitive-services/personalizer/toc.yml

@@ -66,6 +66,8 @@
   - name: Create and configure Personalizer
     href: how-to-settings.md
     displayName: azure, portal, settings, evaluation, offline, policy, export, model, configure
+  - name: Manage your learning policy
+    href: how-to-learning-policy.md
   - name: Analyze
     items:
     - name: Offline evaluation

articles/cognitive-services/personalizer/troubleshooting.md

@@ -67,6 +67,11 @@ This is typically due to timestamps, user IDs or some other fine grained feature
 
 The offline evaluation uses the trained model data from the events in that time period. If you did not send any data in the time period between start and end time of the evaluation, it will complete without any results. Submit a new offline evaluation by selecting a time range with events you know were sent to Personalizer.
 
+## Learning policy
+
+### How do I import a learning policy?
+
+Learn more about [learning policy concepts](concept-active-learning.md#understand-learning-policy-settings) and [how to apply](how-to-learning-policy.md) a new learning policy. If you do not want to select a learning policy, you can use the [offline evaluation](how-to-offline-evaluation.md) to suggest a learning policy, based on your current events.
 
 
 ## Security