モジュール定義ファイル

モジュール定義ファイルとは

モジュールで提供する処理 (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つめの出力データの定義、後述の入出力定義を参照>": {}
      }
    }
  }
}

型の定義

definitions 内の型宣言の書式

全体の構造のうち、definitions 内の型宣言の部分は下記の書式とする。

{
  "<型の名前。definitions内で一意である必要がある>": {
    "description": "<型の説明>",
    "definition": "<型の構造の定義、書式は後述>"
  }
}

型の構造の定義

型の構造の定義は下記の書式で行う。 definitions 内の型宣言中の definition の値や、後述の入出力定義の paramtype の値として利用する。

{
  "type": "<型の種別。model (モデル)、model_set (複数のモデルの集合)、data (データ)、others (その他)>",
  "form": "<file (ファイル)、directory (ディレクトリ)、STDIN/STDOUT。typeがmodel_setの場合はdirectoryのみ可>",
  "files": [
    "<ファイルの定義。ディレクトリ内に配置されるファイルを列記>"
  ],
  "format": "<formがdirectory以外の場合に記述。後述のファイルフォーマットの定義を記入>",
  "paramtype": "<typeがmodel_setの場合のみ指定。定義ファイル中のdefinitionsで定義されている型の名前の文字列、もしくは、本項の型定義のdefinitionの内側と同じ構造のJSON。いずれの場合もtypeはmodelである必要がある>"
}

型の構造の定義の書式は、type が model、data、others か model_set かと、form が file か directory かで異なる。

1. type が model、data、others で form が directory の場合

{
  "type": "<データの種別。model (モデル)、data (データ)、others (その他)>",
  "form": "directory",
  "files": [
    "<ファイルの定義情報>"
  ]
}

2. type が model、data、others で form が file もしくは STDIN/STDOUT の場合

{
  "type": "<データの種別。model (モデル)、data (データ)、others (その他)>",
  "form": "<file もしくは STDIN/STDOUT>",
  "format": "<後述のファイルフォーマットの定義を記入>"
}

3. type が model_set の場合

{
  "type": "model_set",
  "form": "directory",
  "paramtype": "<typeがmodelになっているパラメータ定義のname、もしくは、パラメータ定義のdefinition部分と同じ構造>"
}

ファイルの定義

型の構造の form が directory の場合は directory 内に配置されるファイルの名前や種別を files 内の配列に列記する必要がある。その書式は下記の通り。

{
  "name": "<ファイルの名称（ラベルでありファイル名ではない）>",
  "path": "<ファイル名、ディレクトリ内の相対パスとする、ワイルドカードを可とする>",
  "form": "<file (ファイル) もしくは directory (ディレクトリ)>",
  "files": [
    "<formがdirectoryの場合のみ。ディレクトリ内に配置されるファイルを定義>",
    "<ファイルの定義のJSON、本項の定義を再帰的に記述>"
  ],
  "format": "<formが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": {
      "description": "集約前と集約後のモデル",
      "definition": {
        "type": "model",
        "form": "directory",
        "files": [
          {
            "name": "model_data",
            "path": "model.dat.xdata_meta",
            "form": "file",
            "format": {
              "type": "json",
              "structure": ""
            }
          },
          {
            "name": "model_file",
            "path": "model.dat",
            "form": "file",
            "format": {
              "type": "state_dict",
              "structure": ""
            }
          }
        ]
      }
    }
  },
  "scripts": {
    "fed_avg_aggregate": {
      "description": "FedAvg aggregate",
      "path": "aggregate",
      "type": "aggregation",
      "input": {
        "input_model_set": {
          "description": "input models",
          "path": "models",
          "paramtype": {
            "type": "model_set",
            "form": "directory",
            "paramtype": "the_model"
          }
        }
      },
      "output": {
        "output_model": {
          "description": "output models",
          "path": "aggregated_model",
          "paramtype": "the_model"
        }
      }
    }
  }
}