4. フレームワーク仕様

ここではフレームワークとしてのDialBBの仕様を説明します．Pythonプログラミングの知識がある読者を想定しています．

4.1. 入出力

DialBBのメインモジュールは，クラスAPI（メソッド呼び出し）で，ユーザ発話と付加情報をJSON形式で受けとり，システム発話と付加情報をJSON形式で返します．

メインモジュールは，ブロックを順に呼び出すことによって動作します．各ブロックはJSON形式（pythonの辞書型）のデータを受け取り，JSON形式のデータを返します．

各ブロックのクラスや入出力仕様はアプリケーション毎のコンフィギュレーションファイルで規定します．

4.1.1. DialogueProcessorクラス

アプリケーションの作成は，dialbb.main.DialogueProcessorクラスのオブジェクトを作成することで行います．

これは以下の手順で行います．

• DialBBがGitHubのREADMEに従いpipでインストールされているか，dialbbがモジュール検索パスにあるとします．

• DialBBを利用するアプリケーションの中で，以下のようにDialogueProcessorのインスタンスを作成し，processメソッドを呼び出します．

  from dialbb.main import DialogueProcessor
  dialogue_processor = DialogueProcessor(<コンフィギュレーションファイル> <追加のコンフィギュレーション>)
  response = dialogue_processor.process(<リクエスト>, initial=True)  # 対話セッション開始時
  response = dialogue_processor.process(<リクエスト>) # セッション継続時
  

  <追加のコンフィギュレーション>は，以下のような辞書形式のデータで，keyは文字列でなければなりません．

  {
    "<key1>": <value1>,
    "<key2>": <value2>,
      ...
  }
  

  これは，コンフィギュレーションファイルから読み込んだデータに追加して用いられます．もし，コンフィギュレーションファイルと追加のコンフィギュレーションで同じkeyが用いられていた場合，追加のコンフィギュレーションの値が用いられます．

  <リクエスト>とresponse（レスポンス）は辞書型のデータで，以下で説明します．

  DialogueProcessor.processはスレッドセーフではありません．

4.1.2. リクエスト

4.1.2.1. セッション開始時

以下の形のJSONです．

{
  "user_id": <ユーザID: 文字列>,
  "aux_data": <補助データ: オブジェクト（値の型は任意）>
}

• user_idは必須で，aux_dataは任意です．

• <ユーザID>はユーザに関するユニークなIDです. 同じユーザが何度も対話する際に，以前の対話の内容をアプリが覚えておくために用います．

• <補助データ>は，クライアントの状態をアプリに送信するために用います．JSONオブジェクトで，内容はアプリ毎に決めます．

4.1.2.2. セッション開始後

以下の形のJSONです．

