迁移到 V3 创作实体Migrate to V3 Authoring entity

V3 创作提供了一种新的实体类型,即机器学习实体,还可以向机器学习实体和应用程序的其他实体或功能添加关系。The V3 authoring provides one new entity type, the machine-learning entity, along with the ability to add relationships to the machine-learning entity and other entities or features of the application.

实体在 V3 中可分解Entities are decomposable in V3

使用 V3 创作 API 所创建的实体(通过使用 API 或通过门户创建)使你能够构建具有父级和子级的分层实体模型。Entities created with the V3 authoring APIs, either using the APIs or with the portal, allow you to build a layered entity model with a parent and children. 父级称为“机器学习实体”,子级称为机器学习实体的“子实体” 。The parent is known to as the machine-learning entity and the children are known as subentities of the machine learned entity.

每个子实体也是一种机器学习实体,但添加了功能的配置选项。Each subentity is also a machine-learning entity but with the added configuration options of features.

这些新关系与 V2 创作相比有何优势How do these new relationships compare to V2 authoring

V2 创作提供分层实体和复合实体以及角色和功能来完成相同的任务。V2 authoring provided hierarchical and composite entities along with roles and features to accomplish this same task. 由于实体、功能和角色之间没有显式的关系,因此很难理解 LUIS 在预测过程中暗示关系的方式。Because the entities, features, and roles were not explicitly related to each other, it was difficult to understand how LUIS implied the relationships during prediction.

在 V3 中,关系是显式的,由应用作者设计。With V3, the relationship is explicit and designed by the app authors. 因此,应用作者可以:This allows you, as the app author, to:

  • 在示例言语中直观地了解 LUIS 如何预测这些关系Visually see how LUIS is predicting these relationships, in the example utterances
  • 通过交互式测试窗格或在终结点处测试这些关系Test for these relationships either with the interactive test pane or at the endpoint
  • 通过结构良好的、已命名的嵌套 .json 对象在客户端应用程序中使用这些关系Use these relationships in the client application, via a well-structured, named, nested .json object

规划Planning

迁移时,请在迁移计划中考虑以下事项:When you migrate, consider the following in your migration plan:

  • 备份 LUIS 应用,并在单独的应用上执行迁移。Back up your LUIS app, and perform the migration on a separate app. 同时配备 V2 和 V3 应用可以验证所需的更改和对预测结果的影响。Having a V2 and V3 app available at the same time allows you to validate the changes required and the impact on the prediction results.
  • 捕获当前的预测成功指标Capture current prediction success metrics
  • 捕获当前仪表板信息作为应用状态的快照Capture current dashboard information as a snapshot of app status
  • 查看现有意向、实体、短语列表、模式和批处理测试Review existing intents, entities, phrase lists, patterns, and batch tests
  • 可以在无需更改的情况下迁移以下元素:The following elements can be migrated without change :
    • 意向Intents
    • 实体Entities
      • 正则表达式实体Regular expression entity
      • 列表实体List entity
    • 功能Features
      • 短语列表Phrase list
  • 迁移以下元素时需要进行更改:The following elements need to be migrated with changes :
    • 实体Entities
      • 分层实体Hierarchical entity
      • 复合实体Composite entity
    • 角色 - 角色仅可应用于机器学习(父级)实体。Roles - roles can only be applied to a machine-learning (parent) entity. 角色不能应用于子实体Roles can't be applied to subentities
    • 使用分层实体和复合实体的批处理测试和模式Batch tests and patterns that use the hierarchical and composite entities

在设计迁移计划时,请在所有分层实体和复合实体迁移完成后,留出时间查看最终的机器学习实体。When you design your migration plan, leave time to review the final machine-learning entities, after all hierarchical and composite entities have been migrated. 可以直接进行迁移,也可以进行更改,在进行了更改并查看了批处理测试结果后,你可能会因预测 JSON(更统一的 JSON)而进行更改,这样传递到客户端应用的最终信息的组织方式会不同。While a straight migration will work, after you make the change and review your batch test results, and prediction JSON, the more unified JSON may lead you to make changes so the final information delivered to the client-side app is organized differently. 这类似于代码重构,应对其使用组织已有的同一审查过程。This is similar to code refactoring and should be treated with the same review process your organization has in place.

