Delen via

.lg-bestandsindeling

  • Artikel

VAN TOEPASSING OP: SDK v4

Het LG-bestand beschrijft taalgeneratiesjablonen met entiteitsverwijzingen en hun samenstelling. In dit artikel worden de verschillende concepten beschreven die worden uitgedrukt met de .lg-bestandsindeling.

Speciale tekens

Opmerkingen

Gebruik > dit om een opmerking te maken. Alle regels met dit voorvoegsel worden overgeslagen door de parser.

> This is a comment.

Escape-teken

Als \ escape-teken gebruiken.

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

Matrices en objecten

Een matrix maken

Als u een matrix wilt maken, gebruikt u de syntaxis ${[object1, object2, ...]} . Bijvoorbeeld deze expressie:

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

Geeft als resultaat de matrix ['a', 'b', 'c'].

Maak een -object

Gebruik de syntaxis ${{key1:value1, key2:value2, ...}} om een object te maken. Bijvoorbeeld deze expressie:

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

Retourneert het volgende JSON-object:

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

Sjablonen

Sjablonen vormen het kernconcept van het systeem voor het genereren van talen. Elke sjabloon heeft een naam en een van de volgende:

  • een lijst met een-van-variatietekstwaarden
  • een definitie van gestructureerde inhoud
  • een verzameling voorwaarden, elk met:

Sjabloonnamen

Sjabloonnamen zijn hoofdlettergevoelig en kunnen alleen letters, onderstrepingstekens en cijfers bevatten. Hier volgt een voorbeeld van een sjabloon met de naam TemplateName.

# TemplateName

Sjablonen kunnen niet beginnen met een getal en een deel van een sjabloonnaam die is gesplitst door . kan niet beginnen met een getal.

Variaties van sjabloonreacties

Variaties worden uitgedrukt als een Markdown-lijst. U kunt elke variatie vooraf laten gaan met behulp van de -, ', of + het teken.

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

# Template2
* text variation 1
* text variation 2

# Template3
+ one
+ two

Eenvoudige antwoordsjabloon

Een eenvoudige antwoordsjabloon bevat een of meer variaties van tekst die worden gebruikt voor samenstelling en uitbreiding. Een van de beschikbare variaties wordt willekeurig geselecteerd door de LG-bibliotheek.

Hier volgt een voorbeeld van een eenvoudige sjabloon met twee variaties.

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

Sjabloon voor voorwaardelijk antwoord

Met sjablonen voor voorwaardelijke antwoorden kunt u inhoud ontwerpen die is geselecteerd op basis van een voorwaarde. Alle voorwaarden worden uitgedrukt met behulp van adaptieve expressies.

Belangrijk

Voorwaardelijke sjablonen kunnen niet worden genest in één sjabloon voor voorwaardelijke antwoorden. Gebruik samenstelling in een gestructureerde antwoordsjabloon om voorwaardelijke voorwaarden te nesten.

If-else-sjabloon

Met de if-else-sjabloon kunt u een sjabloon maken waarmee een verzameling wordt gekozen op basis van een trapsgewijze volgorde van voorwaarden. De evaluatie is van boven naar beneden en stopt wanneer een voorwaarde wordt geëvalueerd true of het ELSE-blok wordt bereikt.

Voorwaardelijke expressies worden tussen accolades ${}. Hier volgt een voorbeeld met een eenvoudige sjabloondefinitie voor voorwaardelijke antwoorden als ELSE.

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

Hier volgt een ander voorbeeld met een definitie van een if-else-sjabloon voor voorwaardelijke antwoorden. Houd er rekening mee dat u verwijzingen naar andere sjablonen voor eenvoudige of voorwaardelijke antwoorden kunt opnemen in de variatie voor een van de voorwaarden.

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

Schakelen tussen sjablonen

Met de switchsjabloon kunt u een sjabloon ontwerpen die overeenkomt met de waarde van een expressie in een CASE-component en uitvoer produceert op basis van dat geval. Voorwaardeexpressies staan tussen accolades ${}.

U kunt als volgt een SWITCH CASE DEFAULT-blok opgeven in LG.

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

Hier volgt een ingewikkelder VOORBEELD VAN 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()}

Notitie

Net als bij voorwaardelijke sjablonen kunnen switchsjablonen niet worden genest.

Sjabloon voor gestructureerd antwoord

Met gestructureerde antwoordsjablonen kunt u een complexe structuur definiëren die ondersteuning biedt voor belangrijke LG-functionaliteit, zoals sjablonen, samenstelling en vervanging, terwijl u de interpretatie van de gestructureerde reactie aan de beller van de LG-bibliotheek overlaat.

Voor bottoepassingen bieden we systeemeigen ondersteuning voor:

  • activiteitsdefinitie
  • kaartdefinitie

