.lg dosya biçimi

Makale
10/24/2023

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

.lg dosyası, varlık başvuruları ve bunların bileşimiyle dil oluşturma şablonlarını açıklar. Bu makale .lg dosya biçimiyle ifade edilen çeşitli kavramları kapsar.

Özel Karakterler

Açıklamalar

Açıklama oluşturmak için kullanın > . Bu önek içeren tüm satırlar ayrıştırıcı tarafından atlanır.

> This is a comment.

Atlatma karakteri

Kaçış karakteri olarak kullanın \ .

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

Diziler ve nesneler

Dizi oluşturma

Dizi oluşturmak için ${[object1, object2, ...]} söz dizimini kullanın. Örneğin, bu ifade:

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

dizisini ['a', 'b', 'c']döndürür.

nesnesi oluşturun

Nesne oluşturmak için ${{key1:value1, key2:value2, ...}} söz dizimini kullanın. Örneğin, bu ifade:

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

Aşağıdaki JSON nesnesini döndürür:

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

Şablonlar

Şablonlar , dil oluşturma sisteminin temel kavramıdır. Her şablonun bir adı ve aşağıdakilerden biri vardır:

çeşitleme metin değerlerinin listesi
yapılandırılmış içerik tanımı
her biri aşağıdaki koşullara sahip bir koşul koleksiyonu:
- uyarlamalı ifade
- koşul başına bir çeşitleme metin değerlerinin listesi

Şablon adları

Şablon adları büyük/küçük harfe duyarlıdır ve yalnızca harf, alt çizgi ve sayı içerebilir. Aşağıda adlı TemplateNamebir şablon örneği verilmiştir.

# TemplateName

Şablonlar bir sayı ile başlayamaz ve şablon adının herhangi bir bölümü ile bölünürken bir sayıyla başlayamaz.

Şablon yanıtı çeşitlemeleri

Çeşitlemeler Markdown listesi olarak ifade edilir. Her varyasyona -ön ek olarak , ' veya + karakterini kullanabilirsiniz.

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

# Template2
* text variation 1
* text variation 2

# Template3
+ one
+ two

Basit yanıt şablonu

Basit bir yanıt şablonu, birleştirme ve genişletme için kullanılan bir veya daha fazla metin varyasyonu içerir. Sağlanan varyasyonlardan biri LG kitaplığı tarafından rastgele seçilecektir.

burada iki çeşitleme içeren basit bir şablon örneği verilmiştir.

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

Koşullu yanıt şablonu

Koşullu yanıt şablonları, bir koşula göre seçilen içeriği yazmanıza olanak verir. Tüm koşullar uyarlamalı ifadeler kullanılarak ifade edilir.

Önemli

Koşullu şablonlar tek bir koşullu yanıt şablonunda iç içe yerleştirilemiyor. Koşulluları iç içe yerleştirme amacıyla yapılandırılmış bir yanıt şablonunda oluşturma kullanın.

If-else şablonu

if-else şablonu, basamaklı koşul sırasına göre bir koleksiyon seçen bir şablon oluşturmanıza olanak tanır. Değerlendirme yukarıdan aşağıyadır ve bir koşul olarak değerlendirildiğinde true veya ELSE bloğuna çarpıldığında durur.

Koşullu ifadeler ${} ayracı içine alınır. Aşağıda basit bir IF ELSE koşullu yanıt şablonu tanımını gösteren bir örnek verilmiştır.

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

If-else koşullu yanıt şablonu tanımını gösteren başka bir örnek aşağıda verilmiştır. Koşulların herhangi biri için varyasyona diğer basit veya koşullu yanıt şablonlarına başvurular ekleyebileceğinizi unutmayın.

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

Şablon değiştir

Anahtar şablonu, bir ifadenin değerini CASE yan tümcesi ile eşleştiren ve bu duruma göre çıkış üreten bir şablon tasarlamanıza olanak tanır. Koşul ifadeleri ${} ayraçları içine alınır.

LG'de SWITCH CASE DEFAULT bloğunu şu şekilde belirtebilirsiniz.

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

Aşağıda daha karmaşık bir SWITCH CASE DEFAULT örneği verilmişti:

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

Dekont

Koşullu şablonlar gibi anahtar şablonları da iç içe yerleştirilemiyor.

Yapılandırılmış yanıt şablonu

Yapılandırılmış yanıt şablonları, yapılandırılmış yanıtın yorumunu LG kitaplığının arayanlarına bırakırken şablon oluşturma, oluşturma ve değiştirme gibi büyük LG işlevlerini destekleyen karmaşık bir yapı tanımlamanıza olanak sağlar.

Bot uygulamaları için şunları yerel olarak destekliyoruz:

etkinlik tanımı
kart tanımı

Daha fazla bilgi için yapı yanıtı şablonları hakkında bilgi edinin.

Şablon oluşturma ve genişletme

Şablonlara başvurular

