Oracle Cloud Infrastructureドキュメント

ダイアログ・フロー定義

ダイアログ・フロー定義は、会話自体のモデルであり、スキルとそのユーザー間の対話を反復できます。

スキル・ビルダーを使用して、OBotMLでのユーザー強制終了交換のフレームワーク、Digital Assistant独自のYAML実装を定義します。 これは、スキルが示す内容と内容の両方に関してダイアログを記述できる、単純なマークアップ言語です。

サンプルの会話に基づいて作業スキルを生成できる会話デザイナを確認することもできます。 これは、プロトタイプとして使用する作業スキルを迅速に開発するための便利な方法です。 「会話デザイナ」も参照してください。

ダイアログ・フローの構造

OBotML定義は3つの主要な部分に分かれています: contextdefaultTransitionsおよびstates contextノード内のセッションで使用可能な変数を定義します。 フロー自体の定義については、statesの項で説明しています。 ダイアログ・フローは、metadataノードから開始されます。この場合、platformVersionはOracle Digital Assistantのプラットフォーム・バージョンを識別します。 バージョン番号は常に二重引用符("1.1")で囲みます。 ダイアログ・フローは、次のようにレイアウトされています:
metadata:
  platformVersion: "1.1"
main: true
name: "HelloKids"
context:
  variables:
    variable1: "entity1"
    variable2: "error"
...
States      
    state1:
      component: "a custom or built-in component" 
      properties: 
        property1: "component-specific property value"
        property2: "component-specific property value"
      transitions:
        actions:
          action1: "value1"
          action2: "value2"
    state2:
      component: "a custom or built-in component" 
      properties: 
        property1: "component-specific property value"
        property2: "component-specific property value"
      transitions:
        actions:
          action1: "value1"
          action2: "value2"
...

コンテキスト・ノード

contextノード内で定義する変数は、intstringbooleandoublefloatなどのプリミティブ・タイプです。 変数はマップ(JSONオブジェクト)として定義することも、変数を使用してエラー処理を記述することもできます。

次のスニペットに示すように、PizzaBotダイアログのフロー定義では、組込みまたはカスタム・エンティティ(この場合は、PizzaSizeおよびPizzaCrustの変数)の変数に名前を付けることができます。 組込みエンティティやカスタム・エンティティに加えて、ユーザー入力から解決されるインテントを保持するnlpresultエンティティの変数も宣言できます。 これらの変数は、フロー全体にスコープ指定されます。 「OBotMLでのダイアログ・フローの記述方法」には、ダイアログ・フローの様々な部分をアセンブルする方法が示されています。 ユーザー変数の値をスコープ設定して、ボットがユーザーを認識し、最初の会話の後にユーザー・プリファレンスを保持できるようにすることもできます。 「ユーザー・スコープ変数」では、これらの変数について説明します。
metadata:
  platformVersion: "1.1"
main: true
name: "PizzaBot"
context:
  variables:
    size: "PizzaSize"
    type: "PizzaType"
    crust: "PizzaCrust"
    iResult: "nlpresult"

defaultTransitionsノード

2つの場所に遷移を設定できます: ダイアログ・フロー状態またはdefaultTransitionsノードにあるコンポーネント定義の一部として。 このノードはグローバル・ナビゲーションを設定します。 例えば:
defaultTransitions
  next: "..."
  error: "..."
  actions:
    action_name1: "..."
    action_name2: "..."
   
デフォルトの遷移は、状態内に遷移が定義されていない場合や遷移のトリガーに必要な条件を満たさない場合にトリガーされるというフォールバックとして機能します。
defaultTransitionsノードを使用して、ボット・スキルが予期しないユーザーのアクションを正常に処理できるようルーティングを定義します。 特に、ユーザーが前回の返信でオプションをタップしたときに、そのスキルを使用して、ボットで現在(さらに適切な)返信のいずれかのオプションではなく、以前の返信内のオプションを適切に反応できるようにすることができます。 次のスニペットでNONEアクションに示すように、この遷移を、すべての予期しないアクションを処理する状態にルーティングするように構成できます。
defaultTransitions:
  error: "globalErrorHandler"
 ...
globalErrorHandler:
  component: System.Switch
  properties:
   source: "${system.errorState}"
   values:
   - "getOrderStatus"
   - "displayOrderStatus"
   - "createOrder"
  transitions:
    actions:
      NONE: "unhandledError"
      getOrderStatus: "handleOrderStatusError"
      displayOrderStatus: "handleOrderStatusError"
      createOrder: "handleOrderStatusError"

