DDE Tutorial

How to start

Step 0.導論

Zenbo 是一隻具有多功能的機器人，內部有許多APP(程式)在執行。Zenbo上的APP越多，能做的事就越多。因此我們可以將Zenbo視為一個APP的平台。

開發者可以將自己開發的APP安裝在Zenbo上執行，讓它具有特殊能力，或提供特別的服務。每一支APP可以包含多個Zenbo會的Domain(技能)。舉例來說，今天我們可以建立一支遊戲王的APP，裡面有著各式小遊戲。這些不同的小遊戲便可以視為不同的Domain(例如ZooGame、CardGame、BoardGame等等)。

Zenbo 內部因為有口語理解模組 (Spoken Language Understanding / SLU)，將語音辨識資訊轉化為結構化的語意資料，並提供給適當的Domain 處理。所以Zenbo APP並不是一般的 Android APP，它能了解話中的Intent(意圖)。

為了處理語音辨識結果與APP Domain所需的流程設計，必須使用DDE(dialogue development environment)來解決這些需求，進而提供開發者建立有用的語意資料。使用DDE之前需要先清楚一個概念:人類與Zenbo的對話是透過一連串的Intent(意圖)語句組成。Concept(概念)則是語句的詞彙，而Plan(流程)則是負責串起語句之間的流程來建立一段完整對話。所以如何使用DDE來編輯Plan / Intent /Concept是重要的課題。

以上圖來看， User在問答中的語句為Intent，Intent中的詞彙為Concept。例如I want to play the zoo game 的zoo game可替換成隸屬同個Concept ”Game”的card game或者 board game，然後Plan將三段對話串連起來讓Zenbo跟使用者交談。接著我們將引領你透過以下教學，一步步地輕鬆建立自己的Domain。

Step 1. 建立新 Project

[1-1]開啟DDE的網址，登入帳號密碼

[1-2]使用者登入對話編輯器(DDE)以後，會彈出Project Center。選取右下角的”Create A New Project”。

[1-3]點選新增Project框中的橘色”Edit”

[1-4] 彈出App Name填寫的視窗，填寫 "動物叫聲王"後按下"Save"。

App Name 不一定要在此時就先填寫，也可以進入 Project Info 填寫，在步驟2內會說明。

[1-5]進入編輯畫面。

(如果要重新選擇Project，可透過點取左上角的Project Center來選取)

Step 2. 填好 Project info資訊

填寫Project info的目的為測試與上架:

如果是僅在DDE上測試，只需填好 DDE Domain ID、Version 、Brand、App Name。

如果是在 Zenbo上測試，需填寫 DDE Domain ID、Version 、Package Name、Brand、App Name、Launch Activity。

如果是為了上架，需填寫DDE Domain ID、Version、Developer App ID、Package Name、Brand、App Name、Launch Activity。

[2-1]確認上方控制列有Project Center / Indo /Dev ...

[2-2]選取 Info

Info位於下圖

[2-3]點選Register 來註冊DDE Domain ID

假設要使用Zenbo進行測試會需要使用到UUID(universally unique identifier，如何使用詳見Update Your Apk On Zenbo文章)

如果已註冊過可直接選取，跳至步驟[2-5]

[2-4]填入Domain Name 與 Domain Description後按下”Create”

[2-5]點選”All”查看建立好的ID

假設要使用Zenbo進行測試會需要使用到UUID(universally unique identifier，如何使用詳見Update Your Apk On Zenbo文章)

[2-6](選填)點選已註冊過的Developer APP ID

APP ID 是透過開發者網站(App Key Management)註冊得到的，如果要上架才需要填入。填入APP ID後也會為你填入其他已經在開發者網站填過的資訊(例如package name、brand、app name)。

如何註冊可觀看Developer APP ID詳見Update Your Apk On Zenbo文章)

[2-7](選填)若要在Zenbo上測試需填寫Package Name欄位

(詳情請看Update Your Apk On Zenbo文章)

[2-8]填寫Brand，例如可以填寫華碩。

[2-9]填寫App Name，例如可以填寫動物叫聲王

[2-10](選填) 若要在Zenbo上測試需填寫 Launch Activity欄位

(詳情請看Update Your Apk On Zenbo文章)

備註:

Package name與Launch activity是為了與app的 manifest的內容連結，需填寫正確，才可以靠語音來啟動Zenbo的app。

