Alterações no ponto de extremidade de previsão para a V3

As APIs do ponto de extremidade de previsão de consulta V3 foram alteradas. Use este guia para entender como migrar para as APIs de ponto de extremidade versão 3. Atualmente, não há nenhuma data até a qual a migração precisa ser concluída.

Status geralmente disponível – essa API V3 inclui alterações significativas de solicitação e resposta JSON da API V2.

A API V3 fornece os seguintes novos recursos:

A solicitação e a resposta do ponto de extremidade de previsão têm alterações significativas para dar suporte aos novos recursos listados acima, incluindo o seguinte:

A documentação de referência está disponível para a V3.

Alterações da V3 da versão prévia para GA

A V3 fez as seguintes alterações como parte da mudança para GA:

  • As seguintes entidades predefinidas têm respostas JSON diferentes:

  • Alteração JSON do corpo da solicitação:

    • de preferExternalEntities para preferExternalEntities
    • parâmetro score opcional para entidades externas
  • Alterações JSON do corpo da resposta:

    • normalizedQuery removido

Estratégia de adoção sugerida

Se você usar o Bot Framework, Verificação Ortográfica do Bing V7 ou desejar migrar apenas a criação de aplicativos LUIS, continue usando o ponto de extremidade V2.

Se você souber que nenhum de seus aplicativos cliente ou integrações (Bot Framework e Verificação Ortográfica do Bing V7) foram afetados, e você está confortável migrando sua criação de aplicativo LUIS e seu ponto de extremidade de previsão ao mesmo tempo, comece a usar o ponto de extremidade de previsão V3. O ponto de extremidade de previsão v2 ainda estará disponível e será uma boa estratégia de fallback.

Para obter informações sobre como usar a API de Verificação Ortográfica do Bing, consulte como corrigir palavras incorretas.

Sem suporte

Aplicativos cliente Bot framework e Serviço de Bot do Azure

Continue usando o ponto de extremidade de previsão da API V2 até que a V4.7 do Bot Framework seja lançada.

Alterações de URL do ponto de extremidade

Alterações por nome do slot e nome da versão

O formato da chamada HTTP do ponto de extremidade V3 foi alterado.

Se desejar consultar por versão, primeiro você precisará publicar via API com "directVersionPublish":true. Consulte o ponto de extremidade que referencia a ID de versão em vez do nome do slot.

Valores válidos para SLOT-NAME
production
staging

Alterações de solicitação

Alterações na cadeia de caracteres de consulta

Os parâmetros de cadeia de caracteres de consulta da API V3 incluem:

Parâmetro de consulta Nome do portal do LUIS Tipo Versão Padrão Finalidade
log Salvar logs booleano V2 e V3 false Armazenar consulta no arquivo de log. O valor padrão é false.
query - string Somente V3 Nenhum padrão - ele é necessário na solicitação GET Na V2, o enunciado a ser previsto está no parâmetro q.

Na V3, a funcionalidade é passada no parâmetro query.
show-all-intents Incluir pontuações para todas as intenções booleano Somente V3 false Retorne todas as intenções com a pontuação correspondente no objeto prediction.intents. As intenções são retornadas como objetos em um objeto pai intents. Isso permite acesso programático sem a necessidade de encontrar a intenção em uma matriz: prediction.intents.give. Na V2, elas foram retornadas em uma matriz.
verbose Incluir mais detalhes de entidades booleano V2 e V3 false Na V2, quando definidas como true, todas as intenções previstas foram retornadas. Se você precisar de todas as intenções previstas, use o parâmetro V3 de show-all-intents.

Na V3, esse parâmetro fornece apenas detalhes de metadados de entidade de previsão de entidades.
timezoneOffset - string V2 - Fuso horário aplicado às entidades datetimeV2.
datetimeReference - string V3 - Fuso horário aplicado às entidades datetimeV2. Substitui timezoneOffset de V2.

Corpo POST V3