状態ノード

ダイアログの各ビットとその関連操作は、ダイアログ・フロー内のロジックを管理する一連の遷移状態として定義します。 アクションをキューに入れるために、OBotML定義内の各stateノードは、ダイアログのそのポイントで必要とされる機能を提供するコンポーネントの名前を付けます。 状態は基本的にコンポーネントの周りに構築されます。 コンポーネント固有のプロパティが含まれ、コンポーネントの実行後にトリガーされる他の状態への遷移が定義されます。
  state_name:
    component: "component_name"
    properties:
      component_property: "value"
      component_proprety: "value"
    transitions:
      actions:
        action_string1: "go_to_state1"
        action_string2: "go_to_state2"
状態定義には、コンポーネントに固有の遷移、または任意のコンポーネントに対して定義できる標準のnexterroractionsまたはreturn遷移(「フロー・ナビゲーションおよび遷移」を参照)が含まれます。 状態内の遷移セットは、defaultTransitionsノードに定義されているグローバル遷移でオーバーライドできます。
PizzaBotには、顧客の年齢を検証する一連のstateノードが含まれています。 これらの状態には、ユーザーが入力した整数値を取得してチェックし、必要に応じてテキスト文字列を出力するコンポーネントが含まれています。 プロセスを開始するために、askageの状態のコンポーネントはユーザー入力をリクエストし、checkAge状態に移動します。この状態では、AgeCheckerコンポーネントがユーザー入力を検証します。 ここでは、ダイアログは司法です: transitionsキーによって、blockまたはallowの状態が定義されます。 allowの状態がトリガーされると、ユーザーは処理を続行できます。 後続の状態定義では、ユーザーのコンテキストを保存するために、ユーザーの順序が完了するまでユーザー入力が追跡されます。 ただし、ユーザー入力によってAgeCheckerコンポーネントでblockアクションがトリガーされる場合、ダイアログがunderageの状態に遷移するため、会話はサブページ・ユーザーに対して終了します。
metadata:
platformVersion: "1.1"
main: true
name: "PizzaBot"
context:
  variables:
    size: "PizzaSize"
    type: "PizzaType"
    crust: "PizzaCrust"
    cheese: "CheeseType"
    iResult: "nlpresult"
...

  askage:
    component: "System.Output"
    properties:
      text: "How old are you?"
    transitions: {}
  checkage:
    component: "AgeChecker"
    properties:
      minAge: 18
    transitions:
      actions:
        allow: "crust"
        block: "underage"
  crust:
    component: "System.List"
    properties:
      options: "Thick,Thin,Stuffed,Pan"
      prompt: "What crust do you want for your Pizza?"
      variable: "crust"
    transitions: {}
...
    underage:
    component: "System.Output"
    properties:
      text: "You are too young to order a pizza"
    transitions:
      return: "underage"

OBotMLでのダイアログ・フローの記述方法

OBotMLでは、単純な構文を使用して、変数を設定し、状態を定義します。 これはYAMLのバリアントであるため、ダイアログ・フローを定義するときには、YAML間隔の規則に留意してください。 最初から始める必要はありません。 かわりに、デフォルトのダイアログ・フロー定義を基本的なテンプレートとして使用できます。
ダイアログの上部のメタデータ定義とともに、テンプレートにはすでにcontextおよびstatesのノードがあるため、既存のボイラープレートを削除して独自のコンテンツを追加するだけで済みます。 構文的に発音のある状態定義の作成に役立つように、コンポーネントの追加のメニューのコンポーネント・テンプレートを使用します。 変数の設定と状態の定義のヒントは、「ダイアログ・フロー構文」を参照してください。
ノート

検証をクリックし、ダイアログ・フローを書き込むときにロガーのウィンドウ(これはデバッグ・アイコンのイメージです。)を確認します。

ダイアログ・フロー構文

操作方法 これを使用
ダイアログ・フロー全体でコンテキストを保持する変数を設定します。
contextノード内で、次の構文を使用 : variablename: "variableType" 例:
main: true
name: "FinancialBotMainFlow"
context:
  variables:
    accountType: "AccountType"
    txnType: "TransactionType"
    txnSelector: "TransactionSelector"
    toAccount: "ToAccount"
    spendingCategory: "TrackSpendingCategory"
    paymentAmount: "string"

変数は、エンティティ(AccountTypeToAccountなど)として、プリミティブ(paymentAmount: “string”)として定義できます。

