マーケットプレイス版Oracle WebCenter Content For OCIでセマンティック検索を有効にする

# はじめに

マーケットプレイス版Oracle WebCenter Content For OCI(以降**WCC For OCI**)は、Oracle Cloud Infrastructure上のVMベースのソリューションとして提供されます。WCC For OCIを使用すると、顧客は数回クリックするだけで環境をプロビジョニング/セットアップでき、クラウド上でコンテンツ・ソリューションを提供できるようになります。

詳細は製品ドキュメントおよび概要紹介資料をご確認ください

https://docs.oracle.com/en/cloud/paas/webcenter-content/webcenter-content-on-marketplace/index.html

https://speakerdeck.com/oracle4engineer/oracle-webcenter-content-for-oci-on-marketplace

# この記事で説明すること、しないこと

2025年2月にWCC For OCIの**14c(14.1.2.0.0)** 対応版がリリースされました。また、WCC14c For OCIのみ利用できる新機能として**セマンティック検索(Semantic Search)** もあわせてリリースされました

https://docs.oracle.com/en/cloud/paas/webcenter-content/content-marketplace-whatsnew/index.html#february-2025

この記事では、WCC14c For OCIのセマンティック検索機能を有効化する手順について説明します

なお、セマンティック検索で利用するOracle Database 23aiのAI Vector Searchに関する説明は割愛します。詳細は以下の製品ドキュメントおよびスライドをご確認ください

https://docs.oracle.com/cd/G11854_01/vecse/overview-ai-vector-search.html

https://speakerdeck.com/oracle4engineer/oracle-ai-vector-search

https://speakerdeck.com/oracle4engineer/oracle-ai-vector-search-technical


# WCCのセマンティック検索とは

ユーザーが自然文で検索文を入力すると、WCC側でその意味や文脈を考慮し、関連性の高いコンテンツを検索し、提供します。全文検索のように検索キーワードの取捨選択に時間をかけることなく、効率的な検索ができるようになります
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/41bff489-f5e2-478b-8103-6f67971ce5f1.png)

加えて、ユーザーに付与されたアクセス権限により、セマンティック検索の結果が変わります。従来の検索機能と同じで、セマンティック検索もWCCのアクセス権限管理に応じた検索結果を返します
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/c3f60739-2b9d-44ac-9a3e-0087701295f7.png)

最後に、ユーザーはドキュメントをWCCにアップロードするだけで、特別な操作不要です。セマンティック検索で利用する索引はバックグラウンドで自動的に作成されます
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/e4e8f142-d3a1-4339-a177-bdc419c1dc00.png)

## セマンティック検索の利用条件
WCCのセマンティック検索を利用する条件は以下の通りです（※2025年4月21日時点）

1. **マーケットプレイス版WCC14c For OCI**を利用すること
1. データベースとして**Oracle Database 23ai**を利用すること（Oracle Database 23aiの新機能**Oracle AI Vector Search**を利用します）

# セマンティック検索の構成手順

以下の製品ドキュメントに従って、WCCのセマンティック検索機能を構成・有効化します

https://docs.oracle.com/en/cloud/paas/webcenter-content/semantic-search/index.html

作業手順は以下の通りです

