モジュール定義ファイル
モジュール定義ファイルとは
モジュールで提供する処理 (script) や取り扱うデータ構造を規定したファイルであり，モジュールのインタフェイス仕様を宣言する役割を担う．
JSON 形式のファイルで作成し，モジュール内に definition.json という名前で保存しておく．
xData FL は definition.json を取得することで，モジュールが提供する処理を把握し，xData FL が提供するモジュール実行 Web API が呼ばれた際に，そのパラメータを適切に解釈し，要求された処理に必要となるデータの準備や，処理結果の解釈，保存などが行えるようになる．
モジュール定義ファイルの構造
全体的な構造
モジュール定義ファイルは下記の様な構造を持った JSON とする．
{
name: <モジュールの名前．java と同様に FQDN の形式で記述する．これによりモジュールを一意に識別出来るようにする>,
description: <モジュールの説明>,
supports: <TBD モジュールがサポートする機能を列記する>,
# 型定義部
definitions: {
<パラメータの型の定義, 後述の型定義を参照>,
...
},
# スクリプト定義部
scripts: {
<スクリプト名（ラベル），Web API を呼ぶ際には別途定義するモジュール名と，このスクリプト名を渡すことで実行したい処理を指定する．スクリプト名はモジュール内でユニークである必要がある．モジュールの name と script の name を組み合わせることで，任意のモジュール群からスクリプトを一意に特定できる>: {
description: <スクリプトの説明．人間 (もしくは LLM) に読ませるための物>
path: <実行したい処理の service 名．docker-compose.yml に定義した service の名前を記述する>,
type: <スクリプトの種別，training (model と data を入力して model を出力), prediction (model と data を入力して data (と model) を出力，prediction しながら model の更新を行うタイプのは別のラベルを振った方がいいかも), aggregation (複数の model を入力して model を出力), model_transformation (model を入力して model を出力), data_transformation (data を入力して data を出力)>,
input: { # スクリプトが要求する入力を定義する
<1つめの入力データの定義, 後述の入出力定義を参照>,
<2つめの入力データの定義, 後述の入出力定義を参照>,
...
},
output: { # スクリプトの出力を定義する
<1つめの出力データの定義, 後述の入出力定義を参照>,
<2つめの出力データの定義, 後述の入出力定義を参照>,
...
},
...
},
<スクリプト名>: {
type: <スクリプト種別>,
...
},
...
}
}
型の定義
definitions 内の型宣言の書式
全体の構造のうち，definitions 内の型宣言の部分は下記の書式とする．
<型の名前．definitions 内で一意である必要がある>: {
description: <型の説明>,
definition: <型の構造の定義，書式は後述>
}
型の構造の定義
型の構造の定義は下記の書式で行う． definitions 内の型宣言中の definition の値や，後述の入出力定義の paramtype の値として利用する．
{
type: <型の種別，model (モデル)，model_set (複数のモデルの集合), data (データ)，others (その他)>,
form: <file (ファイル)，directory (ディレクトリ)，STDIN/STDOUT, type が model_set の場合は directory のみ可>,
files: [ # form がディレクトリの場合のみ
<ファイルの定義, ディレクトリ内に配置されるファイルを列記>,
<ファイルの定義, ディレクトリ内に配置されるファイルを列記>,
...
],
format: <form が directory 以外の場合に記述．後述のファイルフォーマットの定義を記入>,
paramtype: <type が model_set の場合のみ指定．定義ファイル中の definitions で定義されている型の名前の文字列，もしくは，本項の型定義の definition の内側と同じ構造の JSON, いずれの場合も type は model である必要がある>
}
型の構造の定義の書式は, type が model, data, others か model_set かと，form が file か directory かで異なる．
-
type が model, data, others で form が dierctory の場合
{ type: <データの種別，model (モデル)，data (データ)，others (その他)>, form: "directory", files: [ <ファイルの定義情報> ] } -
type が model, data, others で form が file もしくは STDIN/STDOUT の場合
{ type: <データの種別，model (モデル)，data (データ)，others (その他)>, form: <file もしくは STDIN/STDOUT>, format: <後述のファイルフォーマットの定義を記入> } -
type が model_set の場合
{ type: "model_set", form: "directory", paramtype: <type が model になっているパラメータ定義の name もしくは，パラメータ定義の definition 部分と同じ構造> }
ファイルの定義
型の構造の form が directory の場合は directory 内に配置されるファイルの名前や種別を files 内の配列に列記する必要がある．その書式は下記の通り．
{
name: <ファイルの名称（ラベルでありファイル名ではない）>
path: <ファイル名，ディレクトリ内の相対パスとする，ワイルドカードを可とする>
form: <file (ファイル) もしくは directory (ディレクトリ)>
files: [ # form が direcotry の場合のみ．ディレクトリ内に配置されるファイルを定義する
<ファイルの定義の JSON，本項の定義を再帰的に記述>,
<ファイルの定義の JSON，本項の定義を再帰的に記述>,
...
],
format: <forms が file の場合，後述のファイルフォーマットの定義を記入>
}
ファイルフォーマットの定義
ファイルの書式等を宣言する
{
type: ファイルの形式 CSV, JSON, Movie など
structure: <ファイルの形式，ファイル種別に応じて異なる>
]
type が CSV の場合の structure の指定方法
{
lineseparator: <行の区切り，デフォルトは CR LF>
delimiter: <カラムの区切り，デフォルトはカンマ>
columns: [
{
name: <カラムの名前（ラベル）>,
type: <カラムの型，string, number, date, geometory, など>
},
... カラム数の分，繰り返す
]
}
その他のファイルフォーマットについては必要に応じて随時規定する
モデルの受け渡し方法
型の種別 (type) が model となっている場合は，システムは下記の 2 種類のファイルを取り扱う．いずれもファイルフォーマットの定義の type の指定で区別する
- モデルのメタデータ．json 形式のファイル．format の type に "json" と書く
- モデル本体. 当面は pytorch の state_dict の形式とする．format の type に "state_dict" と書く
入力定義の際には，form が directory の場合， files の中の format.type が json となっていればその path 名のファイルにメタデータを，format.type が "state_dict" となっていればその path 名のファイルにモデルのバイナリデータをファイルとして保存する．
出力定義の際には，同様に json になっているファイルからメタデータを読込んで， state_dict になっているファイルをモデルの本体として取り扱う．
入出力の定義
<入出力データの名前（ラベル），Web API を呼ぶ際に各入出力のデータをどの(テーブルから取得|テーブルに保存)するかを指定する．スクリプトの入力/出力の name はユニークである必要がある>: {
description: <入出力データの説明．人間 (もしくは LLM) に読ませるための物>,
path: <入力/出力用のディレクトリ内の相対パス>,
paramtype: <パラメータの型の name (文字列) もしくは上述の型の構造の定義>
}
モジュール定義の記述例
連合学習のモデル集約アルゴリズム FedAvg を実装したモジュールの定義ファイルの例を下記に示す．
このモジュールはモデルの集約処理（複数のモデルを入力として受け取り，集約したモデルを出力する処理) を実装したスクリプトを 1 つ内包している．入力データは一定の条件で取得されたモデル群，出力は単一のモデルを出力する．
{
"name": "module.fed-avg-module.aggregate",
"description": "FedAvg aggregate module",
"supports": "",
"definitions": {
"the_model": { # 本モジュールでは入出力でモデルを取り扱うため，共通の型として the_model を定義している
"description": "集約前と集約後のモデル",
"definition": {
"type": "model", # モデルなので type は "model"
"form": "directory",
"files": [
{
"name": "model_data",
"path": "model.dat.xdata_meta",
"form": "file",
"format": {
"type": "json", # model で type が json となっているファイルにはメタデータを保存する
"structure": ""
}
},
{
"name": "model_file",
"path": "model.dat",
"form": "file",
"format": {
"type": "state_dict", # model で type が state_dict となっているファイルにはモデルそのものを保存する
"structure": ""
}
}
]
}
}
},
"scripts": {
"fed_avg_aggregate": { # 本モジュールは集約処理を実装した script を 1 つ内包する．名前は fed_avg_aggregate とする
"description": "FedAvg aggregate",
"path": "aggregate",
"type": "aggregation", # スクリプトの種類は aggregation
"input": { # 入力データはモデルの集合
"input_model_set": { # input ディレクトリの下に models ディレクトリを作成し，その下にさらにディレクトリを掘って，definitions の "the_model" で定義されたファイル群を生成する．models の下に掘られるディレクトリ名はシステムが決める
"description": "input models",
"path": "models",
"paramtype": {
"type": "model_set",
"form": "directory",
"paramtype": "the_model"
}
}
},
"output": {
"output_model": { # 出力はモデルが 1 つ．こちらは output ディレクトリの下に aggregated_model というディレクトリを掘って， the_model で定義した構造に沿って model の情報を保存する．
"description": "output models",
"path": "aggregated_model",
"paramtype": "the_model"
}
}
}
}
}