はじめに

Oracle Container Registry からOML4Py 2.1.1 Clinetコンテナが提供されました。
これまで OML4Py クライアントをセットアップするには、Python をソースからビルドし、必要なサードパーティパッケージをバージョン固定でインストールし、Oracle Instant Client を導入して環境変数を設定するという複数のステップが必要でした。コンテナを使うことで、これらの作業がひとつの Podman pull コマンドに集約されます。

このコンテナを使って、Hugging Face の事前学習済み埋め込みモデルを Oracle AI Vector Search や Oracle Select AI で利用できる ONNX 形式に変換・ロードし、Embeddingしてみました。

コンテナを使った作業の流れ

Podman をインストールし、Oracle Container Registry からコンテナイメージを pull
コンテナを起動し、Python セッションを開始
ONNXPipelineConfig.show_preconfigured() で利用可能なモデル一覧を確認
ONNXPipeline で対象モデルを選択し、export2db() でデータベースに直接ロード
SQL の VECTOR_EMBEDDING() でベクトルが生成されることを確認

事前準備

対応 OS: Oracle Linux 8、9、または 10（x86_64）(この記事では Oracle Linux 9を利用)
コンテナランタイム: Podman（Docker は非対応）
Oracle アカウント: Oracle Container Registry (OCR) からイメージを pull するために無料の Oracle アカウントが必要です
rootless Podman の設定: /etc/subuid および /etc/subgid にユーザーエントリが存在すること
接続先 Database: Oracle AI Database 26aiまたは Oracle Autonomous AI Database 26ai (この記事ではOCI Base Databaseを利用)

コンテナ内に含まれるパッケージ

パッケージ	バージョン
Python	3.13.5
oracledb	3.3.0
pandas	2.2.3
numpy	2.1.0
scikit-learn	1.6.1
scipy	1.14.1
matplotlib	3.10.4
torch	2.10.0
onnxruntime	1.20.0
transformers	4.56.1

手順

Step 1: Podman をインストール

まず Podman がインストールされているか確認します。

podman version

出力例（インストール済みの場合）:

Client:       Podman Engine
Version:      4.9.4-rhel
API Version:  4.9.4-rhel
Go Version:   go1.25.7 (Red Hat 1.25.7-1.module+el8.10.0+90804+12f38c29)
Built:        Tue Mar 17 11:33:06 2026
OS/Arch:      linux/amd64

インストールされていない場合は、OS に応じて以下のコマンドを実行します。

Oracle Linux 8 の場合:

sudo dnf module install -y container-tools:ol8

Oracle Linux 9 および 10 の場合:

sudo dnf install -y container-tools

コマンド完了後、"Complete!" というメッセージが表示されれば成功です。

$ podman version
Client:       Podman Engine
Version:      5.6.0
API Version:  5.6.0
Go Version:   go1.25.9 (Red Hat 1.25.9-1.0.1.el9_7)
Built:        Fri May 29 13:42:49 2026
OS/Arch:      linux/amd64

Step 2: rootless Podman の前提条件を確認

rootless Podman は、コンテナ内のユーザー ID をホスト上の非特権 ID にマッピングするために /etc/subuid および /etc/subgid が必要です。これらが設定されていない場合、次のコマンドで設定します。

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER

設定を適用します。

podman system migrate

エントリが存在するか確認します。

grep $USER /etc/subuid

出力例:

opc:100000:65536

Step 3: Oracle Container Registry にサインインしてイメージを pull

OCR にサインイン・ライセンス同意

Oracle Container Registry にアクセス
Sign In を選択し、Oracle SSO のユーザー名とパスワードで認証
初めて OCR を利用する場合は、一度限りの登録手続きが表示されます
OML4Py クライアントコンテナのライセンス同意を求められたら確認して同意（ユーザーアカウントにつき一度だけ必要）

OCR 認証トークンを生成

Podman から OCR にログインする際のパスワードとなる認証トークンを生成します。

OCR ページ右上のプロフィール名をクリック
ドロップダウンから Auth Token を選択
Generate Secret Key をクリックし、表示されたトークンをすぐにコピー

注意: 認証トークンは生成時に一度しか表示されません。紛失した場合は既存のトークンを削除して新たに生成する必要があります。

Podman で OCR にログインしてイメージを pull

podman login container-registry.oracle.com

プロンプトが表示されたら、Oracle SSO のユーザー名と生成した認証トークン（パスワードとして）を入力します。

$ podman login container-registry.oracle.com
Username: youraddress@example.com
Password:
Login Succeeded!

続いて OML4Py クライアントイメージを pull します。

