V3 的预测终结点更改

查询预测终结点 V3 API 已更改。 请使用本指南了解如何迁移到终结点 API 版本 3。 目前没有完成迁移的截止日期。

公开提供的状态 - 此 V3 API 包括 V2 API 的重大 JSON 请求和响应更改。

V3 API 提供以下新功能:

预测终结点请求响应已发生重大更改,可以支持上面列出的新功能。这些更改包括:

为 V3 提供了参考文档

从预览版到正式版的 V3 更改

V3 在从预览版过渡到正式版的过程中进行了以下更改:

  • 以下预构建的实体具有不同的 JSON 响应:

  • 请求正文 JSON 更改:

    • preferExternalEntities 更改为 preferExternalEntities
    • 外部实体的可选 score 参数
  • 响应正文 JSON 更改:

    • 删除了 normalizedQuery

建议的采用策略

如果使用 Bot Framework、必应拼写检查 V7 或者只要迁移 LUIS 应用创作,请继续使用 V2 终结点。

如果你知道自己的客户端应用程序或集成(Bot Framework 和必应拼写检查 V7)不受影响,并且愿意同时迁移 LUIS 应用创作和预测终结点,则可开始使用 V3 预测终结点。 V2 预测终结点仍将可用,是一项良好的回退策略。

不支持

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

请继续使用 V2 API 预测终结点,直到 Bot Framework V4.7 发布。

终结点 URL 更改

按槽名称和版本名称进行的更改

V3 终结点 HTTP 的格式调用已更改。

如果希望按版本查询,首先需要使用 "directVersionPublish":true 通过 API 进行发布。 查询引用版本 ID 而不是槽名称的终结点。

SLOT-NAME 的有效值
production
staging

请求更改

查询字符串更改

V3 API 查询字符串参数包括:

查询参数 LUIS 门户名称 类型 版本 默认 目的
log 保存日志 boolean V2 和 V3 false 将查询存储在日志文件中。 默认值为 false。
query - string 仅 V3 无默认值 - 在 GET 请求中是必需的 在 V2 中 ,要预测的言语位于 q 参数中。

在 V3 中 ,该功能在 query 参数中传递。
show-all-intents 包括所有意向的分数 boolean 仅 V3 false prediction.intents 对象中返回包含相应评分的所有意向。 意向将在父 intents 对象中作为对象返回。 这样,便可以通过编程方式进行访问,而无需在数组中查找意向:prediction.intents.give。 在 V2 中,这些意向在数组中返回。
verbose 包括更多实体详细信息 boolean V2 和 V3 false 在 V2 中 ,如果设置为 true,则返回所有预测意向。 如果需要所有预测的意向,请使用 V3 参数 show-all-intents

在 V3 中 ,此参数仅提供实体预测的实体元数据详细信息。
timezoneOffset - string V2 - 应用于 datetimeV2 实体的时区。
datetimeReference - string V3 - 应用于 datetimeV2 实体的时区。 替换 V2 中的 timezoneOffset

V3 POST 正文

{
    "query":"your utterance here",
    "options":{
        "datetimeReference": "2019-05-05T12:00:00",
        "preferExternalEntities": true
    },
    "externalEntities":[],
    "dynamicLists":[]
}
属性 类型 版本 默认 目的
dynamicLists array 仅 V3 非必需。 使用动态列表可以扩展已在 LUIS 应用中的已训练且已发布的现有列表实体。
externalEntities array 仅 V3 非必需。 外部实体可让 LUIS 应用在运行时识别和标记实体,这些实体可用作现有实体的特征。
options.datetimeReference string 仅 V3 无默认值 用于确定 datetimeV2 偏移量。 datetimeReference 的格式是 ISO 8601。
options.preferExternalEntities boolean 仅 V3 false 指定是使用用户的外部实体(与现有实体具有相同名称),还是使用模型中的现有实体进行预测。
query string 仅 V3 必需。 在 V2 中,要预测的言语位于 q 参数中。

在 V3 中,该功能在 query 参数中传递。

响应更改

查询响应 JSON 已发生更改,允许以更合理的编程方式访问最常用的数据。

顶级 JSON 更改

verbose 设置为 true 时(在 intents 属性中返回所有意向及其评分),V2 的顶级 JSON 属性为:

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

V3 的顶级 JSON 属性为:

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

intents 对象是未排序的列表。 不要假设 intents 中的第一个子级对应于 topIntent。 请改用 topIntent 值来查找评分:

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

响应 JSON 架构已发生更改,允许:

  • 消除原始言语 query 与返回的预测 prediction 之间的差别。
  • 更轻松地以编程方式访问预测的数据。 可以按意向和实体的 name 访问值,而无需枚举 V2 中的数组。 对于预测的实体角色,将返回角色名称,因为它在整个应用中是唯一的。
  • 将遵循数据类型(如果已确定)。 数字不再作为字符串返回。
  • 第一个优先级预测信息与其他元数据之间的差别在 $instance 对象中返回。

实体响应更改

在言语中标记实体的位置

在 V2 中,使用 startIndexendIndex 在言语中标记实体。

在 V3 中,使用 startIndexentityLength 标记实体。

访问实体元数据的 $instance

如果你需要实体元数据,则查询字符串需要使用 verbose=true 标志,并且响应在 $instance 对象中包含元数据。 以下部分的 JSON 响应中提供了示例。

预测的每个实体以数组的形式表示

prediction.entities.<entity-name> 对象包含一个数组,因为可以在言语中多次预测每个实体。

预构建实体更改

V3 响应对象包含对预构建实体的更改。 查看特定的预构建实体以了解详细信息。

列表实体预测更改

列表实体预测的 JSON 已更改为数组的数组:

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

每个内部数组对应于言语中的文本。 内部对象是一个数组,因为相同的文本可以出现在列表实体的多个子列表中。

entities 对象与 $instance 对象之间映射时,将为列表实体预测保留对象顺序。

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];

使用实体角色名称而不是实体名称

在 V2 中,entities 数组返回具有实体名称(唯一标识符)的所有预测实体。 在 V3 中,如果实体使用角色,并且预测针对实体角色,则主标识符是角色名称。 之所以能够这样做,是因为实体角色名称必须在整个应用中唯一,这包括其他模型(意向、实体)名称。

在以下示例中,假设某段言语包含文本 Yellow Bird Lane。 此文本将作为自定义 Location 实体的 Destination 角色进行预测。

言语文本 实体名称 角色名称
Yellow Bird Lane Location Destination

在 V2 中,实体由实体名称以及用作对象属性的角色进行标识:

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

在 V3 中,如果预测针对角色,则实体由实体角色引用:

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

在 V3 中,可以使用用于返回实体元数据的 verbose 标志来实现相同的结果:

"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"
            }
        ]
    }
}

在预测时扩展应用

了解关于如何在预测运行时扩展应用的概念

后续步骤

使用 V3 API 文档更新对 LUIS 终结点 API 的现有 REST 调用。