Изменения конечной точки прогноза для версии 3

Важно!

LUIS будет прекращена 1 октября 2025 г. и с 1 апреля 2023 г. вы не сможете создавать новые ресурсы LUIS. Мы рекомендуем перенести приложения LUIS на разговорное распознавание речи , чтобы воспользоваться преимуществами непрерывной поддержки продуктов и многоязычных возможностей.

API версии 3 конечной точки прогнозирования запросов изменились. Воспользуйтесь информацией, приведенной в данном руководстве, чтобы понять, как перейти на API конечных точек версии 3. В настоящее время дата, до которой необходимо завершить миграцию, не установлена.

Общедоступный статус - данный API версии 3 включает значительные изменения запросов и ответов JSON из V2 API.

API версии 3 предоставляет следующие новые функции:

В запрос и ответ конечной точки прогнозирования внесены существенные изменения для поддержки новых функций, перечисленных выше, включая следующие:

Справочная документация доступна для версии 3.

Версия 3 меняется с предварительной версии на общедоступную

Версия 3 внесла следующие изменения в рамках перехода на общедоступную версию:

  • Следующие предварительно созданные объекты имеют разные ответы JSON:

  • Запрос на изменение JSON тела:

    • с preferExternalEntities по preferExternalEntities
    • опциональный параметр score для внешних объектов
  • Изменения JSON тела ответа:

    • normalizedQuery удалено

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

Если вы используете Bot Framework, службу проверки орфографии Bing V7 или хотите перенести только разработку приложения LUIS, продолжайте использовать конечную точку версии 2.

Если вы знаете, что ни одно из ваших клиентских приложений или интеграций (Bot Framework и Проверка орфографии Bing V7) не затронуто, и вам удобно одновременно переносить разработку приложения LUIS и конечную точку прогнозирования, начните использовать конечную точку прогнозирования версии 3. Конечная точка прогнозирования версии 2 по-прежнему будет доступна и представляют собой хорошую стратегию отката.

Для получения информации об использовании API службы проверки орфографии Bing см. раздел Как исправить слова с ошибками.

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

Клиентские приложения Bot Framework и службы Azure Bot Service

Продолжайте использовать конечную точку прогнозирования API версии 2, пока не будет выпущена версия Bot Framework версии 4.7.

Изменения URL-адреса конечной точки

Изменения по названию слота и названию версии

Формат HTTP-вызова конечной точки версии 3 изменился.

Если вы хотите сделать запрос по версии, вам сперва необходимо опубликовать через API с "directVersionPublish":true. Запросите конечную точку, указав идентификатор версии вместо имени слота.

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

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

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

Ниже представлены некоторые параметры строки запроса API версии 3.

Параметр запроса Имя портала LUIS Тип Версия По умолчанию Назначение
log Сохранение журналов Логическое V2 & V3 false Сохранение запроса в файле журнала. Значение по умолчанию — false.
query - строка Только версия 3 Значение по умолчанию отсутствует — оно является обязательным только в запросе GET. В версии 2 прогнозируемый речевой фрагмент находится в параметре q.

В версии 3 функциональность передается в параметре query.
show-all-intents Включение оценок для всех намерений Логическое Только версия 3 false Возврат всех намерений с соответствующей оценкой в объекте prediction.intents. Намерения возвращаются в виде объектов в родительском объекте intents. Эта команда обеспечивает программный доступ без необходимости находить намерение в массиве: prediction.intents.give. В версии 2 они возвращались в массиве.
verbose Включение дополнительных сведений о сущностях Логическое V2 & V3 false В версии 2 возвращались все прогнозируемые намерения, если было задано значение true. Если требуются все прогнозируемые намерения, используйте параметр show-all-intents версии 3.

В версии 3 этот параметр предоставляет только сведения о метаданных сущности прогнозирования сущностей.
timezoneOffset - строка V2 - Часовой пояс, применяемый к сущностям datetimeV2.
datetimeReference - строка V3 - Часовой пояс, применяемый к сущностям datetimeV2. Заменяет timezoneOffset из версии 2.

V3 POST body

{
    "query":"your utterance here",
    "options":{
        "datetimeReference": "2019-05-05T12:00:00",
        "preferExternalEntities": true
    },
    "externalEntities":[],
    "dynamicLists":[]
}
Свойство Тип Версия По умолчанию Назначение
dynamicLists array Только версия 3 Не требуется. Динамические списки позволяют расширить существующий обученный и опубликованный объект списка уже в приложении LUIS.
externalEntities array Только версия 3 Не требуется. Внешние сущности дают вашему приложению LUIS возможность идентифицировать и маркировать сущности во время выполнения, которые могут использоваться в качестве функций для существующих сущностей.
options.datetimeReference строка Только версия 3 Нет значения по умолчанию Используется для определения смещения datetimeV2. Формат datetimeReference - ISO 8601.
options.preferExternalEntities Логическое Только версия 3 false Указывает, используется ли внешняя сущность пользователя (с тем же именем, что и существующий объект) или для прогнозирования используется существующий объект в модели.
query строка Только версия 3 Обязательный элемент. В версии 2 прогнозируемое высказывание указывается в параметре q.

В версии 3 функциональные возможности передаются в параметре query.

Изменения ответа

JSON ответа на запрос изменен, чтобы обеспечить более широкий программный доступ к наиболее часто используемым данным.

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

Лучшие свойства JSON для версии 2: если для verbose задано значение true, все намерения и их оценки возвращаются в свойстве intents:

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

Основные свойства JSON для версии 3:

{
    "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.
  • Упрощенный программный доступ к прогнозируемым данным. Вместо перечисления через массив в V2 вы можете получить доступ к значениям по имени как для намерений, так и для сущностей. Для предполагаемых ролей сущностей возвращается имя роли, поскольку оно уникально для всего приложения.
  • Типы данных, если они определены, учитываются. Числовые значения больше не возвращаются в виде строк.
  • Различие между прогнозной информацией первого приоритета и дополнительными метаданными, возвращаемыми в объекте $instance.

Изменения ответа сущности

Маркировка размещения сущностей в высказываниях

В версии 2 объект был отмечен в высказывании с помощью startIndex и endIndex.

В версии 3 объект отмечен значками startIndex и entityLength.

Доступ $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];

Имя роли сущности вместо имени сущности

В версии 2 массив entities возвращал все предсказанные сущности с именем сущности, являющимся уникальным идентификатором. В версии 3, в случае если сущность использует роли и прогноз предназначен для роли сущности, основным идентификатором является имя роли. Это возможно, поскольку имена ролей сущностей должны быть уникальными для всего приложения, включая имена других моделей (намерений, сущностей).

В следующем примере: рассмотрим высказывание, которое включает текст, Yellow Bird Lane. Данный текст предсказывается как пользовательская роль Location объекта Destination.

Текст речевого фрагмента Имя сущности Имя роли
Yellow Bird Lane Location Destination

В версии 2 сущность идентифицируется по имени сущности с ролью как свойством объекта:

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

В версии 3 на объект ссылается роль объекта, если прогноз предназначен для роли:

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

В версии 3 тот же результат с флагом 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"
            }
        ]
    }
}

Расширение приложения во время прогнозирования

Изучите концепции расширения приложения во время выполнения прогнозирования.

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

Используйте документацию по API версии 3, чтобы обновить существующие вызовы REST для API конечной точки LUIS.