Çeşitleme metni, karmaşık yanıtların bileşimine ve çözümüne yardımcı olmak için başka bir adlandırılmış şablona başvurular içerebilir. Diğer adlandırılmış şablonlara başvurular, ${<TemplateName>()}gibi küme ayraçları kullanılarak belirtilir.

> 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

Şablonu çağırmak GreetingReply aşağıdaki genişletme çözümlerinden biriyle sonuçlanabilir:

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

Varlıklar

Doğrudan bir çeşitleme metni içinde kullanıldığında, varlık başvuruları ${entityName} gibi küme ayraçları içine alınarak veya parametre olarak kullanıldığında küme ayracı olmadan belirtilir.

Varlıklar parametre olarak kullanılabilir:

önceden oluşturulmuş bir işlev içinde
koşullu yanıt şablonundaki bir koşul içinde
şablon çözümleme çağrısına

Varyasyonlarda önceden oluşturulmuş işlevleri kullanma

Uyarlamalı ifadeler tarafından desteklenen önceden oluşturulmuş işlevler, daha da güçlü metin bileşimi elde etmek için bir çeşitleme metninde satır içi olarak da kullanılabilir. Bir ifadeyi satır içinde kullanmak için küme ayraçları içinde kaydırmanız yeterlidir.

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

Yukarıdaki örnek, koleksiyondaki tüm değerleri recentTasks listelemek için önceden oluşturulmuş birleştirme işlevini kullanır.

Verilen şablonlar ve önceden oluşturulmuş işlevler aynı çağrı imzasını paylaşır; şablon adı önceden oluşturulmuş işlev adıyla aynı olamaz.

Şablon adı önceden oluşturulmuş bir işlev adıyla eşleşmemelidir. Önceden oluşturulmuş işlev önceliklidir. Bu tür çakışmaları önlemek için şablon adınıza başvururken ön lg. ödeme yapabilirsiniz. Örnek:

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

Çeşitlemelerdeki çok satırlı metin

Her çeşitleme, üç tırnak içine alınmış çok satırlı metin içerebilir.

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

Çok satırlı varyasyon, istenen işlemi ayraçlar (${}) içine alarak şablon genişletme ve varlık değiştirme isteğinde bulunabilir.

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

Çok satırlı destekle, Dil Oluşturma alt sisteminin karmaşık bir JSON veya XML'yi (bot'un konuşulan yanıtını denetlemek için SSML sarmalanmış metni gibi) tamamen çözümlemesini sağlayabilirsiniz.

Şablonların parametrizasyonu

Bağlamsal yeniden kullanılabilirliğe yardımcı olmak için şablonlar parametriz edilebilir. Şablona farklı arayanlar, genişletme çözünürlüğünde kullanılmak üzere farklı değerler geçirebilir.

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

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

# timeOfDayGreeting
- ${timeOfDayGreetingTemplate(timeOfDay)}

Dış başvuruları içeri aktarma

Dil oluşturma şablonlarınızı ayrı dosyalara bölebilir ve bir şablona başka bir dosyadan başvurabilirsiniz. Başka bir dosyada tanımlanan şablonları içeri aktarmak için Markdown stili bağlantıları kullanabilirsiniz.

[Link description](filePathOrUri)

