6. 非推奨となった組み込みブロッククラス

ver2.0で以下のブロックは非推奨となりました．

DialBBパッケージをインストールしても，これらのブロックで必要なライブラリがインストールされない可能性があります．

6.1. Japanese Canonicalizer （日本語文字列正規化ブロック）

(dialbb.builtin_blocks.preprocess.japanese_canonicalizer.JapaneseCanonicalizer)

入力文字列の正規化を行います．

6.1.1. 入出力

入力
- input_text: 入力文字列（文字列）
  - 例："ＣＵＰ Noodle 好き"
出力
- output_text: 正規化後の文字列（文字列）
  - 例："cupnoodle好き"

6.1.2. 処理内容

入力文字列に対して以下の処理を行います．

前後のスペースの削除
英大文字→英小文字
改行の削除
全角→半角の変換（カタカナを除く）
スペースの削除
Unicode正規化（NFKC）

6.2. Simple Canonicalizer （単純文字列正規化ブロック）

(dialbb.builtin_blocks.preprocess.simple_canonicalizer.SimpleCanonicalizer)

ユーザ入力文の正規化を行います．主に英語が対象です．

6.2.1. 入出力

入力
- input_text: 入力文字列（文字列）
  - 例：" I like ramen"
出力
- output_text: 正規化後の文字列（文字列）
  - 例："i like ramen"

6.2.2. 処理内容

入力文字列に対して以下の処理を行います．

前後のスペースの削除
英大文字→英小文字
改行の削除
スペースの連続を一つのスペースに変換

6.3. LR-CRF Understander （ロジスティック回帰と条件付き確率場を用いた言語理解ブロック）

