開發自定義命令應用程式
重要
自定義命令將於 2026 年 4 月 30 日淘汰。 自 2023 年 10 月 30 日起,您無法在 Speech Studio 中建立新的自定義命令應用程式。 與此變更相關, LUIS 將於 2025 年 10 月 1 日淘汰。 自 2023 年 4 月 1 日起,您無法建立新的 LUIS 資源。
在本操作說明文章中,您將瞭解如何開發及設定自定義命令應用程式。 自定義命令功能可協助您建置專為語音優先互動體驗優化的豐富語音命令應用程式。 此功能最適合工作完成或命令控制案例。 它非常適合物聯網(IoT)裝置,以及環境與無頭裝置。
在本文中,您會建立可以開啟和關閉電視、設定溫度,以及設定警示的應用程式。 建立這些基本命令之後,您將瞭解下列自定義命令的選項:
- 將參數新增至命令
- 將組態新增至命令參數
- 建置互動規則
- 建立語音響應的語言產生範本
- 使用自訂語音工具
使用簡單命令建立應用程式
從建立空的自定義命令應用程式開始。 如需詳細資訊,請參閱 快速入門。 在此應用程式中,您會建立空白專案,而不是匯入專案。
在 [ 名稱] 方塊中,輸入專案名稱 Smart-Room-Lite (或您選擇的另一個名稱)。
在 [語言] 列表中,選取 [英文][美國]。
選取或建立 LUIS 資源。
更新 LUIS 資源 (選擇性)
您可以更新您在 [新增專案] 視窗中選取的製作資源。 您也可以設定預測資源。
當您的自定義命令應用程式發佈時,會使用預測資源進行辨識。 在開發和測試階段,您不需要預測資源。
新增 TurnOn 命令
在您建立的空白 Smart-Room-Lite 自定義命令應用程式中,新增命令。 命令會處理語句 Turn on the tv
。 它會以訊息 Ok, turning the tv on
回應。
- 選取 左窗格頂端的 [新增] 命令,以建立新的命令 。 [ 新增] 命令 視窗隨即開啟。
- 針對 [ 名稱] 欄位,提供值
TurnOn
。 - 選取 建立。
中間窗格會列出命令的屬性。
下表說明命令的組態屬性。 如需詳細資訊,請參閱 自定義命令概念和定義。
組態 | 描述 |
---|---|
範例句子 | 使用者可以說來觸發此命令的範例語句。 |
參數 | 完成命令所需的資訊。 |
完成規則 | 要採取的動作來完成命令。 範例:回應使用者或與 Web 服務通訊。 |
互動規則 | 處理更特定或複雜情況的其他規則。 |
新增範例句子
在 [ 範例句子] 區 段中,您會提供使用者可以說出什麼範例。
在中間窗格中,選取 [範例句子]。
在右側的窗格中,新增範例:
Turn on the tv
在窗格頂端,選取 [ 儲存]。
您還沒有參數,因此您可以移至 [完成規則 ] 區段。
新增完成規則
接下來,命令需要完成規則。 此規則會告知使用者正在採取履行動作。
如需規則和完成規則的詳細資訊,請參閱 自定義命令概念和定義。
選取預設完成規則 [完成]。 然後編輯它,如下所示:
設定 建議的值 名描述 名稱 ConfirmationResponse
描述規則用途的名稱 條件 無 決定規則執行時機的條件 動作 傳送語音回應>簡單編輯器> Ok, turning the tv on
規則條件為 true 時要採取的動作 選取 [ 儲存] 以儲存動作。
回到 [ 完成規則] 區段中,選取 [ 儲存 ] 以儲存所有變更。
注意
您不需要使用命令隨附的預設完成規則。 您可以刪除預設完成規則,並新增您自己的規則。
新增 SetTemperature 命令
現在再新增一個命令, SetTemperature
。 這個指令會採用單一語句 , Set the temperature to 40 degrees
並使用 訊息 Ok, setting temperature to 40 degrees
回應 。
若要建立新的指令,請遵循您用於 TurnOn
命令的步驟,但使用範例句子 Set the temperature to 40 degrees
。
然後編輯現有的 完成 完成規則,如下所示:
設定 | 建議的值 |
---|---|
名稱 | ConfirmationResponse |
條件 | 無 |
動作 | 傳送語音回應>簡單編輯器>第一個變化>Ok, setting temperature to 40 degrees |
選取 [ 儲存] 以儲存命令的所有變更。
新增 SetAlarm 命令
建立新的 SetAlarm
命令。 使用範例句子 Set an alarm for 9 am tomorrow
。 然後編輯現有的 完成 完成規則,如下所示:
設定 | 建議的值 |
---|---|
名稱 | ConfirmationResponse |
條件 | 無 |
動作 | 傳送語音回應>簡單編輯器>第一個變化>Ok, setting an alarm for 9 am tomorrow |
選取 [ 儲存] 以儲存命令的所有變更。
試試看
使用測試窗格測試應用程式的行為:
- 在窗格右上角,選取 [ 訓練] 圖示。
- 定型完成時,選取 [ 測試]。
使用語音或文字試用下列語句範例:
- 您輸入: 將溫度設定為 40 度
- 預期回應:確定,將溫度設定為40度
- 您輸入: 開啟電視
- 預期的回應:好吧,打開電視
- 您輸入: 明天上午 9 點設定警示
- 預期回應:確定,明天上午 9 點設定警示
提示
在測試窗格中,您可以選取 [回合詳細 數據] 以取得如何處理此語音輸入或文字輸入的相關信息。
將參數新增至命令
在本節中,您將瞭解如何將參數新增至命令。 命令需要參數才能完成工作。 在複雜的案例中,參數可用來定義觸發自定義動作的條件。
設定 TurnOn 命令的參數
從編輯現有的 TurnOn
命令開始,以開啟和關閉多個裝置。
現在命令會同時處理開啟和關閉案例,請將命令重新命名為 TurnOnOff。
在左側窗格中,選取 TurnOn 命令。 然後在窗格頂端的 [新增] 命令旁,選取 [編輯] 按鈕。
在 [ 重新命名] 命令 視窗中,將名稱變更為 TurnOnOff。
將新的參數新增至 命令。 參數代表使用者是否想要開啟或關閉裝置。
在中間窗格頂端,選取 [ 新增]。 從下拉功能表中,選取 [參數]。
在右邊窗格的 [參數] 區段中,於 [名稱] 方塊中新增
OnOff
。選取必要。 在 [ 新增必要參數 的回應] 視窗中,選取 [ 簡單編輯器]。 在 [ 第一個變化 ] 字段中,新增 [開啟] 或 [關閉]。
選取更新。
使用下表設定參數的屬性。 如需命令所有組態屬性的相關信息,請參閱 自定義命令概念和定義。
組態 建議的值 名描述 名稱 OnOff
參數的描述性名稱 必要 Selected 複選框,指出此命令完成之前是否需要此參數的值。 必要參數的回應 簡單編輯器> On or Off?
當這個參數未知時,詢問此參數值的提示。 型別 String 參數類型,例如 Number、String、Date Time 或 Geography。 Configuration 接受來自內部目錄的預先定義輸入值 對於字串,此設定會將輸入限制為一組可能的值。 預先定義的輸入值 on
,off
一組可能的值及其別名。 若要新增預先定義的輸入值,請選取 [新增預先定義的輸入]。 在 [ 新增專案 ] 視窗中,輸入 [名稱 ],如上表所示。 在此情況下,您不會使用別名,因此您可以將此欄位保留空白。
選取 [ 儲存] 以儲存參數的所有組態。
新增 SubjectDevice 參數
若要新增第二個參數來代表可以使用此命令控制的裝置名稱,請選取 [ 新增]。 使用下列組態。
設定 建議的值 名稱 SubjectDevice
必要 Selected 必要參數的回應 簡單編輯器> Which device do you want to control?
型別 String Configuration 接受來自內部目錄的預先定義輸入值 預先定義的輸入值 tv
,fan
別名 ( tv
)television
,telly
選取 [儲存]。
修改範例句子
對於使用參數的命令,新增涵蓋所有可能組合的範例句子會很有説明。 例如:
- 完整參數資訊:
turn {OnOff} the {SubjectDevice}
- 部分參數資訊:
turn it {OnOff}
- 沒有參數資訊:
turn something
使用不同程度資訊的範例句子可讓自定義命令應用程式使用部分資訊來解析單次解析度和多回合解析度。
考慮到該資訊,請編輯範例句子以使用這些建議的參數:
turn {OnOff} the {SubjectDevice}
{SubjectDevice} {OnOff}
turn it {OnOff}
turn something {OnOff}
turn something
選取 [儲存]。
提示
在範例句子編輯器中,使用大括弧來參考您的參數。 例如: turn {OnOff} the {SubjectDevice}
。
使用索引標籤來自動完成先前建立的參數。
修改完成規則以包含參數
變更現有的完成規則 ConfirmationResponse
。
在 [條件] 區段中,選取 [新增條件]。
在 [ 新增條件] 視窗中的 [ 類型 ] 列表中,選取 [ 必要參數]。 在下列清單中,選取 [OnOff ] 和 [SubjectDevice]。
選取 建立。
在 [ 動作] 區段中,將滑鼠停留在 [動作] 上方並選取 [編輯] 按鈕,以編輯 [傳送語音回應 ] 動作。 這次,請使用新建立
OnOff
的參數SubjectDevice
:Ok, turning the {SubjectDevice} {OnOff}
選取 [儲存]。
選取右側窗格頂端的 [ 定型 ] 圖示,以試用變更。
定型完成時,選取 [ 測試]。 [ 測試您的應用程式 ] 視窗隨即出現。 請嘗試下列互動:
- 輸入: 關閉電視
- 輸出:確定,關閉電視
- 輸入: 關閉電視
- 輸出:確定,關閉電視
- 輸入: 將其關閉
- 輸出:您要控制的裝置為何?
- 輸入: 電視
- 輸出:確定,關閉電視
設定 SetTemperature 命令的參數
SetTemperature
修改 命令以啟用它,以將溫度設定為使用者指示。
TemperatureValue
新增參數。 使用下列組態:
組態 | 建議的值 |
---|---|
名稱 | TemperatureValue |
必要 | Selected |
必要參數的回應 | 簡單編輯器>What temperature would you like? |
類型 | Number |
編輯範例語句以使用下列值。
set the temperature to {TemperatureValue} degrees
change the temperature to {TemperatureValue}
set the temperature
change the temperature
編輯現有的完成規則。 使用下列組態。
組態 | 建議的值 |
---|---|
條件 | 必要參數>TemperatureValue |
動作 | 傳送語音回應>Ok, setting temperature to {TemperatureValue} degrees |
設定 SetAlarm 命令的參數
新增名為 DateTime
的參數。 使用下列組態。
設定 | 建議的值 |
---|---|
名稱 | DateTime |
必要 | Selected |
必要參數的回應 | 簡單編輯器>For what time? |
類型 | DateTime |
日期預設值 | 如果遺漏日期,請使用今天。 |
時間預設值 | 如果遺漏時間,請使用當天的開始時間。 |
注意
本文主要使用 String、Number 和 DateTime 參數類型。 如需所有支持的參數類型及其屬性的清單,請參閱 自定義命令概念和定義。
編輯範例語句。 請使用下面的值。
set an alarm for {DateTime}
set alarm {DateTime}
alarm for {DateTime}
編輯現有的完成規則。 使用下列組態。
設定 | 建議的值 |
---|---|
動作 | 傳送語音回應>Ok, alarm set for {DateTime} |
使用與不同命令相關的語句,一起測試三個命令。 (您可以在不同的命令之間切換。
- 輸入: 設定警示
- 輸出:時間為何?
- 輸入: 開啟電視
- 輸出:確定,開啟電視
- 輸入: 設定警示
- 輸出:時間為何?
- 輸入: 下午 5 點
- 輸出:確定,已設定警示
2020-05-01 17:00:00
將組態新增至命令參數
在本節中,您將深入了解進階參數設定,包括:
- 參數值如何屬於自定義命令應用程式外部定義的集合。
- 如何在參數值上新增驗證子句。
將參數設定為外部目錄實體
自定義命令功能可讓您設定字串類型參數,以參考透過 Web 端點裝載的外部目錄。 因此,您可以獨立更新外部目錄,而不需編輯自定義命令應用程式。 在目錄專案眾多的情況下,此方法很有用。
SubjectDevice
從命令重複使用 參數TurnOnOff
。 此參數的目前組態是 接受來自內部目錄的預先定義輸入。 此組態是指參數位態中的裝置靜態清單。 將此內容移至可以獨立更新的外部數據源。
若要移動內容,請從新增 Web 端點開始。 在左側窗格中,移至 [Web 端點] 區 段。 新增 Web 端點 URL。 使用下列組態。
設定 | 建議的值 |
---|---|
名稱 | getDevices |
URL | <Your endpoint of getDevices.json> |
方法 | 取得 |
然後,設定並裝載會傳回 JSON 檔案的 Web 端點,該檔案會列出可控制的裝置。 Web 端點應該會傳回格式如下的 JSON 檔案:
{
"fan" : [],
"refrigerator" : [
"fridge"
],
"lights" : [
"bulb",
"bulbs",
"light",
"light bulb"
],
"tv" : [
"telly",
"television"
]
}
接下來,移至 SubjectDevice 參數設定頁面。 設定下列屬性。
設定 | 建議的值 |
---|---|
Configuration | 接受來自外部目錄的預先定義輸入 |
目錄端點 | getDevices |
方法 | 取得 |
然後選取儲存。
重要
除非您已在左側窗格的 [Web 端點] 區段中設定 Web 端點 ,否則不會看到設定參數以接受外部目錄輸入的選項。
選取 [定型] 來試試看。 定型完成後,選取 [ 測試 ] 並嘗試一些互動。
- 輸入: 開啟
- 輸出:您要控制的裝置為何?
- 輸入: 燈光
- 輸出:確定,開啟燈
注意
您現在可以控制裝載在 Web 端點上的所有裝置。 但您仍然需要將應用程式定型,以測試新的變更,然後重新發佈應用程式。
將驗證新增至參數
驗證是適用於特定參數類型的建構,可讓您設定參數值的條件約束。 如果值不落在條件約束內,它們會提示您進行更正。 如需擴充驗證建構的參數類型清單,請參閱 自定義命令概念和定義。
使用 SetTemperature
命令測試驗證。 使用下列步驟來新增 參數的 Temperature
驗證。
在左側窗格中,選取 SetTemperature 命令。
在中間窗格中,選取 [ 溫度]。
在右側的窗格中,選取 [新增驗證]。
在 [ 新增驗證] 視窗中,設定驗證,如下表所示。 然後選取建立。
參陣組態 建議的值 描述 最小值 60
針對 Number 參數,此參數可以假設的最小值 最大值 80
針對 Number 參數,此參數可以假設的最大值 失敗回應 簡單編輯器>第一個變化> Sorry, I can only set temperature between 60 and 80 degrees. What temperature do you want?
如果驗證失敗,要求新值的提示
選取右側窗格頂端的 [ 定 型] 圖示來試試看。 定型完成後,選取 [ 測試]。 請嘗試一些互動:
- 輸入: 將溫度設定為72度
- 輸出:確定,將溫度設定為72度
- 輸入: 將溫度設定為45度
- 輸出:很抱歉,我只能設定 60 度到 80 度之間的溫度
- 輸入: 改為將其設為72度
- 輸出:確定,將溫度設定為72度
新增互動規則
互動規則是處理特定或複雜情況的額外規則。 雖然您可以自由撰寫自己的互動規則,但在此範例中,您會針對下列案例使用互動規則:
- 確認命令
- 將單步驟更正新增至命令
如需互動規則的詳細資訊,請參閱 自定義命令概念和定義。
將確認新增至命令
若要新增確認,您可以使用 SetTemperature
命令。 若要達成確認,請使用下列步驟建立互動規則:
在左側窗格中,選取 SetTemperature 命令。
在中間窗格中,選取 [新增],以新增互動規則。 然後選取 [互動規則>確認] 命令。
此動作會新增三個互動規則。 規則會要求使用者確認警示的日期和時間。 他們期待下一輪確認(是或否)。
使用下列組態修改 Confirm 命令互動規則:
- 將名稱變更為 [確認溫度]。
- 已設定 [所有必要參數] 條件。
- 新增動作: 輸入>傳送語音回應>您確定要將溫度設定為 {TemperatureValue} 度嗎?
- 在 [期望] 區段中,保留 [預期確認使用者] 的預設值。
修改確認成功互動規則以處理成功的確認(使用者說是)。
- 將名稱變更為 確認溫度成功。
- 讓現有的 確認條件保持成功 。
- 新增條件:輸入>必要參數>TemperatureValue。
- 將預設 的執行后狀態 值保留為 [執行完成規則]。
修改確認拒絕互動規則,以在確認遭到拒絕時處理案例(使用者表示否)。
- 將名稱變更為 拒絕確認溫度。
- 保留現有的 確認遭到 拒絕的條件。
- 新增條件:輸入>必要參數>TemperatureValue。
- 新增動作:輸入>傳送語音響應>沒有問題。然後是什麼溫度?
- 將預設 的執行后狀態 值變更為 [等候使用者輸入]。
重要
在本文中,您會使用內建的確認功能。 您也可以手動新增互動規則。
選取 [定型] 以試用變更。 定型完成時,選取 [ 測試]。
- 輸入: 將溫度設定為80度
- 輸出:您確定要將溫度設定為80度嗎?
- 輸入: 否
- 輸出:沒有問題。 然後是什麼溫度?
- 輸入: 72 度
- 輸出:您確定要將溫度設定為 72 度嗎?
- 輸入: 是
- 輸出:確定,將溫度設定為72度
在命令中實作更正
在本節中,您會設定單步驟修正。 執行履行動作之後,會使用此更正。 如果命令尚未完成,您也會看到預設如何啟用更正的範例。 若要在指令未完成時新增更正,請新增 參數 AlarmTone
。
在左窗格中,選取 SetAlarm 命令。 然後新增參數 AlarmTone。
- 名稱>
AlarmTone
- 類型>字串
- 預設值>Chimes
- 組態>接受來自內部目錄的預先定義輸入值
- 預先定義的輸入值>Chimes、 Jingle 和 Echo (這些值是個別預先定義的輸入。
接下來,將 DateTime 參數的回應更新為 [準備] 以音調設定為 {AlarmTone}。時間為何?。 然後修改完成規則,如下所示:
- 選取現有的完成規則 ConfirmationResponse。
- 在右側的窗格中,將滑鼠停留在現有的動作上,然後選取 [ 編輯]。
- 將語音回應更新為
OK, alarm set for {DateTime}. The alarm tone is {AlarmTone}
。
重要
警示音調可以在進行中的命令中變更,而不需要任何明確的設定。 例如,當命令尚未完成時,它可以變更。 如果命令尚未完成,則所有命令參數預設都會啟用更正,而不論回合號碼為何。
完成命令時實作更正
即使命令完成,自定義命令平臺仍允許進行單步驟修正。 此功能預設不會啟用。 它必須明確設定。
使用下列步驟來設定單步驟修正:
- 在 SetAlarm 命令中,新增 Update previous 命令類型的互動規則,以更新先前設定的警示。 將互動規則重新命名為 更新先前的警示。
- 保留預設條件: 必須更新上一個命令。
- 新增條件:輸入>必要的參數>DateTime。
- 新增動作:輸入>傳送語音回應>簡單編輯器>將先前的警示時間更新至 {DateTime}。
- 將預設 的執行后狀態 值保留為 Command 完成。
選取 [定型] 以試用變更。 等候定型完成,然後選取 [ 測試]。
- 輸入: 設定警示。
- 輸出:準備好以音調設定警示作為 Chimes。 時間為何?
- 輸入: 明天上午 9 點,將音調設為靜樂。
- 輸出:確定,針對 設定
2020-05-21 09:00:00
警示。 警鐘的語氣是靜樂。 - 輸入: 否,上午 8 點。
- 輸出:將先前的警示時間更新為 2020-05-29 08:00。
注意
在實際的應用程式中, 在此更正規則的 [動作 ] 區段中,您也需要將活動傳回給用戶端,或呼叫 HTTP 端點來更新系統中的警示時間。 此動作應該只負責更新警示時間。 它不應該負責命令的任何其他屬性。 在此情況下,該屬性會是警示音調。
新增語音響應的語言產生範本
語言產生 (LG) 範本可讓您自定義傳送給客戶端的回應。 它們會將變異數引入回應。 您可以使用下列項目來達成語言產生:
- 語言產生範本。
- 自適性表達式。
自定義命令範本是以 Bot Framework 的 LG 範本為基礎。 因為自定義命令功能會在需要時建立新的 LG 範本(針對參數或動作中的語音回應),因此您不需要指定 LG 範本的名稱。
因此,您不需要像這樣定義範本:
# CompletionAction
- Ok, turning {OnOff} the {SubjectDevice}
- Done, turning {OnOff} the {SubjectDevice}
- Proceeding to turn {OnOff} {SubjectDevice}
相反地,您可以定義沒有名稱的範本主體,如下所示:
這項變更會對傳送至用戶端的語音回應帶來變化。 針對語句,會隨機挑選所提供選項中的對應語音回應。
藉由利用 LG 範本,您也可以使用調適型運算式來定義命令的複雜語音回應。 如需詳細資訊,請參閱 LG 範本格式。
根據預設,自定義命令功能支援所有功能,但有下列次要差異:
- 在 LG 範本中,實體會表示為
${entityName}
。 自定義命令功能不會使用實體。 但是您可以使用參數做為變數,搭配${parameterName}
表示法或{parameterName}
表示法。 - 自定義命令功能不支援範本組合和擴充,因為您永遠不會直接編輯 .lg 檔案。 您只會編輯自動建立範本的回應。
- 自訂命令功能不支援 LG 插入的自訂函式。 支援預先定義的函式。
- 自訂命令功能不支援選項,例如
strict
、replaceNull
與lineBreakStyle
。
將範本回應新增至 TurnOnOff 命令
TurnOnOff
修改 命令以新增參數。 使用下列組態。
設定 | 建議的值 |
---|---|
名稱 | SubjectContext |
必要 | 未選取 |
型別 | String |
預設值 | all |
Configuration | 接受來自內部目錄的預先定義輸入值 |
預先定義的輸入值 | room 、 、 bathroom all |
修改完成規則
編輯現有完成規則 ConfirmationResponse 的 [動作] 區段。 在 [ 編輯動作] 視窗中,切換至 [ 範本編輯器]。 然後將文字取代為下列範例。
- IF: @{SubjectContext == "all" && SubjectDevice == "lights"}
- Ok, turning all the lights {OnOff}
- ELSEIF: @{SubjectDevice == "lights"}
- Ok, turning {OnOff} the {SubjectContext} {SubjectDevice}
- ELSE:
- Ok, turning the {SubjectDevice} {OnOff}
- Done, turning {OnOff} the {SubjectDevice}
使用下列輸入和輸出來定型和測試您的應用程式。 請注意回應的變化。 變化是由範本值的多個替代專案所建立,也由調適型運算式使用所建立。
- 輸入: 開啟電視
- 輸出:確定,開啟電視
- 輸入: 開啟電視
- 輸出:完成,開啟電視
- 輸入: 關閉燈光
- 輸出:確定,關閉所有燈
- 輸入: 關閉會議室燈
- 輸出:確定,關閉房間燈
使用自訂語音
自訂「自訂命令」回應的另一種方式是選取輸出語音。 使用下列步驟將預設語音切換為自訂語音:
- 在自定義命令應用程式中,選取左側窗格中的 [設定]。
- 在中間窗格中,選取 [自定義語音]。
- 在資料表中,選取自定義語音或公用語音。
- 選取 [儲存]。
現在應用程式會以選取的語音回應,而不是默認語音。
下一步
- 瞭解如何 使用語音 SDK 將自定義命令應用程式 與用戶端應用程式整合。
- 使用 Azure DevOps 為您的自訂命令應用程式設定持續部署 。