Modelo de resposta estruturado

Artigo
10/24/2023

APLICA-SE A: SDK v4

Os modelos de resposta estruturada permitem que os desenvolvedores definam uma estrutura complexa que suporta a funcionalidade extensiva da geração de linguagem (LG), como modelos e composição, deixando a interpretação da resposta estruturada para o chamador da biblioteca LG.

Para aplicativos de bot, o seguinte suporte é fornecido:

O modelo de atividade do Bot Framework inclui vários campos personalizáveis. As propriedades a seguir são as mais comumente usadas e são configuráveis por meio de uma definição de modelo de atividade:

Propriedade	Caso de utilização
Texto	Exibir texto usado pelo canal para renderizar visualmente
Falar	Texto falado usado pelo canal para renderizar de forma audível
Anexos	Lista de anexos com o seu tipo. Usado por canais para renderizar como cartões de interface do usuário ou outros tipos genéricos de anexos de arquivos.
Ações sugeridas	Lista de ações renderizadas como sugestões ao usuário.
InputHint	Controla o estado do fluxo de captura de áudio em dispositivos que suportam entrada falada. Os valores possíveis incluem `accepting`, , `expecting`ou `ignoring`.

Não há nenhum comportamento de fallback padrão implementado pelo resolvedor de modelo. Se uma propriedade não for especificada, ela permanecerá não especificada. Por exemplo, a propriedade não é atribuída automaticamente para ser a propriedade se apenas a SpeakTextText propriedade for especificada.

Definição

Aqui está a definição de um modelo estruturado:

# TemplateName
> this is a comment
[Structure-name
    Property1 = <plain text> .or. <plain text with template reference> .or. <expression>
    Property2 = list of values are denoted via '|'. e.g. a | b
> this is a comment about this specific property
    Property3 = Nested structures are achieved through composition
]

Aqui está um exemplo de um modelo de texto básico:

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

Aqui está um exemplo de texto com uma ação sugerida. Use | para indicar uma lista.

> With '|' you are making attachments a list.
# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    SuggestedActions = 10 | 20 | 30
]

Aqui está um exemplo de uma definição de cartão de herói:

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

Nota

LG fornece alguma variabilidade na definição da placa, que é convertida para se alinhar com a definição da placa SDK. Por exemplo, ambos os image campos e images são suportados em todas as definições de cartão na LG, embora apenas images sejam suportados na definição de placa SDK.

Os valores definidos em todos os image campos e em um cartão HeroCard ou miniatura são combinados e images convertidos em uma lista de imagens no cartão gerado. Para os outros tipos de cartões, o último valor definido no modelo será atribuído ao image campo. Os valores atribuídos ao image/images campo podem ser uma cadeia de caracteres, expressão adaptável ou matriz no formato usando |.

Abaixo está a combinação dos modelos anteriores:

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
    Attachments = ${HeroCard()}
    SuggestedActions = 10 | 20 | 30
    InputHint = expecting
]

# GetAge
- how old are you?
- what is your age?

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

Por padrão, qualquer referência de modelo é avaliada uma vez durante a avaliação de um modelo estruturado.

Por exemplo, # AskForAge.prompt retorna o mesmo texto de resolução para as Speak propriedades e Text .

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

Você pode usar <TemplateName>!() para solicitar uma nova avaliação em cada referência dentro de um modelo estruturado.

No exemplo abaixo, Speak e Text pode ter texto de resolução diferente porque GetAge é reavaliado em cada instância.

[Activity
    Text = ${GetAge()}
    Speak = ${GetAge!()}
]

# GetAge
- how old are you?
- what is your age?

Veja como exibir um carrossel de cartões:

# AskForAge.prompt
[Activity
> Defaults to carousel layout in case of list of cards
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
]

# AskForAge.prompt_2
[Activity
> Explicitly specify an attachment layout
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
    AttachmentLayout = list
]

# HeroCard (title, subtitle, text)
[Herocard
    title = ${title}
    subtitle = ${subtitle}
    text = ${text}
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

Use \ como um personagem de fuga.

> You can use '\' as an escape character
> \${GetAge()} would not be evaluated as expression, would be parsed as '${getAge()}' string
# AskForAge.prompt
[Activity
        Text = \${GetAge()}
        SuggestedActions = 10 \| cards | 20 \| cards
]

Composição do modelo estruturado

O seguinte comportamento de composição é suportado com modelos estruturados:

A composição é sensível ao contexto da estrutura. Se o modelo de destino que está sendo referido também for um modelo estruturado, o tipo de estrutura deverá corresponder. Por exemplo, um ActivityTemplate pode ser referido em outro ActivityTemplate.
As referências ao modelo de resposta simples ou condicional podem existir em qualquer lugar dentro de um modelo estruturado.

Suponha que você tenha o seguinte modelo:

# T1
[Activity
    Text = ${T2()}
    Speak = foo bar ${T3().speak}
]

# T2
- This is awesome

# T3
[Activity
    Speak = I can also speak!
]

Um convite à apresentação de evaluateTemplate('T1') propostas resultaria na seguinte estrutura interna:

[Activity
    Text = This is awesome
    Speak = I can also speak!
]

Referência completa a outro modelo estruturado

Você pode incluir uma referência a outro modelo estruturado como uma propriedade em outro modelo estruturado ou como uma referência em outro modelo de resposta simples ou condicional

Aqui está um exemplo de referência completa a outro modelo estruturado:

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
]

Com este conteúdo, uma chamada para evaluateTemplate('ST1') resultará na seguinte estrutura interna:

[MyStruct
    Text = foo
    Speak = bar
]

Quando a mesma propriedade existir no modelo de chamada e no modelo chamado, o conteúdo no chamador substituirá qualquer conteúdo no modelo chamado.

Eis um exemplo:

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
    Text = zoo
]

Neste contexto, uma chamada para evaluateTemplate('ST1') resultará na seguinte estrutura interna:

[MyStruct
    Text = foo
    Speak = bar
]

Note que este estilo de composição só pode existir ao nível da raiz. Se houver uma referência a outro modelo estruturado dentro de uma propriedade, a resolução será contextual para essa propriedade.

Referência de arquivo externo em anexo estruturado

Há duas funções pré-construídas usadas para fazer referência externa a arquivos

fromFile(fileAbsoluteOrRelativePath) carrega um arquivo especificado. O conteúdo retornado por esta função apoiará a avaliação do conteúdo. As referências, propriedades e expressões do modelo são avaliadas.
ActivityAttachment(content, contentType) Define o contentType Se ainda não estiver especificado no conteúdo.

Com essas duas funções pré-criadas, você pode obter qualquer conteúdo definido externamente, incluindo todos os tipos de cartão. Use o seguinte LG estruturado para compor uma atividade:

# AdaptiveCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'adaptiveCard')}
]

# HeroCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'heroCard')}
]

Você também pode usar anexos, vistos abaixo:

# AdaptiveCard
[Attachment
    contenttype = adaptivecard
    content = ${json(fromFile('../../card.json'))}
]

# HeroCard
[Attachment
    contenttype = herocard
    content = ${json(fromFile('../../card.json'))}
]

Informações adicionais

Referência da API C#
Referência da API JavaScript
Leia Depurar com Ferramentas Adaptáveis para saber como analisar e depurar modelos.

Partilhar via