podman pull container-registry.oracle.com/database/oml4py-client:2.1.1.0.0

$ podman pull container-registry.oracle.com/database/oml4py-client:2.1.1.0.0
Trying to pull container-registry.oracle.com/database/oml4py-client:2.1.1.0.0...
Getting image source signatures
Copying blob 3d99478b45ad done   |
Copying blob 5e861cb8ee23 done   |
Copying config 03f866a6cb done   |
Writing manifest to image destination
03f866a6cb75acad97fe08dc096083954708ad84290059947b92835e84c1e054

pull 完了後、イメージが取得されていることを確認します。

podman images

出力例:

REPOSITORY                                            TAG         IMAGE ID      CREATED      SIZE
container-registry.oracle.com/database/oml4py-client  2.1.1.0.0   03f866a6cb75  6 weeks ago  5.74 GB

container-registry.oracle.com/database/oml4py-client:2.1.1.0.0 がリストに表示されていれば成功です。

Step 4: OML4Py2.1.1 Clientコンテナを起動

コンテナ内の書き込み可能ディレクトリは /u01/oml_home です。ホストに用意したtnsnames.oraやWalletのディレクトリをマウントします。

podman run -it --name <コンテナ名> \
  -v <ホスト出力フォルダ>:/u01/oml_home/:U,Z \
  container-registry.oracle.com/database/oml4py-client:2.1.1.0.0

podman run --name oml4py -it \
  -v /home/opc/wallet:/u01/oml_home/wallet:U,Z \
  -e TNS_ADMIN=/u01/oml_home/wallet \
  container-registry.oracle.com/database/oml4py-client:2.1.1.0.0 \
  /bin/bash

注意: 同名のコンテナがすでに存在する場合、Error: the container name "<コンテナ名>" is already in use というエラーが表示されます。先に podman rm <コンテナ名> で既存のコンテナを削除するか、podman run コマンドに --replace フラグを追加してください。

（オプション）既存コンテナへの再接続

2 回目以降のセッションで同じコンテナを再起動する場合は podman run ではなく以下を使用します。

podman start -ai <コンテナ名>

Step 5: 事前設定済みモデルを ONNX に変換してデータベースにロード

コンテナ内に入ったら、Python セッションを開始します。

python3

利用可能な事前設定済みモデルを確認

import oml
from oml.utils import ONNXPipeline, ONNXPipelineConfig

ONNXPipelineConfig.show_preconfigured()

実行例:

>>> import oml
... from oml.utils import ONNXPipeline, ONNXPipelineConfig
...
... ONNXPipelineConfig.show_preconfigured()
...
['sentence-transformers/all-mpnet-base-v2', 'sentence-transformers/all-MiniLM-L6-v2', 'sentence-transformers/multi-qa-MiniLM-L6-cos-v1', 'sentence-transformers/distiluse-base-multilingual-cased-v2', 'sentence-transformers/all-MiniLM-L12-v2', 'BAAI/bge-small-en-v1.5', 'BAAI/bge-base-en-v1.5', 'taylorAI/bge-micro-v2', 'intfloat/e5-small-v2', 'intfloat/e5-base-v2', 'thenlper/gte-base', 'thenlper/gte-small', 'TaylorAI/gte-tiny', 'sentence-transformers/paraphrase-multilingual-mpnet-base-v2', 'intfloat/multilingual-e5-base', 'intfloat/multilingual-e5-small', 'sentence-transformers/stsb-xlm-r-multilingual', 'Snowflake/snowflake-arctic-embed-xs', 'Snowflake/snowflake-arctic-embed-s', 'Snowflake/snowflake-arctic-embed-m', 'mixedbread-ai/mxbai-embed-large-v1', 'openai/clip-vit-large-patch14', 'google/vit-base-patch16-224', 'microsoft/resnet-18', 'microsoft/resnet-50', 'WinKawaks/vit-tiny-patch16-224', 'Falconsai/nsfw_image_detection', 'WinKawaks/vit-small-patch16-224', 'nateraw/vit-age-classifier', 'rizvandwiki/gender-classification', 'AdamCodd/vit-base-nsfw-detector', 'trpakov/vit-face-expression', 'BAAI/bge-reranker-base', 'BAAI/bge-large-en-v1.5', 'ibm-granite/granite-embedding-278m-multilingual', 'thenlper/gte-large', 'Snowflake/snowflake-arctic-embed-l', 'WhereIsAI/UAE-Large-V1']

パイプラインを作成

変換対象のモデルを選択してパイプラインを作成します。

pipeline = ONNXPipeline(model_name="sentence-transformers/all-MiniLM-L6-v2")

