PolarSearch との外部モデルサービスの統合 - PolarDB - Alibaba Cloud ドキュメントセンター

PolarSearch は ML Plugin のコネクタフレームワークを用いて、外部モデルサービスに接続します。本ガイドでは、セルフホスト型のモデルや Alibaba Cloud Model Studio (Bailian) などの外部サービスを PolarSearch と統合し、テキスト埋め込み、検索結果の再ランキング、および大規模言語モデル（LLM）による推論を実行する方法について説明します。

概要

本統合ではコネクタアーキテクチャが採用されます。まず、PolarSearch が外部モデルの API とどのように通信するかを定義するコネクタを作成します。その後、このコネクタを PolarSearch 内のモデルとして登録・デプロイします。デプロイ完了後、モデルに対してリクエストを送信できるようになります。

環境の準備：認証情報の設定およびアウトバウンドネットワークアクセスの有効化を行います。
コネクタの作成：各モデルタイプごとに API エンドポイント、認証方式、およびリクエスト／応答フォーマットを定義します。
モデルの登録およびデプロイ：コネクタを PolarSearch 内で呼び出し可能なモデルとして登録します。
モデルのテスト：テストリクエストを送信して、エンドツーエンドの接続性を確認します。

ステップ 1：環境の準備

アクセス認証情報および環境変数の設定

開始前に、以下の情報を準備し、環境変数として設定してください。これらの値を一元管理することで、以降の curl コマンドが簡潔になり、コピーおよび実行が容易になります。

パラメーター	説明	例の値
`POLARSEARCH_HOST_PORT`	ご利用の PolarSearch ノードへの接続アドレスです。詳細については、「接続文字列の取得」をご参照ください。	`pc-xxx.polardbsearch.rds.aliyuncs.com:3001`
`USER_PASSWORD`	PolarSearch ノードの管理者アカウントです。	`polarsearch_user:your_password`
`YOUR_API_KEY`	外部モデルサービスの API キーです。説明 Alibaba Cloud Model Studio (Bailian) を使用する場合は、「API キーの取得」をご参照ください。セルフホスト型のモデルサービスで認証が不要な場合は、`YOUR_API_KEY` 環境変数の設定を省略できます。	`sk-xxxxxxxxxxxxxxxxxxxxxxxx`

手順：ターミナルで以下のコマンドを実行し、例の値を実際の情報に置き換えてください。

# PolarSearch のホストおよびポートを設定
export POLARSEARCH_HOST_PORT="pc-xxx.polardbsearch.rds.aliyuncs.com:3001"

# PolarSearch の管理者ユーザー名およびパスワードを設定
export USER_PASSWORD="polarsearch_user:your_password"

# Alibaba Cloud Model Studio (Bailian) の API キーを設定
export YOUR_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

信頼済みコネクタエンドポイントの追加

セキュリティのため、PolarSearch はデフォルトで外部ネットワークへのアクセスをブロックします。モデルサービスのエンドポイントを信頼リストに追加するため、クラスター設定を変更する必要があります。これにより、PolarSearch からそのサービスを呼び出せるようになります。

セルフホスト型モデル：セルフホスト型モデルと PolarSearch が同一の仮想プライベートクラウド（VPC）内にあることを確認してください。
Alibaba Cloud Model Studio (Bailian)：プライベートネットワーク経由でモデルサービスにアクセスすることを推奨します。そのためには、エンドポイントを使用します。
- エンドポイントを作成する際は、エンドポイントと PolarSearch が同一の仮想プライベートクラウド（VPC）内にあることを確認してください。
- エンドポイントを作成すると、ep-xxx.dashscope.cn-beijing.privatelink.aliyuncs.com のようなエンドポイントドメイン名が付与されます。このドメインを信頼リストに追加してください。

CLI

curl -XPUT "https://${POLARSEARCH_HOST_PORT}/_cluster/settings" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "persistent": {
    "plugins.ml_commons.connector.private_ip_enabled": true,
    "plugins.ml_commons.trusted_connector_endpoints_regex": [
      "^http://ep-***.dashscope.cn-beijing.privatelink.aliyuncs.com/.*$"
    ]
  }
}'

ダッシュボード

PUT _cluster/settings
{
  "persistent": {
    "plugins.ml_commons.connector.private_ip_enabled": true,
    "plugins.ml_commons.trusted_connector_endpoints_regex": [
      "^http://ep-***.dashscope.cn-beijing.privatelink.aliyuncs.com/.*$"
    ]
  }
}

ステップ 2：コネクタの作成

コネクタは、PolarSearch が外部モデルサービスと通信する方法（API エンドポイント、認証方式、リクエスト／応答フォーマットなど）を定義します。使用したい各モデルタイプごとに、個別のコネクタを作成する必要があります。

以下の例では、Alibaba Cloud Model Studio (Bailian)（DashScope）を使用します。他のサービスプロバイダーに接続する場合は、エンドポイント、モデル名、およびリクエストフォーマットをそれぞれ調整してください。

テキスト埋め込みコネクタ