{
  "user_id": <ユーザID: 文字列>,
  "session_id": <セッションID: 文字列>,
  "user_utterance": <ユーザ発話文字列: 文字列>,
  "aux_data":<補助データ: オブジェクト (値の型は任意>
}

• user_id, session_id, user_utteranceは必須．aux_dataは任意です．

• <セッションID>は，サーバのレスポンスに含まれているセッションIDです．

• <ユーザ発話文字列>は，ユーザが入力した発話文字列です．

4.1.3. レスポンス

{
  "session_id":<セッションID: 文字列>,
  "system_utterance": <システム発話文字列: 文字列>, 
  "user_id":<ユーザID: 文字列>, 
  "final": <対話終了フラグ: ブール値> 
  "aux_data":<補助データ: オブジェクト（値の型は任意>
}

• <セッションID>は，対話のセッションのIDです．対話開始のリクエストを送信した際に新しいセッションIDが生成されます．後述の外部DBを使う場合には，ハッシュ値が使われます．

• <システム発話文字列>は，システムの発話です．

• <ユーザID>は，リクエストで送られたユーザのIDです．

• <対話終了フラグ>は，対話が終了したかどうかを表すブール値です．

• <補助データ>は，対話アプリがクライアントに送信するデータです．サーバの状態などを送信するのに使います．

4.2. WebAPI

アプリケーションにWebAPI経由でアクセスすることもできます．

4.2.1. サーバの起動

DialBBがGitHubのREADMEに従いpipでインストールされていることを前提とします．

以下のコマンドで起動します．

$ dialbb-server [--port <port>] <config file>

port（ポート番号）のデフォルトは8080です．

4.2.2. クライアントからの接続（セッションの開始時）

• URI

  http://<server>:<port>/init
  

• リクエストヘッダ

  Content-Type: application/json
  

• リクエストボディ

  クラスAPIの場合のリクエストと同じJSON形式のデータです．

• レスポンス

  クラスAPIの場合のレスポンスと同じJSON形式のデータです．

4.2.3. クライアントからの接続（セッション開始後）

• URI

  http://<server>:<port>/dialogue
  

• リクエストヘッダ

  Content-Type: application/json
  

• リクエストボディ

  クラスAPIの場合のリクエストと同じJSON形式のデータです．

• レスポンス

  クラスAPIの場合のレスポンスと同じJSON形式のデータです．

4.3. コンフィギュレーション

コンフィギュレーションは辞書形式のデータで，YAMLファイルで与えることを前提としています．

コンフィギュレーションに必ず必要なのはblocks要素のみです．blocks要素は，各ブロックがどのようなものかを規定するもの（これをブロックコンフィギュレーションと呼びます）のリストで，以下のような形をしています．

blocks:
  - <ブロックコンフィギュレーション>
  - <ブロックコンフィギュレーション>
  ...
  - <ブロックコンフィギュレーション>

各ブロックコンフィギュレーションの必須要素は以下です．

• name

  ブロックの名前．ログで用いられます．

• block_class

  ブロックのクラス名です．モジュールを検索するパス（sys.pathの要素の一つ．環境変数PYTHONPATHで設定するパスはこれに含まれます）からの相対で記述します．

  コンフィギュレーションファイルのあるディレクトリは，モジュールが検索されるパス（sys.pathの要素）に自動的に登録されます．

  組み込みクラスは，dialbb.builtin_blocks.<モジュール名>.<クラス名>の形で指定してください．dialbb.builtin_blocksからの相対パスでも書けますが，非推奨です．

• input

  メインモジュールからブロックへの入力を規定します．辞書型のデータで，keyがブロック内での参照に用いられ，valueがblackboard（メインモジュールで保持されるデータ）での参照に用いられます．例えば，

  input: 
    sentence: canonicalized_user_utterance
  

  のように指定されていたとすると，ブロック内でinput['sentence']で参照できるものは，メインモジュールのblackboard['canonicalized_user_utterance']です．

  指定されたキーがblackboardにない場合，該当するinputの要素はNoneになります．

• output

  ブロックからメインモジュールへの出力を規定します．input同様，辞書型のデータで，keyがブロック内での参照に用いられ，valueがblackboardでの参照に用いられます．

  output:
    output_text: system_utterance
  

  の場合，ブロックからの出力をoutputとすると，

    blackboard['system_utterance'] = output['output_text']
  

  の処理が行われます．blackboardがすでにsystem_utteranceをキーとして持っていた場合は，その値は上書きされます．

4.4. 対話履歴の保持

(ver 1.2で追加)

4.4.1. Blackboardへの対話履歴の保持

blackboardのdialogue_histroy要素には，メインプロセス内部の処理により，以下の形式の対話履歴が保持されます．

[
  {
     "speaker": "user",
     "user_id": <入力のuser_id. user_idが入力にない場合は””>
     "aux_data": <入力のaux_data. aux_dataが入力にない場合は{}>,
     "utterance": ""
  },
  {
    "speaker": "system",
    "aux_data": <出力のaux_data. aux_dataが出力にない場合は{}>,
    "utterance": <システム発話文字列>
  },
  {
     "speaker": "user",
     "user_id": <入力のuser_id. user_idが入力にない場合は””>
     "aux_data": <入力のaux_data. aux_dataが入力にない場合は{}>,
     "utterance": <ユーザ発話文字列>
  }
  ...
]

4.4.2. 対話履歴の外部DBでの保存

DialBBアプリケーションをWebサーバとして動作させ，リクエストが集中した際にロードバランサを使って複数インスタンスでに処理を分散させる場合，文脈情報を外部DB（MongoDB)に保存することで，一つのセッションを異なるインスタンスで処理することが可能です．

外部DBを使うには，コンフィギュレーションのトップレベルに以下のようにcontext_db要素を指定します．

context_db:
  host: localhost
  port: 27017
  user: admin
  password: password

各キーは以下です．

• host （str)

  MongoDBが動作しているホスト名

• port (int. デフォルト値27017)

  MongoDBのアクセスのためのポート番号

• user （str)

  MongoDBのアクセスのためのユーザ名

• password （str)

  MongoDBのアクセスのためのパスワード

4.5. ブロックの自作方法

