V3 的预测终结点更改Prediction endpoint changes for V3

查询预测终结点 V3 API 已更改。The query prediction endpoint V3 APIs have changed. 请使用本指南了解如何迁移到终结点 API 版本 3。Use this guide to understand how to migrate to version 3 endpoint APIs.

公开提供的状态 - 此 V3 API 包括 V2 API 的重大 JSON 请求和响应更改。Generally available status - this V3 API include significant JSON request and response changes from V2 API.

V3 API 提供以下新功能:The V3 API provides the following new features:

预测终结点请求响应已发生重大更改,可以支持上面列出的新功能。这些更改包括:The prediction endpoint request and response have significant changes to support the new features listed above, including the following:

为 V3 提供了参考文档Reference documentation is available for V3.

从预览版到正式版的 V3 更改V3 changes from preview to GA

V3 在从预览版过渡到正式版的过程中进行了以下更改:V3 made the following changes as part of the move to GA:

  • 以下预构建的实体具有不同的 JSON 响应:The following prebuilt entities have different JSON responses:

  • 请求正文 JSON 更改:Request body JSON change:

    • preferExternalEntities 更改为 preferExternalEntitiesfrom preferExternalEntities to preferExternalEntities
    • 外部实体的可选 score 参数optional score parameter for external entities
  • 响应正文 JSON 更改:Response body JSON changes:

    • 删除了 normalizedQuerynormalizedQuery removed

建议的采用策略Suggested adoption strategy

如果使用 Bot Framework、必应拼写检查 V7 或者只要迁移 LUIS 应用创作,请继续使用 V2 终结点。If you use Bot Framework, Bing Spell Check V7, or want to migrate your LUIS app authoring only, continue to use the V2 endpoint.

如果你知道自己的客户端应用程序或集成(Bot Framework 和必应拼写检查 V7)不受影响,并且愿意同时迁移 LUIS 应用创作和预测终结点,则可开始使用 V3 预测终结点。If you know none of your client application or integrations (Bot Framework, and Bing Spell Check V7) are impacted and you are comfortable migrating your LUIS app authoring and your prediction endpoint at the same time, begin using the V3 prediction endpoint. V2 预测终结点仍将可用,是一项良好的回退策略。The V2 prediction endpoint will still be available and is a good fall-back strategy.

Bot Framework 和 Azure 机器人服务客户端应用程序Bot Framework and Azure Bot Service client applications

请继续使用 V2 API 预测终结点,直到 Bot Framework V4.7 发布。Continue to use the V2 API prediction endpoint until the V4.7 of the Bot Framework is released.

弃用 V2 APIV2 API Deprecation

在 2020 年 6 月 8 日发布 V3 预览版后至少 9 个月内不会弃用 V2 预测 API。The V2 prediction API will not be deprecated for at least 9 months after the V3 preview, June 8th, 2020.

终结点 URL 更改Endpoint URL changes

按槽名称和版本名称进行的更改Changes by slot name and version name

V3 终结点 HTTP 的格式调用已更改。The format of the V3 endpoint HTTP call has changed.

如果希望按版本查询,首先需要使用 "directVersionPublish":true 通过 API 进行发布If you want to query by version, you first need to publish via API with "directVersionPublish":true. 查询引用版本 ID 而不是槽名称的终结点。Query the endpoint referencing the version ID instead of the slot name.

SLOT-NAME 的有效值Valid values for SLOT-NAME
production
staging

请求更改Request changes

查询字符串更改Query string changes

V3 API 包含不同的查询字符串参数。The V3 API has different query string parameters.

参数名称Param name 类型Type 版本Version 默认Default 目的Purpose
log booleanboolean V2 和 V3V2 & V3 falsefalse 将查询存储在日志文件中。Store query in log file. 默认值为 false。Default value is false.
query stringstring 仅 V3V3 only 无默认值 - 在 GET 请求中是必需的No default - it is required in the GET request 在 V2 中,要预测的言语位于 q 参数中。In V2, the utterance to be predicted is in the q parameter.

在 V3 中,该功能在 query 参数中传递。In V3, the functionality is passed in the query parameter.
show-all-intents booleanboolean 仅 V3V3 only falsefalse prediction.intents 对象中返回包含相应评分的所有意向。Return all intents with the corresponding score in the prediction.intents object. 意向将在父 intents 对象中作为对象返回。Intents are returned as objects in a parent intents object. 这样,便可以通过编程方式进行访问,而无需在数组中查找意向:prediction.intents.giveThis allows programmatic access without needing to find the intent in an array: prediction.intents.give. 在 V2 中,这些意向在数组中返回。In V2, these were returned in an array.
verbose booleanboolean V2 和 V3V2 & V3 falsefalse 在 V2 中,如果设置为 true,则返回所有预测意向。In V2, when set to true, all predicted intents were returned. 如果需要所有预测的意向,请使用 V3 参数 show-all-intentsIf you need all predicted intents, use the V3 param of show-all-intents.

