Confluence Data Center のセマンティック検索では、OpenSearch の ML (機械学習) Commons プラグインを使用して、Confluence コンテンツのベクトル埋め込みを生成し、保存します。ユーザーが検索すると、それらの埋め込みに対してニューラル (ベクトル) クエリが実行され、キーワードの一致度ではなく意味的類似度に基づいて順位付けされた検索結果が返されます。

この機能を使用するには、OpenSearch クラスターで ML タスクを実行できる必要があります。つまり、テキスト埋め込みモデルをホストし、提供できなければなりません。設定方法は、OpenSearch クラスターをお客様自身で管理しているか、Amazon OpenSearch Service を使用しているかによって異なります。

Confluence のセマンティック検索を有効にする前に、OpenSearch クラスターが次のいずれかの条件を満たしていることを確認してください。

• ml ノード ロールが割り当てられた専用の OpenSearch ノード

• ML Commons タスクをデータ ノード上で実行できるよう、キャパシティを確認したうえで意図的に行われた設定

• Amazon OpenSearch Service の本番ドメインの場合、ML タスクをデータ ノードから分離する本番環境向けの保護機能を無効にするのではなく、ML コネクタを使用する、サポート対象のリモート推論設定

ステップ 1: ML がすでに有効になっているか確認する

セルフホスト型 OpenSearch

OpenSearch Dashboards の Dev Tools または任意の REST クライアントから、次のコマンドを実行します。

GET /_cat/nodes?v&h=name,node.roles

Example output:

name                  node.roles
data-e5b89ad7         data,ingest,ml
os-node-02            data,ingest,cluster_manager

node.roles 列に ml が含まれているか確認します。また、現在のクラスター設定も確認してください。

GET /_cluster/settings?include_defaults=true&filter_path=**.ml_commons

Example output:

{
    "persistent": {
        "plugins": {
            "ml_commons": {
                "only_run_on_ml_node": "true",
                "native_memory_threshold": "90"
            }
        }
    },
    ...
}

出力は、少なくとも 1 つのノードに ml ロールが割り当てられており、かつ plugins.ml_commons.only_run_on_ml_node が true (既定) であることを確認してください。

AWS マネージド OpenSearch

OpenSearch Dashboards の Dev Tools または任意の REST クライアントから、次のコマンドを実行します。

GET /_plugins/_ml/stats

Example output:

{
    "ml_model_index_status": "non-existent",
    "ml_config_index_status": "green",
    "ml_connector_count": 0,
    ...
}

 また、リモート推論が有効になっているかどうかも確認してください。

GET /_cluster/settings?include_defaults=true&filter_path=**.plugins.ml_commons.only_run_on_ml_node,**.plugins.ml_commons.remote_inference.enabled,**.plugins.ml_commons.task_dispatcher.eligible_node_role.*

Example output:

{
    "persistent": {
        "plugins": {
            "ml_commons": {
                "only_run_on_ml_node": "true"
            }
        }
    },
    "defaults": {
        "plugins": {
            "ml_commons": {
                  ...
                },
                "remote_inference": {
                    "enabled": "true"
                }
            }
        }
    }
}

本番環境の AWS ドメインでは、plugins.ml_commons.only_run_on_ml_node を false に設定しないでください。AWS では、本番環境のドメインで代わりにコネクタを使用することを明示的に推奨しています。

ML がすでに有効になっている場合は、「ステップ 3: モデルを設定する」に進んでください。有効になっていない場合は、ご利用のデプロイ環境に該当する以下のセクションの手順に従ってください。

ステップ 2: OpenSearch クラスターで ML を有効にする

OpenSearch のデプロイを自社で管理している場合 (オンプレミス、ベア メタル、クラウド VM など) と、AWS マネージド OpenSearch サービスを使用している場合では、ML を有効にする方法が異なります。環境に応じて、それぞれの手順に従う必要があります。

セルフホスト型 OpenSearch