如果没有为 V2 模型准备好批处理测试且没有在迁移中将批处理测试迁移到 V3 模型,则将无法验证迁移对终结点预测结果的影响。If you don't have batch tests in place for your V2 model, and migrate the batch tests to the V3 model as part of the migration, you won't be able to validate how the migration will impact the endpoint prediction results.

从 V2 实体迁移Migrating from V2 entities

当开始向 V3 创作模型迁移时,应考虑如何迁移到机器学习实体及其子实体和功能。As you begin to move to the V3 authoring model, you should consider how to move to the machine-learning entity, and its subentities and features.

下表说明了需要从 V2 实体设计迁移到 V3 实体设计的实体。The following table notes which entities need to migrate from a V2 to a V3 entity design.

V2 创作实体类型V2 authoring entity type V3 创作实体类型V3 authoring entity type 示例Example
复合实体Composite entity 机器学习实体Machine learned entity 详细了解learn more
分层实体Hierarchical entity 机器学习实体的角色machine-learning entity's role 详细了解learn more

迁移 V2 复合实体Migrate V2 Composite entity

V2 复合实体的每个子级都应使用 V3 机器学习实体的子实体来表示。Each child of the V2 composite should be represented with a subentity of the V3 machine-learning entity. 如果复合子级是预生成的实体、正则表达式实体或列表实体,应在子实体上将此作为必需的功能进行应用。If the composite child is a prebuilt, regular expression, or a list entity, this should be applied as a required feature on the subentity.

计划将复合实体迁移到机器学习实体时的注意事项:Considerations when planning to migrate a composite entity to a machine-learning entity:

  • 子实体不能在模式中使用Child entities can't be used in patterns
  • 子实体不再进行共享Child entities are no longer shared
  • 如果子实体以前是非机器学习实体,需要对其进行标记Child entities need to be labeled if they used to be non-machine-learned

现有功能Existing features

用于在复合实体中增强字词的任何短语列表应作为一种功能应用于机器学习(父级)实体、子实体(子级)实体或意向(如果短语列表仅应用于一个意向)。Any phrase list used to boost words in the composite entity should be applied as a feature to either the machine-learning (parent) entity, the subentity (child) entity, or the intent (if the phrase list only applies to one intent). 计划将此功能添加到应最大程度增强的实体。Plan to add the feature to the entity where it should boost most significantly. 如果功能会最大程度地提高子实体(子级)的预测,请不要按常规方式将功能添加到机器学习(父级)实体中。Do not add the feature generically to the machine-learning (parent) entity, if it will most significantly boost the prediction of a subentity (child).

新增功能New features

在 V3 创作中,添加一个计划步骤,以便将实体评估为所有实体和意向的可能功能。In V3 authoring, add a planning step to evaluate entities as possible features for all the entities and intents.

示例实体Example entity

此实体只是一个示例。This entity is an example only. 你自己的实体迁移可能有其他需要注意的事项。Your own entity migration may require other considerations.

请考虑使用 V2 复合实体来修改使用以下内容的比萨 orderConsider a V2 composite for modifying a pizza order that uses:

  • 用于传递时间的预生成的 datetimeV2prebuilt datetimeV2 for delivery time
  • 用于增强某些词的短语列表,如比萨、派、酥皮和配料phrase list to boost certain words such as pizza, pie, crust, and topping
  • 用于检测配料(如蘑菇、橄榄、意大利辣香肠)的列表实体。list entity to detect toppings such as mushrooms, olives, pepperoni.

此实体的一个示例言语是:An example utterance for this entity is:

Change the toppings on my pie to mushrooms and delivery it 30 minutes later

下表演示了迁移:The following table demonstrates the migration:

V2 模型V2 models V3 模型V3 models
父级 - 名为 Order 的组件实体Parent - Component entity named Order 父级 - 名为 Order 的机器学习实体Parent - machine-learning entity named Order
子级 - 预生成的 datetimeV2Child - Prebuilt datetimeV2 * 将预生成的实体迁移到新应用。* Migrate prebuilt entity to new app.
* 在父级上为预生成的 datetimeV2 添加必需功能。* Add required feature on parent for prebuilt datetimeV2.
子级 - 配料的列表实体Child - list entity for toppings * 将列表实体迁移到新应用。* Migrate list entity to new app.
* 然后在父级上为列表实体添加必需功能。* Then add a required feature on the parent for the list entity.