1. [Oracle Database 23ai環境を構築する](#1-oracle-database-23ai環境を構築する)
1. [マーケットプレイスからWCC14c For OCIをプロビジョニングする](#2-マーケットプレイスからwcc14c-for-ociをプロビジョニングする)
1. [セマンティック検索ができるようにWCCを構成する](#3-セマンティック検索ができるようにwccを構成する)
1. [埋め込みモデルをデータベースにロードする](#4-埋め込みモデルをデータベースにロードする)
1. [WCCが使用する埋め込みモデルを指定し、索引を作成する](#5-wccが使用する埋め込みモデルを指定し索引を作成する)

## 1. Oracle Database 23ai環境を構築する

OCI上にOracle Database 23aiの環境を作成します。今回は、以下のOCIチュートリアルを参考に**Autonomous Transaction Processing - Serverless**(以降**ATP-S**)の環境を作成します

https://oracle-japan.github.io/ocitutorials/adb/adb101-provisioning/

:::note info
`データベース・バージョンの選択`は**23ai**を選択します
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/da7d6e77-0dc0-44ec-bb6a-0cbaec77efab.png)
:::

## 2. マーケットプレイスからWCC14c For OCIをプロビジョニングする

### 2.1 プロビジョニング
マーケットプレイスからWCC14c For OCIの環境をプロビジョニングします。プロビジョニング時は前の手順で作成したOracle Database 23aiの**ATP-S**を指定します

プロビジョニング手順を説明したQiita記事が公開されていますので、こちらを参考に作成します

https://qiita.com/shinwata/items/d7b478031ea45f0a3565

:::note info
スタック作成時のバージョンは **14.1.2.0.0_x.x.x(yyyy/mm/dd)** を選択します（ここでは`14.1.2.0.0_25.2.1(2025/2/27)`を選択）  
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/38daacd2-c9a8-4004-acfa-99c1d764dd48.png)
:::



### 2.2 プロビジョニング完了後の追加作業

プロビジョニング完了後、以下Qiita記事の追加作業をすべて実施します（ローカライゼーションの設定、日本語フォントの追加、全文検索機能の有効化）

https://qiita.com/nakasato310/items/5c45f761fd61c7976832

:::note info
WCCのセマンティック検索機能を利用する場合、**OracleTextSearch**(Oracle DatabaseのOracle Textを利用した全文検索機能)の有効化は必須です
:::

## 3. セマンティック検索ができるようにWCCを構成する

### 3.1 Smart Contentコンポーネントを有効化する

1. WCCのネイティブUIにアクセスします。URLは`https://<ロードバランサのパブリックIPアドレス>:16200/cs/`です
1. 管理ユーザーでサインインします（ここでは`weblogic`ユーザーでサインインしました）
1. **管理→管理サーバー→コンポーネント・マネージャ**を開き、**拡張コンポーネント・マネージャ**をクリックします
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/627261eb-6d07-44f5-a15e-fd794756e7a7.png)

1. **無効なコンポーネント**から**SmartContent**を選択し、**有効化**をクリックします
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/ca1abdb8-1d19-472e-bd5c-c4d98da2eedf.png)

1. **Fusion Middleware Control**（もしくはWebLogic Remote Console）から**UCM_Server**を再起動します

### 3.2 セマンティック検索機能の有効化

1. 管理ユーザーでサインインします
1. **管理→管理サーバー→一般構成**を開きます
1. **追加の構成変数** に以下2つのパラメータを追加し、**保存**をクリックします
```config:追加の構成変数(config.cfg)
IsDataBaseHybridSearchEnabled=True
SemanticSearchSupport=true
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/63680637-3e23-456a-a4f3-4924446c0989.png)

1. **UCM_Server**を再起動します

## 4. 埋め込みモデルをデータベースにロードする

Oracle Database 23aiは、ONNX形式の埋め込みモデルをデータベース内にロードして、埋め込みベクトルの生成を行うことできます。WCC14c For OCIでは、この機能を利用してセマンティック検索を構成します

データベースにロードするONNX形式の埋め込みモデルの入手方法は2つあります。どちらを使ってもWCCのセマンティック検索は動作しますが、日本語対応を考慮すると2点目の**多言語埋め込みモデルの[intfloat/multilingual-e5-base](https://huggingface.co/intfloat/multilingual-e5-base)** の利用をお勧めします

- オラクルが提供するONNXフォーマットの[Hugging Face all-MiniLM-L12-v2 model](https://docs.oracle.com/en/database/oracle/machine-learning/oml4py/2-23ai/mlpug/onnx-pipeline-models-text-embedding.html)を利用する
    - 関連記事: [Now Available! Pre-built Embedding Generation model for Oracle Database 23ai](https://blogs.oracle.com/machinelearning/post/use-our-prebuilt-onnx-model-now-available-for-embedding-generation-in-oracle-database-23ai)
- Oracle Machine Learning for Python(**OML4Py**)を利用して自分でエクスポートした埋め込みモデルを利用する
    - 関連記事: [Oracle Autonomous Database で In-database 埋め込みモデルを使ってベクトルを生成する](
https://qiita.com/yuji-arakawa/items/e43e0ad9f0f033fd55ab)

ここでは、多言語埋め込みモデルの**intfloat/multilingual-e5-base**を利用した場合について説明します

### 4.1 ONNXファイルを生成する

以下Qiita記事を参考に、OML4Pyの環境を作成し、**intfloat/multilingual-e5-base** のモデルをONNX形式でエクスポートします

https://qiita.com/yuji-arakawa/items/e43e0ad9f0f033fd55ab

### 4.2 ONNXファイルをオブジェクトストレージにアップロードする

1. エクスポートしたONNX形式のファイル（ここでは`multilingual-e5-base.onnx`）を、オブジェクトストレージのバケットにアップロードします
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/3d9aed63-6b68-4ebd-87d1-b5d422d021fc.png)

1. バケットにアップロードした`multilingual-e5-base.onnx`へのURLをメモします

1. OCIコンソールを利用し、**認証トークン**を作成し、メモします。認証トークンの作成方法は以下ドキュメントをご確認ください

https://docs.oracle.com/ja-jp/iaas/Content/Registry/Tasks/registrygettingauthtoken.htm

### 4.3 オブジェクトストレージからONNXファイルをATPにロードする

1. OCIコンソールのクラウド・シェルを利用して、ATPにSQL Plusで接続できるように環境を準備します。今回は、以下のQiita記事を参考に準備します

https://qiita.com/letian/items/38b968cee3a9619c63e5

1. クラウド・シェル上でSQL Plusを起動し、**admin**ユーザーでATPに接続します
```sql
satoshi_na@cloudshell:~ (us-chicago-1)$ sqlplus admin@wccmpatps23ai_low

SQL*Plus: Release 19.0.0.0.0 - Production on Mon Apr 21 08:19:48 2025
Version 19.19.0.0.0

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

Enter password: 
Last Successful login time: Mon Apr 21 2025 08:18:10 +00:00

Connected to:
Oracle Database 23ai Enterprise Edition Release 23.0.0.0.0 - for Oracle Cloud and Engineered Systems
Version 23.8.0.25.05

SQL> 
```

1. 以下のSQLを実行し、WCCが使用するデータベースユーザーに必要な権限を付与します。WCCが利用するデータベースユーザーは`<マーケットプレイス作成時に指定したプレフィックス>_OCS`です。ここではプレフィックスに`WCCMP1412`を指定したので、権限を付与するデータベースユーザーは`WCCMP1412_OCS`です
```sql
GRANT DB_DEVELOPER_ROLE TO WCCMP1412_OCS;
GRANT CREATE MINING MODEL TO WCCMP1412_OCS;
CREATE DIRECTORY STAGING AS 'STAGE';
GRANT READ ON DIRECTORY STAGING TO WCCMP1412_OCS;
GRANT WRITE ON DIRECTORY STAGING TO WCCMP1412_OCS;
```
1. SQL Plus一旦終了し、**WCCのデータベースユーザー**（ここでは`WCCMP1412_OCS`）で再接続します
```sql
satoshi_na@cloudshell:~ (us-chicago-1)$ sqlplus WCCMP1412_OCS@wccmpatps23ai_low

SQL*Plus: Release 19.0.0.0.0 - Production on Mon Apr 21 08:32:59 2025
Version 19.19.0.0.0

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

Enter password: 
Last Successful login time: Mon Apr 21 2025 08:27:34 +00:00

Connected to:
Oracle Database 23ai Enterprise Edition Release 23.0.0.0.0 - for Oracle Cloud and Engineered Systems
Version 23.8.0.25.05

SQL>
```

1. オブジェクトストレージにアクセスするためのクレデンシャルを作成します。`username`には認証トークンを発行したユーザー名、`password`には前の手順で発行した認証トークンをそれぞれ設定します

```SQL
begin
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OBJ_STORE_CRED',
    username => '<ユーザー名>',
    password => '<認証トークン>'
  );