Brand 與App Name則是當您的App在上架的階段時，我們預期您靠語音來啟動Zenbo。app 的語句須大概符合

我要用<AppName>

我要用<Brand>的<AppName>

的規範。上述兩句也是每個Project會幫您預設的第一個靠語音來啟動Zenbo的app的語句設計 ( Cross Intent)

例如: brand = 華碩, app name = 動物叫聲王

啟動語句 = 我要使用華碩動物叫聲王規劃行程

Step3. 簡易建立一個Domain

如Step. 0所描述，每一個Domain代表一個技能，例如查天氣、查詢時刻表、聽音樂、說笑話等。一個Domain內，必定會有許多的互動。所以在建立Domain時，我們建議初學者者以Plan為基礎，再建立需要引用的Intent(語句)。一般新建的Project裡，會有預設的Plan(ThisPlanLaunchingThisApp ) / Intent(UtteranceToLanuchApp) /Concept(動作、事件) 來輔佐設計者建立啟動App的行為。以下為簡略的操作說明。

[3-1]先點選Plans的tab

[3-2]點選進入 ThisPlanLaunchingThisApp這個plan，新建的project都會有此預設的plan給開發者改寫。

[3-3]確認”Is the plan able to launch the app?” 是 true，代表此plan為啟動app的plan

[3-4]設定Event Type為CSR(語音辨識結果)，利用語音辨識觸發plan。

[3-5]設定Intent ID至 “UtteranceToLaunchApp”

[3-6]點選edit intent進入Intent，顯示如下畫面

可以看到在此Intent，有兩個語句。在語句中藍色標籤為一般文字，橘色標籤為詞彙集合(Concept)。例如"動作"可能會填入聽、看、吃、跑等詞彙。這裡面比較特別的是 BrandName 與 VoiceTag，這兩個Concept為系統自動擷取Project Info所填寫的BrandName 與 VoiceTag(App Name)，依照前面章節的教學，現在應該為華碩與 動物王。

[3-7]點選橘色"動作"標籤，點選Go to this concept，進入該concept

[3-8]點選 +New Instance

[3-9]撰寫Instance ID 並點選 "+ different lang"，選擇語系以後填入其Instance集合

筆者的開發環境為繁體中文的Zenbo，所以語系選擇繁中。

[3-10] 按下Back to the intent page回到Intent

[3-11]點選橘色"事件"標籤，點選Go to this concept，進入該concept

[3-12]點選 +New Instance

[3-13]撰寫Instance ID 並點選 "+ different lang"，填入其Instance集合

[3-14] 按下Back to the intent page回到Intent

[3-15] 按下Back to the plan page 會到Plan

[3-16] 新增Action，點選 +New Action

[3-17] 設定Task的Type為TTS(Response)，使用"Text"的表達方式，語系選擇"繁中"。最後鍵入"歡迎來到華碩動物王，你想要聽什麼動物的叫聲嗎?"

[3-18]按下Publish按鈕後，按下"Continue to publish"

[3-19] 確認訊息無誤，按下"Continue to publish"

[3-20] 確認訊息無誤後，按下"Continue to publish"

[3-21] Publish成功後，在測試視窗輸入 "我要用華碩動物王聽叫聲"

[3-22] 可以看到成功的得到回應

透過以上的教學，想必你已經成功建立一個Domain。但是一個充實的Domain必定包含多個Plan才能完成對話或者行為表現，所以接下來會先說明如何用Plan建立流程。

Step4. Plan基本功能說明與應用

[4-1]如同之前，先點選plan的tab

[4-2]再次點選進入 ThisPlanLaunchingThisApp

[4-3]將Output Contexts 填入為”myFirstSentence”

Plan 與 Plan之間的流程是透過 Input Context 與 Output Contexts 串接而成。假設PlanA有任一的Ouput Contexts連接至Plan B的 Input Context(唯一)，若流程在Plan A，即可透過觸發 Plan B 的Event (ex. CSR)進入 Plan B。

[4-4]按下Add，產生新的Plan “NewNode1”

[4-5]點擊NewNode1

[4-6]更改ID為myFirstPlan

[4-7]確認 ”Is the plan able to launch the app?” 是 false

備註:

假設為false，才會產生input context欄位供填寫。

[4-8]填寫Input Context為 “myFirstSentence”

與步驟4-3相呼應

[4-9]點選 +New Event

[4-10]選擇Event的 Intent ID，並且按下 "CREATE A NEW INTENT" ，進入編輯Intent的程序。