データベースに直接ロード

export2db() の引数はデータベース上でのモデル名（オブジェクト名）です。Hugging Face のモデル名（sentence-transformers/all-MiniLM-L6-v2 など）とは別物です。Oracle の識別子規則に従い、英字で始まり、英数字とアンダースコアのみで構成する必要があります。スラッシュ（/）やハイフン（-）は使用できません。ここでは MINILM_L6_V2 とします。

ユーザー名・パスワードで接続する場合:

oml.connect(user="<ユーザー名>", password="<パスワード>", dsn="<サービス名>")
pipeline.export2db("MINILM_L6_V2")

Wallet の TNS エイリアスで接続する場合（Wallet をマウントして起動した場合）:

oml.connect(user="", password="", dsn="<TNSエイリアス>")
pipeline.export2db("MINILM_L6_V2")

ロード結果を確認

SQL*Plus でモデルがロードされているか確認します。

sqlplus <ユーザー名>/<パスワード>@<サービス名>

SELECT MODEL_NAME, ALGORITHM, MINING_FUNCTION
FROM USER_MINING_MODELS
WHERE MODEL_NAME = 'MINILM_L6_V2';

出力例:

MODEL_NAME
-------------------------------------------------------------
ALGORITHM                      MINING_FUNCTION
------------------------------ ------------------------------
MINILM_L6_V2
ONNX                           EMBEDDING

ベクトルが生成されることを確認します。

SELECT VECTOR_EMBEDDING(MINILM_L6_V2 USING 'May the vectors be with you' AS DATA) AS embedding;

出力例:

EMBEDDING
---------------------------------------------------------------------
[-1.60649009E-002,-4.39648442E-002,-3.46924202E-003,-1.17296912E-002, …

ファイルにエクスポート

データベースに直接ロードするのではなく、ONNX ファイルとして出力する場合は export2file を使用します。

pipeline.export2file("MINILM_L6_V2")

>>> pipeline.export2file("MINILM_L6_V2")
/usr/local/lib/python3.13/site-packages/transformers/modeling_attn_mask_utils.py:196: TracerWarning: torch.tensor results are registered as constants in the trace. You can safely ignore this warning if you use this function to create tensors out of constant variables that would be the same every time you call this function. In any other case, this might cause the trace to be incorrect.
  inverted_mask = torch.tensor(1.0, dtype=dtype) - expanded_mask

コンテナ内の現在のワーキングディレクトリ（デフォルト: /u01/oml_home）に MINILM_L6_V2.onnx が生成されます。1 GB 以上のモデルや use_external_data = True に設定されたモデルの場合は zip アーカイブとして出力されます。

[oml_user@c2c9668a2db9 ~]$ ls /u01/oml_home/
MINILM-L6-V2.onnx  MINILM_L6_V2.onnx  wallet

Step 6: ONNX モデルファイルをコンテナの外にコピー

コンテナからホストマシンにモデルファイルをコピーするには、ホスト側で以下のコマンドを実行します。

podman cp <コンテナ名>:<コンテナ内のファイルパス> <ホスト出力フォルダ>

例:

podman cp oml4py:/u01/oml_home/MINILM_L6_V2.onnx /home/opc/wallet/

コピーした ONNX ファイルは、Private AI Services Container の /v1/embeddings REST エンドポイント経由で埋め込み生成に使用できます。

Step 7: クリーンアップ

コンテナを停止・削除する場合は以下を実行します。

# コンテナを停止
podman stop <コンテナ名>

# コンテナを削除
podman rm <コンテナ名>

# イメージを削除（不要な場合）
podman rmi container-registry.oracle.com/database/oml4py-client:2.1.1.0.0

おわりに

今回の検証で確認できたポイントは以下の通りです。

OML4Py 2.1.1 クライアントコンテナを使うことで、Hugging Face の埋め込みモデルから ONNX ファイルへの変換環境を Podman 1 コマンドで構築できます
ONNXPipelineConfig.show_preconfigured() で 30 種類以上の事前設定済みモデルが確認でき、モデル変換の手間が大幅に削減されます
export2db() を使えばモデルを直接データベースにロードでき、SQL の VECTOR_EMBEDDING() 関数でそのまま利用可能です
export2file() でエクスポートした ONNX ファイルは、Private AI Services Container にも転用できるため、一度の変換作業で複数の展開先に対応できます

Oracle AI Vector Search や Select AI を活用したセマンティック検索・RAG 基盤を構築したいエンジニアや、既存の Oracle Database 環境に AI 機能を追加したいデータベース管理者にとって、手軽な出発点となる機能です。

参考情報