※本記事は、Doug Hood による”Getting Started with Private AI Services Container” を翻訳したものです。

はじめに

先日、Oracle Private AI Services Container が Oracle Container Registry で利用可能になったことをお知らせしました。今回は、「何が新しいのか」から一歩進んで、「どう動くのか」を見ていきます。この投稿では、自分の環境にコンテナをインストールし、構成し、使用するまでを順を追って説明します。

このブログを読み終えると、次のことを理解できます。

  • Oracle Private AI Services Container のソフトウェア要件とハードウェア要件
  • Oracle Linux 8 に Podman をインストールする方法
  • Oracle Container Registry からコンテナ・イメージをダウンロードする方法
  • コンテナからインストール・スクリプトを取り出す方法
  • HTTP を使用してコンテナをインストールおよび構成する方法
  • HTTP/SSL を使用してコンテナをインストールおよび構成する方法
  • コンテナが稼働中かどうかを確認する方法
  • コンテナが正常な状態かどうかを確認する方法
  • ロード済みの埋め込みモデルを一覧表示する方法
  • 異なる埋め込みモデルでベクトルを作成する方法
  • 埋め込みモデルの実行時メトリクスを確認する方法

前提条件

以下の例では、Oracle Cloud Infrastructure（OCI）上の仮想マシンで稼働する Oracle Linux 8 を使用し、標準で含まれている OpenSSL ソフトウェアを活用します。また、Oracle Linux 8 向けの Podman もインストールします。

前提となる環境として、privateaivm という名前の VM を使用します。この VM は 2 OCPU、24 GB のメモリー、36 GB のディスク容量を持つデフォルトのブート・ボリュームで構成されています。この環境は、このブログのすべての例を実行するための十分な土台になります。

Oracle Container Registry からイメージをダウンロードするには、無償のOracleアカウントが必要です。このアカウントには、対応する Single Sign-On（SSO）ユーザー名が割り当てられます。インストール作業の中で最も難しい部分は、Oracle Container Registry からコンテナ・イメージを取得することになる場合がよくあります。Oracle Account、Oracle Single Sign-On、Oracle Container Registry は、Oracle Private AI Services Container とは独立して使われる標準的な Oracle の技術です。

Oracle Private AI Services Container のインストールに必要な詳細な前提条件については、公式ドキュメントのInstall the Private AI Services Containerを参照してください。

Podman のインストール

これらの例では、コンテナ・ランタイムとして Podman を使用します。現時点では、インストール・スクリプトは Docker をサポートしていません。

Oracle Linux 8 の仮想マシンにログインしたら、次のコマンドを実行して Podman ソフトウェア・パッケージをインストールします。

sudo dnf module install -y container-tools:ol8

・・・

Podman が正しくインストールされていること、およびイメージがロードされているかどうかを確認します。

podman version
podman images

コンテナ・イメージをダウンロードする手順

1. Oracle Container Registry にサインインする

Oracle Container Registry のPrivate AI Services Containerページにアクセスし、サインインします。サインイン・リンクはページ右上にあります。

無償のOracleアカウントを持っているか、新しく作成する必要があります。Oracle Single Sign-On（SSO）のユーザー名とパスワードの入力を求められます。まだcontainer-registry.oracle.com に登録していない場合は、登録を促されます。登録により、あなたの SSO ユーザー名が Oracle Container Registry に SSO 利用可能ユーザーとして関連付けられます。

この一度限りの登録が完了すると、次回以降に Sign In をクリックした際は、SSO ユーザー名とパスワードの入力だけで済みます。

注
Oracle Account の SSO ユーザー名とパスワードは、必ず自分自身のものを使用してください。私のものではありません。

2. ライセンス契約に同意する

Oracle Private AI Services Container のライセンス契約を読み、同意するには、Continue をクリックする必要があります。このライセンスは無償で利用でき、クレジットカードも不要です。また、同意は一度だけでよく、以後のアクセスではその状態が保持されます。

以下はOracle Private AI Services Container のライセンスの冒頭

…

以下はOracle Private AI Services Container のライセンスの末尾

こちらを確認したうえで、コンテナをダウンロードするには Accept をクリックする必要があります。同意しない場合は、コンテナをダウンロードできません。

