Freigeben über

LG-Dateiformat

  • Artikel

GILT FÜR: SDK v4

In der LG-Datei werden Vorlagen für die Sprachgenerierung mit Entitätsverweisen und deren Komposition beschrieben. In diesem Artikel werden die verschiedenen Konzepte behandelt, die mit dem LG-Dateiformat ausgedrückt werden.

Sonderzeichen

Kommentare

Verwenden Sie >, um einen Kommentar zu erstellen. Alle Zeilen mit diesem Präfix werden vom Parser übersprungen.

> This is a comment.

Escapezeichen

Verwenden Sie als Escapezeichen \.

# TemplateName
- You can say cheese and tomato \[toppings are optional\]

Arrays und Objekte

Erstellen eines Arrays

Verwenden Sie zum Erstellen eines Arrays die Syntax ${[object1, object2, ...]} . Dieser Ausdruck, zum Beispiel:

${['a', 'b', 'c']}

Gibt das Array ['a', 'b', 'c'] zurück.

Erstellen eines -Objekts

Verwenden Sie zum Erstellen eines Objekts die Syntax ${{key1:value1, key2:value2, ...}} . Dieser Ausdruck, zum Beispiel:

${{user: {name: "Wilson", age: 27}}}

Gibt folgendes JSON-Objekt zurück:

{
  "user": {
    "name": "Wilson",
    "age": 27
  }
}

Vorlagen

Vorlagen sind das Kernkonzept des Systems zur Sprachgenerierung. Jede Vorlage verfügt über einen Namen und eine der folgenden Komponenten:

  • eine Liste von Textwerten mit 1-von-Variationen
  • eine Definition für strukturierte Inhalte
  • eine Sammlung von Bedingungen, jeweils mit:

Vorlagennamen

Bei Vorlagennamen wird die Groß-/Kleinschreibung beachtet und darf nur Buchstaben, Unterstriche und Zahlen enthalten. Es folgt ein Beispiel für eine ManifestVorlagendatei namens TemplateName.

# TemplateName

Vorlagen können nicht mit einer Zahl beginnen und ein Teil eines Vorlagennamens, der durch geteilt wird, kann nicht mit einer Zahl beginnen.

Vorlagen-Antwortvariationen

Variationen werden als Markdown-Liste ausgedrückt. Sie können jeder Variation mithilfe der Zeichen -, ' oder + ein Präfix voranstellen.

# Template1
- text variation 1
- text variation 2
- one
- two

# Template2
* text variation 1
* text variation 2

# Template3
+ one
+ two

Vorlage für eine einfache Antwort

Eine Vorlage für eine einfache Antwort enthält Textvariationen, die für Komposition und Erweiterung verwendet werden. Eine der bereitgestellten Variationen wird von der LG-Bibliothek nach dem Zufallsprinzip ausgewählt.

Im Folgenden finden Sie ein Beispiel für eine einfache Vorlage, die zwei Variationen enthält.

> Greeting template with two variations.
# GreetingPrefix
- Hi
- Hello

Vorlage für eine bedingte Antwort

Mithilfe von Vorlagen für bedingte Antworten können Sie Inhalte erstellen, die basierend auf einer Bedingung ausgewählt werden. Alle Bedingungen werden mithilfe von adaptiven Ausdrücken ausgedrückt.

Wichtig

Bedingte Vorlagen können nicht in einer einzelnen Vorlage für eine bedingte Antwort geschachtelt werden. Verwenden Sie die Komposition in einer Vorlage für eine strukturierte Antwort, um bedingte Vorlagen zu schachteln.

IF-ELSE-Vorlage

Mit einer IF-ELSE-Vorlage können Sie eine Vorlage erstellen, die eine Sammlung basierend auf einer kaskadierenden Reihenfolge von Bedingungen auswählt. Die Auswertung erfolgt von oben nach unten und wird beendet, wenn eine Bedingung als true ausgewertet oder der ELSE-Block erreicht wird.

Bedingte Ausdrücke werden in geschweifte Klammern ${} eingeschlossen. Im Folgenden finden Sie ein Beispiel, das eine Definition für eine einfache IF-ELSE-Vorlage für bedingte Antworten zeigt.