end;
/
```

1. オブジェクトストレージからONNXファイルをダウンロードします。`credential_name`には直前の手順で作成した**OBJ_STORE_CRED**、`object_url`にはバケット内のONNXファイルのURLを、それぞれ設定します
```sql
BEGIN
  DBMS_CLOUD.GET_OBJECT(
    credential_name => 'OBJ_STORE_CRED',
    object_uri => 'https://objectstorage.us-chicago-1.oraclecloud.com/n/orasejapan/b/atp23ai-bucket/o/multilingual-e5-base.onnx',
    directory_name => 'staging',
    file_name => 'multilingual-e5-base.onnx'
  );
END;
/
```

1. ONNXファイルがダウンロードできたか？を確認します。`multilingual-e5-base.onnx`が表示されることを確認します

```sql
SQL> SELECT OBJECT_NAME, CREATED FROM TABLE(DBMS_CLOUD.LIST_FILES('staging'));

OBJECT_NAME
--------------------------------------------------------------------------------
CREATED
---------------------------------------------------------------------------
all_MiniLM_L12_v2.onnx
31-MAR-25 06.27.55.905020 AM +00:00

multilingual-e5-base.onnx
07-APR-25 07.21.55.235137 AM +00:00


SQL> 
```

1. ONNXファイルをデータベースにロードします。ここでは、モデル名を**multilinguale5base**と指定しました

```sql
BEGIN
  DBMS_VECTOR.LOAD_ONNX_MODEL(
    'staging',
    'multilingual-e5-base.onnx',
    'multilinguale5base',
    json('{"function":"embedding","input":{"input":["DATA"]}}')
  );
