Dela via

.lg-filformat

  • Artikel

GÄLLER FÖR: SDK v4

.lg-filen beskriver språkgenereringsmallar med entitetsreferenser och deras sammansättning. Den här artikeln beskriver de olika begrepp som uttrycks med .lg-filformatet.

Specialtecken

Kommentarer

Använd > för att skapa en kommentar. Alla rader som har det här prefixet hoppas över av parsern.

> This is a comment.

Escape-tecken

Använd \ som escape-tecken.

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

Matriser och objekt

Skapa en matris

Om du vill skapa en matris använder du syntaxen ${[object1, object2, ...]} . Det här uttrycket kan till exempel vara:

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

Returnerar matrisen ['a', 'b', 'c'].

Skapa ett -objekt

Om du vill skapa ett objekt använder du syntaxen ${{key1:value1, key2:value2, ...}}} . Det här uttrycket kan till exempel vara:

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

Returnerar följande JSON-objekt:

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

Mallar

Mallar är huvudkonceptet för språkgenereringssystemet. Varje mall har ett namn och något av följande:

  • en lista över en varianttextvärden
  • en strukturerad innehållsdefinition
  • en samling villkor, var och en med:

Mallnamn

Mallnamn är skiftlägeskänsliga och kan bara innehålla bokstäver, understreck och siffror. Följande är ett exempel på en mall med namnet TemplateName.

# TemplateName

Mallar kan inte börja med ett tal, och en del av ett mallnamn som delas med . kan inte börja med ett tal.

Varianter av mallsvar

Variationer uttrycks som en Markdown-lista. Du kan prefixa varje variant med hjälp av -tecknet , eller+ .

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

# Template2
* text variation 1
* text variation 2

# Template3
+ one
+ two

Enkel svarsmall

En enkel svarsmall innehåller en eller flera varianter av text som används för komposition och expansion. En av de angivna varianterna väljs slumpmässigt av LG-biblioteket.

Här är ett exempel på en enkel mall som innehåller två varianter.

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

Mall för villkorsstyrd svar

Med mallar för villkorsstyrd respons kan du skapa innehåll som har valts baserat på ett villkor. Alla villkor uttrycks med hjälp av anpassningsbara uttryck.

Viktigt!

Villkorsmallar kan inte kapslas i en enda mall för villkorliga svar. Använd komposition i en strukturerad svarsmall för att kapsla villkor.

If-else-mall

Med mallen if-else kan du skapa en mall som väljer en samling baserat på en sammanhängande villkorsordning. Utvärderingen är uppifrån och ned och stoppas när ett villkor utvärderas till true eller om ELSE-blocket har träffats.

Villkorsuttryck omges av klammerparenteser ${}. Här är ett exempel som visar en enkel malldefinition för villkorsstyrd IF ELSE-svar.

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

Här är ett annat exempel som visar en mall för villkorsstyrd svarsmall för if-else. Observera att du kan inkludera referenser till andra enkla eller villkorsstyrda svarsmallar i varianten för något av villkoren.

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

Växla mall

Med switchmallen kan du utforma en mall som matchar ett uttrycks värde med en CASE-sats och som genererar utdata baserat på det fallet. Villkorsuttryck omges av klammerparenteser ${}.

Så här kan du ange standardblocket SWITCH CASE i LG.

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

Här är ett mer komplicerat standardexempel för SWITCH CASE:

> 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()}

Kommentar

Precis som villkorsstyrda mallar kan du inte kapsla om mallar.

Mall för strukturerade svar

Med strukturerade svarsmallar kan du definiera en komplex struktur som stöder viktiga LG-funktioner, till exempel templating, sammansättning och ersättning, samtidigt som tolkningen av det strukturerade svaret lämnas till anroparen av LG-biblioteket.

För robotprogram stöder vi internt:

  • aktivitetsdefinition
  • kortdefinition

Läs mer om mallar för struktursvar.

Mallsammansättning och expansion

Referenser till mallar