迁移 V2 分层实体Migrate V2 Hierarchical entity

在 V2 创作中,在 LUIS 中存在角色之前,会提供一个分层实体。In V2 authoring, a hierarchical entity was provided before roles existing in LUIS. 两者的目的都是基于上下文使用情况提取实体。Both served the same purpose of extracting entities based on context usage. 如果你有分层实体,可以将其视为具有角色的简单实体。If you have hierarchical entities, you can think of them as simple entities with roles.

在 V3 创作中:In V3 authoring:

  • 可以在机器学习(父级)实体上应用角色。A role can be applied on the machine-learning (parent) entity.
  • 角色不能应用于任何子实体。A role can't be applied to any subentities.

此实体只是一个示例。This entity is an example only. 你自己的实体迁移可能有其他需要注意的事项。Your own entity migration may require other considerations.

请考虑使用 V2 分层实体来修改比萨 orderConsider a V2 hierarchical entity for modifying a pizza order:

  • 其中每个子级确定是使用原始配料还是最终配料where each child determines either an original topping or the final topping

此实体的一个示例言语是:An example utterance for this entity is:

Change the topping from mushrooms to olives

下表演示了迁移:The following table demonstrates the migration:

V2 模型V2 models V3 模型V3 models
父级 - 名为 Order 的组件实体Parent - Component entity named Order 父级 - 名为 Order 的机器学习实体Parent - machine-learning entity named Order
子级 - 具有原始和最终比萨配料的分层实体Child - Hierarchical entity with original and final pizza topping * 向每个配料的 Order 添加角色。* Add role to Order for each topping.

将约束功能替换为必需功能的 API 更改API change constraint replaced with required feature

此更改是在 2020 年 5 月的 //Build 大会上发布和执行的,仅适用于其中的应用会使用约束功能的 v3 创作 API。This change was made in May 2020 at the //Build conference and only applies to the v3 authoring APIs where an app is using a constrained feature. 如果要从 v2 创作迁移到 v3 创作,或尚未使用 v3 约束功能,请跳过此部分。If you are migrating from v2 authoring to v3 authoring, or have not used v3 constrained features, skip this section.

功能 - 能够要求现有实体需为另一个模型的功能,并且仅在检测到实体时才提取该模型。Functionality - ability to require an existing entity as a feature to another model and only extract that model if the entity is detected. 功能未发生更改,但 API 和术语已更改。The functionality has not changed but the API and terminology have changed.

以前的术语Previous terminology 新术语New terminology
constrained feature
constraint
instanceOf
required feature
isRequired

自动迁移Automatic migration

从 2020 年 6 月 19 日开始,将无法使用以前公开此功能的创作 API 以编程方式创建约束。Starting June 19 2020 , you won’t be allowed to create constraints programmatically using the previous authoring API that exposed this functionality.

所有现有约束功能都将自动迁移到所需功能标志。All existing constraint features will be automatically migrated to the required feature flag. 不需要对预测 API 进行编程更改,也不会对预测准确性的质量造成任何影响。No programmatic changes are required to your prediction API and no resulting change on the quality of the prediction accuracy.

LUIS 门户更改LUIS portal changes

LUIS 预览版门户将此功能称为“约束”。The LUIS preview portal referenced this functionality as a constraint . 当前的 LUIS 门户将此功能指定为“必需功能”。The current LUIS portal designates this functionality as a required feature .

以前的创作 APIPrevious authoring API

此功能应用于预览版的创作 API 创建实体子级 API,作为实体定义的一部分,并使用实体的子级的 instanceOf 属性:This functionality was applied in the preview authoring Create Entity Child API as the part of an entity's definition, using the instanceOf property of an entity's child:

{
    "name" : "dayOfWeek",
    "instanceOf": "datetimeV2",
    "children": [
        {
           "name": "dayNumber",
           "instanceOf": "number",
           "children": []
        }
    ]
}

新的创作 APINew authoring API

此功能现在通过添加实体功能关系 API 进行应用,并使用 featureNameisRequired 属性。This functionality is now applied with the Add entity feature relation API using the featureName and isRequired properties. featureName 属性的值是模型的名称。The value of the featureName property is the name of the model.

{
    "featureName": "YOUR-MODEL-NAME-HERE",
    "isRequired" : true
}

后续步骤Next steps