Vorlage für eine strukturierte Antwort

Artikel
12/29/2023

GILT FÜR: SDK v4

Mit Vorlagen für strukturierte Antworten können Entwickler eine komplexe Struktur definieren, die die umfangreiche Funktionalität zur Sprachgenerierung (Language Generation, LG) unterstützt (z. B. Vorlagen und Komposition), und gleichzeitig die Interpretation der strukturierten Antwort beim Aufrufer der LG-Bibliothek belassen.

Für Bot-Anwendungen wird Folgendes unterstützt:

Aktivitätsdefinition
Kartendefinition

Die Bot Framework-Aktivitätsvorlage umfasst mehrere anpassbare Felder. Die unten gezeigten Eigenschaften werden am häufigsten verwendet und können über eine Aktivitätsvorlagendefinition konfiguriert werden:

Eigenschaft	Anwendungsfall
Text	Anzeigetext, der vom Kanal zum visuellen Rendern verwendet wird
Sprechen	Gesprochener Text, der vom Kanal zum Rendern der Sprachausgabe verwendet wird
Anlagen	Liste der Anlagen mit ihrem Typ. Wird von Kanälen zum Rendern als Benutzeroberflächenkarten oder andere generische Dateianlagentypen verwendet.
SuggestedActions	Liste der Aktionen, die für den Benutzer als Vorschläge gerendert werden.
InputHint	Steuert den Status des Audioerfassungsstreams auf Geräten, die gesprochene Eingaben unterstützen. Zu den möglichen Werten gehören `accepting`, `expecting` oder `ignoring`.

Es gibt kein Standardfallbackverhalten, das vom Vorlagenlöser implementiert wird. Wenn keine Eigenschaft angegeben ist, wird diese weiterhin nicht angegeben. Beispielsweise wird die Speak-Eigenschaft nicht automatisch als Text-Eigenschaft zugewiesen, wenn nur die Text-Eigenschaft angegeben wurde.

Definition

Dies ist die Definition einer strukturierten Vorlage:

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

Im Folgenden finden Sie ein Beispiel für eine einfache Textvorlage:

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

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

Im Folgenden finden Sie ein Beispiel für Text mit einer vorgeschlagenen Aktion: Verwenden Sie |, um eine Liste anzugeben.

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

Hier ist ein Beispiel für die Definition einer Hero-Karte:

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

Hinweis

LG bietet eine gewisse Variabilität bei der Kartendefinition, die in Übereinstimmung mit dem SDK Kartendefinition konvertiert wird. Beispielsweise werden sowohl image- als auch images-Felder in allen Kartendefinitionen in LG unterstützt, obwohl nur images in der SDK-Kartendefinition unterstützt werden.

Die in allen image– oder images-Feldern einer HeroCard oder Vorschauminiatur-Karte definierten Werte werden kombiniert und in eine Bildliste in der generierten Karte konvertiert. Für die anderen Typen von Karten wird dem image-Feld der zuletzt definierte Wert in der Vorlage zugewiesen. Die Werte, die Sie dem image/images-Feld zuweisen, können eine Zeichenfolge, ein adaptiver Ausdruck oder ein Array im Format | sein.

Im Folgenden finden Sie eine Kombination der vorherigen Vorlagen:

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

Standardmäßig wird jeder Vorlagenverweis während der Auswertung einer strukturierten Vorlage einmal ausgewertet.

Beispielsweise gibt # AskForAge.prompt den gleichen Auflösungstext sowohl für die Speak-Eigenschaft als auch für die Text-Eigenschaft zurück.

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

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

Sie können <TemplateName>!() verwenden, um für jeden Verweis innerhalb einer strukturierten Vorlage eine neue Auswertung anzufordern.

Im folgenden Beispiel verfügen Speak und Text möglicherweise über einen anderen Auflösungstext, da GetAge für jede Instanz erneut ausgewertet wird.

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

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

Hier sehen Sie, wie Sie ein Kartenkarussell anzeigen:

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

Verwenden Sie als Escapezeichen \.

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

Komposition strukturierter Vorlagen

Das folgende Kompositionsverhalten wird bei strukturierten Vorlagen unterstützt:

Bei der Komposition wird der Strukturkontext berücksichtigt. Wenn die referenzierte Zielvorlage auch eine strukturierte Vorlage ist, muss der Strukturtyp übereinstimmen. Beispielsweise kann in einer ActivityTemplate auf eine andere ActivityTemplate verwiesen werden.
Verweise auf einfache oder bedingte Antwortvorlagen können an beliebiger Stelle innerhalb einer strukturierten Vorlage angegeben werden.

Angenommen, Sie verwenden die folgende Vorlage:

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

# T2
- This is awesome

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

Ein Aufruf von evaluateTemplate('T1') würde zur folgenden internen Struktur führen:

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

Vollständiger Verweis auf eine andere strukturierte Vorlage

Sie können einen Verweis auf eine andere strukturierte Vorlage als Eigenschaft in einer anderen strukturierten Vorlage oder als Verweis in einer anderen Vorlage für einfache oder bedingte Antworten einschließen.

Hier ist ein Beispiel für einen vollständigen Verweis auf eine andere strukturierte Vorlage:

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

Mit diesem Inhalt führt ein Aufruf von evaluateTemplate('ST1') zur folgenden internen Struktur:

[MyStruct
    Text = foo
    Speak = bar
]

Wenn dieselbe Eigenschaft sowohl in der aufrufenden Vorlage als auch in der aufgerufenen Vorlage vorhanden ist, überschreibt der Inhalt des Aufrufers alle Inhalte in der aufgerufenen Vorlage.

Ein Beispiel:

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

Mit diesem Kontext führt ein Aufruf von evaluateTemplate('ST1') zur folgenden internen Struktur:

[MyStruct
    Text = foo
    Speak = bar
]

Beachten Sie, dass diese Art der Komposition nur auf der Root-Ebene möglich ist. Wenn ein Verweis auf eine andere strukturierte Vorlage innerhalb einer Eigenschaft enthalten ist, erfolgt die Auflösung dieser Eigenschaft kontextbezogen.

Verweis auf eine externe Datei in der Anlage (strukturiert)

Es gibt zwei vordefinierte Funktionen, die für externe referenzierte Dateien verwendet werden.

fromFile(fileAbsoluteOrRelativePath) lädt eine angegebene Datei. Von dieser Funktion zurückgegebene Inhalte unterstützen die Auswertung von Inhalten. Vorlagenverweise, Eigenschaften und Ausdrücke werden ausgewertet.
ActivityAttachment(content, contentType) legt den contentType fest, wenn dieser nicht bereits im Inhalt angegeben ist.

Mit diesen beiden vordefinierten Funktionen können Sie alle extern definierten Inhalte pullen, einschließlich aller Kartentypen. Verwenden Sie die folgende strukturierte Sprachgenerierung, um eine Aktivität zu erstellen:

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

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

Sie können auch Anlagen verwenden, wie unten aufgeführt:

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

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

Zusätzliche Informationen

C#-API-Referenz
JavaScript-API-Referenz
Lesen Sie Debuggen mit adaptiven Tools, um zu erfahren, wie Sie Vorlagen analysieren und debuggen.

Freigeben über