.lg fájlformátum

Cikk
10/24/2023

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Az .lg fájl az entitáshivatkozásokat és azok összetételét tartalmazó nyelvi létrehozási sablonokat ismerteti. Ez a cikk az .lg fájlformátummal kifejezett különböző fogalmakat ismerteti.

Speciális karakterek

Megjegyzések

Megjegyzés létrehozásához használható > . Az elemző kihagyja az előtaggal rendelkező összes sort.

> This is a comment.

Escape karakter

Használjon \ menekülési karakterként.

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

Tömbök és objektumok

Tömb létrehozása

Tömb létrehozásához használja a ${[object1, object2, ...]} szintaxist. Ez a kifejezés például a következő:

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

A tömböt ['a', 'b', 'c']adja vissza.

Egy -objektum létrehozása

Objektum létrehozásához használja a ${{key1:value1, key2:value2, ...}} szintaxist. Ez a kifejezés például a következő:

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

A következő JSON-objektumot adja vissza:

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

Templates

A sablonok a nyelvi létrehozási rendszer alapfogalmát képezik. Minden sablonnak van egy neve, és az alábbiak egyike:

egy változat szöveges értékeinek listája
strukturált tartalomdefiníció
feltételek gyűjteménye, amelyek mindegyike a következőkkel rendelkezik:
- adaptív kifejezés
- egy változat szöveges értékeinek listája feltételenként

Sablonnevek

A sablonnevek megkülönböztetik a kis- és nagybetűket, és csak betűket, aláhúzásjeleket és számokat tartalmazhatnak. Az alábbiakban egy példa látható egy sablonra TemplateName.

# TemplateName

A sablonok nem kezdődhetnek számmal, és a sablonnevek . szerinti felosztása nem kezdődhet számmal.

Sablonválasz-változatok

A változatok Markdown-listaként vannak kifejezve. Az egyes változatokat előtagként a " vagy + a -"" karakter használatával lehet előtaggal elnevezni.

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

# Template2
* text variation 1
* text variation 2

# Template3
+ one
+ two

Egyszerű válaszsablon

Az egyszerű válaszsablonok egy vagy több szövegváltozatot tartalmaznak, amelyeket a szövegösszeállításhoz és a bővítéshez használnak. A megadott változatok egyikét véletlenszerűen választja ki az LG könyvtár.

Íme egy példa egy egyszerű sablonra, amely két változatot tartalmaz.

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

Feltételes válaszsablon

A feltételes válaszsablonokkal egy feltétel alapján kiválasztott tartalmat készíthet. Minden feltétel adaptív kifejezésekkel van kifejezve.

Fontos

A feltételes sablonok nem ágyazhatók be egyetlen feltételes válaszsablonba. A feltételes beágyazáshoz strukturált válaszsablonban használjon összeállítást.

If-else sablon

Az if-else sablon lehetővé teszi, hogy olyan sablont hozzon létre, amely a feltételek kaszkádolt sorrendje alapján választ ki egy gyűjteményt. A kiértékelés felülről lefelé történik, és leáll, ha egy feltétel kiértékelése true vagy az EL Standard kiadás blokk találata történik.

A feltételes kifejezések a ${}kapcsos zárójelek közé vannak zárva. Íme egy példa, amely egy egyszerű HA EL Standard kiadás feltételes válaszsablon definícióját mutatja be.

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

Íme egy másik példa, amely egy if-else feltételes válaszsablon definícióját mutatja be. Vegye figyelembe, hogy bármely feltétel változatában hivatkozhat más egyszerű vagy feltételes válaszsablonokra.

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

Sablon váltása

A kapcsolósablon lehetővé teszi, hogy olyan sablont tervezzen, amely megfelel egy kifejezés értékének egy CA Standard kiadás záradéknak, és az eset alapján hozza létre a kimenetet. A feltételkifejezések kapcsos zárójelek közé tartoznak: ${}.

Így adhatja meg a HITELESÍTÉSSZOLGÁLTATÓ VÁLTÁSA Standard kiadás ALAPÉRTELMEZETT blokkot az LG-ben.

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

Íme egy bonyolultabb SWITCH CA Standard kiadás ALAPÉRTELMEZETT példa:

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

Megjegyzés:

A feltételes sablonokhoz hasonlóan a kapcsolósablonok nem ágyazhatók be.

Strukturált válaszsablon

A strukturált válaszsablonokkal olyan összetett struktúrát határozhat meg, amely támogatja az LG főbb funkcióit, például a templatálást, az összetételt és a helyettesítést, miközben a strukturált válasz értelmezését az LG-kódtár hívójára bízza.

A robotalkalmazások esetében natív módon támogatjuk a következőt:

tevékenységdefiníció
kártyadefiníció