> time of day greeting reply template with conditions.
# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
    - good morning
- ELSE:
    - good evening

Im Folgenden finden Sie ein weiteres Beispiel, das die Definition einer IF-ELSE-Vorlage für bedingte Antworten zeigt. Beachten Sie, dass Sie Verweise auf andere Vorlagen für einfache oder bedingte Antworten in der Variation für eine der Bedingungen einschließen können.

# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
    - ${morningTemplate()}
- ELSEIF: ${timeOfDay == 'afternoon'}
    - ${afternoonTemplate()}
- ELSE:
    - I love the evenings! Just saying. ${eveningTemplate()}

SWITCH-Vorlage

Mithilfe der SWITCH-Vorlage können Sie eine Vorlage entwerfen, die den Wert eines Ausdrucks mit einer CASE-Klausel vergleicht und die Ausgabe auf der Grundlage dieser Klausel erzeugt. Bedingte Ausdrücke werden in geschweifte Klammern ${} eingeschlossen.

Im Folgenden wird erläutert, wie Sie in LG einen SWITCH-CASE-DEFAULT-Block angeben können.

# TestTemplate
- SWITCH: ${condition}
- CASE: ${case-expression-1}
    - output1
- CASE: ${case-expression-2}
    - output2
- DEFAULT:
   - final output

Im Folgenden finden Sie ein komplexeres Beispiel für SWITCH-CASE-DEFAULT:

> Note: Any of the cases can include reference to one or more templates.
# greetInAWeek
- SWITCH: ${dayOfWeek(utcNow())}
- CASE: ${0}
    - Happy Sunday!
-CASE: ${6}
    - Happy Saturday!
-DEFAULT:
    - ${apology-phrase()}, ${defaultResponseTemplate()}

Hinweis

Wie bedingte Vorlagen können auch Switch-Vorlagen nicht geschachtelt werden.

Vorlage für eine strukturierte Antwort

Mit Vorlagen für strukturierte Antworten können Sie eine komplexe Struktur definieren, die die LG-Hauptfunktionalität unterstützt (z. B. Vorlagen, Komposition und Ersetzung), und gleichzeitig die Interpretation der strukturierten Antwort beim Aufrufer der LG-Bibliothek belassen.

Für Botanwendungen wird Folgendes nativ unterstützt:

  • Aktivitätsdefinition
  • Kartendefinition

Weitere Informationen finden Sie unter Vorlage für eine strukturierte Antwort.

Vorlagenkomposition und -erweiterung

Verweise auf Vorlagen

Der Variantentext kann Verweise auf andere benannte Vorlagen enthalten, um die Komposition und Auflösung von komplexen Antworten zu unterstützen. Verweise auf andere benannte Vorlagen werden mit geschweiften Klammern gekennzeichnet, z. B. ${<TemplateName>()}

> Example of a template that includes composition reference to another template.
# GreetingReply
- ${GreetingPrefix()}, ${timeOfDayGreeting()}

# GreetingPrefix
- Hi
- Hello

# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
    - good morning
- ELSEIF: ${timeOfDay == 'afternoon'}
    - good afternoon
- ELSE:
    - good evening

Ein Aufruf der Vorlage GreetingReply kann zu einer der folgenden Erweiterungsauflösungen führen:

Hi, good morning
Hi, good afternoon
Hi, good evening
Hello, good morning
Hello, good afternoon
Hello, good evening

Entitäten

Wenn sie direkt innerhalb eines 1-von-Variationstexts verwendet werden, werden Entitätsverweise durch Einschließen in geschweifte Klammern (z. B. „${entityName}“) gekennzeichnet. Die geschweiften Klammern können weggelassen werden, wenn sie als Parameter verwendet werden.

Entitäten können als Parameter verwendet werden:

Verwenden von vordefinierten Funktionen in Variationen

