Merge pull request #111374 from diberry/diberry/0414-luis-external-entities

[Cogsvcs] LUIS - CSE - external entities

Author: megvanhuygen

articles/cognitive-services/LUIS/luis-concept-feature.md

@@ -12,40 +12,40 @@ ms.topic: conceptual
 ms.date: 11/03/2019
 ms.author: diberry
 ---
-# Machine-learned features 
+# Machine-learned features
 
 In machine learning, a _feature_ is a distinguishing trait or attribute of data that your system observes & learns through. In Language Understanding (LUIS), a feature describes and explains what is significant about your intents and entities.
 
-In the [preview LUIS portal](https://preview.luis.ai), features are _descriptors_ because they are used to _describe_ the intent or entity.  
+In the [preview LUIS portal](https://preview.luis.ai), features are _descriptors_ because they are used to _describe_ the intent or entity.
 
 ## Features (_descriptors_) in Language Understanding
 
-Features, also known as descriptors, describe clues to help Language Understanding identify the example utterances. Features include: 
+Features, also known as descriptors, describe clues to help Language Understanding identify the example utterances. Features include:
 
 * Phrase list as a feature to intents or entities
 * Entities as features to intents or entities
 
-Features should be considered as a necessary part of your schema for model decomposition. 
+Features should be considered as a necessary part of your schema for model decomposition.
 
 ## What is a phrase list
 
-A phrase list is a list of words, phrases, numbers or other characters that help identify the concept you are trying to identify. The list is case-insensitive. 
+A phrase list is a list of words, phrases, numbers or other characters that help identify the concept you are trying to identify. The list is case-insensitive.
 
 ## When to use a phrase list
 
-With a phrase list, LUIS considers context and generalizes to identify items that are similar to, but not an exact text match. If you need your LUIS app to be able to generalize and identify new items, use a phrase list. 
+With a phrase list, LUIS considers context and generalizes to identify items that are similar to, but not an exact text match. If you need your LUIS app to be able to generalize and identify new items, use a phrase list.
 
-When you want to be able to recognize new instances, like a meeting scheduler that should recognize the names of new contacts, or an inventory app that should recognize new products, start with a machine-learned entity. Then create a phrase list that helps LUIS find words with similar meaning. This phrase list guides LUIS to recognize examples by adding additional significance to the value of those words. 
+When you want to be able to recognize new instances, like a meeting scheduler that should recognize the names of new contacts, or an inventory app that should recognize new products, start with a machine-learned entity. Then create a phrase list that helps LUIS find words with similar meaning. This phrase list guides LUIS to recognize examples by adding additional significance to the value of those words.
 
-Phrase lists are like domain-specific vocabulary that help with enhancing the quality of understanding of both intents and entities. 
+Phrase lists are like domain-specific vocabulary that help with enhancing the quality of understanding of both intents and entities.
 
 ## Considerations when using a phrase list
 
-A phrase list is applied, by default, to all models in the app. This will work for phrase lists that can cross all intents and entities. For decomposability, you should apply a phrase list to only the models it is relevant to. 
+A phrase list is applied, by default, to all models in the app. This will work for phrase lists that can cross all intents and entities. For decomposability, you should apply a phrase list to only the models it is relevant to.
 
-If you create a phrase list (created globally by default), then later apply it as a descriptor (feature) to a specific model, it is removed from the other models. This removal adds relevance to the phrase list for the model it is applied to, helping improve the accuracy it provides in the model. 
+If you create a phrase list (created globally by default), then later apply it as a descriptor (feature) to a specific model, it is removed from the other models. This removal adds relevance to the phrase list for the model it is applied to, helping improve the accuracy it provides in the model.
 
-The `enabledForAllModels` flag controls this model scope in the API. 
+The `enabledForAllModels` flag controls this model scope in the API.
 
 <a name="how-to-use-phrase-lists"></a>
 
@@ -60,29 +60,30 @@ The `enabledForAllModels` flag controls this model scope in the API.
 * language that is from another language but frequently used in your app
 * key words and phrases in your example utterances
 
-Do **not** add every possible word or phrase. Instead, add a few words or phrases at a time, then retrain and publish. As the list grows over time, you may find some terms have many forms (synonyms). Break these out into another list. 
+Do **not** add every possible word or phrase. Instead, add a few words or phrases at a time, then retrain and publish. As the list grows over time, you may find some terms have many forms (synonyms). Break these out into another list.
 
 <a name="phrase-lists-help-identify-simple-exchangeable-entities"></a>
 
-## When to use an entity as a feature 
+## When to use an entity as a feature
 
-An entity can be added as a feature at the intent or the entity level. 
+An entity can be added as a feature at the intent or the entity level.
 
 ### Entity as a feature to an intent
 
 Add an entity as a descriptor (feature) to an intent when the detection of that entity is significant for the intent.
 
-For example, if the intent is for booking a flight and the entity is ticket information (such as the number of seats, origin, and destination), then finding the ticket information entity should add weight to the prediction of the book flight intent. 
+For example, if the intent is for booking a flight and the entity is ticket information (such as the number of seats, origin, and destination), then finding the ticket information entity should add weight to the prediction of the book flight intent.
 
 ### Entity as a feature to another entity
 
 An entity (A) should be added as a feature to another entity (B) when the detection of that entity (A) is significant for the prediction of entity (B).
 
-For example, if the street address entity (A) is detected, then finding the street address (A) adds weight to the prediction for the shipping address entity (B). 
+For example, if the street address entity (A) is detected, then finding the street address (A) adds weight to the prediction for the shipping address entity (B).
 
 ## Best practices
 Learn [best practices](luis-concept-best-practices.md).
 
 ## Next steps
 
-See [Add Features](luis-how-to-add-features.md) to learn more about how to add features to your LUIS app.
+* [Extend](schema-change-prediction-runtime.md) your app models at prediction runtime
+* See [Add Features](luis-how-to-add-features.md) to learn more about how to add features to your LUIS app.

articles/cognitive-services/LUIS/luis-migration-api-v3.md

@@ -2,7 +2,7 @@
 title: Prediction endpoint changes in the V3 API
 description: The query prediction endpoint V3 APIs have changed. Use this guide to understand how to migrate to version 3 endpoint APIs.
 ms.topic: conceptual
-ms.date: 03/11/2020
+ms.date: 04/14/2020
 ms.author: diberry
 ---
 
@@ -11,14 +11,12 @@ ms.author: diberry
 
 The query prediction endpoint V3 APIs have changed. Use this guide to understand how to migrate to version 3 endpoint APIs.
 
-[!INCLUDE [Waiting for LUIS portal refresh](./includes/wait-v3-upgrade.md)]
-
 **Generally available status** - this V3 API include significant JSON request and response changes from V2 API.
 
 The V3 API provides the following new features:
 
-* [External entities](#external-entities-passed-in-at-prediction-time)
-* [Dynamic lists](#dynamic-lists-passed-in-at-prediction-time)
+* [External entities](schema-change-prediction-runtime.md#external-entities-passed-in-at-prediction-time)
+* [Dynamic lists](schema-change-prediction-runtime.md#dynamic-lists-passed-in-at-prediction-time)
 * [Prebuilt entity JSON changes](#prebuilt-entity-changes)
 
 The prediction endpoint [request](#request-changes) and [response](#response-changes) have significant changes to support the new features listed above, including the following:
@@ -119,14 +117,12 @@ The V3 API has different query string parameters.
 
 |Property|Type|Version|Default|Purpose|
 |--|--|--|--|--|
-|`dynamicLists`|array|V3 only|Not required.|[Dynamic lists](#dynamic-lists-passed-in-at-prediction-time) allow you to extend an existing trained and published list entity, already in the LUIS app.|
-|`externalEntities`|array|V3 only|Not required.|[External entities](#external-entities-passed-in-at-prediction-time) give your LUIS app the ability to identify and label entities during runtime, which can be used as features to existing entities. |
+|`dynamicLists`|array|V3 only|Not required.|[Dynamic lists](schema-change-prediction-runtime.md#dynamic-lists-passed-in-at-prediction-time) allow you to extend an existing trained and published list entity, already in the LUIS app.|
+|`externalEntities`|array|V3 only|Not required.|[External entities](schema-change-prediction-runtime.md#external-entities-passed-in-at-prediction-time) give your LUIS app the ability to identify and label entities during runtime, which can be used as features to existing entities. |
 |`options.datetimeReference`|string|V3 only|No default|Used to determine [datetimeV2 offset](luis-concept-data-alteration.md#change-time-zone-of-prebuilt-datetimev2-entity). The format for the datetimeReference is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).|
-|`options.preferExternalEntities`|boolean|V3 only|false|Specifies if user's [external entity (with same name as existing entity)](#override-existing-model-predictions) is used or the existing entity in the model is used for prediction. |
+|`options.preferExternalEntities`|boolean|V3 only|false|Specifies if user's [external entity (with same name as existing entity)](schema-change-prediction-runtime.md#override-existing-model-predictions) is used or the existing entity in the model is used for prediction. |
 |`query`|string|V3 only|Required.|**In V2**, the utterance to be predicted is in the `q` parameter. <br><br>**In V3**, the functionality is passed in the `query` parameter.|
 
-
-
 ## Response changes
 
 The query response JSON changed to allow greater programmatic access to the data used most frequently.
@@ -277,185 +273,12 @@ In V3, the same result with the `verbose` flag to return entity metadata:
 }
 ```
 
-## External entities passed in at prediction time
-
-External entities give your LUIS app the ability to identify and label entities during runtime, which can be used as features to existing entities. This allows you to use your own separate and custom entity extractors before sending queries to your prediction endpoint. Because this is done at the query prediction endpoint, you don't need to retrain and publish your model.
-
-The client-application is providing its own entity extractor by managing entity matching and determining the location within the utterance of that matched entity and then sending that information with the request.
-
-External entities are the mechanism for extending any entity type while still being used as signals to other models like roles, composite, and others.
-
-This is useful for an entity that has data available only at query prediction runtime. Examples of this type of data are constantly changing data or specific per user. You can extend a LUIS contact entity with external information from a user's contact list.
-
-### Entity already exists in app
-
-The value of `entityName` for the external entity, passed in the endpoint request POST body, must already exist in the trained and published app at the time the request is made. The type of entity doesn't matter, all types are supported.
-
-### First turn in conversation
-
-Consider a first utterance in a chat bot conversation where a user enters the following incomplete information:
-
-`Send Hazem a new message`
-
-The request from the chat bot to LUIS can pass in information in the POST body about `Hazem` so it is directly matched as one of the user's contacts.
-
-```json
-    "externalEntities": [
-        {
-            "entityName":"contacts",
-            "startIndex": 5,
-            "entityLength": 5,
-            "resolution": {
-                "employeeID": "05013",
-                "preferredContactType": "TeamsChat"
-            }
-        }
-    ]
-```
-
-The prediction response includes that external entity, with all the other predicted entities, because it is defined in the request.
-
-### Second turn in conversation
-
-The next user utterance into the chat bot uses a more vague term:
-
-`Send him a calendar reminder for the party.`
-
-In the previous utterance, the utterance uses `him` as a reference to `Hazem`. The conversational chat bot, in the POST body, can map `him` to the entity value extracted from the first utterance, `Hazem`.
-
-```json
-    "externalEntities": [
-        {
-            "entityName":"contacts",
-            "startIndex": 5,
-            "entityLength": 3,
-            "resolution": {
-                "employeeID": "05013",
-                "preferredContactType": "TeamsChat"
-            }
-        }
-    ]
-```
-
-The prediction response includes that external entity, with all the other predicted entities, because it is defined in the request.
-
-### Override existing model predictions
-
-The `preferExternalEntities` options property specifies that if the user sends an external entity that overlaps with a predicted entity with the same name, LUIS chooses the entity passed in or the entity existing in the model.
-
-For example, consider the query `today I'm free`. LUIS detects `today` as a datetimeV2 with the following response:
-
-```JSON
-"datetimeV2": [
-    {
-        "type": "date",
-        "values": [
-            {
-                "timex": "2019-06-21",
-                "value": "2019-06-21"
-            }
-        ]
-    }
-]
-```
-
-If the user sends the external entity:
-
-```JSON
-{
-    "entityName": "datetimeV2",
-    "startIndex": 0,
-    "entityLength": 5,
-    "resolution": {
-        "date": "2019-06-21"
-    }
-}
-```
-
-If the `preferExternalEntities` is set to `false`, LUIS returns a response as if the external entity were not sent.
-
-```JSON
-"datetimeV2": [
-    {
-        "type": "date",
-        "values": [
-            {
-                "timex": "2019-06-21",
-                "value": "2019-06-21"
-            }
-        ]
-    }
-]
-```
-
-If the `preferExternalEntities` is set to `true`, LUIS returns a response including:
-
-```JSON
-"datetimeV2": [
-    {
-        "date": "2019-06-21"
-    }
-]
-```
-
-
+<a name="external-entities-passed-in-at-prediction-time"></a>
+<a name="override-existing-model-predictions"></a>
 
-#### Resolution
-
-The _optional_ `resolution` property returns in the prediction response, allowing you to pass in the metadata associated with the external entity, then receive it back out in the response.
-
-The primary purpose is to extend prebuilt entities but it is not limited to that entity type.
-
-The `resolution` property can be a number, a string, an object, or an array:
-
-* "Dallas"
-* {"text": "value"}
-* 12345
-* ["a", "b", "c"]
-
-
-
-## Dynamic lists passed in at prediction time
-
-Dynamic lists allow you to extend an existing trained and published list entity, already in the LUIS app.
-
-Use this feature when your list entity values need to change periodically. This feature allows you to extend an already trained and published list entity:
-
-* At the time of the query prediction endpoint request.
-* For a single request.
-
-The list entity can be empty in the LUIS app but it has to exist. The list entity in the LUIS app isn't changed, but the prediction ability at the endpoint is extended to include up to 2 lists with about 1,000 items.
-
-### Dynamic list JSON request body
-
-Send in the following JSON body to add a new sublist with synonyms to the list, and predict the list entity for the text, `LUIS`, with the `POST` query prediction request:
-
-```JSON
-{
-    "query": "Send Hazem a message to add an item to the meeting agenda about LUIS.",
-    "options":{
-        "timezoneOffset": "-8:00"
-    },
-    "dynamicLists": [
-        {
-            "listEntity*":"ProductList",
-            "requestLists":[
-                {
-                    "name": "Azure Cognitive Services",
-                    "canonicalForm": "Azure-Cognitive-Services",
-                    "synonyms":[
-                        "language understanding",
-                        "luis",
-                        "qna maker"
-                    ]
-                }
-            ]
-        }
-    ]
-}
-```
+## Extend the app at prediction time
 
-The prediction response includes that list entity, with all the other predicted entities, because it is defined in the request.
+Learn [concepts](schema-change-prediction-runtime.md) about how to extend the app at prediction runtime.
 
 ## Deprecation