Merge pull request #78395 from diberry/0530-personalizer

[Cogsvcs] Personalizer - docs from private repo

Author: atookey

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

@@ -0,0 +1,67 @@
+---
+title: Active learning - Personalizer
+titleSuffix: Azure Cognitive Services
+description: 
+services: cognitive-services
+author: edjez
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: personalizer
+ms.topic: overview
+ms.date: 05/30/2019
+ms.author: edjez
+---
+
+# Active learning and learning policies 
+
+When your application calls the Rank API, you receive a rank of the content. Business logic can use this rank to determine if the content should be display to the user. When you display the ranked content, that is an _active_ rank event. When your application does not display that ranked content, that is an _inactive_ rank event. 
+
+Active rank event information is returned to Personalizer. This information is used to continue training the model through the current learning policy.
+
+## Active events
+
+Active events should always be shown to the user and the reward call should be returned to close the learning loop. 
+
+### Inactive events 
+
+Inactive events shouldn't change the underlying model because the user wasn't given a chance to choose from the ranked content.
+
+## Don't train with inactive rank events 
+
+For some applications, you may need to call the Rank API without knowing yet if your application will display the results to the user. 
+
+This happens when:
+
+* You may be pre-rendering some UI that the user may or may not get to see. 
+* Your application may be doing predictive personalization in which Rank calls are made with less real-time context and their output may or may not be used by the application. 
+
+### Disable active learning for inactive rank events during Rank call
+
+To disabling automatic learning, call Rank with `learningEnabled = False`.
+
+Learning for an inactive event is implicitly activated if you send a reward for the Rank.
+
+## Learning policies
+
+Learning policy determines the specific *hyperparameters* of the model training. Two models of the same data, trained on different learning policies, will behave differently.
+
+### Importing and exporting Learning Policies
+
+You can import and export learning policy files from the Azure portal. This allows you to save existing policies, test them, replace them, and archive them in your source code control as artifacts for future reference and audit.
+
+### Learning policy settings
+
+The settings in the **Learning Policy** are not intended to be changed. Only change the settings when you understand how they impact Personalizer. Changing settings without this knowledge will cause side effects, including invalidating Personalizer models.
+
+### Comparing effectiveness of learning policies
+
+You can compare how different Learning Policies would have performed 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 with the current learning policy.
+
+### Discovery of optimized learning policies
+
+Personalizer can create a more optimized learning policy when doing an [offline evaluation](how-to-offline-evaluation.md). 
+A more optimized learning policy, which is shown to have better rewards in an offline evaluation, will yield better results when used online in Personalizer.
+
+After an optimized learning policy has been created, you can apply it directly to Personalizer so it replaces the current policy immediately, or you can save it for further evaluation and decide in the future whether to discard, save, or apply it later.

articles/cognitive-services/personalizer/csharp-quickstart-commandline-feedback-loop.md

@@ -37,7 +37,9 @@ Getting started with Personalizer involves the following steps:
 
 ## Change the model update frequency
 
-In the Personalizer resource in the Azure portal, change the **Model update frequency** to 10 seconds. This will train the service rapidly, allowing you to see how the top action changes for each iteration
+In the Personalizer resource in the Azure portal, change the **Model update frequency** to 10 seconds. This will train the service rapidly, allowing you to see how the top action changes for each iteration.
+
+When a Personalizer Loop is first instantiated, there is no model since there has been no Reward API calls to train from. Rank calls will return equal probabilities for each item. Your application should still always rank content using the output of RewardActionId.
 
 ![Change model update frequency](./media/settings/configure-model-update-frequency-settings.png)
 

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

@@ -59,7 +59,9 @@ After changing this setting, make sure to select **Save**.
 
 ### Model update frequency
 
-**Model update frequency** sets how often a new Personalizer model is retrained. 
+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.
 
 ![Model update frequency sets how often a new Personalizer model is retrained.](media/settings/configure-model-update-frequency-settings.png)
 
@@ -73,7 +75,7 @@ After changing this setting, make sure to select **Save**.
 
 ## Export the Personalizer model
 
-From the Resource management's section for **Model and Policy**, review model creation and last updated date and export the current model.
+From the Resource management's section for **Model and Policy**, 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)
 

articles/cognitive-services/personalizer/toc.yml

@@ -27,6 +27,9 @@
     - name: "Features Action and Context"
       href: concepts-features.md
       displayName: action, context, feature, namespace, JSON, best practice, set
+    - name: Active learning
+      href: concept-active-learning.md
+      displayName: active, inactive
     - name: Rewards
       href: concept-rewards.md
       displayName: reward, wait time, default reward 
@@ -44,7 +47,7 @@
   items:
   - name: Create and configure Personalizer
     href: how-to-settings.md
-    displayName: azure, portal, settings, evaluation, offline, policy
+    displayName: azure, portal, settings, evaluation, offline, policy, export, model
   - name: Analyze
     items: 
     - name: Offline evaluation