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

DDE(dialogue development environment) 提供開發者建立有用的APP Domain語意資料，以便在對話過程中，能適切地處理語音辨識出來的純文字資料，並且提供APP Domain所需的流程設計。人類與Zenbo的對話是透過一連串的Intent(意圖)語句組成，Concept(概念)則是語句的詞彙，而Plan(流程)則是負責串起語句之間的流程來建立一段完整對話。

以上圖來看， 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”進入編輯畫面。

(如果要重新選擇Project，可透過點取左上角的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

[2-2]選取Project Info

Project 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，例如我可以填寫asus。

[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 = asus, app name = 台北公車王

啟動語句 = 我要使用asus台北公車王規劃行程

Step 3. 建立Concept

千千萬萬的語句中往往都會包含許多的詞彙，為了提高編列語句的效率，DDE提供詞彙類別的概念”Concept”。語句便可以透過引用已編輯過後的詞彙，建造變化多端的語句。

[3-1]點選DDE的Tab至Concepts

[3-2]點擊Add產生初始ID為NewNode1的Concept

[3-3]點擊NewNode1，開始編輯其內容

[3-4]點選Class欄位，改值”NewNode1” => “animal”

[3-5]按下Instances的 +New item

[3-6]在Instance的ID欄位填”老虎”

[3-7]在Instance的語言選擇 Traditional Chinese

[3-8]在Instance裡面填入”百獸之王”，按下Enter。填入”巨型貓咪”，按下Enter。填入”老虎”，按下Enter。填入”Tiger”，按下Enter。

[3-9]請仿造 [3-5]~[3-8]形成下圖

備註:上列步驟為增加多種動物名稱，而每種Instance 放置相似意思的詞彙。

當zenbo背景設定是你所設定的Lang時會引用該Instance，當然你也可以選擇全語言通用。而上圖中的藍色標籤可以透過點擊改變其中的值。

[3-10]按下Back鍵

[3-11]點擊Concept “動作”

[3-12]請仿造 [3-5]~[3-8]形成下圖

[3-13]按下Back鍵

[3-14]點擊Concept ”事件”

[3-15]請仿造 [3-5]~[3-8]形成下圖

Step 4. 建立 Intent

各種對話流程，必定是建構在一句句的語句之上。Intent便是DDE用以產生各種句型的地方

[4-1]按下Intent的Tab

[4-2]按下Add按鈕

[4-3]點選NewNode1進入編輯

[4-4]點選ID的欄位，改變值”NewNode1” => “各種動物的叫聲”

[4-5]更換Language為 Traditional Chinese

Lang是背景系統的語系設定

[4-6]點選Sentences的 +New item來增列語句

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

[4-8]再按一次+New Item

[4-8]填入”我想要聽”後+Enter。

[4-9]填入 “@” + Enter

[4-10]選擇animal

註解:

如果想要用一句話來表達聽多種動物的意思，便需要引用在上一步所編列好的Concept: animal。假設我想要輸入 我想要聽@動物的叫聲 來表達我想要聽某種動物的叫聲，便可以先輸入 我想要聽 然後鍵入 @ 符號，此時會有上圖選單列出現，並且選擇Refer->Ref Class，並且點選animal後，鍵入 的叫聲 。

[4-11]輸入“的叫聲”+Enter，最後可以得到如下圖的畫面。

[4-12]按下左上角的Back鍵

[4-13]點擊Intent “UtteranceToLanuchApp” 查看。

畫面如下:

BrandName與VoiceTag為內建的Concept。

BrandName為project-info裡所設定的Brand，VoiceTag為 App Name。

建立完以後的句子會像是 我要用 asus 叫聲動物王 聽 叫聲。

Step 5. 建立 Plans

一個健全的對話系統，必定需要操控對話流程。DDE透過Plan來建立來串接各式語句的流程。

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

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

[5-3]確認”Will this plan launch this app” 是 true，代表此plan為啟動app的plan

[5-4]點選Event 的 +New Item

[5-5]設定Event為CSR(語言辨識結果)

宣告利用語言辨識結果來觸發此plan

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

[5-7]新增Action，點選 +New Item

[5-8]將Output Contexts 填入為”myFirstSententce”

[5-9]點開 Task List 內的 + New Item

[5-10]選取Task Type為 TTS來設定回覆語句

[5-11]設定Response下的Lang為Traditional Chinese

備註:

因為編者的Zenbo背景為繁體中文，所以設定Traditional Chinese。

[5-12]設定Response下的Text為 “歡迎來到華碩動物王，你想要聽什麼動物的叫聲嗎?”

[5-13]點選左上角的”Back” 返回至Plan外層

[5-14]並且按下Add，產生新的Plan “NewNode1”

[5-15]點擊進去NewNode1

[5-16]更改ID為myFirstPlan

[5-17]確認 ”Will this plan launch this app” 是 false

備註:

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

[5-18]填寫Input Context為 “myFirstSentence”

[5-19]新增Event

[5-20]選擇Event Type 為 CSR

[5-21]選擇Event的 Intent ID為 “各種動物的叫聲”

[5-22]新增Action

[5-23]點選Action中的Task裡面之+New Item

[5-24]設定Task Type為 “TTS”

[5-25]選擇其Response的Lang為 Traditional Chinese

[5-26]填寫其Response的Text為”好的，為您播放!”

解釋:

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

如果流程要到plan “myFirstPlan” 的話，就必須要把”myFirstPlan”中的 input context 設定為 myFirstSentence，一旦流程進入“ThisPlanLaunchingThisApp”之後，再觸發” myFirstPlan”的event就會進入”myFirstPlan”。總而言之，plan的流程是藉由context串連以及event觸發。當input context符合與event觸發(可在app的程式碼撰寫中，設定透過其他event觸發，例如點擊)，就會進入此plan。

當流程確定進入plan之中，便會執行其Action。在上面的步驟裡面，我們設定了TTS 的Task在Action中。一旦Action的條件滿足(在此都是選擇always)，就會執行Task以及設定output context。

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

Step 6.Belief

本步驟教學Belief(變數)的抽取以及使用

[6-1]按下Intent的tab

[6-2]點選Intent ”各種動物的叫聲”

[6-3]點選橘色animal的Tag

[6-4]選擇Set Belief

[6-5]填寫animal_name至 Name欄位

備註:

在此是將belief name設定為 animal_name

[6-7]點選Plan tab

[6-8]進入Plan ”myFirstPlan”

[6-9]看頁面最下方的belief，並且點擊+New belief

[6-10]選擇ID為剛剛設定的 animal_name

[6-11]點擊Define Class

[6-12]點選class 至 animal

[6-13]確定Required為required

備註:

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

[6-14]更改此plan的TTS為“好的，為您播放{animal_name}的叫聲!”

備註:

{animal_name}為引用belief(目前僅在TTS 與 Condition引用)

這裡主要是教學先在intent裡面設定belief擷取，讓動物名稱(例如老虎)會被設入animal_name。最後在plan中，設定好對應的belief ID 以及Class(Concept)，就可以使用該Belief。最後在TTS使用此Belief，說出 “為您播放老虎的叫聲”。

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特定資訊。

Step 7. Publish

完成一個完整的domain之後，就需要將configuration publish至server，然後進行測試。

[7-1]按下編輯器右上角的Publish

[7-2]先跳出對你當下的APP Config檢測結果

[7-3]確認完點擊Continue To Publish

[7-4]跳出對話視窗告知你SLU(Spoken Language Understanding) 的 data 有無異常

[7-5]確認正常後按下 “Continue To Publish”，然後得到成功訊息即完成Publish

Step 8. 測試

在DDE的右側，有簡單的測試視窗提供給開發者。按下麥克風可以透過口說的方式進行對話，或者也可以輸入文字到有放大鏡的欄位。

[8-1]鍵入我要用asus動物王聽叫聲

[8-2]觀察右下方資訊，可以看到被對應到哪個Domain、Plan以及Output Contexts等資訊。

[8-3]最後再輸入 我想要聽老虎的叫聲

[8-4]觀看結果，發現的確有串到下一個Plan “”。(如果放置成錯誤的Lang，測試中文的時候會沒有任何回應)。

[8-5]繼續將結果往下拉觀察

可以看到成功地進入正確的domain、plan以及belief。

本教學提供簡易使用DDE來建立domain。如果想知道如何建立在Zenbo上與建立好的domain進行測試，請繼續往下看Zenbo的對話建立與載入(apk 篇)

文件。如果想更深入的學習如何使用DDE強大的語句編輯功能，請點選左側Basic Concepts學習。

Appendix

匯入與載出
我們可以將資料利用匯出而存至外部空間，也可以將匯出的資料載入回DDE。可以分兩種型式
- Export/Import Partial Config
  - 整個Domain匯出。
- Export/Import/Append Partial Config
  - 僅匯出/載入部分的Config。

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

Lang為該欄位的語言設定，如果Zenbo Device的整體語系與被設定的語系相符時，才會將輸入的資料載入。我們以Instance為例:
- 當Device語系偵測為繁體中文時會載入上列詞彙。所以會知道Tiger與老虎是同義詞，並不是語系設定為繁體中文，該欄位裡面就必須全部為繁體中文。