(dialbb.builtin_blocks.understanding_with_lr_crf.lr_crf_understander.Understander）

ロジスティック回帰と条件付き確率場を用いて，ユーザ発話タイプ（インテントとも呼びます）の決定とスロットの抽出を行います．

コンフィギュレーションのlanguage要素がjaの場合は日本語，enの場合は英語の言語理解を行います．

本ブロックは，起動時にExcelで記述した言語理解用知識を読み込み，ロジスティック回帰と条件付き確率場のモデルを学習します．

実行時は，学習したモデルを用いて言語理解を行います．

6.3.1. 入出力

入力
- input_text: 入力文字列
入力文字列は正規化されていると仮定します．

例："好きなのは醤油"

出力

nlu_result: 言語理解結果（辞書型または辞書型のリスト）

後述のブロックコンフィギュレーションのパラメータnum_candidatesが1の場合，言語理解結果は辞書型で以下のような形式です．

 {
 "type": <ユーザ発話タイプ（インテント）>, 
   "slots": {
    <スロット名>: <スロット値>, 
  ..., 
  <スロット名>: <スロット値>
 }
}

以下が例です．

 {
 "type": "特定のラーメンが好き", 
 "slots": {
    "favorite_ramen": "醤油ラーメン"
 }
 }

num_candidatesが2以上の場合，複数の理解結果候補のリストになります．

 [
 {
   "type": <ユーザ発話タイプ（インテント）>, 
     "slots": {
     <スロット名>: <スロット値>, 
	 ..., 
	 <スロット名>: <スロット値>
 }
},
  {
  "type": <ユーザ発話タイプ（インテント）>, 
    "slots": {
  <スロット名>: <スロット値>, 
  ..., 
  <スロット名>: <スロット値>
  }
},
  ....
]

6.3.2. ブロックコンフィギュレーションのパラメータ

knowledge_file（文字列）

知識を記述したExcelファイルを指定します．コンフィギュレーションファイルのあるディレクトリからの相対パスで記述します．
flags_to_use（文字列のリスト）

各シートのflagカラムにこの値のうちのどれかが書かれていた場合に読み込みます．このパラメータがセットされていない場合はすべての行が読み込まれます．
num_candidates（整数．デフォルト値1）

言語理解結果の最大数（n-bestのn）を指定します．
canonicalizer

辞書記述を正規化する際に使うプログラムを指定します．
- class （文字列）
  
  正規化のブロックのクラスを指定します．基本的にアプリケーションで用いる正規化のブロックと同じものを指定します．
knowledge_google_sheet (ハッシュ)
- Excelの代わりにGoogle Sheetsを用いる場合の情報を記述します．（Google Sheetsを利用する際の設定はこはたさんの記事が参考になりますが，Google Cloud Platformの設定画面のUIがこの記事とは多少変わっています．）
  - sheet_id （文字列）
    
    Google SheetのIDです．
  - key_file（文字列）
    
    Goole Sheet APIにアクセスするためのキーファイルをコンフィギュレーションファイルのディレクトリからの相対パスで指定します．

6.3.3. 言語理解知識

言語理解知識は，以下の2つのシートからなります．

シート名	内容
utterances	タイプ毎の発話例
slots	スロットとエンティティの関係および同義語のリスト

シート名はブロックコンフィギュレーションで変更可能ですが，変更することはほとんどないと思いますので，詳細な説明は割愛します．

6.3.3.1. utterancesシート

各行は次のカラムからなります．

flag

利用するかどうかを決めるフラグ．Y (yes), T (test)などを書くことが多いです．どのフラグの行を利用するかはコンフィギュレーションに記述します．サンプルアプリのコンフィギュレーションでは，すべての行を使う設定になっています．
type

発話のタイプ（インテント）
utterance

発話例．
slots

発話に含まれるスロット．スロットを以下の形で記述します．
```
<スロット名>=<スロット値>, <スロット名>=<スロット値>, ... <スロット名>=<スロット値> 
```
以下が例です．
```
地方=札幌, 好きなラーメン=味噌ラーメン
```
utterancesシートのみならずこのブロックで使うシートにこれ以外のカラムがあっても構いません．

6.3.3.2. slotsシート

各行は次のカラムからなります．

flag

utterancesシートと同じ
slot name

スロット名．utterancesシートの発話例で使うもの．言語理解結果でも用います．
entity

辞書エントリー名．言語理解結果に含まれます．
synonyms

同義語を','で連結したものです．

6.4. ChatGPT Understander （ChatGPTを用いた言語理解ブロック）

(dialbb.builtin_blocks.understanding_with_chatgpt.chatgpt_understander.Understander）

OpenAI社のChatGPTを用いて，ユーザ発話タイプ（インテントとも呼びます）の決定とスロットの抽出を行います．

コンフィギュレーションのlanguage要素がjaの場合は日本語，enの場合は英語の言語理解を行います．

本ブロックは，起動時にExcelで記述した言語理解用知識を読み込み，プロンプトのユーザ発話タイプのリスト，スロットのリスト，Few shot exampleに変換します．

実行時は，プロンプトに入力発話を付加してChatGPTに言語理解を行わせます．

6.4.1. 入出力

入力
- input_text: 入力文字列
入力文字列は正規化されていると仮定します．

例："好きなのは醤油"

出力

nlu_result: 言語理解結果（辞書型）

以下の形式

{
  "type": <ユーザ発話タイプ（インテント）>, 
  "slots": {
     <スロット名>: <スロット値>, 
     ..., 
     <スロット名>: <スロット値>
    }
}

以下が例です．

{
  "type": "特定のラーメンが好き", 
  "slots": {
     "favorite_ramen": "醤油ラーメン"
  }
}

6.4.2. ブロックコンフィギュレーションのパラメータ

knowledge_file（文字列）

知識を記述したExcelファイルを指定します．コンフィギュレーションファイルのあるディレクトリからの相対パスで記述します．
flags_to_use（文字列のリスト）

各シートのflagカラムにこの値のうちのどれかが書かれていた場合に読み込みます．このパラメータがセットされていない場合はすべての行が読み込まれます．
canonicalizer

辞書記述を正規化する際に使うプログラムを指定します．
- class （文字列）
  
  正規化のブロックのクラスを指定します．基本的にアプリケーションで用いる正規化のブロックと同じものを指定します．
knowledge_google_sheet (ハッシュ)
- Excelの代わりにGoogle Sheetを用いる場合の情報を記述します．（Google Sheetを利用する際の設定はこはたさんの記事が参考になりますが，Google Cloud Platformの設定画面のUIがこの記事とは多少変わっています．）
  - sheet_id （文字列）
    
    Google SheetのIDです．
  - key_file（文字列）
    
    Goole Sheet APIにアクセスするためのキーファイルをコンフィギュレーションファイルのディレクトリからの相対パスで指定します．
gpt_model (文字列．デフォルト値はgpt-5.4-nano）

ChatGPTのモデルを指定します．gpt-4oなどが指定できます．
prompt_template

プロンプトテンプレートを書いたファイルをコンフィギュレーションファイルのディレクトリからの相対パスで指定します．

これが指定されていない場合は，dialbb.builtin_blocks.understanding_with_chatgpt.prompt_template_ja.PROMPT_TEMPLATE_JA （日本語）または，dialbb.builtin_blocks.understanding_with_chatgpt.prompt_template_en.PROMPT_TEMPLATE_EN （英語）が使われます．

プロンプトテンプレートは，言語理解をChatGPTに行わせるプロンプトのテンプレートで，@で始まる以下の変数を含みます．
- @types 発話タイプの種類を列挙したものです．
- @slot_definitions スロットの種類を列挙したものです．
- @examples 発話例と，タイプ，スロットの正解を書いた，いわゆるfew shot exampleです．
- @input 入力発話です．
これらの変数には，実行時に値が代入されます．

6.4.3. 言語理解知識

本ブロックの言語理解知識の記述形式は，LR-CRF Understanderの言語理解知識の記述形式と全く同じです．詳細はLR-CRF Understanderの説明の6.3.3 章を参照してください．

6.5. ChatGPT Dialogue （ChatGPTベースの対話ブロック）

(dialbb.builtin_blocks.chatgpt.chatgpt.ChatGPT)

OpenAI社のChatGPTを用いて対話を行います．

(llm_dialogue)と同じですが，ChatGPTのモデルしか使えません．コンフィギュレーションのモデル指定のパラメータはmodelではなく，gpt_modelです．

6.6. ChatGPT NER （ChatGPTを用いた固有表現抽出ブロック）

(dialbb.builtin_blocks.ner_with_chatgpt.chatgpt_ner.NER）

OpenAI社のChatGPTを用いて，固有表現の抽出を行います．

コンフィギュレーションのlanguage要素がjaの場合は日本語，enの場合は英語の固有表現抽出を行います．

本ブロックは，起動時にExcelで記述した固有表現用知識を読み込み，固有表現のクラスのリスト，各固有表現クラスの説明，各クラスの固有表現の例，抽出例（Few shot example）に変換し，プロンプトに埋め込みます．

実行時は，プロンプトに入力発話を付加してChatGPTに固有表現抽出を行わせます．

6.6.1. 入出力

入力
- input_text: 入力文字列
- aux_data: 補助データ（辞書型)
出力
- aux_data: 補助データ（辞書型）
  
  入力されたaux_dataに固有表現抽出結果を加えたものです．
  
  固有表現抽出結果は，以下の形です．
```
{"NE_<ラベル>": "<固有表現>", "NE_<ラベル>": "<固有表現>", ...}
```
  <ラベル>は固有表現のクラスです．固有表現は見つかった固有表現で，input_textの部分文字列です．同じクラスの固有表現が複数見つかった場合，:で連結します．
  
  例
```
{"NE_人名": "田中:鈴木", "NE_料理": "味噌ラーメン"}
```

6.6.2. ブロックコンフィギュレーションのパラメータ

knowledge_file（文字列）

固有表現知識を記述したExcelファイルを指定します．コンフィギュレーションファイルのあるディレクトリからの相対パスで記述します．
flags_to_use（文字列のリスト）

各シートのflagカラムにこの値のうちのどれかが書かれていた場合に読み込みます．このパラメータがセットされていない場合はすべての行が読み込まれます．
knowledge_google_sheet (ハッシュ)
- Excelの代わりにGoogle Sheetを用いる場合の情報を記述します．（Google Sheetを利用する際の設定はこはたさんの記事が参考になりますが，Google Cloud Platformの設定画面のUIがこの記事とは多少変わっています．）
  - sheet_id （文字列）
    
    Google SheetのIDです．
  - key_file（文字列）
    
    Goole Sheet APIにアクセスするためのキーファイルをコンフィギュレーションファイルのディレクトリからの相対パスで指定します．
gpt_model (文字列．デフォルト値はgpt-5.4-nano）

ChatGPTのモデルを指定します．gpt-4oなどが指定できます．
prompt_template

プロンプトテンプレートを書いたファイルをコンフィギュレーションファイルのディレクトリからの相対パスで指定します．

これが指定されていない場合は，dialbb.builtin_blocks.ner_with_chatgpt.chatgpt_ner.prompt_template_ja .PROMPT_TEMPLATE_JA （日本語）または，dialbb.builtin_blocks.ner_with_chatgpt.chatgpt_ner.prompt_template_en .PROMPT_TEMPLATE_EN （英語）が使われます．

プロンプトテンプレートは，言語理解をChatGPTに行わせるプロンプトのテンプレートで，@で始まる以下の変数を含みます．
- @classes 固有表現のクラスを列挙したものです．
- @class_explanations 各固有表現クラスの説明を列挙したものです．
- @ne_examples 各固有表現クラスの固有表現の例を列挙したものです．
- @ner_examples 発話例と，固有表現抽出結果の正解を書いた，いわゆるfew shot exampleです．
- @input 入力発話です．
これらの変数には，実行時に値が代入されます．

6.6.3. 固有表現抽出知識

固有表現抽出知識は，以下の2つのシートからなります．

シート名	内容
utterances	発話と固有表現抽出結果の例
classes	スロットとエンティティの関係および同義語のリスト

シート名はブロックコンフィギュレーションで変更可能ですが，変更することはほとんどないと思いますので，詳細な説明は割愛します．

6.6.3.1. utterancesシート

各行は次のカラムからなります．

flag

利用するかどうかを決めるフラグ．Y (yes), T (test)などを書くことが多いです．どのフラグの行を利用するかはコンフィギュレーションに記述します．
utterance

発話例．
entities

発話に含まれる固有表現．固有表現を以下の形で記述します．
```
<固有表現クラス>=<固有表現>, <固有表現クラス>=<固有表現>, ... <固有表現クラス>=<固有表現> 
```
以下が例です．
```
人名=太郎, 地名=東京
```
utterancesシートのみならずこのブロックで使うシートにこれ以外のカラムがあっても構いません．

6.6.3.2. classesシート

各行は次のカラムからなります．

flag

utterancesシートと同じ
class

固有表現クラス名．
explanation

固有表現クラスの説明
examples

固有表現の例を','で連結したものです．

6.7. spaCy-Based Named Entity Recognizer （spaCyを用いた固有表現抽出ブロック）

(dialbb.builtin_blocks.ner_with_spacy.ne_recognizer.SpaCyNER)

(ver0.6で追加）

spaCyおよびGiNZAを用いて固有表現抽出を行います．

6.7.1. 入出力

入力
- input_text: 入力文字列（文字列）
- aux_data: 補助データ（辞書型）
出力
- aux_data: 補助データ（辞書型）
  
  入力されたaux_dataに固有表現抽出結果を加えたものです．
  
  固有表現抽出結果は，以下の形です．
```
{"NE_<ラベル>": "<固有表現>", "NE_<ラベル>": "<固有表現>", ...}
```
  <ラベル>は固有表現のクラスです．固有表現は見つかった固有表現で，input_textの部分文字列です．同じクラスの固有表現が複数見つかった場合，:で連結します．
  
  例
```
{"NE_Person": "田中:鈴木", "NE_Dish": "味噌ラーメン"}
```
  固有表現のクラスについては，spaCy/GiNZAのモデルのサイトを参照してください．
  - ja-ginza-electra (5.1.2):，https://pypi.org/project/ja-ginza-electra/
  - en_core_web_trf (3.5.0):，https://spacy.io/models/en#en_core_web_trf-labels

6.7.2. ブロックコンフィギュレーションのパラメータ

model (文字列．必須）

spaCy/GiNZAのモデルの名前です．ja_ginza_electra (日本語），en_core_web_trf (英語）などを指定できます．
patterns (オブジェクト．任意）

ルールベースの固有表現抽出パターンを記述します．パターンは，spaCyのパターンの説明に書いてあるものをYAML形式にしたものです．

以下が日本語の例です．
```
patterns: 
  - label: Date
    pattern: 昨日
  - label: Date
    pattern: きのう
```

6.7.3. 処理内容

spaCy/GiNZAを用いてinput_text中の固有表現を抽出し，aux_dataにその結果を入力して返します．