テキスト埋め込みコネクタは、意味検索のためにテキストをベクトル表現に変換します。以下は、Alibaba Cloud Model Studio (Bailian) を使用して作成した text-embedding-v4 モデル向けのコネクタの例です：

説明

セルフホスト型の埋め込みモデルで credential が不要な場合は、credential および headers.Authorization フィールドを省略できます。

CLI

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/connectors/_create" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
    "name": "text-embedding コネクタ",
    "description": "text-embedding コネクタ",
    "version": "1",
    "protocol": "http",
    "parameters": {
        "endpoint": "<your_model_endpoint>",
        "model": "text-embedding-v4"
    },
    "credential": {
        "api_key": "${YOUR_API_KEY}"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "headers": {
                "Authorization": "Bearer ${credential.api_key}"
            },
            "url": "http://${parameters.endpoint}/compatible-mode/v1/embeddings",
            "request_body": "{ \"model\": \"${parameters.model}\", \"input\": ${parameters.input} }",
            "pre_process_function": "connector.pre_process.openai.embedding",
            "post_process_function": "connector.post_process.openai.embedding"
        }
    ]
}'

ダッシュボード

POST /_plugins/_ml/connectors/_create
{
    "name": "text-embedding コネクタ",
    "description": "text-embedding コネクタ",
    "version": "1",
    "protocol": "http",
    "parameters": {
        "endpoint": "<your_model_endpoint>",
        "model": "text-embedding-v4"
    },
    "credential": {
        "api_key": "<your_api_key>"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "headers": {
                "Authorization": "Bearer ${credential.api_key}"
            },
            "url": "http://${parameters.endpoint}/compatible-mode/v1/embeddings",
            "request_body": "{ \"model\": \"${parameters.model}\", \"input\": ${parameters.input} }",
            "pre_process_function": "connector.pre_process.openai.embedding",
            "post_process_function": "connector.post_process.openai.embedding"
        }
    ]
}

正常に実行された場合、connector_id が返されます。この ID を記録し、後続のステップで使用してください。

{
  "connector_id": "zocsGp0BFhPfW-xxxxxx"
}

再ランキングコネクタ

再ランキングコネクタは、検索結果を関連性に基づいて並べ替え、検索拡張生成（RAG）ワークフローにおける結果の品質を向上させます。以下は、Alibaba Cloud Model Studio (Bailian) で作成した gte-rerank モデル向けのコネクタの例です：

CLI

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/connectors/_create" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "name": "text-rerank コネクタ",
  "description": "text-rerank コネクタ",
  "version": "1",
  "protocol": "http",
  "parameters": {
    "endpoint": "<your_model_endpoint>",
    "model": "qwen3-rerank",
    "query": "",
    "documents": []
  },
  "credential": {
    "api_key": "${YOUR_API_KEY}"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer ${credential.api_key}"
      },
      "url": "http://${parameters.endpoint}/api/v1/services/rerank/text-rerank/text-rerank",
      "request_body": "{ \"model\": \"${parameters.model}\", \"input\": { \"query\": \"${parameters.query}\", \"documents\": ${parameters.documents} } }"
    }
  ]
}'

ダッシュボード

POST /_plugins/_ml/connectors/_create
{
  "name": "text-rerank コネクタ",
  "description": "text-rerank コネクタ",
  "version": "1",
  "protocol": "http",
  "parameters": {
    "endpoint": "<your_model_endpoint>",
    "model": "qwen3-rerank",
    "query": "",
    "documents": []
  },
  "credential": {
    "api_key": "<your_api_key>"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer ${credential.api_key}"
      },
      "url": "http://${parameters.endpoint}/api/v1/services/rerank/text-rerank/text-rerank",
      "request_body": "{ \"model\": \"${parameters.model}\", \"input\": { \"query\": \"${parameters.query}\", \"documents\": ${parameters.documents} } }"
    }
  ]
}

大規模言語モデル（LLM）コネクタ

大規模言語モデル（LLM）コネクタは、テキスト生成のために LLM を呼び出します。これにより、PolarSearch での会話型 AI やコンテンツ生成が可能になります。以下は、Alibaba Cloud Model Studio (Bailian) を使用して作成した qwen-max モデル向けのコネクタの例です：

コマンドライン

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/connectors/_create" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
    "name": "qwen-llm コネクタ",
    "description": "qwen-llm コネクタ",
    "version": "1",
    "protocol": "http",
    "parameters": {
        "endpoint": "<your_model_endpoint>",
        "model": "qwen-max"
    },
    "credential": {
        "api_key": "${YOUR_API_KEY}"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "headers": {
                "Authorization": "Bearer ${credential.api_key}"
            },
            "url": "http://${parameters.endpoint}/compatible-mode/v1/chat/completions",
            "request_body": "{ \"model\": \"${parameters.model}\", \"messages\": ${parameters.messages} }"
        }
    ]
}'

ダッシュボード

