ONNXパイプライン・モデル: テキスト埋込み

ONNXパイプライン・モデルは、テキストを入力として受け入れ、埋込みを出力として生成するテキスト埋込みモデルを提供します。パイプライン・モデルでは、テキストに必要な前処理および後処理も提供されます。

ノート:

このAPIは23.7で更新されています。23.6以下のバージョンでは、PythonパッケージEmbeddingModelおよびEmbeddingModelConfigが使用されています。これらのパッケージは、それぞれONNXPipelineおよびONNXPipelineConfigに置き換えられます。最新バージョンを使用することをお薦めします。非推奨のPythonクラスの詳細は、「事前トレーニング済モデルをONNXモデルに変換するPythonクラス(非推奨)」を参照してください。
この機能は、OML4Py 2.1クライアントでのみ動作します。OML4Pyサーバーではサポートされていません。
データベース内の埋込みモデルには、トークン化と後処理を含める必要があります。トークン化を外部で処理し、テンソルをSQL演算子に渡し、出力テンソルをベクトルに変換する必要があるため、コアONNXモデルをDBMS_VECTOR.LOAD_ONNX_MODELに指定するだけでは不十分です。
Oracleは、Hugging Face all-MiniLM-L12-v2モデルをONNX形式で提供しており、DBMS_VECTOR.LOAD_ONNX_MODELを使用してデータベースに直接ダウンロードできます。詳細は、ブログ投稿「Oracle Database 23aiの事前組込み埋込み生成モデルが利用可能になりました」を参照してください。

データの埋込みを生成するためのONNX形式の事前トレーニング済モデルがない場合、外部ソースから事前トレーニング済モデルをダウンロードして、そのモデルを前処理ステップおよび後処理ステップで拡張されたONNX形式に変換し、結果のONNX形式のモデルをOracle DatabaseにインポートするPythonパッケージが用意されています。DBMS_VECTOR.LOAD_ONNX_MODELプロシージャまたはexport2db()関数を使用して、ファイルをマイニング・モデルとしてインポートします(eport2db()は、ONNXPipelineオブジェクトのメソッドです)。次に、ONNXモデルでデータベース内のONNX Runtimeを利用して、ベクトル埋込みを生成します。

Pythonパッケージでは、大まかに次のタスクが実行されます:

外部ソース(Hugging Faceリポジトリなどから)からシステムに事前トレーニング済モデルをダウンロードします
前処理および後処理ステップを使用してモデルを拡張し、新しいONNXモデルを作成します
拡張したONNXモデルを検証します
データ・マイニング・モデルとしてデータベースにロードするか、オプションでファイルにエクスポートします

Pythonパッケージは、事前構成済リストのどのモデルも入力として受けることができます。または、特定のモデル・グループ(テキスト・モデルやイメージ・モデルなど)の共通構成を含む組込みテンプレートを使用できます。事前構成済リストとは何か、組込みテンプレートとは何か、およびそれらを使用する方法を理解するには、以降の説明をお読みください。

制限事項

この表では、Pythonパッケージの制限について説明します。

ノート:

この機能は、OML4Py 2.1クライアントでのみ使用できます。

パラメータ	説明
`Transformer Model Type`	テキスト埋込みをサポートするトランスフォーマ・モデルをサポートします。
`Model Size`	モデル・サイズは1GB未満にする必要があります。量子化はサイズを小さくするのに役立ちます。
`Tokenizers`	`BERT`、`GPT2`、`SENTENCEPIECE`、`CLIP,` または`ROBERTA`である必要があります。

モデルの事前構成済リスト

モデルの事前構成済リストは、Pythonパッケージで提供される外部リソース・リポジトリの共通モデルです。事前構成済モデルには既存の仕様があります。ユーザーは、開始点としてテキスト・テンプレートを使用して独自の仕様を作成できます。事前構成済リストのすべてのモデル名のリストを取得するには、show_preconfigured関数を使用します。

テンプレート

Pythonパッケージには組込みテキスト・テンプレートが用意されており、前処理操作と後処理操作を使用して事前トレーニング済モデルを構成できます。テンプレートには、事前トレーニング済モデルのデフォルト仕様があります。この仕様を変更または拡張して、カスタム構成を作成できます。テキスト・テンプレートでは、デフォルトで後処理操作として平均プーリングおよび正規化が使用されます。

テキスト・モデルをONNX形式に変換し、それらをファイルまたはデータベースに格納するためのエンドツーエンドの例:

Pythonパッケージoml.utilsを使用するには、次のものがあることを確認します:

