joblibのAPIドキュメント
Joblibで提供されるクラス
Memoryクラス
Parallelクラス
MemoryクラスのAPI
joblib.memory.Memoryクラス
class joblib.memory.Memory(location=None, backend='local', cachedir=None,
mmap_mode=None, compress=False ,verbose1,
bytes_limit=None, backend_options=None)
同じ入力引数で呼び出されるたびに関数の戻り値をキャッシュするためのコンテキストオブジェクト。
すべての値は、ファイルシステムの深いディレクトリ構造にキャッシュされます。
コンストラクタ __init__()
__init__(location=None, backend='local', cachedir=None,
mmap_mode=None, compress=False, verbose=1,
bytes_limit=None, backend_options=None)
location: str, None
データストアとして使用するベースディレクトリのパスまたはNone。 Noneが指定されている場合、キャッシュは行われず、Memoryオブジェクトは完全に透過的です。 このオプションは、バージョン0.12以降のcachedirを置き換えます。
backend: str、オプション
キャッシュファイルの読み取り/書き込み用のストアバックエンドのタイプ。
デフォルトは'local'です。この場合、location引数はディスクストレージへのパスです。
'local'バックエンドは、通常のファイルシステム操作を使用して、バックエンド内のデータを操作しています。
cachedir: str or None、オプション
mmap_mode: None, ‘r+’, ‘r’, ‘w+’, ‘c’、オプション
キャッシュnumpy配列からロードするときに使用されるメモリマップモード。 引数の意味については、numpy.load を参照してください。
compress: boolean or integer、オプション
ディスクに保存されたデータを圧縮するかどうか。 整数を指定する場合は、1〜9にする必要があり、圧縮量を設定します。 圧縮された配列はメモリマップでは読み取れないことに注意してください。
verbose: int、オプション
詳細フラグは、関数の評価時に発行されるデバッグメッセージを制御します。
bytes_limit: int、オプション
キャッシュのサイズのバイト単位の制限
backend_options: dict、オプション
ストアバックエンドの構成に使用される名前付きパラメーターのディクショナリが含まれています。
アトリビュート
depth: int、オプション
出力されるオブジェクトの深さ。
cache()メソッド
cache(func=None, ignore=None, verbose=None, mmap_mode=False)
キャッシュnumpy配列からロードするときに使用されるmemmappingモード。 引数の意味については、numpy.loadを参照してください。 デフォルトでは、メモリオブジェクトのものが使用されます。
func: callable, optional
デコレートするオリジナルの関数
ignore: 文字列のリスト
ハッシュで無視する引数名のリスト
verbose: integer、オプション
関数の詳細モード。 デフォルトでは、メモリオブジェクトのものが使用されます。
mmap_mode: None, ‘r+’, ‘r’, ‘w+’, ‘c’、オプション
キャッシュnumpy配列からロードするときに使用されるメモリマップモード。 引数の意味については、numpy.loadを参照してください。 デフォルトでは、メモリオブジェクトのものが使用されます。
戻り値: MemorizedFuncオブジェクト: デコレートした関数
clear()メソッド
clear(warn=True)
キャッシュディレクトリ全体を消去します。
eval()メソッド
eval(func, *args, **kwargs)
func: callable: メモリのコンテキストで使用するeval関数
*args および **kwargs ：funcに渡される引数
このメソッドは、キャッシュが最新でない場合にのみ関数が呼び出されることを除いて、組み込みのapplyと同様に機能します。
デコレートされた関数での便利なメソッド
Memory.cache()で装飾された関数は、MemorizedFuncオブジェクトであり、通常の関数のように動作するだけでなく、キャッシュの探索と管理に役立つメソッドを公開します。
MemorizedFunc()メソッド
class joblib.memory.MemorizedFunc(func, location, backend = 'local'、
ignore = None、mmap_mode = None、
compress = False、verbose = 1、timestamp = None）
呼び出されるたびに戻り値をキャッシュするための関数を装飾する呼び出し可能なオブジェクト。
キャッシュを検査またはクリーンアップするためのメソッドが提供されています。
func: callable
デコレートするオリジナルの関数
location: string
joblibキャッシュの場所。 使用するストアバックエンドによって異なります。
backend: str
キャッシュファイルの読み取り/書き込み用のストアバックエンドのタイプ。
デフォルトは'local'です。この場合、location引数はディスクストレージへのパスです。
ignore: list or None
再計算するかどうかを選択するときに無視する変数名のリスト。
mmap_mode: None, ‘r+’, ‘r’, ‘w+’, ‘c’
キャッシュnumpy配列からロードするときに使用されるメモリマップモード。 値の意味については、numpy.loadを参照してください。
compress: boolean or integer
ディスクに保存されたデータを圧縮するかどうかのフラグ。 整数を指定する場合は、1〜9にする必要があり、圧縮量を設定します。 圧縮された配列はメモリマップでは読み取れないことに注意してください。
verbose: int、オプション
詳細フラグは、関数の評価時に発行されるメッセージを制御します。
アトリビュート
depth: int、オプション
出力されるオブジェクトの深さ。
call()メソッド
call(*args, **kwargs)
指定された引数を使用して関数を強制的に実行し、出力値を保持します。
clear()メソッド
clear(warn=True)
キャッシュディレクトリ全体を消去します。
ParallelクラスのAPI
joblib.Prallelクラス
class joblib.Parallel(n_jobs=None, backend=None, verbose=0, timeout=None,
pre_dispatch='2 * n_jobs', batch_size='auto', temp_folder=None,
max_nbytes='1M', mmap_mode='r', prefer=None, require=None)
読み取り可能な並列マッピングのヘルパークラス。
n_jobs: `int
backend=”multiprocessing”の場合のPythonワーカープロセスの数や、backend=” threading”の場合のスレッドプールのサイズなど、同時に実行されるジョブの最大数。
n_job=-1を与えた場合、すべてのCPUが使用されます。 n_jobs=1を指定すると、並列計算コードはまったく使用されないため、デバッグに役立ちます。
n_jobs=-1未満のの場合、（n_cpus + 1 + n_jobs）が使用されます。 したがって、n_jobs = -2の場合、1つを除くすべてのCPUが使用されます。 parallel_backendコンテキストマネージャーで実行されて、n_jobsに別の値を設定しない限り、Noneはn_jobs=1（順次実行）として解釈されるデフォルト値です。
backend: str、ParallelBackendBaseインスタンス or None、デフォルト: 'loky'
並列化バックエンドの実装を指定します。 サポートされているバックエンドは次のとおりです。
“loky”: デフォルトで使用されるlokyは、ワーカーPythonプロセスと入力データと出力データを交換するときに、通信とメモリのオーバーヘッドを引き起こす可能性があります。multiprocessing.Poolに基づく以前のプロセスベースのバックエンドを「マルチプロセス処理」します。 lokyよりも堅牢ではありません。
"threading"：threadingは、非常にオーバーヘッドの少ないバックエンドですが、呼び出された関数がPythonオブジェクトに大きく依存している場合、PythonのGILの影響を受けます。 スレッド処理は、実行のボトルネックがGILを明示的に解放するコンパイル済み拡張機能である場合に最も役立ちます。例えば、Cythonでwith nogilブロックにラップされたループやNumPyなどのライブラリへの高価な呼び出しなどの場合です。
register_parallel_backendを呼び出してバックエンドを登録できます。 これにより、好みのバックエンドを実装できます。ライブラリ内のParallelの呼び出しでバックエンド名をハードコーディングすることはお勧めしません。 代わりに、ライブラリユーザーがparallel_backendコンテキストマネージャーを使用して外部からバックエンドを変更できるように、preferまたはrequireを設定することをお勧めします。
prefer: "pricesses"、"threads"、None デフォルト：None
parallel_backendコンテキストマネージャーで特定のバックエンドが選択されていない場合に、デフォルトのバックエンドを選択するためのソフトヒント。 デフォルトのプロセスベースのバックエンドは"loky"であり、デフォルトのスレッドベースのバックエンドは"threading"です。 バックエンドパラメータが指定されている場合は無視されます。
require: "sharedmem" or None デフォルト：None
バックエンドを選択するための強制的制約。 "sharedmem"に設定すると、ユーザーがparallel_backendを使用して非スレッドベースのバックエンドを要求した場合でも、選択したバックエンドはシングルホストでスレッドベースになります。
webose: int、オプション
詳細レベル：ゼロ以外の場合、進行状況メッセージが出力されます。 50を超えると、出力はstdoutに送信されます。 メッセージの頻度は、詳細レベルとともに増加します。 10を超える場合は、すべての反復が報告されます。
timeout：float、オプション
完了する各タスクのタイムアウト制限。 タスクに時間がかかると、TimeOutErrorが発生します。 n_jobs != 1の場合にのみ適用されます
pre_dispatch: "all"、int 、"3 * njobs"のような式
事前にディスパッチされるタスクのバッチ数。 デフォルトは "2 * n_jobs" です。 batch_size=”auto”の場合、これは妥当なデフォルトであり、ワーカーはアイドル状態にあるべきではありません。
batch_size: int、"auto" デフォルト: "auto"
各ワーカーに一度にディスパッチするタスク数。 個々の計算処理が非常に速い場合、オーバーヘッドのために、ワーカーへの呼び出しのディスパッチは順次計算よりも遅くなる可能性があります。 複数の高速計算を一緒にバッチ処理すると、これを軽減することができます。 "auto"では、バッチが完了するのにかかる時間を追跡し、推測に基づいて、バッチサイズを動的に調整して0.5秒のオーダーの時間を維持します。 初期バッチサイズは1です。
batch_size="auto"とbackend="threading"の組み合わせの場合は、スレッドバックエンドのオーバーヘッドが非常に少なく、より大きなバッチサイズを使用しても利益が得られないため、一度に1つのタスクのバッチをディスパッチします。
temp_folder: str、オプション デフォルト: None
ワーカープロセスとメモリを共有するために大きな配列をメモリマッピングするためにプールによって使用されるフォルダー。backend= が ”loky”または“multiprocessing”の場合にのみ有効
temp_folderがNoneの場合、次のフォルダーの順番に試行します。
環境変数JOBLIB_TEMP_FOLDERが指すフォルダー。
/dev/shmフォルダーが存在し、書き込み可能である場合
これは最新のLinuxディストリビューションでデフォルトで使用可能なRAMディスクファイルシステムです。
TMP、TMPDIR、またはTEMP環境変数が示すシステムの一時フォルダー
max_nbytes: int、str、None、オプション デフォルト: "1M'
temp_folderで自動メモリマッピングをトリガーする、ワーカーに渡される配列のサイズのしきい値。 バイト単位の整数、または、1 メガバイトの場合は"1M"などの文字列として与えることもできます。大きな配列のメモリマッピングを無効にするためには、Noneを使用します。
backend= が ”loky”または“multiprocessing”の場合にのみ有効
mmap_mode: None、r、r+、w+、c
ワーカーに渡されるnumpy配列のメモリマッピングモード。
ヘルパー関数
joblib.delayed()
joblib.delayed(function)
function: callable
関数の引数をキャプチャするために使用されるデコレータ。
joblib.register_parallel_backend()
joblib.register_parallel_backend(name, factory, make_default=False)
新しいパラレルバックエンドファクトリを登録します。
name: str
指定したバックエンドがParallelクラスに渡され、新しいバックエンドを選択できます。
factory: callable
ParallelBackendBaseのインスタンスを返す、引数を取らない任意の呼び出し可能オブジェクト。
make_default: bool
make_default=Trueを設定することにより、デフォルトのバックエンドをグローバルに上書きします。
注意：この関数は実験的なものです。
joblibの将来のバージョンで変更される可能性があります。
joblib.parallel_backend()
joblib.parallel_backend(backend, n_jobs=-1, inner_max_num_threads=None, **backend_params)
withブロック内でParallelオブジェクトが使用するデフォルトのバックエンドを変更します。
バックエンドが文字列の場合、register_parallel_backend関数を使用して以前に登録された実装と一致している必要があります。
デフォルトでは、次のバックエンドを使用できます。
"loky"：単一ホストのプロセスベースの並列処理。デフォルト
"threading"：単一ホスト、スレッドベースの並列処理、
"multiprocessing"：従来のシングルホスト、プロセスベースの並列処理。
"dask"：DasKバックエンドを使用しての分散処理
"ray"：分散型クラスタ Ray を使用しての分散処理
または、バックエンドをインスタンスとして直接渡すこともできます。
デフォルトでは、呼び出し元が n_jobs引数に明示的な値を渡さない限り、使用可能なすべてのワーカーが使用されます。
これは、backend="バックエンド名"引数をParallelクラスのコンストラクターに渡す代わりの方法です。 これは、joblibを内部的に使用するけれど、独自のAPIでバックエンド引数を公開しないライブラリコードを呼び出す場合に特に役立ちます。
code: python
>> from operator import neg
>> with parallel_backend('threading'):
... print(Parallel()(delayed(neg)(i + 1) for i in range(5)))
...
Pythonオブジェクトを操作する関数を実行する場合は、"loky"をお勧めします。 "threading"は、Python の GILを解放する関数に最も効率的なオーバーヘッドの少ない代替手段です。 I /OバウンドまたはCPUバウンドのようなコードはGILを明示的に解放するネイティブコードへのいくつかの呼び出しを含みます。
さらに、Dask および Distributed パッケージがインストールされている場合は、"dask"バックエンドを使用して、オーバーサブスクリプションなしでネストされた並列呼び出しのスケジューリングを改善し、複数のホストのネットワーククラスターに並列呼び出しを分散できる可能性があります。
分散型クラスタが利用できる場合は、"ray"バックエンドを使用して、ノードのクラスターにワークロードを分散することもできます。(Rayについては"Rayを使ってみよう"で解説しています) "ray"バックエンドを使用するには、次の行を追加します。
code: python
>> from ray.util.joblib import register_ray
>> register_ray()
>> with parallel_backend("ray"):
... print(Parallel()(delayed(neg)(i + 1) for i in range(5)))
注意 ：この関数は実験的なものです。
joblibの将来のバージョンで変更される可能性があります。
Joblibは、OpenBLAS、Intel MKL、OpenMPなどのサードパーティのスレッドプールライブラリで使用できるスレッド数を制限することにより、オーバーサブスクリプション(コアよりも多くのワーカースレッドがあるときに発生する状態)を制限しようとします。 各ワーカーのデフォルトの制限はmax(cpu_count() // effective_n_jobs, 1) で求まる値に設定されていますが、この制限は、子プロセスでこの制限を設定するために使用されるinner_max_num_threads引数で上書きできます。
joblib.dump()
joblib.dump(value, filename, compress=0, protocol=None, cache_size=None)
任意のPythonオブジェクトを1つのファイルに永続化します。
value: 任意のPythonオブジェクト
指定したオブジェクトをディスクに格納する
filename: str、pathlib.Path、ファイルオブジェクト
保存されるファイルオブジェクトまたはファイルのパス。
サポートされているファイル名拡張子（.z、.gz、.bz2、.xz、.lzma）のいずれかに対応する圧縮方法が自動的に使用されます。
compress: boolean or integer、２値のタプル、オプション
データのオプションの圧縮レベル。 0またはFalseでは圧縮しません。値が大きいほど圧縮率は高くなりますが、読み取りと書き込みの時間も遅くなります。 多くの場合、3を使用することは適切な値となります。compress=Trueの場合、使用される圧縮レベルは3です。compressが2値のタプルの場合、最初の要素は、サポートされているコンプレッサー間の文字列（例： 'zlib'、 'gzip'、 'bz2'、 'lzma'、'xz '）、2番目の要素は、圧縮レベルに対応する0から9までの整数でなければなりません。
protocol: int、オプション
Pickleプロトコル。サポートされているプロトコルは0、1、2、3、4です。デフォルトは3です。
プロトコル3は、Python3用に設計された後方互換性のないプロトコルです。
使用するプロトコルが高いほど、Pythonの最近のバージョンが必要になります。
負のプロトコルバージョンを指定すると、処理できる最高値のプロトコルが選択されます。
詳細については、pickle.dumpのドキュメントを参照してください。
cache_size: 正の整数、オプション
このオプションは0.10で非推奨になり、効果はありません。
戻り値：ファイル名のリスト
データが保存されているファイル名のリスト。 compress=Falseの場合、各配列は異なるファイルに保存されます。
注意
ロード時のメモリマッピングは、圧縮ファイルには使用できません。
したがって、圧縮を使用すると、読み込みが大幅に遅くなる可能性があります。
さらに、圧縮ファイルは、ダンプおよびロード中に余分なメモリを消費します。
joblib.load()
joblib.load(filename, mmap_mode=None)
joblib.dumpで永続化されたファイルからPythonオブジェクトを再構築します。
注意：joblib.loadはpickleモジュールに依存しているため、任意のPythonコードを実行できます。
したがって、信頼できないソースからファイルをロードするために使用しないでください。
filename: str、pathlib.Path、ファイルオブジェクト
ファイルオブジェクトまたはオブジェクトのロード元のファイルのパス
mmap_mode: None, ‘r+’, ‘r’, ‘w+’, ‘c’、オプション
キャッシュnumpy配列からロードするときに使用されるメモリマップモード。 引数の意味については、numpy.load を参照してください。
Noneでない場合、アレイはディスクからメモリマップされます。 このモードは、圧縮ファイルには影響しません。 この場合、再構築されたオブジェクトは、最初にピクルされたオブジェクトと正確に一致しなくなる可能性があることに注意してください。
戻り値: 任意のPython オブジェクト
ファイルに保存されているオブジェクト
注意：
この関数は、ダンプ中に個別に保存されたnumpy配列ファイルをロードできます。
mmap_mode引数が指定されている場合、それはnumpy.loadに渡され、配列はmemmapとしてロードされます。 結果として再構築されたオブジェクトは元のpickle化されたオブジェクトと一致しない可能性があります。
ファイルが圧縮されて保存された場合、配列をメモリに保存できないことに注意してください。
joblib.hash()
joblib.hash(obj, hash_name='md5', coerce_mmap=False)
numpy配列を含むPythonオブジェクトを一意に識別するための迅速なハッシュ計算。
hash_name: "md5"、"sha1"
使用されるハッシュアルゴリズム。 sha1の方が安全だと思われますが、md5の方が高速です。
coerce_mmap: boolean
numpy.memmapとnumpy.ndarrayの間に相違がないようにするかどうかのフラグ
joblib.register_compressor()
joblib.register_compressor(compressor_name, compressor, force=False)
新しい圧縮処理を登録します。
compressor_name: str
新しい圧縮処理の名前
compressor: CompressorWrapper
CompressorWrapperのインスタンスオブジェクト