END;
/
```

1. ロードしたモデルを確認します。**multilinguale5base**がロードされていることを確認します

```sql
SQL> SELECT MODEL_NAME, MINING_FUNCTION, ALGORITHM, ALGORITHM_TYPE, round(MODEL_SIZE/1024/1024) MB FROM user_mining_models;

MODEL_NAME
--------------------------------------------------------------------------------
MINING_FUNCTION                ALGORITHM                      ALGORITHM_
------------------------------ ------------------------------ ----------
        MB
----------
MULTILINGUALE5BASE
EMBEDDING                      ONNX                           NATIVE
       270

MINILM_MODEL
EMBEDDING                      ONNX                           NATIVE
       127

SQL> 
```

1. ロードしたモデル**multilinguale5base**を利用した埋め込みベクトルの生成を確認します
```sql
SQL> SELECT TO_VECTOR(VECTOR_EMBEDDING( multilinguale5base USING 'こんにちは' as data)) AS embedding;

EMBEDDING
--------------------------------------------------------------------------------
[-1.92252826E-003,3.63082401E-002,-2.13882537E-004,2.37099547E-002,2.24683508E-0

SQL>
```

以上で埋め込みモデルをデータベースにロードできました

## 5. WCCが使用する埋め込みモデルを指定し、索引を作成する

1. WCCのネイティブUIに管理ユーザーでサインインします。ここではweblogicユーザーでサインインします

1. **管理→SmartContent→Hybrid Index Configuration**をクリックします
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/63531322-3b93-4876-87bf-3d8646cc6906.png)


1. `EmbeddingModelName`に前の手順でロードしたモデル名（ここでは**multilinguale5base**）を入力します。その他のパラメータはデフォルト値のままとします

1. **Update Configuration**をクリックします
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/bfa6bf8f-552c-411c-9064-b18c1cc42114.png)

1. バックグランドでハイブリッド索引の作成が開始されます。さらに、WCCのユーザーインタフェース上に`Index build in progress. Semantic search might give inconsistent result`の**アラート**が表示されます
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/5f7d2e0b-b8e6-417d-9c28-c1a0b6ab5f50.png)

1. **アラート**をクリックすると、ハイブリッド索引の作成ステータスを確認できます

1. しばらく待つとハイブリッド索引の作成が終了(staus=`Completed`)し、アラートが消えます
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/297f9f26-1848-488f-a40a-761ed649bb5d.png)

以上でセマンティック検索の構成は完了です

:::note info
埋め込みモデルを更新する場合は、**Cleanup Data and Hybird Index**をクリックし、既存のハイブリッド索引と関連データを削除します。その後、`EmbeddingModeName`に新しい埋め込みモデルの名前を入力し、**Update Configuration**をクリックします。
この操作により、WCCは新しく設定された埋め込みモデルを使用して、既存のドキュメントに新しい埋め込みベクトルを作成します
:::

# 動作確認（セマンティック検索の実行）

実際にセマンティック検索をWCCのユーザーインタフェースから実行します。セマンティック検索は、マーケットプレイス版WCC For OCIのみ利用可能な**Redwood UI**からのみ実行できます

1. WCCのRedwood UIにアクセスします。URLは`https://<ロードバランサのパブリックIPアドレス>:16200/cs?IdcService=REDWOODUI`です
1. **ユーザー名**と**パスワード**を入力します

1. 画面下部のナビゲーションメニューの**検索**をクリックします
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/e2ad9655-38a9-41f4-8558-36d87973aa47.png)

1. 検索の横の**ファイル**をクリックし、**AI Search**を選択します
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/8a491d62-a9f8-430a-a3dd-e5e7e38b2487.png)

1. 検索文を自然文で入力します（例: `Oracle Fusion Middlewareの開発計画をおしえて`　`障害報告のあげかたをおしえて`など）
1. 検索結果として、意味的に類似したコンテンツを含む文書を関連性の高い順に表示されます
   ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/120110/4356d175-fd98-4441-a61b-c2b0f12d6aed.png)


# おわりに

マーケットプレイス版Oracle WebCenter Content 14c For OCIのセマンティック検索機能を有効化する手順を紹介しました。皆さまのお役に立てば幸いです