Varianttext kan innehålla referenser till en annan namngiven mall för att underlätta komposition och lösning av avancerade svar. Referenser till andra namngivna mallar anges med hjälp av klammerparenteser, till exempel ${<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

Att anropa mallen GreetingReply kan resultera i någon av följande expansionslösningar:

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

Entiteter

När de används direkt i en varianttext betecknas entitetsreferenser genom att de omges av klammerparenteser, till exempel ${entityName}, eller utan klammerparenteser när de används som en parameter.

Entiteter kan användas som en parameter:

Använda fördefinierade funktioner i varianter

Fördefinierade funktioner som stöds av adaptiva uttryck kan också användas infogade i en varianttext för att uppnå ännu kraftfullare textsammansättning. Om du vill använda ett uttryck infogat kan du helt enkelt omsluta det i klammerparenteser.

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

Exemplet ovan använder funktionen join prebuilt för att visa alla värden i recentTasks samlingen.

Angivna mallar och fördefinierade funktioner delar samma anropssignatur. Ett mallnamn kan inte vara samma som ett fördefiniert funktionsnamn.

Ett mallnamn får inte matcha ett fördefiniert funktionsnamn. Den fördefinierade funktionen har företräde. För att undvika sådana konflikter kan du förbereda lg. när du refererar till mallnamnet. Till exempel:

> 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')}

Flerradstext i varianter

Varje variant kan innehålla flerradstext som omges av tre citattecken.

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

Flerradsvariant kan begära mallexpansion och entitetsersättning genom att omsluta den begärda åtgärden i klammerparenteser, ${}.

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

Med stöd för flera rader kan du låta undersystemet Language Generation lösa en komplex JSON eller XML (till exempel SSML-omsluten text för att styra robotens talade svar).

Parametrisering av mallar

För att underlätta kontextuell återanvändning kan mallar parametriseras. Olika anropare till mallen kan skicka in olika värden för användning i expansionsmatchning.

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

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

# timeOfDayGreeting
- ${timeOfDayGreetingTemplate(timeOfDay)}

Importera externa referenser

Du kan dela upp dina språkgenereringsmallar i separata filer och referera till en mall från en fil i en annan. Du kan använda markdown-länkar för att importera mallar som definierats i en annan fil.

[Link description](filePathOrUri)

Alla mallar som definierats i målfilen hämtas. Kontrollera att mallnamnen är unika (eller namnrymdsbaserade med # \<namespace>.\<templatename>) mellan filer som hämtas.

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

Funktioner som matas in av LG

Anpassningsbara uttryck ger möjlighet att mata in en anpassad uppsättning funktioner. Läs funktioner som matas in från LG-biblioteket för mer information.

Alternativ

Utvecklare kan ange parseralternativ för att ytterligare anpassa hur indata utvärderas. Använd notationen > !# för att ange parseralternativ.

Viktigt!

Den senaste inställningen som hittades i filen överträffar alla tidigare inställningar som finns i samma dokument.

Strikt alternativ

Utvecklare som inte vill tillåta ett null-resultat för ett null-utvärderat resultat kan implementera det strikta alternativet. Nedan visas ett exempel på ett enkelt strikt alternativ:

> !# @strict = true
# template
- hi

Om det strikta alternativet är aktiverat genererar null-fel ett vänligt meddelande.

# welcome
- hi ${name}

Om namnet är null skulle diagnostiken vara "namn" som utvärderas till null. [välkommen] Ett fel uppstod vid utvärdering av "- hi ${name}". Om strikt är inställt på false eller inte anges ges ett kompatibelt resultat. Exemplet ovan skulle generera hi null.

replaceNull-alternativ

Utvecklare kan skapa ombud för att ersätta null-värden i utvärderade uttryck med hjälp av alternativet replaceNull :

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

I exemplet ovan skulle null-indata i variabeln path ersättas med ${path} är odefinierad. Följande indata, där user.name är null: :

hi ${user.name}

Skulle resultera i hi user.name är odefinierat.

lineBreakStyle-alternativ

Utvecklare kan ange alternativ för hur LG-systemet renderar radbrytningar med hjälp av lineBreakStyle-alternativet . Två lägen stöds för närvarande:

  • default: Radbrytningar i flerradstext skapar normala radbrytningar.
  • markdown: Radbrytningar i text med flera rader konverteras automatiskt till två rader för att skapa en ny rad

Exemplet nedan visar hur du anger alternativet lineBreakStyle till markdown:

> !# @lineBreakStyle = markdown

Namnområdesalternativ

Du kan registrera ett namnområde för de LG-mallar som du vill exportera. Om inget namnområde har angetts anges namnområdet till filnamnet utan ett tillägg.

Exemplet nedan visar hur du anger namnområdesalternativet till foo:

> !# @Namespace = foo

Exportalternativ

Du kan ange en lista över LG-mallar som ska exporteras. De exporterade mallarna kan anropas som fördefinierade funktioner.

Exemplet nedan visar hur du anger exportalternativet till template1, template2:

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

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

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

Använd foo.template1(1,2), foo.template2(['a', 'b', 'c'], ',') för att anropa dessa exporterade mallar.

Cacheomfång

Med alternativen för cacheomfång kan du styra när LG-utvärderaren omvärderar ett uttryck som det har sett före och när det lagrar och använder ett cachelagrat resultat.

  • Global cache är effektiv i livscykeln för en utvärdering. LG cachelagrar alla utvärderingsresultat, och om mallnamnet och parametrarna är desamma returnerar resultatet från cacheminnet.
  • Omfång för lokal cache är standard. Om den tidigare mallen har anropats med samma mallnamn och samma parametrar i samma lager returneras det cachelagrade resultatet direkt i samma lager.
  • Inget cacheomfång inaktiverar alla cacheomfång och returnerar varje gång det nya resultatet.

Exempel finns i exempel på globala och lokala cacheomfång.

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

Observera att alternativet cacheomfång är skiftlägeskänsligt.

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

Observera att cacheomfånget följer omfånget för Filen Microsoft Entrance .lg.

Anta att du har två filer: a.lg och b.lg, som visas nedan:

a.lg

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

b.lg

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

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

Om du kör följande kod ser du att template2 det cachelagrade resultatet av det första utvärderade resultatet används på grund av cacheomfångsalternativet global i a.lg:

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

Åter köra markpåverkan

Om mallnamnet slutar med "!", tvingar mallen omkörning. Det här resultatet läggs inte till i cacheminnet oavsett cacheomfånget.

Anta att du har följande mall:

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

template1!() utlöses och resultatet läggs till i cacheminnet. Den andra template1() klonar resultatet från den första template1(). Det sista anropet använder resultaten som lagras i cacheminnet.

Exempel på globalt cacheomfång

Anta att du har följande mallar:

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

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

# template3
- ${template2()}

template2 skulle utvärderas en gång, och den andra körningen i template3 skulle tillämpa cachen för den första.

Ett annat exempel finns i följande kodfragment:

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});

En mall parsas med hjälp av Templates.ParseFile() funktionen och mallutvärderingsresultaten lagras i result1. Observera att det andra utvärderingsresultatet, result2, släpper alla resultat som tidigare cachelagrats.

Exempel på omfång för lokal cache

Följande exempel visar när det lokala cacheomfånget fungerar och inte fungerar. Anta att t() och subT() är mallar som tar en parameter:

>  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)}

Ytterligare resurser