小結:

Event是觸發此plan的先決條件之一。可以看到在Plan “ThisPlanLaunchingThisApp”中，event的設定為CSR(語言辨識結果)，而觸發的Intent為 “UtteranceToLaunchApp”。在Action裡的設定，output contexts 為”myFirstSentence”。

如果流程需要接續至另一個plan “myFirstPlan” 的話，需要把”myFirstPlan”中的 input context 設定為 myFirstSentence，與 “ThisPlanLaunchingThisApp”的 output context相符。一旦流程進入“ThisPlanLaunchingThisApp”之後，再觸發” myFirstPlan”的event就會進入”myFirstPlan”。

總而言之，plan的流程是藉由context串連以及event觸發。當input context相符且event被觸發，就會進入此plan。

當流程確定進入plan之中，一旦Action的條件滿足(無設定視為Always)，就會執行Task以及設定output context。

在此還有一個需要注意的地方,如果將 "Is the plan to launch the app" 選擇為true

會出現下圖選項

如果選擇"Always resume", 當此App被啟動後，因需求被置於背景時，一旦被重新呼叫後，不會重新設定context。

相反的，選擇其他兩個選項時，再次被呼叫(cross-intent)會重新設定context為此plan的context。

Step5. Intent基本功能說明與應用

各種對話流程，必定是建構在一句句的語句之上。Intent便是DDE用以產生各種句型的地方。本章節主要說明Intent如何與Plan以及Concept進行串接。

[5-1] 延續 4-10 更改 Intent ID 為 "各種動物的叫聲"

[5-2] 會看到提醒視窗，告知更改ID會讓Plan引用的ID一起變動，請點選Yes

[5-3]更換Language為 Traditional Chinese

Language設定為當Zenbo的背景語系與該Language相符時會使用該Intent

[5-4]點選Sentences的 +New Sentence來增列語句

[5-5]在新增的欄位中填入”我想要聽河馬的叫聲” 並且 + Enter

[5-6]再按一次+New Sentence

[5-7]填入”我想要聽”後+Enter。

[5-8]填入 "河馬" 後 + Enter

[5-9] 填入"的叫聲" + Enter，此時應該會形成下圖

[5-10] 點選 "河馬"，並且點擊 "Add a new instance to a new concept" ，再輸入animal且按下確認，就會形成橘色的Concept標籤。

[5-11]點擊橘色標籤，選擇 "Go to this Concept"，進入該Concept。

Step6. Cocept基本功能說明與應用

語句往往包含許多的詞彙，所以為了提高編列語句的效率，DDE提供詞彙類別的概念”Concept”讓語句透過引用詞彙來建造變化多端的語句。

[6-1] 延續步驟5-10，可以看到以下畫面

Instacese的ID 與值已經被填入"河馬"，而該Concept ID 則為animal。

[6-2] 考慮到河馬可能有其他稱呼，鍵入其他詞彙如 "大嘴巴" 至Instance ID為河馬的Instance裡。

[6-3] 動物也有可能會是其他動物，按下+ New Instance

[6-4]輸入 Instance ID "老虎"

[6-5]按下+ different lang

[6-6] 填寫 "百獸之王" "巨型貓咪" "老虎"至Instance。結果如下圖:

值得注意的是，Lang選項在本例中，由於筆者的Zenbo背景語系是中文，所以語系設定為繁體中文。

[6-7]完成Concept設定之後，按下"Back to intent page" 回到Intent。

Step7. Beleif(變數) 的整合與應用

使用者與機器人的對話中必定包含有用的資訊，我們將會在本章進行教學如何儲存這些資訊與應用。

[7-1] 承 6-7 , 可看到下圖畫面，可以發現第二個句子為 "我想要聽 @animal 的叫聲"。

由於我們在concept animal裡，除了河馬，也放進老虎的instance。所以一旦使用者講出"我想要聽老虎的叫聲"，也會被匹配到。

[7-2]點選橘色 "animal"，

有時候我們需要儲存belief(變數)，透過以上方式，會將對應的值存到belief(變數)裡。如上圖，若使用者說出 "我想要聽老虎的叫聲"，"老虎" 會被儲存到belief(變數)animal_name。

[7-2] 按下"Back to the plan page"，回到一開始的plan。

[7-3] 回到Plan之後，點選 +New Action

[7-4] TTS的參考方式選 "text"

