PolarSearch整合外部模型服務 - PolarDB

PolarSearch支援通過ML Plugin的連接器架構對接外部模型服務，以下介紹如何將自建模型或阿里雲大模型服務平台百鍊等外部模型服務接入PolarSearch，實現文本向量化（Embedding）、結果重排序（Reranking）和大語言模型（LLM）推理。

流程概述

整合採用連接器架構：先建立連接器定義與外部模型API的通訊方式，再將連接器註冊為PolarSearch模型並部署，部署後即可發起請求。

準備環境：配置憑證與開放出站網路訪問。
建立連接器：定義各模型類型的API端點、認證方式和請求/響應格式。
註冊和部署模型：將連接器註冊為PolarSearch中的可調用模型。
測試模型：通過請求驗證端到端連通性。

步驟一：準備環境

配置訪問憑證和環境變數

在開始操作前，請先準備好以下資訊，並設定為環境變數。這將有效簡化後續的curl命令，避免重複修改。統一管理所有配置和憑證，方便後續命令的複製和執行。

變數名	說明	樣本值
`POLARSEARCH_HOST_PORT`	PolarSearch節點的擷取串連地址。	`pc-xxx.polardbsearch.rds.aliyuncs.com:3001`
`USER_PASSWORD`	PolarSearch節點的管理員帳號。	`polarsearch_user:your_password`
`YOUR_API_KEY`	外部模型服務的API Key。說明使用阿里雲大模型服務平台百鍊時，請參見擷取API Key。自建模型服務無身分識別驗證時，可忽略`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"

# 設定您的阿里雲大模型服務平台百鍊 API Key
export YOUR_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

添加可信連接器端點

出於安全考慮，PolarSearch預設禁止訪問外部網路。您需通過修改叢集配置，將模型服務的地址加入信任清單，以允許PolarSearch調用它。

自建模型：需確保自建模型與PolarSearch位於同一專用網路內。
阿里雲大模型服務平台百鍊：建議通過終端節點私網訪問模型服務。
- 建立時，需確保終端節點與PolarSearch位於同一專用網路內。
- 建立後，您會得到一個ep-xxx.dashscope.cn-beijing.privatelink.aliyuncs.com的終端節點網域名稱，將其添加至信任清單中。

命令列

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/.*$"
    ]
  }
}'

Dashboard

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/.*$"
    ]
  }
}

步驟二：建立連接器

連接器（Connector）定義PolarSearch與外部模型服務之間的通訊方式，包括API端點、認證方式和請求/響應格式。為每個需要使用的模型類型建立一個連接器。

以下樣本使用阿里雲百鍊（DashScope）。如需對接其他服務商，調整端點、模型名稱和請求格式即可。

文本向量化連接器（Embedding）

文本向量化連接器將文本轉換為向量表示，用於語義搜尋。以下樣本為使用阿里雲大模型服務平台百鍊建立text-embedding-v4模型的連接器：

說明

自部署的Embedding模型若無訪問憑證，可不添加credential和headers.Authorization。

命令列

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/connectors/_create" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
    "name": "text-embedding connector",
    "description": "text-embedding connector",
    "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"
        }
    ]
}'

Dashboard

POST /_plugins/_ml/connectors/_create
{
    "name": "text-embedding connector",
    "description": "text-embedding connector",
    "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"
}

重排序連接器（Rerank）

重排序連接器根據相關性對搜尋結果重新排序，提升檢索增強產生（RAG）流程的結果品質。以下樣本為使用阿里雲大模型服務平台百鍊建立gte-rerank模型的連接器：

命令列

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/connectors/_create" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "name": "text-rerank connector",
  "description": "text-rerank connector",
  "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} } }"
    }
  ]
}'

Dashboard

POST /_plugins/_ml/connectors/_create
{
  "name": "text-rerank connector",
  "description": "text-rerank connector",
  "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）

大語言模型連接器用於調用大語言模型進行文本產生，支撐PolarSearch流程中的對話式AI和內容產生。以下樣本為使用阿里雲大模型服務平台百鍊建立qwen-max模型的連接器：

命令列

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/connectors/_create" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
    "name": "qwen-llm connector",
    "description": "qwen-llm connector",
    "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} }"
        }
    ]
}'

Dashboard

POST /_plugins/_ml/connectors/_create
{
    "name": "qwen-llm connector",
    "description": "qwen-llm connector",
    "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} }"
        }
    ]
}

步驟三：註冊和部署模型

建立連接器後，將其註冊為PolarSearch中的模型並部署。模型部署後才能處理預測請求。對於每個需要使用的連接器（Embedding、Rerank、LLM），都需要分別執行註冊和部署操作。

註冊模型

以下樣本使用步驟二中建立的連接器註冊一個遠程模型。

命令列

curl -XPOST "https://${POLARSEARCH_HOST_PORT}/_plugins/_ml/models/_register" \
--user "${USER_PASSWORD}" \
-H 'Content-Type: application/json' \
-d '{
  "name": "embedding model",
  "function_name": "remote",
  "description": "embedding model description",
  "connector_id": "<connector_id>"
}'

Dashboard

POST /_plugins/_ml/models/_register
{
  "name": "embedding model",
  "function_name": "remote",
  "description": "embedding model 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}"

Dashboard

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

執行成功後，響應中包含"status": "COMPLETED"，表示模型已部署完成，可以開始使用。

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

步驟四：測試模型

模型部署後，通過預測請求驗證PolarSearch與外部模型服務之間的端到端連通性。

測試文本向量化模型

以下樣本向Embedding模型發送一段文本，驗證其是否返迴向量：

命令列

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"]
  }
}'

Dashboard

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

執行成功後，若響應中的inference_results數組包含向量資料，則說明模型已成功整合。

測試重排序模型

以下樣本向Rerank模型發送一個查詢和一組候選文檔：

命令列

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
  }
}'

Dashboard

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?"}
    ]
  }
}'

Dashboard

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>
```