追加ライブラリのサポートを追加する

Foundry の標準モデル機能が特定のユースケースに不足している場合や、特定のクラスやライブラリがサポートされていない場合、特定の関数を上書きするか、Stage インターフェースに必要な関数を登録することができます。たとえば、Stage のカスタム transform 関数を作成し、Foundry にシリアライズすることができます。

サードパーティのライブラリをサポートしたい場合、Stage の独自の実装を作成できます。

例を見てみたい場合は、名前付きエンティティ認識のために事前にトレーニングされた spaCy モデルを活用する方法に関するチュートリアルをご覧ください。

必要条件

これらは、ユーザーの Code Repository や Code Workbook 環境に追加できる共有 Transforms Python ライブラリに書き込む必要があります。一度インポートされると、ユーザーのカスタム Stage の実装は自動的に foundry_ml に統合されます。

カスタム実装のオプションは以下を説明します:

• model.transform() が呼び出されたときにモデルが実行すべき操作。
• Foundry でモデルをシリアライズおよび保存する方法。
• 下流のトランスフォームで使用できるようにモデルをデシリアライズする方法。

Stage クラスはデシリアライズ時に利用可能である必要があるため、Python 環境のモジュールとして利用可能でなければなりません。

トランスフォームを登録する

モデルクラスを使用するには、クラスが登録された変換関数およびシリアライズ形式を持っていることを確認する必要があります。たとえば、CustomModel ステージを含むモデルがある場合、model.transform() が呼び出されたときに適用される関数を定義する必要があります。

定義された transform 関数は、Spark または Pandas DataFrame のいずれかで操作する必要があります。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from foundry_ml.stage.flexible import stage_transform, register_stage_transform_for_class

class CustomModel(object):

    def __init__(self, name):
        # モデルの初期化
        ...

    def custom_transform(self, df):
        # データフレームに対するカスタム変換を実行
        ...
        return df

# 関数にアノテーションを付けて、ステージ間で渡されるモデルとデータをラップする
@stage_transform()
def _transform(model, df):
    # 上記で定義されたモデルの変換関数を呼び出す
    return model.custom_transform(df)

# Foundry ML ステージレジストリに送信する。force=True を指定して既存の登録済みの変換を上書きする
register_stage_transform_for_class(CustomModel, _transform, force=True)

シリアライザとデシリアライザの登録

クラスの変換関数を登録したので、Foundry にモデルコードのシリアライズとデシリアライズの方法を指示する必要があります。カスタムで作成したモデルステージを使用する場合、ステージは共有Pythonライブラリに書き込み、依存関係としてインポートすることが重要です。

これは、Stageクラスがデシリアライズ時に利用可能である必要があるためです。そうでないと、StageクラスをCode Workbookに書き込み、その後別のCode Workbookから保存されたモデルを読み込もうとすると、モデルを読み込むことができません。

以下の例では、CustomModelをdill ↗を使用してピクル化できると仮定しています。以下の例では、ファイルシステムからモデルを安全に読み書きするために、Foundry の 2 つのヘルパー関数 load_data と safe_write_data を利用しています。spaCy の例では、異なる実装を示しています。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import dill
from foundry_object.utils import safe_write_data, load_data
from foundry_ml.stage.serialization import deserializer, serializer, register_serializer_for_class

# デシリアライザデコレータ
@deserializer("custom_model.dill", force=True)
def _deserializer(filesystem, path):
    # ピクルされたファイルを読み込む
    return dill.loads(load_data(filesystem, path, True), encoding='latin1')

# シリアライザデコレータ
@serializer(_deserializer)
def _serializer(filesystem, value):
    path = 'custom_model.dill'
    # データをシリアル化して安全に書き込む
    safe_write_data(filesystem, path, dill.dumps(value), base64_encode=True)
    return path

# カスタムモデルクラスに対してシリアライザを登録する
register_serializer_for_class(CustomModel, _serializer, force=True)

CustomModel を適切に登録したら、model = Model(Stage(CustomModel(...))) の構文で他の Stage と同様に使用でき、model.transform(dataframe) で実行できます。

モデル内の関数のシリアル化

いくつかのモデルステージ（特にシミュレーションラッパー）は、メイントランスフォーム関数に加えてユーザーが作成した関数を含んでいます。モデルを実行可能にするためには、ユーザーが作成した関数もモデルの状態にシリアル化されなければなりません。内部的には、Python は pickle パッケージを使用して関数を保存しますが、pickle パッケージでは関数を適切にシリアル化するための追加の考慮が必要です。

ステージを読み込む際に、ModuleNotFoundError: No module named '...' などのエラーが発生することがあります。これは、ユーザーが作成した関数が値ではなくリファレンスでシリアル化された場合に発生することがあります。つまり、Python バイトコードを直接シリアル化する代わりに、pickle が関数の名前をシリアル化したということです。

値でのシリアル化を強制するには、コードを直接トランスフォーム関数に移動することができます。

たとえば:

class SimModel(SimulationWrapper):
    def run(self, data, parameters):
        # シミュレーションの実行ロジックがここに入ります
        ...