[7-5] 語言選擇繁中

[7-6]填入TTS為“好的，為您播放{animal_name}的叫聲!”

{animal_name}為引用belief(變數animal_name)的語法 (目前僅在Task內的 TTS 與 Condition引用)

[7-7] 點選+New Belief

還記得在步驟 7-2設定belief，animal_name嗎? 為了要在此plan中使用該belief，我們需要簡單的設定。

[7-8] Required選擇 yes

代表此Belief有被擷取到，才會被允許進入該plan。

[7-9] ID選擇 belief 的 ID，這裡為 "animal_name"

[7-10] 按下Define class，選擇belief所屬的 concept，所以選擇 animal後按下"Save"

[7-11] 點選 Define prompts

由於在required欄位為"yes"，當使用者說了類似的話進入此Plan，一旦無法擷取到belief則會跳出Plan。例如使用者說"我要聽小狗的叫聲"，由於小狗不在concept內，便無法把小狗代入belief中。所以我們需要prompts回問，例如 "你要聽老虎或者河馬的叫聲嗎" ，暗示動物被限制於老虎與河馬。

[7-12] 填入 "你要聽老虎或者河馬的叫聲嗎"，並將語言選擇 "Traditional Chinese"後，按下Save。

Step8. 測試與確認

[8-1] 當資料都建構完畢時，按下右上角的"publish"，將資料傳到雲端。

[8-2]至右側的Test Window 先輸入 "我要用華碩動物王聽叫聲" 來啟動此App。

啟動句的教學，請回看步驟 3

[8-3]看到回應 "歡迎來到華碩動物王，你想要聽什麼動物的叫聲嗎?"。繼續輸入 "我想要聽老虎的叫聲"

[8-4] 看到回應裡引用了BELIEF，並且顯示 belief (animal_name) 被填入 "老虎"。

Testing_domains 欄位代表的是，目前有哪幾個domain正在監聽Test Window 所輸入的句子。

Appendix:

One:

Belief除了直接在DDE UI上引用，也可以透過取得SLU(Spoken Language Understanding) Result後，從中擷取獲得如下:

1.CrossIntent的SLU Json取得方法

Intent intent = getIntent();
JSONObject slu_json;
try {
slu_json = new JSONObject(intent.getStringExtra("json"));
} catch (NullPointerException | JSONException ex) {
ex.printStackTrace();
}

參考連結:

https://zenbo.asus.com/developer/documents/Zenbo-SDK-Getting-Started/Getting-Started

2.In-APP中的SLU JSON取得方法:

如下圖所示，利用call back之後的OnResult得到JSONObject，就是SLU result。

可以透過 RobotUtil.queryListenResultJson來擷取出不同的結果。例如範例中分別獲得 Plan ID 以及 SLU result特定資訊。

Two:

在Action的動作，也可以用Zenbo SDK完成。例如ouput context和TTS的設定可以在程式碼裡用call api的方式達到。

範例如下:

1.設定output context

Set two contexts (helloWorld, helloWorld2) to be listened by DS and then start to listen user utterance.

suppose helloWorld and helloWorld2 are the input context of the plan for the status that i want to make the intent of the plan to be considered by DS.

mRobotAPI.robot.setListenContext(“82F199B9E7774C688114A72457E3C229”, “helloWorld, helloWorld2”);

mRobotAPI.robot.speakAndListen("", 10);

備註:

82F199B9E7774C688114A72457E3C229 是你的 domain uuid，可以透過 project info查詢。此外，設定output context為一次性，至下個session時，如有需要仍需再次設定。

2.設定TTS.

// TTS first then Listen user utterance

mRobotAPI.robot.speakAndListen("Which city do you like?", 10);

Three:

匯入與載出
我們可以將資料利用匯出而存至外部空間，也可以將匯出的資料載入回DDE。可以分兩種型式

Export/Import Partial Config(整個Domain匯出)

Export/Import/Append Partial Config(僅匯出/載入部分的Config)

Append Partial Config，僅僅將跟現行Config不同ID的資料附加上去

Four:

Lang為該欄位的語言設定，如果Zenbo Device的整體語系與被設定的語系相符時，才會將輸入的資料載入。我們以Instance為例:

當Device語系偵測為繁體中文時會載入上列詞彙。所以會知道Tiger與老虎是同義詞，並不是語系設定為繁體中文，該欄位裡面就必須全部為繁體中文。