Vordefinierte Funktionen, die von adaptiven Ausdrücken unterstützt werden, können auch inline in einem 1-von-Variationstext verwendet werden, um eine noch leistungsfähigere Textkomposition zu erzielen. Um einen Ausdruck inline zu verwenden, schließen Sie ihn einfach in geschweifte Klammern ein.

# RecentTasks
- IF: ${count(recentTasks) == 1}
    - Your most recent task is ${recentTasks[0]}. You can let me know if you want to add or complete a task.
- ELSEIF: ${count(recentTasks) == 2}
    - Your most recent tasks are ${join(recentTasks, ', ', ' and ')}. You can let me know if you want to add or complete a task.
- ELSEIF: ${count(recentTasks) > 2}
    - Your most recent ${count(recentTasks)} tasks are ${join(recentTasks, ', ', ' and ')}. You can let me know if you want to add or complete a task.
- ELSE:
    - You don't have any tasks.

Im obigen Beispiel wird die vordefinierte Funktion join verwendet, um alle Werte in der Sammlung recentTasks aufzulisten.

Da bestimmte Vorlagen und vordefinierte Funktionen dieselbe Aufrufsignatur verwenden, darf der Vorlagenname nicht mit dem Namen einer vordefinierten Funktion identisch sein.

Ein Vorlagenname sollte nicht mit dem Namen einer vordefinierten Funktion identisch sein. Die vordefinierte Funktion hat in diesem Fall Vorrang. Um solche Konflikte zu vermeiden, können Sie bei einem Verweis auf Ihren Vorlagennamen die Zeichenfolge lg. voranstellen. Beispiel:

> Custom length function with one parameter.
# length(a)
- This is use's customized length function

# myfunc1
> will call prebuilt function length, and return 2
- ${length('hi')}

# mufunc2
> this calls the lg template and output 'This is use's customized length function'
- ${lg.length('hi')}

Mehrzeiliger Text in Variationen

Jede 1-von-Variation kann mehrzeiligen Text enthalten, der in dreifache Anführungszeichen eingeschlossen ist.

# MultiLineExample
    - ```This is a multiline list
        - one
        - two
        ```
    - ```This is a multiline variation
        - three
        - four
    ```

In mehrzeiligen Variationen können Vorlagenerweiterungen und Entitätsersetzungen angefordert werden, indem der angeforderte Vorgang in geschweifte Klammern (${}) eingeschlossen wird.

# MultiLineExample
    - ```
        Here is what I have for the order
        - Title: ${reservation.title}
        - Location: ${reservation.location}
        - Date/ time: ${reservation.dateTimeReadBack}
    ```

Durch die Unterstützung von mehrzeiligem Text können Sie komplexen JSON- oder XML-Code (z. B. in SSML umschlossenen Text zum Steuern der gesprochenen Antwort des Bots) vollständig im Subsystem zur Sprachgenerierung auflösen.

Parametrisierung von Vorlagen

Um die kontextbezogene Wiederverwendbarkeit zu unterstützen, können Vorlagen parametrisiert werden. Verschiedene Aufrufer der Vorlage können unterschiedliche Werte zur Verwendung bei der Erweiterungsauflösung übergeben.

# timeOfDayGreetingTemplate (param1)
- IF: ${param1 == 'morning'}
    - good morning
- ELSEIF: ${param1 == 'afternoon'}
    - good afternoon
- ELSE:
    - good evening

# morningGreeting
- ${timeOfDayGreetingTemplate('morning')}

# timeOfDayGreeting
- ${timeOfDayGreetingTemplate(timeOfDay)}

Importieren externer Verweise

Sie können Ihre Vorlagen zur Sprachgenerierung in separate Dateien aufteilen und dann in einer Datei auf eine Vorlage in einer anderen Datei verweisen. Sie können Links im Markdown-Stil verwenden, um Vorlagen zu importieren, die in einer anderen Datei definiert sind.

[Link description](filePathOrUri)