@transform(...)
def my_model(...):
  # モデルの定義と初期化を行います
  return Model(Stage(
        SimModel(parameters)  # シミュレーションモデルのインスタンス化
    ))

以下のように記述してください:

Copied!
1
2
3
4
5
6
7
8
9
10
@transform(...)  # デコレーターを使用して関数の動作を変更
def my_model(...):  # my_model 関数の定義
    class SimModel(SimulationWrapper):  # SimulationWrapper クラスを継承した SimModel クラスの定義
        def run(self, data, parameters):  # run メソッドの定義
            ...

    # my_model 関数が Model インスタンスを返す
    return Model(Stage(
        SimModel(parameters)  # SimModel クラスのインスタンスを作成して Stage クラスに渡す
    ))

このルールは、カスタムコードが呼び出す他の関数にも適用されます。シリアライズされた関数やクラスに多くの依存関係があり、それらも値としてシリアライズされる場合、依存関係を Python ライブラリにまとめて、モデルの依存関係として追加することをお勧めします。

共有ライブラリの設定

上記のコードがすべて model.py に配置されていると仮定すると、リポジトリは次のような構造になります。

├── README.md                # プロジェクトの概要や使用方法を説明するファイル
├── build.gradle             # Gradleのビルド設定ファイル
├── ci.yml                   # 継続的インテグレーションの設定ファイル
├── conda_recipe             # Condaパッケージのレシピフォルダ
│   └── meta.yaml            # Condaパッケージのメタデータファイル
├── gradle.properties        # Gradleのプロパティ設定ファイル
├── gradlew                  # Gradleラッパースクリプト (Unix系OS用)
├── gradleww                 # (通常は存在しないファイルなので、typoの可能性あり)
├── settings.gradle          # Gradleの設定ファイル
├── src                      # ソースコードフォルダ
│   ├──custom_plugin         # カスタムプラグインフォルダ
│   │   ├── __init__.py      # Pythonモジュールの初期化ファイル
│   │   └── model.py         # モデル定義ファイル
│   ├── setup.cfg            # Pythonパッケージの設定ファイル
│   └── setup.py             # Pythonパッケージのセットアップスクリプト
└── templateConfig.json      # テンプレート設定ファイル

Foundry がプラグインを検出できるようにするために、まず __init__.py を修正して model.py の内容をパッケージのトップレベルにインポートする必要があります。

Copied!
1
from .model import *  # .modelモジュールからすべてのクラスや関数をインポート

さらに、新しいプラグインを Model プラグインレジストリで検出できるようにするために、setup.py に以下を追加する必要があります:

Copied!
1
2
3
4
entry_points={'foundry_ml.plugins': ['plugin = custom_plugin']},
# entry_points: setuptoolsや他のパッケージ管理ツールにおいて、プラグインや拡張機能のエントリーポイントを指定するための設定
# 'foundry_ml.plugins': カスタムプラグインを指定するためのキー
# 'plugin = custom_plugin': 使用するカスタムプラグインのモジュールパス

コミット、ビルド、そして リリースにタグを付けると、新しいモデルクラスを Code Workbook または Code Repositories で活用できるようになります。

ライブラリクラスでトランスフォーム関数をオーバーライドする

Foundry の標準関数が特定のユースケースに対して十分でない場合、既存のモデルクラスの transform 関数をオーバーライドできます。手順は、カスタムクラスのトランスフォームを登録するセクションと同じです。

ただし、リポジトリは クラス レベルで行われることに注意してください。これは、特定のライブラリ関数（たとえば sklearn の LogisticRegression）の transform() 関数をオーバーライドすると、そのライブラリ関数のすべてのインスタンスが、オーバーライドされたトランスフォーム関数を使用することを意味します。

この動作が望ましくない場合、以下の方法で解決できます：

• ライブラリ関数をラップするラッパークラス（たとえば、LogisticRegressionCustom）を作成する
• 上記の手順に従って、希望するトランスフォーム関数で登録する

その後、この新しいクラスを使用して、ライブラリ関数への呼び出しの動作を変更せずに使用できます。

トラブルシューティング

ステージに対する stage_transform が登録されていない

シリアライズされたモデルでカスタムステージを使用しようとすると、foundry_ml_core.stage.flexible._flexible_stage.FlexibleStageException: No stage_transform registered for stage type: <class 'NoneType'> というエラーが発生することがあります。

このエラーは、以下の手順で解決できることが多いです：

• カスタムステージを含むプラグインパッケージが環境の一部であることを確認してください。
• パッケージが正しく構成されていることを確認してください。特に、パッケージがプラグインとして登録されていることと、上記のように __init__.py ファイルがクラスをインポートしていることを確認してください。
• 場合によっては、Conda がパッケージの古いバージョンを解決することがあります。正しいバージョンのパッケージが使用されていることを確認するために、特定のプラグインバージョンに Conda 環境を固定することをお勧めします。

PyPI パッケージ

現在、Foundry モデルでは PyPI パッケージはサポートされていません。依存関係は Conda から解決する必要があります。