開発者は自分でブロックを作成することができます．

ブロックのクラスはdiabb.abstract_block.AbstractBlockの子孫クラスでないといけません．

4.5.1. 実装すべきメソッド

• __init__(self, *args)

  コンストラクタです．以下のように定義します．

  def __init__(self, *args):
   
       super().__init__(*args)
   
       <このブロック独自の処理>
  

• process(self, input: Dict[str, Any], session_id: str = False) -> Dict[str, Any]

  入力inputを処理し，出力を返します．入力，出力とメインモジュールのblackboardの関係はコンフィギュレーションで規定されます（4.3 章を参照）． session_idはメインモジュールから渡される文字列で，対話のセッション毎にユニークなものです．

4.5.2. 利用できる変数

• self.config (辞書型)

  コンフィギュレーションの内容を辞書型データにしたものです．これを参照することで，独自に付け加えた要素を読みこむことが可能です．

• self.block_config (辞書型)

  ブロックコンフィギュレーションの内容を辞書型データにしたものです．これを参照することで，独自に付け加えた要素を読みこむことが可能です．

• self.name (文字列)

  コンフィギュレーションに書いてあるブロックの名前です．

• self.config_dir (文字列)

  コンフィギュレーションファイルのあるディレクトリです．アプリケーションディレクトリと呼ぶこともあります．

4.5.3. 利用できるメソッド

4.5.3.1. ロギング

以下のロギングメソッドが利用できます．

• log_debug(self, message: str, session_id: str = "unknown")

  標準エラー出力にdebugレベルのログを出力します． session_idにセッションIDを指定するとログに含めることができます．

• log_info(self, message: str, session_id: str = "unknown")

  標準エラー出力にinfoレベルのログを出力します．

• log_warning(self, message: str, session_id: str = "unknown")

  標準エラー出力にwarningレベルのログを出力します．

• log_error(self, message: str, session_id: str = "unknown")

  標準エラー出力にerrorレベルのログを出力します．後述のデバッグモードの時は，Exceptionを投げます．

4.6. デバッグモード

Python起動時の環境変数 DIALBB_DEBUGの値がyes （大文字小文字は問わない）の時，デバッグモードで動作します．この時，dialbb.main.DEBUGの値がTrueになります．アプリ開発者が作成するブロックの中でもこの値を参照することができます．

dialbb.main.DEBUGがTrueの場合，ロギングレベルはdebugに設定され，その他の場合はinfoに設定されます．

4.7. 環境変数の読み込み

上記のDIALBB_DEBUGの他にも，商用LLMのAPIキーの設定などに環境変数を用います．環境変数は，bashの場合のexportなどで設定しても良いですが，アプリケーション起動時のカレントディレクトリの.envに書くことも可能です．以下のような形式で書きます．

DIALBB_DEBUG=yes
OPENAI_API_KEY=....
GOOGLE_API_KEY=...
ANTHROPIC_API_KEY=...

すでに設定されている環境変数は.envの記述では上書きされません．

4.8. テスト

4.8.1. テストシナリオを用いたテスト

以下のコマンドでテストシナリオを用いたテストができます．

$ dialbb-test <アプリケーションコンフィギュレーションファイル> \
  <テストシナリオ> [--output <出力ファイル>]

テストシナリオは以下の形式のテキストファイルです．

<対話の区切り>
System: <システム発話>
User: <ユーザ発話>
System: <システム発話>
User: <ユーザ発話>
...
System: <システム発話>
User: <ユーザ発話>
System: <システム発話>
<対話の区切り>
System: <システム発話>
User: <ユーザ発話>
System: <システム発話>
User: <ユーザ発話>
...
System: <システム発話>
User: <ユーザ発話>
System: <システム発話>
<対話の区切り>
...

<対話の区切り>は，"----init"で始まる文字列です．

テストスクリプトは，<ユーザ発話>を順番にアプリケーションに入力して，システム発話を受け取ります．システム発話がスクリプトのシステム発話と異なる場合はwarningを出します．テストが終了すると，出力されたシステム発話を含め，テストシナリオと同じ形式で対話を出力することができます．テストシナリオと出力ファイルを比較することで，応答の変化を調べることができます．

4.8.2. テストリクエストを用いたテスト

テストシナリオを用いたテストではaux_dataを入力できません．aux_dataを入力するテストを行うには，テストリクエストを用いたテストを行います．

以下のコマンドで実行します．