Lees meer over sjablonen voor structuurreacties voor meer informatie.

Sjabloonsamenstelling en -uitbreiding

Verwijzingen naar sjablonen

Variatietekst kan verwijzingen naar een andere benoemde sjabloon bevatten om te helpen bij de samenstelling en oplossing van geavanceerde antwoorden. Verwijzingen naar andere benoemde sjablonen worden aangeduid met accolades, zoals ${<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

Het aanroepen van de GreetingReply sjabloon kan resulteren in een van de volgende uitbreidingsresoluties:

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

Entiteiten

Wanneer deze rechtstreeks in een variatietekst worden gebruikt, worden entiteitsverwijzingen aangeduid door ze tussen accolades, zoals ${entityName}, of zonder accolades te plaatsen wanneer ze worden gebruikt als parameter.

Entiteiten kunnen worden gebruikt als parameter:

Vooraf gemaakte functies gebruiken in variaties

Vooraf gebouwde functies die worden ondersteund door adaptieve expressies , kunnen ook inline worden gebruikt in een variatietekst om nog krachtigere tekstsamenstelling te bereiken. Als u een expressie inline wilt gebruiken, verpakt u deze in accolades.

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

In het bovenstaande voorbeeld wordt de vooraf samengestelde joinfunctie gebruikt om alle waarden in de recentTasks verzameling weer te geven.

Opgegeven sjablonen en vooraf gedefinieerde functies delen dezelfde aanroephandtekening, een sjabloonnaam kan niet hetzelfde zijn als een vooraf gedefinieerde functienaam.

Een sjabloonnaam mag niet overeenkomen met een vooraf gedefinieerde functienaam. De vooraf gemaakte functie heeft voorrang. Als u dergelijke conflicten wilt voorkomen, kunt u vooraf gaan lg. wanneer u verwijst naar de naam van uw sjabloon. Bijvoorbeeld:

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

Tekst met meerdere regels in variaties

Elke variatie kan bestaan uit tekst met meerdere regels tussen drie aanhalingstekens.

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

Met meerdere regels kunt u sjabloonuitbreiding en entiteitsvervanging aanvragen door de aangevraagde bewerking tussen accolades, ${}te plaatsen.

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

Met ondersteuning voor meerdere regels kunt u het subsysteem Language Generation volledig laten omzetten in een complexe JSON of XML (zoals SSML-tekst met terugloop om het gesproken antwoord van de bot te beheren).

Parametrisatie van sjablonen

Sjablonen kunnen worden geparametriseerd om te helpen bij contextuele herbruikbaarheid. Verschillende bellers aan de sjabloon kunnen verschillende waarden doorgeven voor gebruik in uitbreidingsresolutie.

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

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

# timeOfDayGreeting
- ${timeOfDayGreetingTemplate(timeOfDay)}

Externe verwijzingen importeren

U kunt uw taalgeneratiesjablonen splitsen in afzonderlijke bestanden en verwijzen naar een sjabloon uit het ene bestand in het andere. U kunt markdown-koppelingen gebruiken om sjablonen te importeren die zijn gedefinieerd in een ander bestand.

[Link description](filePathOrUri)

Alle sjablonen die in het doelbestand zijn gedefinieerd, worden opgehaald. Zorg ervoor dat uw sjabloonnamen uniek zijn (of naamruimte met # \<namespace>.\<templatename>) voor bestanden die worden opgehaald.

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

Functies geïnjecteerd door LG

Adaptieve expressies bieden de mogelijkheid om een aangepaste set functies in te voeren. Lees functies die zijn geïnjecteerd uit de LG-bibliotheek voor meer informatie.

Opties

Ontwikkelaars kunnen parseropties instellen om verder aan te passen hoe invoer wordt geëvalueerd. Gebruik de > !# notatie om opties voor parser in te stellen.

Belangrijk

De laatste instelling in het bestand treft alle eerdere instellingen die in hetzelfde document zijn gevonden.

Strikte optie

Ontwikkelaars die geen null-resultaat voor een geëvalueerd resultaat met null willen toestaan, kunnen de strikte optie implementeren. Hieronder ziet u een voorbeeld van een eenvoudige strikte optie:

> !# @strict = true
# template
- hi

Als de strikte optie is ingeschakeld, genereren null-fouten een vriendelijk bericht.

# welcome
- hi ${name}

Als de naam null is, wordt de diagnostische waarde 'naam' geëvalueerd op null. [welkom] Er is een fout opgetreden bij het evalueren van '- hi ${name}'. Als strikt is ingesteld op onwaar of niet ingesteld, wordt er een compatibel resultaat gegeven. In het bovenstaande voorbeeld zou hi null worden geproduceerd.

optie replaceNull

Ontwikkelaars kunnen gemachtigden maken om null-waarden te vervangen in geëvalueerde expressies met behulp van de optie replaceNull :

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

In het bovenstaande voorbeeld wordt de null-invoer in de path variabele vervangen door ${path} niet gedefinieerd. De volgende invoer, waarbij user.name null is:

hi ${user.name}

Zou resulteren in hi user.name niet gedefinieerd is.

optie lineBreakStyle

Ontwikkelaars kunnen opties instellen voor hoe het LG-systeem regeleinden weergeeft met behulp van de optie lineBreakStyle . Er worden momenteel twee modi ondersteund:

  • default: regeleinden in tekst met meerdere regels maken normale regeleinden.
  • markdown: regeleinden in tekst met meerdere regels worden automatisch geconverteerd naar twee regels om een nieuwe regel te maken

In het onderstaande voorbeeld ziet u hoe u de optie lineBreakStyle instelt op markdown:

> !# @lineBreakStyle = markdown

Optie Naamruimte

U kunt een naamruimte registreren voor de LG-sjablonen die u wilt exporteren. Als er geen naamruimte is opgegeven, wordt de naamruimte ingesteld op de bestandsnaam zonder extensie.

In het onderstaande voorbeeld ziet u hoe u de optie voor de naamruimte instelt op foo:

> !# @Namespace = foo

Optie Exporteren

U kunt een lijst met LG-sjablonen opgeven die u wilt exporteren. De geëxporteerde sjablonen kunnen worden aangeroepen als vooraf gedefinieerde functies.

In het onderstaande voorbeeld ziet u hoe u de exportoptie instelt op template1, template2:

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

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

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

Gebruik foo.template1(1,2), foo.template2(['a', 'b', 'c'], ',') dit om deze geëxporteerde sjablonen aan te roepen.

Cachebereik

Met de cachebereikopties kunt u bepalen wanneer de LG-evaluator een expressie die eerder is gezien opnieuw evalueert en wanneer deze een resultaat in de cache opslaat en gebruikt.

  • Globale cache is effectief in de levenscyclus van een evaluatie. LG slaat alle evaluatieresultaten in de cache op en als de sjabloonnaam en parameters hetzelfde zijn, retourneert het resultaat uit de cache.
  • Lokaal cachebereik is de standaardinstelling. Als in dezelfde laag de vorige sjabloon is aangeroepen met dezelfde sjabloonnaam en dezelfde parameters, wordt het resultaat in de cache rechtstreeks geretourneerd.
  • Geen cachebereik schakelt alle cachebereiken uit en elke keer wordt het nieuwe resultaat geretourneerd.

Zie de voorbeelden van globale en lokale cachebereiken voor voorbeelden.

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

Houd er rekening mee dat de cachebereikoptie niet hoofdlettergevoelig is.

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

Houd er rekening mee dat het cachebereik het bereik van het .lg-bestand van Microsoft Entrance volgt.

Stel dat u twee bestanden hebt: a.lg en b.lg, hieronder weergegeven:

a.lg

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

b.lg

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

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

Als u de volgende code uitvoert, ziet u dat template2 het in de cache opgeslagen resultaat van het eerste geëvalueerde resultaat wordt gebruikt vanwege de global cachebereikoptie in 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

Invloed van markering opnieuw uitvoeren

Als de naam van de sjabloon eindigt op '!', wordt de uitvoering van de sjabloon afgevraagd. Dit resultaat wordt niet toegevoegd aan de cache, ongeacht het cachebereik.

Stel dat u de volgende sjabloon hebt:

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

template1!() wordt geactiveerd en het resultaat wordt toegevoegd aan de cache. De tweede template1() clobbers het resultaat van de eerste template1(). De laatste aanroep maakt gebruik van de resultaten die zijn opgeslagen in de cache.

Voorbeeld van een globaal cachebereik

Stel dat u de volgende sjablonen hebt:

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

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

# template3
- ${template2()}

template2 zou eenmaal worden geëvalueerd en de tweede uitvoering zou template3 de cache van de eerste toepassen.

Een ander voorbeeld is in het volgende codefragment:

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

Een sjabloon wordt geparseerd met behulp van de Templates.ParseFile() functie en de resultaten van de sjabloonevaluatie worden opgeslagen in result1. Houd er rekening mee dat de tweede evaluatieresultaten, result2alle resultaten die eerder in de cache waren opgeslagen, worden weggezakt.

Voorbeeld van lokaal cachebereik

In de volgende voorbeelden ziet u wanneer het lokale cachebereik wel en niet werkt. Stel dat t() en subT() sjablonen zijn die een parameter gebruiken:

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

Aanvullende resources