1. ml ロールを持つ OpenSearch ノードを 1 つ以上追加します。本番環境でセマンティック検索の可用性が重要な場合は、ML ノードを 2 つ以上使用してください。
   専用 ML ノードの opensearch.yml の例: 

   node.name: os-ml-1
   # Assign the ml role only — this node will not store index shards
   node.roles: [ ml ]
   cluster.name: <your-cluster-name>
   discovery.seed_hosts: [ <your-seed-host-1>, ... <your-seed-host-n> ]

   ml ロールのみが設定されたノードには、インデックス シャードは保存されません。ノードのすべてのメモリと CPU が ML 推論専用になります。データも保存する場合 (本番環境では非推奨) は、node.roles に data を追加してください。

2. 新しいノードを起動し、クラスターに参加していることを確認します。

   GET /_cat/nodes?v&h=name,node.roles

   新しいノードの roles 列に ml が表示されていることを確認してください。

   name            node.roles
   os-ml-1         ml

3. クラスター設定が正しいことを確認します。

   GET /_cluster/settings?include_defaults=true&filter_path=**.ml_commons

   出力で、only_run_on_ml_node が true であり、native_memory_threshold が適切なゼロ以外の値 (例: 90) になっていることを確認してください。いずれかの設定が正しくない場合は、次のコマンドを実行します。

   PUT /_cluster/settings
   {
         "persistent": {
           "plugins.ml_commons.only_run_on_ml_node": true,
           "plugins.ml_commons.native_memory_threshold": 90
       }
   }

4. ML を使用する準備が整っていることを確認します。

   GET /_plugins/_ml/stats

   HTTP 200 レスポンスが返され、次のような出力が表示されることを確認してください。

   {
       "ml_model_index_status": "non-existent",
       "ml_config_index_status": "green",
       "ml_connector_count": 0,
       ...
   }

   各設定の詳しい説明と手順の一覧については、OpenSearch のドキュメントを参照してください。 

AWS マネージド OpenSearch

Amazon OpenSearch Service はフルマネージド サービスです。opensearch.yml にはアクセスできず、設定ファイルを使用してノードに ml ノード ロールを直接割り当てることもできません。利用可能な方法は、Amazon Bedrock (モデルのデプロイ不要) と Amazon SageMaker (モデルのデプロイが必要) の 2 つです。どちらの方法も、AWS 開発者ガイド (https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ml-amazon-connector.html) に詳しく記載されています。AWS によって随時更新されるため、同ガイドの手順に従うことをお勧めします。

ステップ 3: モデルを設定する

クラスターで ML 機能を有効にしたら (前述のステップ)、ローカルの Sentence Transformer モデルを登録してデプロイする必要があります。OpenSearch は、ML を実行できるノードのメモリにモデルを読み込み、インデックス作成時および検索時の埋め込みの生成に使用します。

ここでも、デプロイ環境に応じて異なる手順に従う必要があります。AWS マネージド OpenSearch の場合は、AWS のドキュメントを参照してください。手順は、選択したリモート推論ツール (AWS Bedrock または AWS SageMaker) によっても異なります。

セルフホスト型の OpenSearch クラスターでは、以下の手順を実行してください。

1. (オプション) モデル グループを登録する - モデル グループを使用すると、関連するモデルを整理し、それらへのアクセスを制御できます。登録は任意ですが (ML Commons によって既定のグループが作成されます)、わかりやすく管理するために登録をお勧めします。 

   POST /_plugins/_ml/model_groups/_register
   {
     "name": "confluence-semantic-search",
     "description": "Sentence-transformer models for Confluence DC Semantic Search"
   }

   返された model_group_id を控えておいてください。これは次のステップで使用します。

