Изменения конечной точки прогнозирования для v3Prediction endpoint changes for 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.

Общедоступное состояние — этот API V3 включает значительные изменения запросов и ответов JSON из API v2.Generally available status - this V3 API include significant JSON request and response changes from V2 API.

API V3 предоставляет следующие новые возможности: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:

Справочная документация доступна для версии 3.Reference documentation is available for V3.

V3 переход с режима просмотра на общедоступныйV3 changes from preview to GA

В рамках перехода к общедоступному версии 3 были внесены следующие изменения: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:

    • normalizedQuery удаленnormalizedQuery removed

Предлагаемая стратегия внедренияSuggested adoption strategy

Если вы используете платформу Bot, Проверка орфографии Bing версии 7 или хотите перенести только создание приложения LUIS, продолжайте использовать конечную точку версии 2.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 версии 7) не затрагивается, и вы сможете одновременно перенести создание приложений 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. Конечная точка прогнозирования версии 2 по-прежнему будет доступна и является хорошей стратегией отката.The V2 prediction endpoint will still be available and is a good fall-back strategy.

Не поддерживаетсяNot supported

API Проверки орфографии BingBing Spell Check

Этот API не поддерживается в конечной точке прогнозирования v3. Продолжайте использовать конечную точку прогнозирования API v2 для исправления орфографии.This API is not supported in V3 prediction endpoint - continue to use V2 API prediction endpoint for spelling corrections. Если при использовании API V3 требуется исправление орфографических ошибок, то клиентское приложение вызывает Проверка орфографии Bing API и изменяет текст на правильное написание перед отправкой текста в API Luis.If you need spelling correction while using V3 API, have the client application call the Bing Spell Check API, and change the text to the correct spelling, prior to sending the text to the LUIS API.

Платформа Bot и клиентские приложения службы Azure BotBot Framework and Azure Bot Service client applications

Продолжайте использовать конечную точку прогнозирования API v2 до выпуска версии 4.7 платформы Bot.Continue to use the V2 API prediction endpoint until the V4.7 of the Bot Framework is released.

Устаревшая версия API v2V2 API Deprecation

API-интерфейс прогнозирования версии 2 не будет считаться устаревшим в течение не менее 9 месяцев после предварительной версии v3, 8 июня 2020.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

Изменился Формат HTTP-вызова конечной точки версии v3 .The format of the V3 endpoint HTTP call has changed.

Если вы хотите выполнить запрос по версии, сначала необходимо ОПУБЛИКОВАТЬ API с помощью "directVersionPublish":true .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.

Допустимые значения для SLOT-NAMEValid values for SLOT-NAME
production
staging

Запрос измененийRequest changes

Изменения строки запросаQuery string changes

Параметры строки запроса API V3 включают:V3 API query string parameters include:

Параметр запросаQuery parameter Имя портала LUISLUIS portal name ТипType ВерсияVersion По умолчаниюDefault НазначениеPurpose
log Сохранить журналыSave logs Логическоеboolean V2 & V3V2 & V3 falsefalse Сохранить запрос в файле журнала.Store query in log file. Значение по умолчанию — false.Default value is false.
query - строкаstring Только версия 3V3 only Нет значения по умолчанию — оно требуется в запросе GET.No default - it is required in the GET request В версии 2utterance для прогнозирования находится в q параметре.In V2, the utterance to be predicted is in the q parameter.

В версии 3функции передаются в query параметре.In V3, the functionality is passed in the query parameter.
show-all-intents Включить оценки для всех целейInclude scores for all intents Логическоеboolean Только версия 3V3 only falsefalse Возврат всех целей с соответствующим показателем в объекте PREDICTION. Fors.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.give .This allows programmatic access without needing to find the intent in an array: prediction.intents.give. В версии 2 они были возвращены в массиве.In V2, these were returned in an array.
verbose Включить дополнительные сведения о сущностяхInclude more entities details Логическоеboolean V2 & V3V2 & V3 falsefalse В версии 2, если задано значение true, возвращаются все прогнозируемые намерения.In V2, when set to true, all predicted intents were returned. Если требуются все прогнозируемые намерения, используйте параметр v3 параметра show-all-intents .If you need all predicted intents, use the V3 param of show-all-intents.

