V3 的預測端點變更Prediction endpoint changes for V3

查詢預測端點 V3 Api 已變更。The query prediction endpoint V3 APIs have changed. 使用本指南來瞭解如何遷移至第3版端點 Api。Use this guide to understand how to migrate to version 3 endpoint APIs.

警告

本文件尚未更新為最新 LUIS 入口網站的文字和螢幕擷取畫面。This document has not been updated with text and screenshots for the latest LUIS portal.

正式運作狀態-此 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 從預覽變更為 GAV3 changes from preview to GA

V3 進行下列變更,做為移至 GA 的一部分: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:

    • preferExternalEntitiespreferExternalEntitiesfrom preferExternalEntities to preferExternalEntities
    • 外部實體的選擇性 score 參數optional score parameter for external entities
  • 回應主體 JSON 變更:Response body JSON changes:

    • normalizedQuery 已移除normalizedQuery removed

建議採用策略Suggested adoption strategy

如果您使用 Bot Framework、Bing 拼寫檢查 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 和 Bing 拼寫檢查 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.

不支援Not supported

  • V3 預測端點不支援 Bing 拼寫檢查 API-繼續使用 V2 API 預測端點進行拼寫更正Bing Spell Check API is not supported in V3 prediction endpoint - continue to use V2 API prediction endpoint for spelling corrections

Bot Framework 和 Azure Bot 服務用戶端應用程式Bot Framework and Azure Bot Service client applications

繼續使用 V2 API 預測端點,直到已釋放 Bot Framework 的4.7。Continue to use the V2 API prediction endpoint until the V4.7 of the Bot Framework is released.

V2 API 淘汰V2 API Deprecation

2020年6月8日之後,V2 預測 API 將不會被淘汰至少9個月。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":trueAPI 發佈If you want to query by version, you first need to publish via API with "directVersionPublish":true. 查詢參考版本識別碼的端點,而不是位置名稱。Query the endpoint referencing the version ID instead of the slot name.

預測 API 版本PREDICTION API VERSION METHODMETHOD URLURL
V3V3 GETGET HTTPs://{REGION}。 api.cognitive.microsoft.com/luis/預測/V3.0/apps/{應用程式識別碼}/slots/{位置名稱}/predict?查詢 ={query}https://{REGION}.api.cognitive.microsoft.com/luis/prediction/v3.0/apps/{APP-ID}/slots/{SLOT-NAME}/predict?query={QUERY}
V3V3 POSTPOST HTTPs://{REGION}。 api.cognitive.microsoft.com/luis/預測/V3.0/apps/{應用程式識別碼}/slots/{位置名稱}/predicthttps://{REGION}.api.cognitive.microsoft.com/luis/prediction/v3.0/apps/{APP-ID}/slots/{SLOT-NAME}/predict
V2V2 GETGET HTTPs://{REGION}。 api.cognitive.microsoft.com/luis/預測/V3.0/apps/{應用程式識別碼}/versions/{版本識別碼}/predict?查詢 ={query}https://{REGION}.api.cognitive.microsoft.com/luis/prediction/v3.0/apps/{APP-ID}/versions/{VERSION-ID}/predict?query={QUERY}
V2V2 POSTPOST HTTPs://{REGION}。 api.cognitive.microsoft.com/luis/預測/V3.0/apps/{應用程式識別碼}/versions/{版本識別碼}/predicthttps://{REGION}.api.cognitive.microsoft.com/luis/prediction/v3.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 booleanboolean V2 & V3V2 & V3 falsefalse 將查詢儲存在記錄檔中。Store query in log file. 預設值為 false。Default value is false.
query stringstring 僅限第 3 版V3 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 僅限第 3 版V3 only falsefalse 傳回在預測. 意圖物件中具有對應分數的所有意圖。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 在第2版中,當設定為 true 時,會傳回所有預測意圖。In V2, when set to true, all predicted intents were returned. 如果您需要所有預測的意圖,請使用 show-all-intents的 V3 參數。If 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 張貼內容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 僅限第 3 版V3 only 不需要。Not required. 動態清單可讓您擴充現有的已定型和已發佈清單實體(已在 LUIS 應用程式中)。Dynamic lists allow you to extend an existing trained and published list entity, already in the LUIS app.
externalEntities arrayarray 僅限第 3 版V3 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 僅限第 3 版V3 only 無預設值No default 用來判斷datetimeV2 位移Used to determine datetimeV2 offset. DatetimeReference 的格式為ISO 8601The format for the datetimeReference is ISO 8601.
options.preferExternalEntities booleanboolean 僅限第 3 版V3 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 僅限第 3 版V3 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 時,V2 的最上層 JSON 屬性會傳回 intents 屬性中的所有意圖和其分數: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和傳回的預測,predictionClear distinction between original utterance, query, and returned prediction, prediction.
  • 以程式設計方式輕鬆存取預測的資料。Easier programmatic access to predicted data. 您可以透過名稱來存取意圖和實體的值,而不是列舉 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 中,實體會標示 startIndexentityLengthIn 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 Lane的語句。In 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 contact 實體。You can extend a LUIS contact entity with external information from a user’s contact list.

實體已存在於應用程式中Entity already exists in app

在提出要求時,已定型和已發佈的應用程式中必須已有外部實體的 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 的要求可以傳入有關 Hazem 的 POST 本文中的資訊,因此它會直接與其中一個使用者連絡人進行比對。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 free 查詢。For 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"
  • {"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個具有大約1000專案的清單。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 preview 之後,V2 API 將不會被淘汰至少9個月。The V2 API will not be deprecated for at least 9 months after the V3 preview.

後續步驟Next steps

使用 V3 API 檔,將現有的 REST 呼叫更新為 LUIS端點api。Use the V3 API documentation to update existing REST calls to LUIS endpoint APIs.