$ dialbb-send-test-requests <アプリケーションコンフィギュレーションファイル> ＜テストリクエストファイル＞

テストリクエストファイルは以下の形式のJSONファイルです．

[
    [
      <最初のセッションの最初の入力>, 
      <最初のセッションの2番目の入力>, 
      ...
    ],
    [
      <2番目のセッションの最初の入力>, 
      <2番目のセッションの2番目の入力>, 
      ...
    ], 
    ...
]

各入力は，以下の形をしています．

• 各セッションの最初の入力（aux_dataがない場合）

  { "user_id": <ユーザID>}
  

• 各セッションの最初の入力（aux_dataがある場合）

  { 
      "user_id": <ユーザID>, 
      "aux_data": <aux_dataの値（辞書）>
  }
  

• 2番目以降の入力（aux_dataがない場合）

  {  
      "user_id": <ユーザID>,
      "user_utterance": "<ユーザ発話テキスト>"
  }
  

• 2番目以降の入力（aux_dataがある場合）

  { 
      "user_id": <ユーザID>,
      "user_utterance": "<ユーザ発話テキスト>",
      "aux_data": <aux_dataの値（辞書）>
  }
  

各セッション最初の入力はそのまま，2番目以降はsession_idが付加されてDialBBアプリケーションに入力されます．

user_idは省略しても構いません．その場合，各セッションの最初の入力は，aux_dataがない場合，空辞書になります．

4.8.3. ユーザシミュレータを用いたテスト

LLMを用いたユーザシミュレータを用いたテスタが付属しています．

4.8.3.1. サンプルの動かし方

以下bashの例で説明します．Windows コマンドプロンプトの場合は適宜読み替えてください．

• DialBBをインストールし，サンプルアプリケーションをダウンロードして展開します．

• 環境変数OPENAI_API_KEYにOpenAI APIのキーを設定します．

  export OPENAI_API_KEY=<OPENAIのAPIキー>
  

• サンプルアプリケーションを展開したディレクトリ（sample_apps）で以下のコマンドを実行します．

  dialbb-sim-tester --app_config llm_dialogue_ja/config.yml --test_config llm_dialogue_ja/simulation/config.yml --output _output.txt
  

• _output.txtに結果が記述されます．

• プログラムの中でテスタを起動するには以下のようにします

  from dialbb.sim_tester.main import test_by_simulation
  
  test_by_simulation("llm_dialogue_ja/config.yml", 
                     "llm_dialogue_ja/simulation/config.yml", output="_output.txt")
  

4.8.3.2. 仕様

• 起動オプション

  dialbb-sim-tester --app_config <DialBBアプリケーションのコンフィギュレーションファイル> --test_config <テストコンフィギュレーションファイル> --output <出力ファイル>
  

• テストコンフィギュレーションファイル

  以下のキーをもつYAML

  • model: （文字列．必須）モデル指定文字列．provider:model_name の形式で指定します．例：google_genai:gemini-2.0-flash-001．ただし，gpt-5.6-luna のようなOpenAIのGPTモデルは openai: を省略できます．

  • settings（オブジェクトのリスト．必須）設定のリスト．以下の要素を持つことができる

    • prompt_template: （文字列．必須）プロンプトテンプレートを記述したテキストファイルのパス．ファイルパスはコンフィギュレーションファイルからの相対パス．

    • initial_aux_data（文字列．任意）対話の最初にDialBBアプリケーションにアクセスする際に，aux_dataに入れる内容を書いたJSONファイルのパス．パスはコンフィギュレーションファイルからの相対パス．

  • temperatures: （浮動小数点数のリスト．任意）GPTの温度パラメータのリスト．デフォルト値は0.7の一要素のみのリスト．settingsのリストの長さ×このリストの長さのセッションが行われます．

  • max_turns: (整数．任意）セッションあたりの最大ターン数．デフォルト値15．

• 関数仕様

  • dialbb.sim_tester.main.test_by_simulation(test_config_file: str, app_config_file: str, output_file: str=None, json_output: bool=False, prompt_params: Dict[str, str])

    パラメータ

    • test_config_file: テストコンフィギュレーション

    • app_config_file: DialBBアプリケーションファイル

    • output_file: 対話ログ出力ファイル

    • json_output: 出力ファイルのフォーマットがJSONかどうか．Falseならテキストファイル．

    • prompt_params: プロンプトに埋め込む情報を辞書型で記述したもの．プロンプトテンプレートに{<key>}があれば，<value>で置き換えられる．