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 query prediction endpoint request and response have significant changes to support the new features listed above, including the following:

V3 API 不支持以下 LUIS 功能:The following LUIS features are not supported in the V3 API:

  • 必应拼写检查 V7Bing Spell Check V7

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

终结点 URL 按槽名称更改Endpoint URL changes by slot name

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

方法METHOD URLURL
GETGET https://{REGION}.api.cognitive.azure.cn/luis/v3.0-preview/apps/{APP-ID}/slots/{SLOT-NAME}/predict?query={QUERY}https://{REGION}.api.cognitive.azure.cn/luis/v3.0-preview/apps/{APP-ID}/slots/{SLOT-NAME}/predict?query={QUERY}
POSTPOST https://{REGION}.api.cognitive.azure.cn/luis/v3.0-preview/apps/{APP-ID}/slots/{SLOT-NAME}/predicthttps://{REGION}.api.cognitive.azure.cn/luis/v3.0-preview/apps/{APP-ID}/slots/{SLOT-NAME}/predict

槽的有效值:Valid values for slots:

  • production
  • staging

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.

预测 API 版本PREDICTION API VERSION 方法METHOD URLURL
V3V3 GETGET https://{REGION}.api.cognitive.azure.cn/luis/prediction/v3.0/apps/{APP-ID}/slots/{SLOT-NAME}/predict?query={QUERY}https://{REGION}.api.cognitive.azure.cn/luis/prediction/v3.0/apps/{APP-ID}/slots/{SLOT-NAME}/predict?query={QUERY}
V3V3 POSTPOST https://{REGION}.api.cognitive.azure.cn/luis/prediction/v3.0/apps/{APP-ID}/slots/{SLOT-NAME}/predicthttps://{REGION}.api.cognitive.azure.cn/luis/prediction/v3.0/apps/{APP-ID}/slots/{SLOT-NAME}/predict
V2V2 GETGET https://{REGION}.api.cognitive.azure.cn/luis/prediction/v3.0/apps/{APP-ID}/versions/{VERSION-ID}/predict?query={QUERY}https://{REGION}.api.cognitive.azure.cn/luis/prediction/v3.0/apps/{APP-ID}/versions/{VERSION-ID}/predict?query={QUERY}
V2V2 POSTPOST https://{REGION}.api.cognitive.azure.cn/luis/predictionv3.0/apps/{APP-ID}/versions/{VERSION-ID}/predicthttps://{REGION}.api.cognitive.azure.cn/luis/predictionv3.0/apps/{APP-ID}/versions/{VERSION-ID}/predict
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 布尔值boolean V2 和 V3V2 & V3 falsefalse 将查询存储在日志文件中。Store query in log file.
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 布尔值boolean 仅 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 布尔值boolean 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.

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. 可以按意向和实体的 named 访问值,而无需枚举 V2 中的数组。Instead of enumerating through an array in V2, you can access values by named 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"
            }
        ]
    }
}

预测时传入的外部实体External entities passed in at prediction time

外部实体可让 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. 这样,在将查询发送到预测终结点之前,便可以使用自己的独立自定义实体提取器。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. 可以使用用户联系人列表中的外部信息扩展 LUIS 联系人实体。You can extend a LUIS contact entity with external information from a user’s contact list.

实体已在应用中存在Entity already exists in app

发出请求时,在终结点请求 POST 正文中传递的外部实体 entityName 值必须事先在已训练且发布的应用中存在。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

聊天机器人发送给 LUIS 的请求可以在 POST 正文中传入有关 Hazem 的信息,以便将此信息直接匹配为用户的联系人之一。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.

    "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.

上面的言语使用 him 作为对 Hazem 的引用。In the previous utterance, the utterance uses him as a reference to Hazem. 在 POST 正文中,聊天机器人可将 him 映射到从第一段言语 Hazem 提取的实体值。The conversational chat bot, in the POST body, can map him to the entity value extracted from the first utterance, Hazem.

    "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

preferExternalEntities 选项属性指定如果用户发送与同名的预测实体重叠的外部实体,LUIS 将选择传入的实体还是模型中存在的实体。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.

例如,考虑查询 today I'm freeFor example, consider the query today I'm free. LUIS 检测到 today 为 datetimeV2,响应如下:LUIS detects today as a datetimeV2 with the following response:

"datetimeV2": [
    {
        "type": "date",
        "values": [
            {
                "timex": "2019-06-21",
                "value": "2019-06-21"
            }
        ]
    }
]

如果用户发送外部实体:If the user sends the external entity:

{
    "entityName": "datetimeV2",
    "startIndex": 0,
    "entityLength": 5,
    "resolution": {
        "date": "2019-06-21"
    }
}

如果 preferExternalEntities 设置为 false,则 LUIS 将返回响应就像未发送外部实体一样。If the preferExternalEntities is set to false, LUIS returns a response as if the external entity were not sent.

"datetimeV2": [
    {
        "type": "date",
        "values": [
            {
                "timex": "2019-06-21",
                "value": "2019-06-21"
            }
        ]
    }
]

如果 preferExternalEntities 设置为 true,则 LUIS 将返回包括以下内容的响应:If the preferExternalEntities is set to true, LUIS returns a response including:

"datetimeV2": [
    {
        "date": "2019-06-21"
    }
]

解决方法Resolution

可选的 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.

resolution 属性可以是数字、字符串、对象或数组:The resolution property can be a number, a string, an object, or an array:

  • "Dallas""Dallas"
  • {"text": "value"}{"text": "value"}
  • 1234512345
  • ["a", "b", "c"]["a", "b", "c"]

预测时传入的动态列表Dynamic lists passed in at prediction time

使用动态列表可以扩展已包含在 LUIS 应用中的已训练并发布的现有列表实体。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.

列表实体在 LUIS 应用中可为空,但必须存在。The list entity can be empty in the LUIS app but it has to exist. LUIS 应用中的列表实体不会更改,但终结点上的预测功能将会扩展,以最多包含 2 个列表,其中有大约 1,000 个项。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.

动态列表 JSON 请求正文Dynamic list JSON request body

发送以下 JSON 正文,以向列表发送包含同义词的新子列表,并使用 POST 查询预测请求预测文本 LUIS 的列表实体: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:

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

预测响应包含该列表实体以及其他所有预测实体,因为该实体已在请求中定义。The prediction response includes that list entity, with all the other predicted entities, because it is defined in the request.

弃用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.