2. 事前トレーニング済みモデルを登録する - OpenSearch では、Hugging Face の厳選された事前トレーニング済み Sentence Transformer モデルが提供されています。これらは OpenSearch のモデル リポジトリから直接ダウンロードされるため、外部でファイルをホストする必要はありません。

   huggingface/sentence-transformers/all-MiniLM-L6-v2 (384 次元、約 80 MB) は高品質な英語の埋め込みを生成し、リアルタイム検索の推論にも十分な速度を備えています。ただし、用途に適したモデルを選定することをお勧めします。多言語対応が必要な場合は、OpenSearch の事前トレーニング済みモデルの一覧を参照してください。

   TORCH_SCRIPT 形式を使用してモデルを登録します (推奨):

   POST /_plugins/_ml/models/_register
   {
     "name": "huggingface/sentence-transformers/all-MiniLM-L6-v2",
     "version": "1.0.1",
     "model_group_id": "<model_group_id>",
     "model_format": "TORCH_SCRIPT"
   }

   TORCH_SCRIPT と ONNX の両方の形式がサポートされています。TORCH_SCRIPT は既定であり、サポートされているすべてのプラットフォームで動作します。ONNX は、一部のハードウェア構成でより高速になる場合があります。詳細については、事前トレーニング済みモデルのページをご確認ください。

   レジスタ呼び出しは非同期であり、 task_id を返します。タスクが完了するまでポーリングします:

   GET /_plugins/_ml/tasks/<task_id>
   
   // Expected response when complete:
   {
     "model_id": "cleMb4kBJ1eYAeTMFFg4",
     "task_type": "REGISTER_MODEL",
     "function_name": "TEXT_EMBEDDING",
     "state": "COMPLETED",
     ...
   }

   次のステップで使用する model_id に注意してください。

3. モデルのデプロイ - モデルをデプロイすると、OpenSearch モデル インデックスから登録済みのモデル チャンクを読み取り、ML 適格ノードのメモリにモデルをロードします。

   POST /_plugins/_ml/models/<model_id>/_deploy

   レジスタ呼び出しは非同期であり、 task_id を返します。タスクが完了するまでポーリングします:

   GET /_plugins/_ml/tasks/<task_id>
   
   // Expected response when complete:
   {
     "task_type": "DEPLOY_MODEL",
     "state": "COMPLETED",
     ...
   }

   デプロイには、モデルのサイズやハードウェアによって、最大 120 秒かかる場合があります。タスクが FAILED 状態になった場合は、ML ノードに十分なネイティブメモリがあることを確認してください。最も一般的な原因は、ネイティブ メモリのサーキット ブレーカーが作動することです。

   OpenSearch のドキュメントによると、次のとおりです。

   「クラスターまたはノードが再起動された場合は、モデルを再デプロイする必要があります。自動再デプロイをセットアップする方法については、『Enable auto redeploy (自動再デプロイの有効化)』を参照してください」

4. モデルのテスト - Confluence DC を設定する前に、モデルが埋め込みを正しく生成することを確認します。

   POST /_plugins/_ml/models/<model_id>/_predict
   {
     "text_docs": ["Confluence semantic search test"],
     "return_number": true,
     "target_response": ["sentence_embedding"]
   }

   正常なレスポンスには、384 個の浮動小数点値を含む sentence_embedding 配列が含まれます (all-MiniLM-L6-v2 の場合):

   {
     "inference_results": [
       {
         "output": [
           {
             "name": "sentence_embedding",
             "data_type": "FLOAT32",
             "shape": [384],
             "data": [-0.023315024, 0.08975691, 0.078479774, ...]
           }
         ]
       }
     ]
   }

   動作が確認できたら、model_id を記録します。これは、セマンティック検索を有効にする際に Confluence DC に提供するものです。

ステップ 4: セマンティック検索用に Confluence を設定する

1. confluence.cfg.xml の設定:
   各 Confluence DC ノードの confluence.cfg.xml に、以下のプロパティを追加します。

   <property name="opensearch.vector.model.id"><model_id></property>

   <model_id> をステップ 3.2 で記録したモデル ID に置き換えてください (例:cleMb4kBJ1eYAeTMFFg4)。変更を適用したら、ノードを再起動してください。

   ステップ 4.2 (インデックス再作成) が実行されるまで、既存の検索とインデックス作成に影響はありません。

2. インデックス再作成
   [管理] → [コンテンツのインデックス作成] に移動し、Confluence サイトの完全なインデックス再作成を実行します。OpenSearch は現在、ダウンタイムを回避するブルー/グリーン再インデックス メカニズムを提供しているため、これによるダウンタイムは発生しない点にご注意ください。

   ML 推論パイプラインが設定された状態でのインデックス再作成は、標準のインデックス再作成よりもかなり多くのリソースを消費します。これは、書き込まれる前にすべてのドキュメントがモデル推論を通過して埋め込みを再生成する必要があるためであり、その結果、操作が I/O ではなく推論のレイテンシに制限され、スループットの低下、CPU とメモリの消費量の増加、および生成されたベクトルによる追加のストレージが発生します。

   インデックス再作成が完了したら、クイック検索 UI を開く (/ を押すか、検索バーをクリックする) ことで、セマンティック検索が有効になっていることを確認できます。左側のパネルの上部に [セマンティック検索] の切り替えが表示されます。
   