オンプレミス・データベース用にLinux X64で実行されているOML4Py 2.1クライアント
Python 3.12 (以前のバージョンは互換性がありません)

。

作業ディレクトリでPythonを起動します。

python3

Python 3.12.6 | (main, Feb 27 2024, 17:35:02) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

OML4Pyクライアントで、Pythonクラスをロードします。
```
from oml.utils import ONNXPipeline, ONNXPipelineConfig
```
次を実行して、すべての事前構成済モデルのリストを取得できます。
```
ONNXPipelineConfig.show_preconfigured()
```
使用可能なテンプレートのリストを取得するには:
```
ONNXPipelineConfig.show_templates()
```
次の中から選択します:
- 事前構成済モデル「sentence-transformers/all-MiniLM-L6-v2」を使用してテキスト・パイプラインを生成し、ローカル・ディレクトリに保存します:
```
#generate from preconfigured model "sentence-transformers/all-MiniLM-L6-v2"
pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")
pipeline.export2file("your_preconfig_file_name",output_dir=".")
```
- 事前構成済モデル「sentence-transformers/all-MiniLM-L6-v2」を使用してテキスト・パイプラインを生成し、データベースに保存します:
```
#generate from preconfigured model "sentence-transformers/all-MiniLM-L6-v2"
pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")
pipeline.export2db("your_preconfig_file_name")
```
  ノート:
  export2db( )が成功するには、データベースへの接続が必要です。次のコードで資格証明を指定して、接続が成功していることを前提としています。
```
import oml 
oml.connect(user="username",password="password",dsn="dsn");
```
- テンプレートを使用したテキスト・パイプラインの生成およびローカル・ディレクトリへの保存
```
from oml.utils import ONNXPipeline, ONNXPipelineConfig
config   = ONNXPipelineConfig.from_template("text", max_seq_length=256,
           distance_metrics=["COSINE"], quantize_model=True)
pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2",
           config=config)
pipeline.export2file("your_preconfig_model_name", output_dir=".")
```
このコードについて説明します。

from oml.utils import ONNXPipeline, ONNXPipelineConfig

この行は、ONNXPipelineおよびONNXPipelineConfigの2つのクラスをインポートします。
事前構成済モデルの最初の例では、ONNX形式モデルが特定のディレクトリに保存されます:
- pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")は、ONNXPipelineクラスのインスタンスを作成し、model_nameパラメータで指定された事前トレーニング済モデルをロードします。pipelineは、テキスト埋込みモデル・オブジェクトです。sentence-transformers/all-MiniLM-L6-v2は、文の埋込みを計算するためのモデルの名前です。これはHugging Faceのモデル名です。Oracleでは、Hugging Faceのモデルをサポートしています。
- export2fileコマンドでは、ユーザー指定のモデル名を持つONNX形式モデルがファイルに作成されます。your_preconfig_file_nameは、ユーザー定義のONNXモデルのファイル名です。
- output_dir="."は、ファイルが保存される出力ディレクトリを指定しています。"."は、現在のディレクトリ(スクリプトが実行されているディレクトリ)を示します。
事前構成済モデルの2番目の例では、ONNXモデルがデータベースに保存されます:
- pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")は、ONNXPipelineクラスのインスタンスを作成し、model_nameパラメータで指定された事前トレーニング済モデルをロードします。pipelineは、テキスト埋込みモデル・オブジェクトです。sentence-transformers/all-MiniLM-L6-v2は、文の埋込みを計算するためのモデルの名前です。これはHugging Faceのモデル名です。Oracleでは、Hugging Faceのモデルをサポートしています。
- export2dbコマンドは、データベースにユーザー定義のモデル名を持つONNX形式モデルを作成します。your_preconfig_model_nameは、ユーザー定義のONNXモデル名です。
テンプレートの例で:
- ONNXPipelineConfig.from_template("text", max_seq_length=256 distance_metrics=["COSINE"], quantize_model=True): この行では、from_templateというメソッドを使用して埋込みモデルの構成オブジェクトを作成します。"text"引数は、テンプレートの名前を示します。max_seq_length=512パラメータは、トークン数としてモデルへの入力の最大長を指定します。デフォルト値はありません。この値は事前構成されていないモデルに対して指定します。
- pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2", config=config)は、特定のモデルおよび以前に定義した構成でONNXPipelieneインスタンスを初期化します。model_name="all-MiniLM-L6-v2"引数は、ロードする事前トレーニング済モデルの名前または識別子を指定します。
- export2fileコマンドでは、ユーザー定義のモデル名を持つONNX形式モデルがファイルに作成されます。your_preconfig_model_nameは、ユーザー定義のONNXモデル名です。
- output_dir="."は、ファイルが保存される出力ディレクトリを指定しています。"."は、現在のディレクトリ(スクリプトが実行されているディレクトリ)を示します。
ノート:
- モデルのサイズは1GBに制限されます。400MBより大きいモデルの場合、Oracleでは量子化することをお薦めします。
  
  量子化では、モデルの重みを高精度表現から低精度形式に変換することで、モデル・サイズが小さくなります。量子化オプションは、重みをINT8に変換します。モデルのサイズを小さくすると、共有メモリーにモデルをキャッシュできるため、パフォーマンスがさらに向上します。