{
    "query":"your utterance here",
    "options":{
        "datetimeReference": "2019-05-05T12:00:00",
        "preferExternalEntities": true
    },
    "externalEntities":[],
    "dynamicLists":[]
}
Propriedade Tipo Versão Padrão Finalidade
dynamicLists matriz Somente V3 Não necessário. As listas dinâmicas permitem estender uma entidade de lista treinada e publicada existente, já no aplicativo LUIS.
externalEntities matriz Somente V3 Não necessário. As entidades externas dão ao seu aplicativo LUIS a capacidade de identificar e rotular entidades durante o runtime, que podem ser usadas como recursos para entidades existentes.
options.datetimeReference string Somente V3 Nenhum padrão Usado para determinar o deslocamento de datetimeV2. O formato para o datetimeReference é ISO 8601.
options.preferExternalEntities booleano Somente V3 false Especifica se a entidade externa do usuário (com o mesmo nome da entidade existente) é usada, ou a entidade existente no modelo é usada para previsão.
query string Somente V3 Obrigatórios. Na V2, o enunciado a ser previsto está no parâmetro q.

Na V3, a funcionalidade é passada no parâmetro query.

Alterações de resposta

A resposta de consulta JSON foi alterada para permitir maior acesso programático aos dados usados com mais frequência.

Alterações JSON de nível superior

As principais propriedades JSON para V2 são, quando verbose é definido como true, que retorna todas as intenções e suas pontuações na propriedade intents:

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

As principais propriedades JSON para V3 são:

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

O objeto intents é uma lista não ordenada. Não suponha que o primeiro filho em intents corresponda a topIntent. Em vez disso, use o valor topIntent para encontrar a pontuação:

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

As alterações de esquema JSON de resposta permitem:

  • Distinção clara entre o enunciado original, query e a previsão retornada prediction.
  • Acesso programático mais fácil aos dados previstos. Em vez de enumerar por meio de uma matriz na V2, você pode acessar valores por nome para intenções e entidades. Para funções de entidade previstas, o nome da função é retornado porque é exclusivo em todo o aplicativo.
  • Os tipos de dados, se determinados, são respeitados. Os numéricos não são mais retornados como cadeias de caracteres.
  • Distinção entre as informações de previsão prioritárias e os metadados adicionais, retornados no objeto $instance.

Alterações de resposta da entidade

Marcando o posicionamento de entidades em enunciados

Na V2, uma entidade foi marcada em um enunciado com startIndex e endIndex.

Na V3, a entidade é marcada com startIndex e entityLength.

Acesso $instance para metadados de entidade

Se você precisar de metadados de entidade, a cadeia de caracteres de consulta precisará usar o sinalizadorverbose=true e a resposta conterá os metadados no objeto $instance. Os exemplos são mostrados nas respostas JSON nas seções a seguir.

Cada entidade prevista é representada como uma matriz

O objeto prediction.entities.<entity-name> contém uma matriz, pois cada entidade pode ser prevista mais de uma vez no enunciado.

Alterações de entidade predefinida

O objeto de resposta V3 inclui alterações em entidades predefinidas. Consulte entidades predefinidas específicas para saber mais.

Listar alterações de previsão de entidade

O JSON para uma previsão de entidade de lista mudou para ser uma matriz de matrizes:

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

Cada matriz interior corresponde ao texto no enunciado. O objeto interior é uma matriz porque o mesmo texto pode aparecer em mais de uma sublista de uma entidade de lista.

Ao mapear entre o objeto entities e o objeto $instance, a ordem dos objetos é preservada para as previsões de entidade de lista.

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

Nome da função de entidade em vez do nome da entidade

Na V2, a matriz entities retornou todas as entidades previstas com o nome da entidade sendo o identificador exclusivo. Na V3, se a entidade usar funções e a previsão for para uma função de entidade, o identificador primário será o nome da função. Isso é possível porque os nomes de função de entidade devem ser exclusivos em todo o aplicativo, incluindo outros nomes de modelo (intenção, entidade).

No exemplo a seguir: considere um enunciado que inclui o texto, Yellow Bird Lane. Esse texto é previsto como uma função de entidade Location personalizada de Destination.

Texto do enunciado Nome da entidade Nome da função
Yellow Bird Lane Location Destination

Na V2, a entidade é identificada pelo nome da entidade com a função como uma propriedade do objeto:

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

Na V3, a entidade será referenciada pela função da entidade, se a previsão for para a função:

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

Na V3, o mesmo resultado com o sinalizador verbose para retornar metadados de entidade:

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

Estende o aplicativo no momento da previsão

Conheça os conceitos sobre como estender o aplicativo no runtime de previsão.

Próximas etapas

Use a documentação da API V3 para atualizar as chamadas REST existentes às APIs de ponto de extremidade do LUIS.