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