További információkért olvassa el a struktúra válaszsablonjait .

Sablonösszeállítás és bővítés

Sablonokra mutató hivatkozások

A változatszöveg tartalmazhat egy másik elnevezett sablonra mutató hivatkozásokat, amelyek segítik a kifinomult válaszok összeállítását és megoldását. Más elnevezett sablonokra mutató hivatkozások zárójelek használatával vannak jelölve, például ${<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

A sablon meghívása GreetingReply a következő bővítési feloldások egyikét eredményezheti:

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

Entitások

Ha közvetlenül egy változatszövegben használják, az entitáshivatkozások úgy vannak jelölve, hogy kapcsos zárójelekbe ( például ${entityName}) vagy kapcsos zárójelek nélkül vannak megadva paraméterként használva.

Az entitások paraméterként használhatók:

előre összeállított függvényen belül
feltételes válaszsablonban lévő feltételen belül
a sablonfeloldási híváshoz

Előre összeállított függvények használata változatokban

Az adaptív kifejezések által támogatott előre összeállított függvények beágyazottan is használhatók egy-egy változatszövegben, hogy még hatékonyabb szövegösszetételt érjenek el. Ha beágyazott kifejezést szeretne használni, egyszerűen csomagolja be kapcsos zárójelekbe.

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

A fenti példa az illesztés előre összeállított függvényével listázza a recentTasks gyűjtemény összes értékét.

Mivel a sablonok és az előre összeállított függvények azonos meghívási aláírással rendelkeznek, a sablonnév nem lehet azonos az előre összeállított függvény nevével.

A sablonnevek nem egyeznek az előre összeállított függvény nevével. Az előre összeállított függvény elsőbbséget élvez. Az ilyen ütközések elkerülése érdekében a sablon nevére való hivatkozáskor előre fel lehet idézni lg. . Például:

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

Többsoros szöveg változatokban

Az egyes változatok többsoros szöveget is tartalmazhatnak, három idézőjelben.

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

A többsoros változat kérheti a sablonbővítést és az entitások helyettesítését, ha a kért műveletet kapcsos zárójelekbe (${}) csatolja.

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

Többsoros támogatással a Language Generation alrendszer teljes mértékben feloldhat egy összetett JSON-t vagy XML-t (például az SSML-be burkolt szöveget a robot beszélt válaszának szabályozásához).

Sablonok parametrizálása

A környezetfüggő újrafelhasználhatóság támogatásához a sablonok parametrizáltak. A sablon különböző hívói különböző értékeket adhatnak át a bővítés felbontásához.

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

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

# timeOfDayGreeting
- ${timeOfDayGreetingTemplate(timeOfDay)}

Külső hivatkozások importálása

A nyelvi létrehozási sablonokat külön fájlokra oszthatja, és hivatkozhat egy másik fájlból származó sablonra. Markdown-stílusú hivatkozásokkal importálhat egy másik fájlban definiált sablonokat.

[Link description](filePathOrUri)

A célfájlban definiált összes sablon be lesz vonva. Győződjön meg arról, hogy a sablonnevek egyediek (vagy névtérrel vannak # \<namespace>.\<templatename>jelölve) a behúzott fájlok között.

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

Az LG által injektált függvények

Az adaptív kifejezések lehetővé teszik, hogy egyéni függvénykészletet injektáljanak. További információkért olvassa el az LG-kódtárból injektált függvényeket.

Beállítások

A fejlesztők elemzési beállításokat állíthatnak be a bemenet kiértékelésének további testreszabásához. Az elemzési beállításokat a > !# jelöléssel állíthatja be.

Fontos

A fájlban található utolsó beállítás az ugyanabban a dokumentumban található összes korábbi beállítást módosítja.

Szigorú beállítás

Azok a fejlesztők, akik nem szeretnének null értéket adni a null értékű kiértékelt eredményeknek, a szigorú beállítást implementálhatják. Az alábbiakban egy egyszerű, szigorú lehetőség látható:

> !# @strict = true
# template
- hi

Ha a szigorú beállítás be van kapcsolva, a null értékű hibák egy rövid üzenetet fognak eredményezni.

# welcome
- hi ${name}

Ha a név null, akkor a diagnosztikát null értékre értékeli a rendszer. [üdvözli] Hiba történt a(z) "- hi ${name}" kiértékelésekor. Ha a szigorú érték hamis vagy nincs beállítva, a rendszer egy kompatibilis eredményt ad meg. A fenti minta hi null értéket eredményezne.

replaceNull beállítás

A fejlesztők delegáltakat hozhatnak létre a kiértékelt kifejezések null értékeinek lecseréléséhez a replaceNull beállítással:

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

A fenti példában a változó null path bemenete ${path} értékre cserélődik, nincs definiálva. A következő bemenet, ahol user.name null:

hi ${user.name}

Azt eredményezné, hogy a hi user.name nincs definiálva.

lineBreakStyle lehetőség

A fejlesztők a lineBreakStyle beállítással beállíthatják, hogy az LG rendszer hogyan renderelje a sortöréseket. Jelenleg két mód támogatott:

default: a többsoros szöveg sortörése normál sortöréseket hoz létre.
markdown: a többsoros szöveg sortörése automatikusan két sorra lesz konvertálva új vonal létrehozásához

Az alábbi példa bemutatja, hogyan állíthatja be a lineBreakStyle beállítást a következőre markdown:

> !# @lineBreakStyle = markdown

Névtér beállítás

Regisztrálhat névteret az exportálni kívánt LG-sablonokhoz. Ha nincs megadva névtér, a névtér kiterjesztés nélküli fájlnévre lesz beállítva.

Az alábbi példa bemutatja, hogyan állíthatja be a névtér beállítást a következőre foo:

> !# @Namespace = foo

Exportálási beállítás

Megadhatja az exportálni kívánt LG-sablonok listáját. Az exportált sablonok hívhatók előre összeállított függvényeknek.

Az alábbi példa bemutatja, hogyan állíthatja be az exportálási beállítást a következőre template1, template2:

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

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

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

Ezeket foo.template1(1,2), foo.template2(['a', 'b', 'c'], ',') az exportált sablonokat hívhatja meg.

Gyorsítótár hatóköre

A gyorsítótár hatókörének beállításaival szabályozhatja, hogy az LG-kiértékelő mikor értékeli újra a korábban és mikor látott kifejezést, és mikor tárolja és használja a gyorsítótárazott eredményt.

A globális gyorsítótár a kiértékelés életciklusában hatékony. Az LG gyorsítótárazza az összes kiértékelési eredményt, és ha a sablon neve és paraméterei megegyeznek, a gyorsítótárból származó eredményt adja vissza.
A helyi gyorsítótár hatóköre az alapértelmezett. Ugyanabban a rétegben, ha az előző sablont ugyanazzal a sablonnévvel és ugyanazokkal a paraméterekkel hívták meg, a gyorsítótárazott eredmény közvetlenül lesz visszaadva.
Egyik gyorsítótár-hatókör sem tiltja le az összes gyorsítótár-hatókört, és minden alkalommal visszaadja az új eredményt.

Példákat a globális és a helyi gyorsítótár hatókörére vonatkozó példákban talál.

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

Vegye figyelembe, hogy a gyorsítótár hatókörének beállítása nem érzékeny a kis- és nagybetűkre.

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

Vegye figyelembe, hogy a gyorsítótár hatóköre a Microsoft Entrance .lg fájl hatókörét követi.

Tegyük fel, hogy két fájllal rendelkezik: a.lg és b.lgaz alábbiakban látható:

a.lg

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

b.lg

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

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

Ha a következő kódot futtatja, láthatja, hogy template2 az első kiértékelt eredmény gyorsítótárazott eredményét használja az a.lg globalgyorsítótár hatókörbeállítása miatt:

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

A megjelölés újrafuttatására gyakorolt hatás

Ha a sablon neve "!"-val végződik, a sablon újra végrehajtást kényszerít. Ez az eredmény a gyorsítótár hatókörétől függetlenül nem lesz hozzáadva a gyorsítótárhoz.

Tegyük fel, hogy a következő sablonnal rendelkezik:

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

template1!() aktiválódik, és az eredmény hozzá lesz adva a gyorsítótárhoz. A második template1() eltömi az eredményt az első template1(). A végső hívás a gyorsítótárban tárolt eredményeket használja.

Példa globális gyorsítótár hatókörre

Tegyük fel, hogy a következő sablonokkal rendelkezik:

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

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

# template3
- ${template2()}

template2 egyszer lesz kiértékelve, a második végrehajtás pedig template3 az első gyorsítótárát alkalmazza.

Egy másik példa a következő kódrészlet:

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

A rendszer a függvény használatával Templates.ParseFile() elemez egy sablont, és a sablon kiértékelési eredményeit a rendszer tárolja.result1 Vegye figyelembe, result2hogy a második kiértékelési eredmény elveti az összes korábban gyorsítótárazott eredményt.

Példa helyi gyorsítótár hatóköre

Az alábbi példák azt mutatják be, hogy a helyi gyorsítótár hatóköre mikor működik, és nem működik. Tegyük fel, hogy egy t()subT() paramétert használó sablonok:

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

További források

C# API-referencia
JavaScript API-referencia
Olvassa el a Hibakeresést az Adaptív eszközökkel , és megtudhatja, hogyan elemezheti és debugálhatja az .lg fájlokat.