Hedef dosyada tanımlanan tüm şablonlar çekilir. Şablon adlarınızın, çekilmekte olan dosyalar arasında benzersiz (veya ile # \<namespace>.\<templatename>ad alanı) olduğundan emin olun.

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

LG tarafından eklenen işlevler

Uyarlamalı ifadeler , özel bir işlev kümesi ekleme olanağı sağlar. Daha fazla bilgi için LG kitaplığından eklenen işlevleri okuyun.

Seçenekler

Geliştiriciler, girişin değerlendirilme biçimini daha fazla özelleştirmek için ayrıştırıcı seçeneklerini ayarlayabilir. > !# Ayrıştırıcı seçeneklerini ayarlamak için gösterimi kullanın.

Önemli

Dosyada bulunan son ayar, aynı belgede bulunan önceki tüm ayarların altındadır.

Katı seçenek

Null olarak değerlendirilen bir sonuç için null sonucuna izin vermek istemeyen geliştiriciler katı seçeneği uygulayabilir. Aşağıda basit bir katı seçenek örneği verilmiştir:

> !# @strict = true
# template
- hi

Katı seçenek açıksa, null hatalar kolay bir ileti oluşturur.

# welcome
- hi ${name}

Ad null ise, tanılama null olarak değerlendirilen 'name' olur . [hoş geldiniz] '- hi ${name}' değerlendirilirken hata oluştu... Strict değeri false olarak ayarlanırsa veya ayarlanmazsa uyumlu bir sonuç verilir. Yukarıdaki örnek hi null üretir.

replaceNull seçeneği

Geliştiriciler, replaceNull seçeneğini kullanarak değerlendirilen ifadelerdeki null değerleri değiştirmek için temsilciler oluşturabilir:

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

Yukarıdaki örnekte değişkendeki path null girişi ${path} ile değiştirilecek tanımlanmamış. Aşağıdaki giriş, burada user.name null: :

hi ${user.name}

Hi user.name tanımsız olarak sonuçlanır.

lineBreakStyle seçeneği

Geliştiriciler, LG sisteminin lineBreakStyle seçeneğini kullanarak satır sonlarını nasıl işleyebileceğinize ilişkin seçenekleri ayarlayabilir. Şu anda iki mod desteklenmektedir:

default: çok satırlı metindeki satır sonları normal satır sonları oluşturur.
markdown: çok satırlı metindeki satır sonları, yeni satır oluşturmak için otomatik olarak iki satıra dönüştürülür

Aşağıdaki örnekte lineBreakStyle seçeneğinin markdownnasıl olarak ayarlanacağı gösterilmektedir:

> !# @lineBreakStyle = markdown

Ad alanı seçeneği

Dışarı aktarmak istediğiniz LG şablonları için bir ad alanı kaydedebilirsiniz. Ad alanı belirtilmemişse, ad alanı bir uzantı olmadan dosya adına ayarlanır.

Aşağıdaki örnekte ad alanı seçeneğinin fooolarak nasıl ayarlanacağı gösterilmektedir:

> !# @Namespace = foo

Dışarı aktarmalar seçeneği

Dışarı aktarılacak LG şablonlarının listesini belirtebilirsiniz. Dışarı aktarılan şablonlar, önceden oluşturulmuş işlevler gibi çağrılabilir.

Aşağıdaki örnekte dışarı aktarma seçeneğinin template1, template2olarak nasıl ayarlanacağı gösterilmektedir:

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

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

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

Dışarı aktarılan bu şablonları çağırmak için kullanın foo.template1(1,2), foo.template2(['a', 'b', 'c'], ',') .

Önbellek kapsamı

Önbellek kapsamı seçenekleri, LG değerlendiricisinin daha önce gördüğü bir ifadeyi ne zaman yeniden değerlendirdiğini ve önbelleğe alınmış bir sonucu depolayıp ne zaman kullandığını denetlemenizi sağlar.

Genel önbellek , değerlendirmenin yaşam döngüsünde etkilidir. LG tüm değerlendirme sonuçlarını önbelleğe alır ve şablon adı ve parametreleri aynıysa önbellekten sonucu döndürür.
Yerel önbellek kapsamı varsayılandır. Aynı katmanda, önceki şablon aynı şablon adı ve aynı parametrelerle çağrıldıysa, önbelleğe alınan sonuç doğrudan döndürülür.
Hiçbiri önbellek kapsamı tüm önbellek kapsamını devre dışı bırakır ve her seferinde yeni sonucu döndürür.

Örnekler için genel ve yerel önbellek kapsamı örneklerine bakın.

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

Önbellek kapsamı seçeneğinin büyük/küçük harfe duyarlı olmadığını unutmayın.

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

Önbellek kapsamının Microsoft Giriş .lg dosyasının kapsamına uyduğunu unutmayın.

İki dosyanız olduğunu varsayalım: a.lg ve b.lgaşağıda gösterilmiştir:

a.lg

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

b.lg

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

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

Aşağıdaki kodu çalıştırırsanız, a.lg dosyasındaki önbellek kapsamı seçeneği nedeniyle değerlendirilen ilk sonucun global önbelleğe alınmış sonucunun kullanıldığına dikkat template2 edersiniz:

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

İşaret etkisini yeniden yürütme

Şablon adı "!" ile bitiyorsa, şablon yeniden yürütmeye zorlar. Bu sonuç, önbellek kapsamından bağımsız olarak önbelleğe eklenmez.

Aşağıdaki şablona sahip olduğunuzu varsayalım:

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

template1!() tetikler ve sonuç önbelleğe eklenir. İkinci template1() , ilk template1()sonucundan elde edilen sonucu tıkar. Son çağrı, önbellekte depolanan sonuçları kullanır.

Genel önbellek kapsamı örneği

Aşağıdaki şablonlara sahip olduğunuzu varsayalım:

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

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

# template3
- ${template2()}

template2 bir kez değerlendirilir ve içindeki ikinci yürütme template3 ilkinin önbelleğini uygular.

Aşağıdaki kod parçacığında başka bir örnek verilmiştir:

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

Bir şablon işlevi kullanılarak Templates.ParseFile() ayrıştırılır ve şablon değerlendirme sonuçları içinde result1depolanır. İkinci değerlendirme sonuçlarının , result2daha önce önbelleğe alınmış tüm sonuçları bırakdığını unutmayın.

Yerel önbellek kapsamı örneği

Aşağıdaki örneklerde yerel önbellek kapsamının ne zaman çalıştığı ve çalışmadığı gösterilmektedir. ve'nin subT() parametreyi kullanan şablonlar olduğunu t() varsayalım:

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

Ek Kaynaklar

C# API Başvurusu
JavaScript API'si başvurusu
.lg dosyalarını analiz etmeyi ve hatalarını ayıklamayı öğrenmek için Uyarlamalı Araçlarla Hata Ayıklama'ya bakın.

Aracılığıyla paylaş