- .onnxファイルは、opsetバージョン17およびirバージョン8で作成されます。これらのバージョン番号の詳細は、https://onnxruntime.ai/docs/reference/compatibility.html#onnx-opset-supportを参照してください。
Pythonを終了します。
```
exit()
```
変換されたモデルがディレクトリに存在するかどうかを確認します。
ノート:
ONNXファイルは、export2fileが使用されている場合にのみ作成されます。export2dbを使用すると、ローカルのONNXファイルは生成されず、モデルはデータベースに保存されます。

拡張子がonnxの現行ディレクトリ内のすべてのファイルをリストします。
```
ls -ltr *.onnx
```
Pythonユーティリティ・パッケージでは、ONNX Runtimeを使用して実行する前に、埋込みテキスト・モデルが検証されます。Oracleでは、stringの入力およびfloat32 [<vector dimension>]の出力に準拠するONNX埋込みモデルがサポートされています。

モデルの入力または出力がこの説明に準拠していない場合は、インポート中にエラーが表示されます。
次の中から選択します:
- PL/SQLを使用して、ONNXモデルをデータベースにロードします:
  1. ONNXモデルをロードするには、次の構文を使用します:
```
BEGIN
   DBMS_VECTOR.LOAD_ONNX_MODEL(
     directory => 'ONNX_IMPORT',
     file_name => 'all-MiniLM-L6.onnx',
     model_name => 'ALL_MINILM_L6');
END;
```
  2. your_template_file_nameという名前のONNXファイルをデータベース・サーバー上のディレクトリに移動し、ファイル・システムおよびデータベースにインポート用のディレクトリを作成します。
```
mkdir -p /tmp/models
sqlplus / as sysdba
alter session set container=ORCLPDB;
```
    必要な権限を適用します。この例では、ORCLPDBという名前のプラガブル・データベースを使用しています。
```
-- directory to store ONNX files for import
CREATE DIRECTORY ONNX_IMPORT AS '/tmp/models';
-- grant your OML user read and write permissions on the directory
GRANT READ, WRITE ON DIRECTORY ONNX_IMPORT to OMLUSER;
-- grant to allow user to import the model
GRANT CREATE MINING MODEL TO OMLUSER;
```
- Pythonを使用して、ONNXモデルをデータベースにロードします:

モデルがデータベースにあることを確認します:

オペレーティング・システム・プロンプトで、SQL*Plusを起動し、接続します。

sqlplus OML_USER/password@pdbname_medium;


SQL*Plus: Release 23.0.0.0.0 - Production on Wed May 1 15:33:29 2024
Version 23.4.0.24.05

Copyright (c) 1982, 2024, Oracle. All rights reserved.

Last Successful login time: Wed May 01 2024 15:27:06 -07:00

Connected to:
Oracle Database 23ai Enterprise Edition Release 23.0.0.0.0 - Production
Version 23.4.0.24.05

データベース内のONNXモデルをリストして、ロードされたことを確認します:

SQL> select MODEL_NAME, ALGORITHM from user_mining_models WHERE MODEL_NAME='YOUR_PRECONFIG_MODEL_NAME';

MODEL_NAME ALGORITHM
-------------------------------------
YOUR_PRECONFIG_MODEL_NAME ONNX

DBMS_VECTOR.LOAD_ONNX_MODELは、モデルをデータベースに保存するためにexport2dbを使用するかわりに、ONNXモデル・ファイルをローカル・システムに保存するためにexport2fileが使用された場合にのみ必要です。DBMS_VECTOR.LOAD_ONNX_MODELは、ONNXフォーマット・モデルをOracle Databaseにインポートして、データベース内ONNXランタイムを活用し、VECTOR_EMBEDDING SQL演算子を使用してベクトル埋込みを生成します。