ライセンスに同意すると、この状態が Oracle Container Registry 上の Private AI Services Container ページ右側に表示されます。

3. コンテナ・イメージを取得するための認証トークンを生成する

Oracle Container Registry にログインするには、認証トークン（パスワードとして使用）が必要です。認証トークンを生成するには、ページ右上の Oracle Account のプロファイル名をクリックし、プロファイル・メニューから Auth Token を選択します。

Auth Token ページで、Generate Secret Key リンクをクリックします。

生成された Auth Token は必ずコピーしてください。表示されるのは一度だけです。

注
以前の Auth Token を忘れた場合でも、新しい Auth Token をいつでも生成できます。

4. コンテナ・イメージをダウンロードする

Private AI Services Container のイメージを仮想マシンにダウンロードします。

a. コマンドラインから Oracle Container Registry にログインする

username には、Oracleアカウントの Single Sign-On / Profile ユーザー名を使用します。

password には、Oracle Container Registry の Web サイトで先ほど生成した Auth Token を使用します。

podman login container-registry.oracle.com

b. OCR からイメージを pull する

コンテナ・イメージのダウンロードにかかる時間は、ネットワーク速度と仮想マシンのストレージ性能に依存します。

podman pull container-registry.oracle.com/database/private-ai:25.1.2.0.0

コンテナのダウンロード時間は、ネットワーク帯域幅と VM 上のストレージ速度によって変わります。

c. コンテナ・イメージがダウンロードされたことを確認する

podman images

d. インストール・スクリプトを取り出す

Private AI Services Container のインストール・スクリプトは、コンテナをインストールおよび構成するための推奨方法です。これらのスクリプトはベスト・プラクティスを実装しており、SELinux の最小権限設定、有効なデジタル証明書と API キーの作成、TLS 1.3 の構成といった複雑な処理を担います。

インストール・スクリプトはコンテナ内に含まれているため、まずコンテナを作成し、その後で Linux ホスト・マシンにスクリプトをコピーする必要があります。

1. コンテナを作成する

上記の podman ps 出力で確認した imageid を使って、コンテナをcreateします。ただし、この時点では起動しません。

export IMAGE_ID=dd3fd4ae5de0
podman create $IMAGE_ID

2. コンテナ ID を確認する

コンテナを作成したときの出力が、新しい container_id です。なお、この時点ではコンテナはまだ起動していません。

export CONTAINER_ID=477cce1adc23fd6911465757d93aac1be0f38e4d60821597160bf54f358c6207

3. インストール・スクリプトを取り出す

export INSTALL_SCRIPT_ZIP=/privateai/scripts/privateai-setup-25.1.2.0.0.zip
export DESTINATION=/home/opc
podman cp $CONTAINER_ID:$INSTALL_SCRIPT_ZIP $DESTINATION

4. インストール・スクリプトを展開する

cd /home/opc
unzip privateai-setup-25.1.2.0.0.zip

これで、インストール作業の中でも最も難しい部分は完了です。ここからは、用意されているスクリプトを使って実際にインストールと構成を行います。こちらのほうがずっと簡単です。

コンテナのインストールと構成

Oracle Private AI Services Container は、HTTP と HTTP/SSL の両方について、デフォルト構成と高度な構成をサポートしています。学習コストを下げるため、このブログでは最もシンプルな構成である「デフォルトの HTTP」と「デフォルトの HTTP/SSL」に絞って説明します。より高度な構成シナリオについては、今後の投稿で取り上げる予定です。

この 2 つの基本構成を使うことで、次の操作を行えます。

  • HTTP または HTTP/SSL のポートを構成する
  • コンテナに同梱されたベクトル埋め込みモデルを使用する
  • コンテナを起動、確認、停止、再起動する
  • Podman と /health エンドポイントを使ってコンテナの状態を確認する
  • 利用可能な埋め込みモデルを表示する
  • さまざまな埋め込みモデルを使ってベクトルを作成する
  • 異なるモデルのパフォーマンス・メトリクスを確認する

HTTP とデフォルト・モデルを使用したインストール

1. 最もシンプルな HTTP 構成を作成する

