Plantilla de respuesta estructurada

  • Artículo

SE APLICA A: SDK v4

Las plantillas de respuesta estructurada permiten a los desarrolladores definir una estructura compleja que admite la funcionalidad ampliada de Language Generation, la cual incluye la creación de plantillas y la redacción, a la vez que se deja la interpretación de la respuesta estructurada a criterio del autor de la llamada de la biblioteca de Language Generation.

En el caso de las aplicaciones de bot, se proporciona la siguiente compatibilidad:

La actividad de Bot Framework incluye varios campos personalizables. Las propiedades que se muestran a continuación son las más usadas y se pueden configurar mediante una definición de plantilla de actividad:

Propiedad Caso de uso
Texto Mostrar el texto utilizado por el canal para representarlo visualmente
Speak Texto hablado que el canal usa para la representación de forma audible
Datos adjuntos Lista de datos adjuntos con su tipo. Lo usan los canales para la representación como tarjetas de interfaz de usuario u otros tipos de datos adjuntos de archivo genéricos.
SuggestedActions Lista de las acciones representadas como sugerencias para el usuario.
InputHint Controla el estado de la secuencia de captura de audio en los dispositivos que admiten entradas de voz. Los posibles valores incluyen: accepting, expecting o ignoring.

No hay ningún comportamiento de reserva predeterminado implementado por el solucionador de plantillas. Si no se especifica una propiedad, esta permanece sin especificar. Por ejemplo, la propiedad Speak no se asigna automáticamente para ser la propiedad Text si solo se especifica la propiedad Text.

Definición

A continuación se muestra la definición de una plantilla estructurada:

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

Este es un ejemplo de una plantilla de texto básica:

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

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

Este es un ejemplo de texto con una acción sugerida. Use | para indicar una lista.

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

A continuación se muestra un ejemplo de definición de una tarjeta Hero:

# 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 proporciona cierta variabilidad en la definición de tarjeta, que se convierte para alinearse con la definición de tarjeta SDK. Por ejemplo, tanto el campo image como images se admiten en todas las definiciones de tarjeta de LG, aunque solo se admitan images en la definición de tarjeta del SDK.

Los valores definidos en todos los campos image y images de una tarjeta HeroCard o miniatura se combinan y convierten en una lista de imágenes de la tarjeta generada. Para los otros tipos de tarjetas, el último valor definido de la plantilla se asignará al campo image. Los valores que asigne al campo image/images pueden ser una cadena, una expresión adaptable o una matriz con el formato |.

A continuación se muestra la combinación de las plantillas 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
]

De forma predeterminada, cualquier referencia de plantilla se evalúa una vez durante la evaluación de una plantilla estructurada.

Por ejemplo, # AskForAge.prompt devuelve el mismo texto de resolución para las propiedades Speak y Text.

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

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

Puede usar <TemplateName>!() para solicitar una nueva evaluación en cada referencia de una plantilla estructurada.

En el ejemplo siguiente, Speak y Text pueden tener texto de resolución diferente porque GetAge se vuelve a evaluar en cada instancia.

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

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

Aquí se indica cómo mostrar un carrusel de tarjetas:

# 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 carácter de escape.

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

Composición de plantilla estructurada

El siguiente comportamiento de composición es compatible con las plantillas estructuradas:

  • La composición depende del contexto de la estructura. Si la plantilla de destino a la que se va a hacer referencia es también una plantilla estructurada, el tipo de estructura debe coincidir. Por ejemplo, se puede hacer referencia a una plantilla de ActivityTemplate en otra plantilla de ActivityTemplate.
  • Las referencias a una plantilla de respuesta simple o condicional pueden existir en cualquier parte de una plantilla estructurada.

Supongamos que tiene la siguiente plantilla:

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

# T2
- This is awesome

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

Una llamada a evaluateTemplate('T1') daría lugar a la siguiente estructura interna:

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

Referencia completa a otra plantilla estructurada

Puedes incluir una referencia a otra plantilla estructurada como una propiedad de otra plantilla estructurada o como una referencia en otra plantilla de respuesta simple o condicional

Este es un ejemplo de referencia completa a otra plantilla estructurada:

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

Con este contenido, una llamada a evaluateTemplate('ST1') dará como resultado la siguiente estructura interna:

[MyStruct
    Text = foo
    Speak = bar
]

Cuando existe la misma propiedad en la plantilla que realiza la llamada como en la que la recibe, el contenido del autor de la llamada sobrescribirá cualquier contenido de la plantilla a la que se ha llamado.

Este es un ejemplo:

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

Con este contexto, una llamada a evaluateTemplate('ST1') dará como resultado la siguiente estructura interna:

[MyStruct
    Text = foo
    Speak = bar
]

Ten en cuenta que este estilo de composición solo puede existir en el nivel raíz. Si hay una referencia a otra plantilla estructurada en una propiedad, la resolución depende del contexto para esa propiedad.

Referencia externa a archivos en datos adjuntos estructurados

Hay dos funciones precompiladas que se usan para hacer referencia a archivos de forma externa

  1. fromFile(fileAbsoluteOrRelativePath) carga un archivo especificado. El contenido devuelto por esta función admitirá la evaluación del contenido. Se evalúan las referencias de plantilla, las propiedades y las expresiones.
  2. ActivityAttachment(content, contentType) establece el contentType si aún no se ha especificado en el contenido.

Con estas dos funciones precompiladas, puede extraer cualquier contenido definido externamente, incluidos todos los tipos de tarjeta. Use la siguiente instancia de Language Generation para crear una actividad:

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

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

También puede usar los datos adjuntos que se muestran a continuación:

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

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

Información adicional