在 V3 中,此参数仅提供实体预测的实体元数据详细信息。In V3, this parameter only provides entity metadata details of entity prediction.
timezoneOffset stringstring V2V2 - 应用于 datetimeV2 实体的时区。Timezone applied to datetimeV2 entities.
datetimeReference stringstring V3V3 - 应用于 datetimeV2 实体的时区Timezone applied to datetimeV2 entities. 替换 V2 中的 timezoneOffsetReplaces timezoneOffset from V2.

V3 POST 正文V3 POST body

{
    "query":"your utterance here",
    "options":{
        "datetimeReference": "2019-05-05T12:00:00",
        "preferExternalEntities": true
    },
    "externalEntities":[],
    "dynamicLists":[]
}
属性Property 类型Type 版本Version 默认Default 目的Purpose
dynamicLists arrayarray 仅 V3V3 only 非必需。Not required. 使用动态列表可以扩展已在 LUIS 应用中的已训练且已发布的现有列表实体。Dynamic lists allow you to extend an existing trained and published list entity, already in the LUIS app.
externalEntities arrayarray 仅 V3V3 only 非必需。Not required. 外部实体可让 LUIS 应用在运行时识别和标记实体,这些实体可用作现有实体的特征。External entities give your LUIS app the ability to identify and label entities during runtime, which can be used as features to existing entities.
options.datetimeReference stringstring 仅 V3V3 only 无默认值No default 用于确定 datetimeV2 偏移量Used to determine datetimeV2 offset. datetimeReference 的格式是 ISO 8601The format for the datetimeReference is ISO 8601.
options.preferExternalEntities booleanboolean 仅 V3V3 only falsefalse 指定是使用用户的外部实体(与现有实体具有相同名称),还是使用模型中的现有实体进行预测。Specifies if user's external entity (with same name as existing entity) is used or the existing entity in the model is used for prediction.
query stringstring 仅 V3V3 only 必需。Required. 在 V2 中,要预测的言语位于 q 参数中。In V2, the utterance to be predicted is in the q parameter.

在 V3 中,该功能在 query 参数中传递。In V3, the functionality is passed in the query parameter.

响应更改Response changes

查询响应 JSON 已发生更改,允许以更合理的编程方式访问最常用的数据。The query response JSON changed to allow greater programmatic access to the data used most frequently.

顶级 JSON 更改Top level JSON changes

verbose 设置为 true 时(在 intents 属性中返回所有意向及其评分),V2 的顶级 JSON 属性为:The top JSON properties for V2 are, when verbose is set to true, which returns all intents and their scores in the intents property:

{
    "query":"this is your utterance you want predicted",
    "topScoringIntent":{},
    "intents":[],
    "entities":[],
    "compositeEntities":[]
}

V3 的顶级 JSON 属性为:The top JSON properties for V3 are:

{
    "query": "this is your utterance you want predicted",
    "prediction":{
        "topIntent": "intent-name-1",
        "intents": {},
        "entities":{}
    }
}

intents 对象是未排序的列表。The intents object is an unordered list. 不要假设 intents 中的第一个子级对应于 topIntentDo not assume the first child in the intents corresponds to the topIntent. 请改用 topIntent 值来查找评分:Instead, use the topIntent value to find the score:

const topIntentName = response.prediction.topIntent;
const score = intents[topIntentName];

响应 JSON 架构已发生更改,允许:The response JSON schema changes allow for:

  • 消除原始言语 query 与返回的预测 prediction 之间的差别。Clear distinction between original utterance, query, and returned prediction, prediction.
  • 更轻松地以编程方式访问预测的数据。Easier programmatic access to predicted data. 可以按意向和实体的 name 访问值,而无需枚举 V2 中的数组。Instead of enumerating through an array in V2, you can access values by name for both intents and entities. 对于预测的实体角色,将返回角色名称,因为它在整个应用中是唯一的。For predicted entity roles, the role name is returned because it is unique across the entire app.
  • 将遵循数据类型(如果已确定)。Data types, if determined, are respected. 数字不再作为字符串返回。Numerics are no longer returned as strings.
  • 第一个优先级预测信息与其他元数据之间的差别在 $instance 对象中返回。Distinction between first priority prediction information and additional metadata, returned in the $instance object.

实体响应更改Entity response changes

在言语中标记实体的位置Marking placement of entities in utterances