これは最も基本的なセットアップです。API キー認証も SSL も使用しません。デフォルトの埋め込みモデルが有効化され、サービスはポート 8080 の HTTP でアクセス可能になります。

ソフトウェアはユーザーのホーム・ディレクトリ配下にインストールできます。

  • PRIVATE_DIR 環境変数は、ホスト・マシン上で各種ディレクトリを作成するディレクトリ・ツリーを指します
  • PRIVATE_DIR の値は /home/opc/privateai である必要はありません

注
http パラメータの前には必ずダッシュを 2 つ付けた --http を指定してください。ダッシュが 2 つでない場合、構文エラーになります。

mkdir /home/opc/privateai
export PRIVATE_DIR=/home/opc/privateai
cd ~/setup
./configSetup.sh -d $PRIVATE_DIR
./containerSetup.sh -d $PRIVATE_DIR --http

このシンプルな構成であれば、これらのスクリプトの実行には数秒しかかかりません。

注

  • security ディレクトリが見つからないという警告は、この構成では影響しません。
  • ディスク容量不足の警告も、この例では無視して構いません。

2a. コンテナが実行中かどうかを確認する

podman ps

Podman の出力では、次の情報を確認できます。

  • コンテナ ID
  • イメージ名
  • コンテナが作成済みであること
  • コンテナの稼働時間
  • 外部および内部の TCP ポート
  • 待ち受けているネットワーク・アドレス
  • コンテナ・インスタンス名

この出力は、コンテナのライフサイクル管理において非常に重要です。

2b. コンテナが HTTP リクエストに応答しているかどうかを確認する

まず始める方法として最も簡単なのは、コンテナと同じマシン上から curl コマンドを実行することです。これにより、HTTP リクエストの接続先として localhost を使用できます。

curl -i http://localhost:8080/health

コンテナ起動後、Web リクエストに応答し始めるまで数秒かかる場合があります。

この curl コマンドは、ローカル・マシン上の /health エンドポイントに対して、デフォルト TCP ポート（8080）を使って HTTP GET リクエストを実行します。-i パラメータは HTTP レスポンス・ヘッダーを表示します。HTTP 200 OK が返れば、コンテナは HTTP リクエストに正常に応答していることを意味します。

3. ロード済みの埋め込みモデルを確認する

Oracle Private AI Services Container は、さまざまなベクトル埋め込みモデルをサポートしています。実際にロードされるモデルは、コンテナのバージョン、同梱されているモデル、および現在の構成設定によって決まります。利用可能なモデル一覧は /models エンドポイントで確認できます。

curl http://localhost:8080/v1/models

この HTTP GET リクエストは、利用可能な埋め込みモデルを表示します。

デフォルト構成では、次のモデルが利用できます。

  • clip-vit-base-patch32-txt
  • clip-vit-base-patch32-img
  • all-mpnet-base-v2
  • all-MiniLM-L12-v2
  • multilingual-e5-base
  • multilingual-e5-large

つまり、これらの埋め込みモデルのいずれを使ってもベクトルを作成できます。英語専用モデル（all-mpnet-base-v2 および all-MiniLM-L12-v2）は、多言語モデルと比べて英語テキストに対してわずかに高い精度を提供します。マルチモーダルなベクトル問い合わせ（例: テキスト + 画像）には CLIP モデルを使用してください。

4. ロード済みモデルを使ってベクトルを作成する

OpenAI API では、一般的な AI 操作のための REST エンドポイント群が定義されています。たとえば、ベクトル埋め込みを作成するには /v1/embeddings エンドポイントを使用します。以下の例では、Oracle Private AI Services Container で /v1/embeddings エンドポイントを使ってベクトルを作成する方法を示します。

curl -X POST -H "Content-Type: application/json" -d '{"model": "multilingual-e5-base", "input":["This is a phrase to vectorize"]}' http://localhost:8080/v1/embeddings

…

このネットワーク・リクエストは、ポート 8080 上の localhost に対して HTTP POST を実行し、/v1/embeddings エンドポイントを呼び出します。POST 本文では JSON を使って、使用する埋め込みモデルと入力データを指定しています。この汎用的な方法により、必要に応じて異なる埋め込みモデルを使い分けられます。OpenAI SDK でも、Python、Node.js、Java など各種言語ライブラリを通じて同等の機能を利用できます。これについては今後のブログで取り上げる予定です。