В версии 3этот параметр предоставляет только метаданные сущности "прогнозирование сущностей".In V3, this parameter only provides entity metadata details of entity prediction.
timezoneOffset - строкаstring V2V2 - Часовой пояс, применяемый к сущностям datetimeV2.Timezone applied to datetimeV2 entities.
datetimeReference - строкаstring V3V3 - Часовой пояс , применяемый к сущностям datetimeV2.Timezone applied to datetimeV2 entities. Заменяет timezoneOffset из v2.Replaces timezoneOffset from V2.

V3 тело сообщенияV3 POST body

{
    "query":"your utterance here",
    "options":{
        "datetimeReference": "2019-05-05T12:00:00",
        "preferExternalEntities": true
    },
    "externalEntities":[],
    "dynamicLists":[]
}
СвойствоProperty TypeType ВерсияVersion По умолчаниюDefault НазначениеPurpose
dynamicLists массивеarray Только версия 3V3 only Не требуется.Not required. Динамические списки позволяют расширить существующую подготовленную и опубликованную сущность списка, уже находящиеся в приложении Luis.Dynamic lists allow you to extend an existing trained and published list entity, already in the LUIS app.
externalEntities массивеarray Только версия 3V3 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 строкаstring Только версия 3V3 only Нет значения по умолчаниюNo default Используется для определения смещения datetimeV2.Used to determine datetimeV2 offset. Формат для Датетимереференце — ISO 8601.The format for the datetimeReference is ISO 8601.
options.preferExternalEntities Логическоеboolean Только версия 3V3 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 строкаstring Только версия 3V3 only Обязательный.Required. В версии 2 utterance для прогнозирования находится в q параметре.In V2, the utterance to be predicted is in the q parameter.

В версии 3 функции передаются в 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.

Изменения верхнего уровня JSONTop level JSON changes

Верхние свойства JSON для v2 —, если для verbose свойства задано значение true, которое возвращает все способы и их оценки в 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":[]
}

Верхние свойства JSON для V3: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 соответствует topIntent .Do 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:

  • Снимите различие между исходным utterance, query и возвращенным прогнозом, prediction .Clear 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

В версии 2 сущность была помечена в utterance с помощью startIndex и endIndex .In V2, an entity was marked in an utterance with the startIndex and endIndex.

В версии 3 сущность помечена startIndex и entityLength .In V3, the entity is marked with startIndex and entityLength.

Доступ $instance для метаданных сущностиAccess $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>Объект содержит массив, так как каждая сущность может быть предсказана более одного раза в utterance.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"]
    ]
}

Каждый внутренний массив соответствует тексту внутри utterance.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 объектом порядок объектов сохраняется для прогнозов объекта List.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

В версии 2 entities массив вернул все прогнозируемые сущности с именем сущности, которое является уникальным идентификатором.In V2, the entities array returned all the predicted entities with the entity name being the unique identifier. В версии 3, если сущность использует роли, а прогноз предназначен для роли сущности, первичный идентификатор — это имя роли.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.

В следующем примере: рассмотрим utterance, включающий текст, 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 текстUtterance text Имя сущностиEntity name Имя ролиRole name
Yellow Bird Lane Location Destination

В версии 2 сущность определяется именем сущности и ролью в качестве свойства объекта: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

API v2 не будет считаться устаревшим по меньшей мере через 9 месяцев после предварительной версии v3.The V2 API will not be deprecated for at least 9 months after the V3 preview.

Дальнейшие действияNext steps

Используйте документацию по API V3 для обновления существующих вызовов RESTFUL к API-интерфейсам конечной точки Luis.Use the V3 API documentation to update existing REST calls to LUIS endpoint APIs.