在 V2 中,使用 startIndexendIndex 在言语中标记实体。In V2, an entity was marked in an utterance with the startIndex and endIndex.

在 V3 中,使用 startIndexentityLength 标记实体。In V3, the entity is marked with startIndex and entityLength.

访问实体元数据的 $instanceAccess $instance for entity metadata

如果你需要实体元数据,则查询字符串需要使用 verbose=true 标志,并且响应在 $instance 对象中包含元数据。If you need entity metadata, the query string needs to use the verbose=true flag and the response contains the metadata in the $instance object. 以下部分的 JSON 响应中提供了示例。Examples are shown in the JSON responses in the following sections.

预测的每个实体以数组的形式表示Each predicted entity is represented as an array

prediction.entities.<entity-name> 对象包含一个数组,因为可以在言语中多次预测每个实体。The prediction.entities.<entity-name> object contains an array because each entity can be predicted more than once in the utterance.

预构建实体更改Prebuilt entity changes

V3 响应对象包含对预构建实体的更改。The V3 response object includes changes to prebuilt entities. 查看特定的预构建实体以了解详细信息。Review specific prebuilt entities to learn more.

列表实体预测更改List entity prediction changes

列表实体预测的 JSON 已更改为数组的数组:The JSON for a list entity prediction has changed to be an array of arrays:

"entities":{
    "my_list_entity":[
        ["canonical-form-1","canonical-form-2"],
        ["canonical-form-2"]
    ]
}

每个内部数组对应于言语中的文本。Each interior array corresponds to text inside the utterance. 内部对象是一个数组,因为相同的文本可以出现在列表实体的多个子列表中。The interior object is an array because the same text can appear in more than one sublist of a list entity.

entities 对象与 $instance 对象之间映射时,将为列表实体预测保留对象顺序。When mapping between the entities object to the $instance object, the order of objects is preserved for the list entity predictions.

const item = 0; // order preserved, use same enumeration for both
const predictedCanonicalForm = entities.my_list_entity[item];
const associatedMetadata = entities.$instance.my_list_entity[item];

使用实体角色名称而不是实体名称Entity role name instead of entity name

在 V2 中,entities 数组返回具有实体名称(唯一标识符)的所有预测实体。In V2, the entities array returned all the predicted entities with the entity name being the unique identifier. 在 V3 中,如果实体使用角色,并且预测针对实体角色,则主标识符是角色名称。In V3, if the entity uses roles and the prediction is for an entity role, the primary identifier is the role name. 之所以能够这样做,是因为实体角色名称必须在整个应用中唯一,这包括其他模型(意向、实体)名称。This is possible because entity role names must be unique across the entire app including other model (intent, entity) names.

在以下示例中,假设某段言语包含文本 Yellow Bird LaneIn the following example: consider an utterance that includes the text, Yellow Bird Lane. 此文本将作为自定义 Location 实体的 Destination 角色进行预测。This text is predicted as a custom Location entity's role of Destination.

言语文本Utterance text 实体名称Entity name 角色名称Role name
Yellow Bird Lane Location Destination

在 V2 中,实体由实体名称以及用作对象属性的角色进行标识:__In V2, the entity is identified by the entity name with the role as a property of the object:

"entities":[
    {
        "entity": "Yellow Bird Lane",
        "type": "Location",
        "startIndex": 13,
        "endIndex": 20,
        "score": 0.786378264,
        "role": "Destination"
    }
]

在 V3 中,如果预测针对角色,则实体由实体角色引用:__In V3, the entity is referenced by the entity role, if the prediction is for the role:

"entities":{
    "Destination":[
        "Yellow Bird Lane"
    ]
}

在 V3 中,可以使用用于返回实体元数据的 verbose 标志来实现相同的结果:In V3, the same result with the verbose flag to return entity metadata:

"entities":{
    "Destination":[
        "Yellow Bird Lane"
    ],
    "$instance":{
        "Destination": [
            {
                "role": "Destination",
                "type": "Location",
                "text": "Yellow Bird Lane",
                "startIndex": 25,
                "length":16,
                "score": 0.9837309,
                "modelTypeId": 1,
                "modelType": "Entity Extractor"
            }
        ]
    }
}

在预测时扩展应用Extend the app at prediction time

了解关于如何在预测运行时扩展应用的概念Learn concepts about how to extend the app at prediction runtime.

弃用Deprecation

在 V3 预览后至少 9 个月内不会弃用 V2 API。The V2 API will not be deprecated for at least 9 months after the V3 preview.

后续步骤Next steps

使用 V3 API 文档更新对 LUIS 终结点 API 的现有 REST 调用。Use the V3 API documentation to update existing REST calls to LUIS endpoint APIs.