5. コンテナを停止する

コンテナは、コンテナ ID でも名前でも停止できます。デフォルトのコンテナ名は privateai です。

podman stop privateai

HTTP/SSL とデフォルト・モデルを使用したインストール

この例では、コンテナに含まれる埋め込みモデルを使い、最もシンプルな SSL 構成を使用します。自己署名デジタル証明書を使うことで、内部向けデプロイメントでも無料で SSL（TLS 1.3）を有効化できます。

1. 完全修飾ホスト名を確認する

デジタル証明書と REST 呼び出し用 URL の両方で使用するため、完全修飾ホスト名を確認します。

export HOST=$(hostname -f)
echo $HOST

2a. SSL でコンテナを構成する

ソフトウェアはユーザーのホーム・ディレクトリ配下にインストールできます。

  • PRIVATE_DIR 環境変数は、ホスト・マシン上で各種ディレクトリを作成するディレクトリ・ツリーを指します
  • この PRIVATE_DIR ディレクトリ・ツリーは /home/opc/privateai である必要はありません
  • SECRETS_DIR にはデジタル証明書と API_KEY が作成されます
  • SECRETS_DIR ディレクトリは /home/opc/secrets である必要はありません
cd /home/opc/setup
mkdir -p /home/opc/privateai
mkdir -p /home/opc/secrets
export PRIVATE_DIR=/home/opc/privateai
export SECRETS_DIR=/home/opc/secrets

2b. デジタル証明書、API キー、キーストアを作成する

./secretsSetup.sh -s $SECRETS_DIR

2c. HTTP/SSL でコンテナを起動する

./configSetup.sh -d $PRIVATE_DIR -s $SECRETS_DIR
./containerSetup.sh -d $PRIVATE_DIR
podman ps

これで、HTTP/SSL を有効化した状態でコンテナがポート 8443 で稼働します。

3. コンテナのヘルス状態を確認する

HTTP/SSL を使用する場合、curl では次の点が必要です。

  • --cacert パラメータでデジタル証明書を参照すること
  • 完全修飾ホスト名を使用すること
  • SSL ポート（例: 8443）を指定すること
curl -i --cacert $SECRETS_DIR/cert.pem https://$HOST:8443/health

/health エンドポイントでは API キーは不要です。

4. API_KEY を定義する

以降の REST 呼び出しでは API キーの値が必要になるため、環境変数に格納しておくと便利です。

export API_KEY=$(cat $SECRETS_DIR/api-key)

API_KEY の値は secretsSetup.sh スクリプトによって生成され、認証に使用されます。

5. HTTP/SSL でロード済みモデルを一覧表示する

SSL で /v1/models および /v1/embeddings REST エンドポイントを使用する場合は、有効な API_KEY とデジタル証明書が必要です。

curl --header "Authorization: Bearer $API_KEY" --cacert $SECRETS_DIR/cert.pem https://$HOST:8443/v1/models

6a. HTTP/SSL でベクトルを作成する

multilingual-e5-base 埋め込みモデルを使用して、”The quick brown fox“というデータのベクトルを作成します。

curl -X POST --header "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model": "multilingual-e5-base", "input":["The quick brown fox"]}' --cacert $SECRETS_DIR/cert.pem https://$HOST:8443/v1/embeddings

…

6b. HTTP/SSL でもう 1 つベクトルを作成する

all-minilm-l12-v2 埋め込みモデルを使用して、”jumped over a lazy dog“というデータのベクトルを作成します。JSON ペイロードの model 属性によって、使用する埋め込みモデルを指定します。

curl -X POST --header "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model": "all-minilm-l12-v2", "input":["jumped over a lazy dog"]}' --cacert $SECRETS_DIR/cert.pem https://$HOST:8443/v1/embeddings

…

7. HTTP/SSL でコンテナ・メトリクスを確認する

次の例を使うと、各埋め込みモデルの実行時メトリクスを確認できます。

curl --header "Authorization: Bearer $API_KEY" --cacert $SECRETS_DIR/cert.pem https://$HOST:8443/metrics/embeddings_call_latency

関連ブログ