スキルのエラー・ハンドラを定義しますか。
エラーを処理する状態を指すdefaultTransitionsノードを定義します。 通常、この状態およびダイアログ・ボックス定義の最後を追加します。 例えば:
context:
  variables:
    iresult: "nlpresult"
defaultTransitions:
  next: "ImplicitTransitionDetected"
  error: "MyErrorState"
...
states:
...
  MyErrorState
    component: "System.Output"
    properties:
      text: "Problem detected in \"${system.errorState}\" state."
    transitions:
      return: "done"          
  

「予期しないアクションのダイアログ・フローの構成」を参照してください。

解決済済インテントの値を保持する変数を定義しますか?
contextノードで、nlpresultエンティティを指定する変数を定義します。 その名前が示すように("nlp"は自然言語処理を表します)、このエンティティはインテント・エンジンによって解決されるインテントを抽出します。 ほぼすべての参照ボットがnlpresult変数を宣言します。 例えば:
main: true
name: "FinancialBotMainFlow"
context:
  variables:
    iResult: "nlpresult"
ユーザー入力に基づいてダイアログ・フローを制御しますか。

通常(常にではありませんが)インテント・エンジンから結果を返すSystem.Intentコンポーネントのnlpresult variableプロパティを定義します。 System.Intentも参照してください。

FinancialBotダイアログ・フローの次のスニペットでは、System.Intentコンポーネントはnlpresult変数(iResult)により戻される値に基づいて先に進むようにダイアログ・エンジンに指示します。 「ダイアログ・フローの構造」で説明しているように、フローのcontextノードでnlpresult変数を宣言し、解決済インテント(iResult:”nlpresult”)を保持できます。 actionsノードで指定された状態によって定義される、可能性のある結果は、信頼度しきい値プロパティも前提となっています。 このオプションのプロパティは、インテント・エンジンによって指定される確率的スコアに対して設定できます。 このSystem.Intentコンポーネントのこの定義は、ユーザー・データ解析時の精度率が40%以上である解決済のインテントに一致する次の状態に移動するようダイアログ・エンジンに指示します。 「信頼度しきい値の動作」も参照してください。

未解決のインテントを処理するためにスキルを配分しますか。

System.IntentunresolvedIntentアクションの状態を定義します。unresolvedIntentは、最小信頼度しきい値内で解決できなかったメッセージを追跡することを求めるインテントです。 このインテントを使用して品質レポートをフィルタする方法は、「失敗レポートの実行」を参照してください。

例:
unresolvedIntent: "unresolved"
...
  unresolved:
    component: "System.Output"
    properties:
      text: "Sorry I don't understand that question!"
    transitions:
      return: "unresolved"
コンポーネントが変数値にアクセスできるようにしますか。
.valueプロパティを式(${crust.value})で使用します。 デフォルト値を置換するには、${variable.value!"default value"}を使用します。 たとえば、thick${crust.value!"thick"}のデフォルト値です。 例えば:
context:
  variables:
    size: "PizzaSize"
    confirm: "YES_NO"
    ...
  confirmState:
    component: "System.List"
      properties:
      options: "Yes,No"
      prompt: "You ordered a ${size.value} pizza. Is this correct?"
      variable: "confirm"
...

変数にnull値が返される可能性が高い場合、Apache FreeMarkerのデフォルト演算子(${variable.value!"default value"})を使用します。 この演算子は、システムおよびカスタム・コンポーネントで使用される変数のvalue定義や、transitions定義で状態を指定する変数など、フロー内で変数の置換を定義する任意の場所で使用できます。 「System.Outputコンポーネントの値式の定義」も参照してください。

再訪に備えてユーザー値を保存します。
状態定義内で、user.プレフィクスを持つ変数定義を追加します。 「ユーザー値設定用の組込みコンポーネント」も参照してください。 例えば:
 checklastorder:
    component: "System.ConditionExists"
    properties:
      variable: "user.lastpizza"

ユーザー変数の詳細は、PizzaBotWithMemory参照ボットのダイアログ・フローを参照してください。

ダイアログ・フローを終了して、ユーザー・セッションを終了します。

return遷移を使用します。

例:
  printBalance:
    component: "BalanceRetrieval"
    properties:
      accountType: "${accountType.value}"
    transitions:
      return: "printBalance"
フロー・ナビゲーションおよび遷移