Es werden alle Vorlagen gepullt, die in der Zieldatei definiert sind. Stellen Sie sicher, dass die Vorlagennamen für alle gepullten Dateien eindeutig sind (oder mit # \<namespace>.\<templatename> einem Namespace zugeordnet sind).

[Shared](../shared/common.lg)

Von LG eingefügte Funktionen

Adaptive Ausdrücke bieten Ihnen die Möglichkeit, einen benutzerdefinierten Satz von Funktionen einzufügen. Weitere Informationen finden Sie unter Von der LG-Bibliothek eingefügte Funktionen.

Optionen

Entwickler können Parseroptionen festlegen, um die Auswertung von Eingaben anzupassen. Verwenden Sie die Notation > !#, um Parseroptionen festzulegen.

Wichtig

Die letzte in der Datei gefundene Einstellung hat Priorität gegenüber vorherigen Einstellungen im selben Dokument.

strict-Option

Entwickler, die kein Null-Ergebnis für ein mit Null ausgewertetes Ergebnis zulassen möchten, können die Option strikt implementieren. Nachstehend sehen Sie ein Beispiel für eine einfache strict-Option:

> !# @strict = true
# template
- hi

Wenn die strict-Option aktiviert ist, lösen NULL-Fehler eine benutzerfreundliche Meldung aus.

# welcome
- hi ${name}

Wenn „name“ den Wert NULL hat, lautet die Diagnose: 'name' als NULL ausgewertet. [welcome] Fehler beim Auswerten von '- hi ${name}'.. Wenn strict auf FALSE oder gar nicht festgelegt ist, wird ein kompatibles Ergebnis ausgegeben. Im obigen Beispiel wird hi null erzeugt.

replaceNull-Option

Entwickler können Stellvertreter zum Ersetzen von Null-Werten in ausgewerteten Ausdrücken erstellen. Dazu verwenden sie die Option replaceNull:

> !# @replaceNull = ${path} is undefined

Im obigen Beispiel wird die NULL-Eingabe in der Variable path durch ${path} is undefined ersetzt. Sehen Sie sich auch die folgende Eingabe an, bei der user.name den Wert NULL hat:

hi ${user.name}

Da Ergebnis lautet in diesem Fall hi user.name is undefined.

lineBreakStyle option

Entwickler können mithilfe der Option lineBreakStyle festlegen, wie das LG-System Zeilenumbrüche rendert. Derzeit werden zwei Modi unterstützt:

  • default: Zeilenumbrüche in mehrzeiligem Text erzeugen normale Zeilenumbrüche.
  • markdown: Zeilenumbrüche in mehrzeiligem Text werden automatisch in zwei Zeilen konvertiert, um einen Zeilenumbruch zu erzeugen.

Im folgenden Beispiel wird gezeigt, wie die Option lineBreakStyle auf markdown festgelegt wird:

> !# @lineBreakStyle = markdown

Namespace (Option)

Sie können einen Namespace für die LG-Vorlagen registrieren, die Sie exportieren möchten. Wenn kein Namespace angegeben ist, wird der Namespace ohne Erweiterung auf den Dateinamen festgelegt.

Im folgenden Beispiel wird gezeigt, wie die Namespace-Option auf foo festgelegt wird:

> !# @Namespace = foo

Exports (Option)

Sie können eine Liste der zu exportierenden LG-Vorlagen angeben. Die exportierten Vorlagen können wie vorgefertigte Funktionen aufgerufen werden.

Im folgenden Beispiel wird gezeigt, wie die Exportoption auf template1, template2 festgelegt wird:

> !# @Namespace = foo
> !# @Exports = template1, template2

# template1(a, b)
- ${a + b}

# template2(a, b)
- ${join(a, b)}

Verwenden Sie foo.template1(1,2), foo.template2(['a', 'b', 'c'], ','), um diese exportierten Vorlagen aufzurufen.

Cache-Bereich

Mit den Cache-Bereichs-Optionen können Sie steuern, wann der LG-Evaluator einen Zuvor gesehenen Ausdruck neu bewertet und ein zwischengespeichertes Ergebnis speichert und verwendet.

  • Der globale Cache ist im Lebenszyklus einer Auswertung wirksam. LG speichert alle Auswertungsergebnisse zwischen und wenn der Vorlagenname und die Parameter identisch sind, wird das Ergebnis aus dem Cache zurückgegeben.
  • Der lokale Cachebereich ist die Standardeinstellung. Wenn in derselben Ebene die vorherige Vorlage mit demselben Vorlagennamen und denselben Parametern aufgerufen wurde, wird das zwischengespeicherte Ergebnis direkt zurückgegeben.
  • Der Bereich ohne Cache deaktiviert den gesamten Cachebereich und gibt jedes Mal das neue Ergebnis zurück.

Beispiele finden Sie in den Beispielen für den globalen und lokalen Cachebereich.

> !# @cacheScope= global // global cache
> !# @cacheScope= local // local cache
> !# @cacheScope= none // none cache
> !# @cacheScope= xxx // fallback to local cache

Beachten Sie, dass bei der Cachebereichs-Option die Groß-/Kleinschreibung nicht beachtet wird.

> !# @cacheScope= global // ok
> !# @CACHESCOPE= global // ok
> !# @cachescope= global // ok

Beachten Sie, dass der Cachebereich dem Bereich der LG-Datei von Microsoft Entrance folgt.

Angenommen, Sie haben zwei Dateien: a.lg und b.lg, unten dargestellt:

a.lg

> !# @cacheScope= global
 [import](b.lg)

b.lg

> !# @cacheScope= none
# template1
- ${template2()} ${template2()}

# template2
- ${rand(1, 10000000)}

Wenn Sie den folgenden Code ausführen, werden Sie feststellen, dass template2 das zwischengespeicherte Ergebnis des ersten ausgewerteten Ergebnisses aufgrund der global Cachebereichsoption in a.lg verwendet wird:

var templates = Templates.ParseFile("a.lg");
var result = templates.Evaluate("template1"); // the second "template2" would use the cache of the first evaluate result

Einfluss der erneuten Ausführung von Markierungen

Wenn der Vorlagenname mit "!" endet, erzwingt die Vorlage die erneute Ausführung. Dieses Ergebnis wird unabhängig vom Cachebereich nicht dem Cache hinzugefügt.

Angenommen, Sie haben folgende Vorlage:

# template2
- ${template1()} ${template1!()} ${template1()}

template1!() wird ausgelöst, und das Ergebnis wird dem Cache hinzugefügt. Der zweite template1() Klobber das Ergebnis aus dem ersten template1(). Der letzte Aufruf verwendet die im Cache gespeicherten Ergebnisse.

Beispiel für den globalen Cachebereich

Angenommen, Sie verwenden die folgenden Vorlagen:

# template1
- ${template2()} ${template3()}

# template2
- ${rand(1, 10)}
- abc
- hi

# template3
- ${template2()}

template2 wird einmal ausgewertet, und die zweite Ausführung in template3 würde den Cache des ersten anwenden.

Der folgende Codeausschnitt ist ein Beispiel.

var templates = Templates.ParseFile("xxx.lg");
var result1 = templates.Evaluate("template", null, new EvaluationOptions { CacheScope = LGCacheScope.Global});

// The second evaluation would drop all the results cached before.
var result2 = templates.Evaluate("template", null, new EvaluationOptions { CacheScope = LGCacheScope.Global});

Eine Vorlage wird mithilfe der Templates.ParseFile() Funktion analysiert, und die Ergebnisse der Vorlagenauswertung werden in result1gespeichert. Beachten Sie, dass die zweiten Auswertungsergebnisse, result2, alle zuvor zwischengespeicherten Ergebnisse fallen lassen.

Beispiel für den lokalen Cache-Bereich

Die folgenden Beispiele zeigen, wann der lokale Cache-Bereich funktioniert und nicht funktioniert. Gehen Sie davon aus, dass t() vorlagen subT() einen Parameter annehmen:

>  Cache works, the second template call would re-use the first's result.
# template1
- ${t(param)} ${t(param)}

> Cache doesn't work because param1's value is different with param2's. value)
# template2
- ${t(param1)} ${t(param2)}

> Cache doesn't work because of different layers.
# template3
- ${subT(param1)} ${t(param2)}

# subT(param)
- ${t(param)}

Weitere Ressourcen