オプション - ロールバック

セマンティック検索を無効にして、キーワード検索のみに戻すには、次の手順に従います。

1. すべてのノードで、confluence.cfg.xml から opensearch.vector.model.id プロパティを削除 (またはコメントアウト) します。

2. すべての Confluence DC ノードのローリング再起動を実行します。

3. 完全なインデックス再作成をトリガーします。これにより、埋め込みパイプラインを使用せずにコンテンツのインデックス再作成が行われ、事実上、セマンティック検索の構成がアクティブな使用からクリアされます。

検索結果の品質のチューニング

セマンティック検索結果の品質は、選択する埋め込みモデルとコンテンツの構造に大きく依存します。Confluence には、結果の品質を調整できる構成プロパティがあります。適切な値は、モデルのスコア範囲とコンテンツによって異なります。以下のガイダンスを出発点として、ご利用の環境での状況に基づいて、繰り返し調整してください。

問題の理解: 弱いマッチと最新性によるブースト

セマンティック検索は、検索クエリと無関係に見える結果を返すことがあります。これは通常、次の理由により発生します。

• 弱いセマンティック一致は依然として返されます。ニューラル クエリは、クエリに特に類似しているものが一つもない場合でも、見つけられる限り最も近いベクトルの一致を返します。これらの「弱い一致」は関連度スコアが低いものの、結果セットには含まれます。

• 最新性スコアリングは、弱い一致を増幅させます。既定では、Confluence はページの更新日時の新しさに基づいて、検索結果を上位に表示します。最近編集された一致度の低いページが、しばらく更新されていない一致度の高いページよりも上位にランク付けされることがあり、その結果、無関係に感じられる結果が生じる可能性があります。

これに対処するための 2 つの補完的なアプローチがあり、そのうちの 1 つまたは両方を適用できます。

アプローチ 1: 弱い一致を除外する

title および contentBody フィールドの k、 min_score、および max_distance プロパティを使用して、最初にどの結果を含めるかを制御します。利用可能なプロパティとそのデフォルト値の完全なリストについては、以下の「認識されるプロパティ」を参照してください。

• min_score — 最小類似度スコアのしきい値を設定します。このしきい値未満の結果は完全に除外されます。モデルが予測可能な範囲でスコアを生成する場合、通常はこれが最も直感的なオプションです。

• max_distance — 最大ベクトル距離のしきい値を設定します。この距離を超える結果は除外されます。l2 などの距離ベースのスペース タイプを扱う場合に便利です。

• k — ニューラル クエリによって返される最近傍候補の数を制限します。値を低くすると、弱い一致が含まれる可能性が低くなります。

アプローチ 2: 最新性スコアリングを無効にする

confluence.cfg.xml で search.scoring.recency を false に設定します。これにより、検索結果に適用される時間減衰ブーストが無効になり、結果は最後に編集された日時ではなく、純粋に関連性スコアのみによってランク付けされるようになります。

次のような場合に適しています。

• ページの最終更新日時に関係なく、強力なセマンティック一致を常に一番上に表示させたい場合。

• モデルに適切な min_score / max_distance しきい値がまだ特定されておらず、実験を行いながら結果の順序を改善したいと考えている場合。

最新性スコアリングを無効にしても、結果から関連性の低い一致は削除されず、ランキングだけが変更されます。これを min_score または max_distance のフィルタリングと組み合わせることで、最大限の制御が可能になります。

認識済みのプロパティ

これらのプロパティは、各 Confluence ノードの confluence.cfg.xml で設定できます。次に例を示します。

<property name="search.scoring.recency">false</property>
<property name="search.semantic.contentBody.neural.min_score">0.5</property>