状態の遷移プロパティを設定することで、ダイアログ・フロー内の特定のパスにダイアログ・エンジンを設定できます。 遷移は、変数値が設定されている場合または設定されていない場合のダイアログの分岐方法を示します。 これにより、会話の典型的なルート(ハッピー・フロー)を記述したり、値の欠落や予期しないユーザーの動作に対応する代替ルートを設定できます。

遷移定義は、フロー順序およびコンポーネントによって異なります。
これを行うには... ...この遷移を使用
ダイアログ・フローでデフォルトのシーケンスを設定します。 ダイアログ・エンジンがダイアログ内の次の状態に移動できるようにするには、空の遷移(transitions: {})を使用するか、transitions定義を省略します。 これらは明示的ではないため、空の遷移によりダイアログのフロー定義が想定どおりに実行されていない場合、トラブルシューティングを実行するのは困難です。 このスキルは、ダイアログ・フローの最終状態(つまり、下部の状態)に空の遷移がある場合にスローされます。これは、ダイアログ・エンジンでは次の処理がわからないためです。
実行する次の状態を指定してください。 next遷移(next: "statename")を設定して、nextキーによって指定された状態にジャンプするようにダイアログ・エンジンに指示します。 「nextおよびデフォルト遷移」に記載されているように、return遷移があるものを除き、nextトランザクションを任意の状態に追加できます。
会話をリセットします。 return遷移を使用して、コンテキスト変数に設定された値をクリアし、ダイアログ・フローをリセットします。 任意の文字列値を遷移させることができます。
  unresolved:
    component: "System.Output"
    properties:
      text: "Sorry! I don't understand that question!"
    transitions:
      return: "unresolved"
return: "done"遷移を定義すると、ユーザー・セッションが終了し、フローの開始時にダイアログ・エンジンが配置されます。
条件アクションをトリガーします。 特定の状態へのナビゲーションをトリガーするactionsキーを定義します。 コンポーネントが処理を完了すると、次に移動する場所をダイアログ・エンジンに指示するアクション文字列が返されます。 アクション・キーを定義しない場合、ダイアログ・エンジンは、デフォルトの遷移またはnext遷移(存在する場合)に依存します。 アクションは必要な数だけ定義できます。 一部の組込みコンポーネントには特定のアクションが用意されています。 たとえば、Apache FreeMarker式を評価するSystem.MatchEntityのようなコンポーネントでは、matchおよびnomatchアクションを使用します。 System.OA uthAccountLinkにはtextReceivedpassfailのアクションがあり、ユーザー・インタフェース・コンポーネントでは独自のアクションが使用されます(「遷移」を参照)。 コンポーネント・テンプレートをガイドとして使用します。 actions遷移は、return遷移を持つ状態を除き、任意の状態で定義できます。
エラーを処理します。 コンポーネントでは、エラーがスローされる場合があります。 これは、システム関連の問題や障害(無効なパスワード、無効なホスト名または通信エラー)が原因で発生することがあります。 エラー処理状態を指定するerror遷移を設定すると、スキルが問題を正常に処理できるようになります:
transitions:
    error: "handleMe"
error遷移を設定しない場合、スキルから予期しないエラー・プロンプトを出力し(Oops! I’m encountering a spot of trouble)セッションを終了します。 error遷移は、return推移を持つものを除き、任意の状態で定義できます。
一部のコンポーネントには、アクションとして定義されたエラーがあります。 これらの組込みエラー推移では、コンポーネント固有のエラーが処理されます:
transitions:
  actions:
    error: "handleMe"
同じ状態では異なるタイプの遷移を使用できます。 次の例では、ダイアログ・エンジン・ナビゲーションがアクションまたはエラーに基づいています。 コンポーネントがいずれかに評価されない場合、ダイアログ・エンジンはnextの遷移に従って処理されます:
state_name:
  component: "component name"
  properties:
    component_property: "value"
    component_proprety: "value"
  transitions:
    next: "go_to_state"
    error: "go_to_error_handler"
    actions:
      action_string1: "go_to_state1"
      action_string2: "go_to_state2"
ノート

複数の遷移を定義できますが、return遷移は例外です。return遷移をerrornextまたはactions遷移と組み合せることはできません。
nextおよびデフォルト遷移