POST /_plugins/_ml/connectors/_create
{
    "name": "qwen-llm コネクタ",
    "description": "qwen-llm コネクタ",
    "version": "1",
    "protocol": "http",
    "parameters": {
        "endpoint": "<your_model_endpoint>",
        "model": "qwen-max"
    },
    "credential": {
        "api_key": "<your_api_key>"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "headers": {
                "Authorization": "Bearer ${credential.api_key}"
            },
            "url": "http://${parameters.endpoint}/compatible-mode/v1/chat/completions",
            "request_body": "{ \"model\": \"${parameters.model}\", \"messages\": ${parameters.messages} }"
        }
    ]
}

ステップ 3：モデルの登録およびデプロイ

コネクタを作成した後、それを PolarSearch 内のモデルとして登録し、その後デプロイします。予測リクエストを処理するには、モデルをデプロイする必要があります。埋め込み、再ランキング、LLM など、使用する各コネクタについて、登録およびデプロイを実行してください。

モデルの登録

この例では、ステップ 2 で作成したコネクタを使用してリモートモデルを登録します。

コマンドライン

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/models/_register" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "name": "埋め込みモデル",
  "function_name": "remote",
  "description": "埋め込みモデルの説明",
  "connector_id": "<connector_id>"
}'

ダッシュボード

POST /_plugins/_ml/models/_register
{
  "name": "埋め込みモデル",
  "function_name": "remote",
  "description": "埋め込みモデルの説明",
  "connector_id": "<connector_id>"
}

正常に実行された場合、model_id が返されます。この ID を記録し、後続のデプロイおよび予測リクエストで使用してください。

{
  "task_id": "wv83Gp0Bd4rNxxxx",
  "status": "CREATED",
  "model_id": "w_83Gp0Bdxxxx"
}

モデルのデプロイ

コマンドライン

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/models/<model_id>/_deploy" \
--user "${USER_PASSWORD}"

ダッシュボード

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

操作が成功した場合、応答には "status": "COMPLETED" が含まれます。これは、モデルがデプロイされ、使用可能になったことを示します。

{
  "task_id": "0Yc4Gp0BFhPfW-xxxx",
  "task_type": "DEPLOY_MODEL",
  "status": "COMPLETED"
}

ステップ 4：モデルのテスト

モデルをデプロイした後、予測リクエストを送信して、PolarSearch と外部モデルサービス間のエンドツーエンドの接続性を確認します。

テキスト埋め込みモデルのテスト

以下の例では、テキストスニペットを埋め込みモデルに送信し、ベクトルが返されることを確認します：

コマンドライン

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/models/<embedding_model_id>/_predict" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "parameters": {
    "input": ["hello world"]
  }
}'

ダッシュボード

POST /_plugins/_ml/models/<embedding_model_id>/_predict
{
  "parameters": {
    "input": ["hello world"]
  }
}

コマンドが正常に実行され、応答内の inference_results 配列にベクトルデータが含まれている場合、モデルは正常に統合されています。

再ランキングモデルのテスト

以下の例では、クエリおよび候補ドキュメントのセットを再ランキングモデルに送信します：

コマンドライン

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/models/<rerank_model_id>/_predict" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "parameters": {
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subfield of artificial intelligence.",
      "Deep learning uses neural networks.",
      "The weather is nice today."
    ],
    "top_n": 3
  }
}'

ダッシュボード

POST /_plugins/_ml/models/<rerank_model_id>/_predict
{
  "parameters": {
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subfield of artificial intelligence.",
      "Deep learning uses neural networks.",
      "The weather is nice today."
    ],
    "top_n": 3
  }
}

コマンドが正常に実行され、応答が関連性に基づいてソートされたドキュメントのリストと、各ドキュメントに対する relevance_score を含む場合、モデルは正常に統合されています。

大規模言語モデルのテスト

以下の例では、会話メッセージを大規模言語モデル（LLM）に送信します：

コマンドライン

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/models/<llm_model_id>/_predict" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "parameters": {
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is PolarSearch?"}
    ]
  }
}'

ダッシュボード

POST /_plugins/_ml/models/<llm_model_id>/_predict
{
  "parameters": {
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is PolarSearch?"}
    ]
  }
}

コマンドが正常に実行され、応答内の inference_results 配列にモデルからのテキスト応答が含まれている場合、モデルは正常に統合されています。

（任意）リソースのクリーンアップ

モデルリソースが不要になった場合、依存関係エラーを回避するため、以下の順序でリソースをクリーンアップしてください：

重要

デプロイ済みのモデルは直接削除できません。まずモデルをアンデプロイしてください。

モデルのアンデプロイ：モデルをアンデプロイすると、そのステータスが DEPLOYED から UNDEPLOYED に変更されます。その後、モデルは予測リクエストを受け付けなくなります。
```
POST /_plugins/_ml/models/<model_id>/_undeploy
```
モデルの削除：登録済みのモデルを削除すると、その登録情報が削除されます。
```
DELETE /_plugins/_ml/models/<model_id>
```
コネクタの削除：他のモデルによって使用されていないコネクタのみ削除できます。コネクタに依存するモデルが存在する場合、削除操作は失敗します。
```
DELETE /_plugins/_ml/connectors/<connector_id>
```