デフォルト(または空の)遷移({})は、コンポーネントの実行が成功した後にダイアログ・エンジンを次の状態に示す暗黙的な遷移です。 想定したユーザー入力を処理する厳格な線形的なプログレッシングにも十分ですが、より複雑な(現実的な)ユーザー対話を行うことはできません。 後者の場合、空の遷移は意図せずルーティングとなり、暗黙的な(値を戻さない)ため、トレースにエラーが発生しやすくなります。 たとえば、フローの最終状態への遷移を空の遷移として定義した場合、スキルは次のことを認識しないため、コンポーネントの実行後に例外をスローします。 アクションは保留中です。 Insights Pathingレポートでは、このエラーは、エラーにかかわらず実行パスが正常に完了しなかったことを示している場合があります。

これらの問題を回避するには、空の移行ではなくnext遷移を使用します。 さらに、returnerrorまたはactionsが定義されていない場合は、必ずnext遷移を使用します。 状態がerroractionsおよびnext遷移を組み合せる場合、next遷移はコンポーネントがerrorまたはactions遷移のいずれかを満たす文字列を返すことができないときにのみトリガーされます。

エラーやアクションができないとき、またはダイアログ・フローに空の遷移がある(または遷移がない)場合に、next遷移がトリガーされるようにするには、defaultTransitionノード内にnextアクションを定義します。 次のスニペットでは、next: "nextRules"グローバル・アクションによって、遷移のないgetName状態のnext遷移がトリガーされます。 これにより、フローをgetNameの状態からnextRulesの状態に移行できます:
context:
  variables:

    name: "string"

defaultTransitions:
  next: "nextRules"

states:
  
  getName:
    component: "System.Text"
    properties:
      prompt: "What's your name please?"
      variable: "name"
      #empty transition as there is no transitions: element defined


  printName:
    component: "System.Output"
    properties:
      text: "Hello ${name.value}." 
    transitions:
      return: "done"


  nextRules:
    component: "System.Output"
    properties:
      text: "Hello ${name.value}. I told you! Next transitions rule the game!" 
    transitions:
      return: "done"
予期しないアクションのダイアログ・フローの構成
ダイアログ・フローを設計するときは、通常、満足なフロー(ユーザーが最も使用するパス)のモデリングを開始します。
シナリオ 解決策
ユーザーは、ボタンをタップするかわりにテキストを入力することで、この状況では不適切に応答します。 ボットがこれを正常に処理できるようにするには、System.Intentコンポーネントがテキスト入力を解決できる状態(CrcPizzaBotの次のスニペットにあるtextReceived: Intentなど)にルーティングします:
ShowMenu:
 component: System.CommonResponse
 properties:
   metadata: ...
   processUserMessage: true
 transitions:
   actions:
     pizza: OrderPizza
     pasta: OrderPasta
     textReceived: Intent
現在のレスポンスのボタンをタップする必要があっても、ユーザーは前のメッセージまでスクロールしてそのオプションをタップします。
デフォルトでは、Digital Assistantは順不同メッセージを処理しますが、「Digital Assistant予期しないアクションの検出方法」の説明に従って、この動作をオーバーライドまたはカスタマイズできます。
context:
  variables:
    iresult: "nlpresult"
defaultTransitions:
  next: "ImplicitTransitionDetected"
  error: "MyErrorState"
  actions:
    system.outOfOrderMessage: "HandleUnexpectedAction"

...

  HandleOutOfOrderMessage:
    component: "System.Switch"
    properties:
      variable: "system.actualState"
      values:
        - "ShowMenu"
        - "OrderPizza"
        - "AskPizzaSize"
    transitions:
      actions:
        NONE: "ActionNoLongerAvailable"
        ShowMenu: "${system.actualState}"
たとえば、デフォルトのsystem.outofOrderMessage遷移を追加すると、ダイアログ・エンジンが、前述のOBotMLスニペットのHandleUnexpectedAction状態など、すべての順不同メッセージを処理する単一の状態に遷移するように通知されます。 様々な方法でこの状態を作成できます:
  • System.OutputまたはSystem.CommonResponseコンポーネントを使用して、“Sorry, this option is no longer available”というメッセージを出力し、return: "done"のトランジションとともにセッションを無効にして、ユーザーがやり直すことができます。 例えば:
    ActionNoLongerAvailable:
        component: "System.Output"
        properties:
          text: "Sorry, this action is no longer available"
        transitions:
          return: "done"
    
  • System.Switchコンポーネントを使用すると、別の状態に遷移することにより、ボットが一部のリクエスト・アクションを順守できるようにできます。 リクエストに応じて、ルーティングを実装するためにカスタム・コンポーネントの作成が必要な場合があります。

別のスキルからのスキルのコール

ユーザーがデジタル・アシスタント内で第2スキルに何かを行うことに関心のあるスキルを一時的に離れるオプショ