为第三方机器学习平台创建连接器
2.9 版本引入
连接器便于访问第三方机器学习（ML）平台上托管的模型。
OpenSearch 为多个平台提供连接器，例如
- Amazon SageMaker 允许您托管和管理文本嵌入模型的生命周期，为 OpenSearch 中的语义搜索查询提供支持。连接后，Amazon SageMaker 托管您的模型，OpenSearch 用于查询推理。这对于重视 Amazon SageMaker 功能的用户，例如模型监控、无服务器托管以及持续训练和部署的工作流自动化，非常有益。
- OpenAI ChatGPT 使您能够从 OpenSearch 集群内部调用 OpenAI 聊天模型。
- Cohere 允许您使用 OpenSearch 中的数据来支持 Cohere 大型语言模型。
- Amazon Bedrock 支持 Bedrock Titan Embeddings 等模型，这些模型可以驱动 OpenSearch 中的语义搜索和检索增强生成。
连接器蓝图
连接器蓝图定义了在发送 API 请求以创建特定连接器时需要提供的一组参数（请求体）。连接器蓝图可能因您访问的平台和模型而异。
OpenSearch 为多个 ML 平台和模型提供连接器蓝图。有关 OpenSearch 提供的完整连接器蓝图列表，请参阅支持的连接器。
作为一名 ML 开发者，您还可以为其他平台和模型创建连接器蓝图。数据科学家和管理员随后可以使用该蓝图创建连接器。他们只需输入其连接服务的 credential 设置，例如 openAI_key。有关创建连接器蓝图的信息，包括所有参数的描述，请参阅连接器蓝图。
创建连接器
您可以通过两种方式预置连接器
-
创建独立连接器：独立连接器可以被多个模型复用和共享，但需要访问 OpenSearch 中的模型和连接器以及连接器正在访问的第三方平台，例如 OpenAI 或 Amazon SageMaker。独立连接器保存在连接器索引中。
-
为特定的外部托管模型创建连接器：或者，您可以创建一个只能与其创建的模型一起使用的连接器。要访问此类连接器，您只需要访问模型本身，因为连接是在模型内部建立的。这些连接器保存在模型索引中。
如果使用 Python，您可以使用 opensearch-py-ml 客户端 CLI 创建连接器。CLI 自动化了许多配置步骤，使设置更快，并减少了出错的可能性。有关使用 CLI 的更多信息，请参阅 CLI 文档。
创建独立连接器
独立连接器可以被多个模型使用。要创建独立连接器，请向 connectors/_create 端点发送请求，并提供 连接器蓝图 中描述的所有参数。
POST /_plugins/_ml/connectors/_create
{
"name": "OpenAI Chat Connector",
"description": "The connector to public OpenAI model service for GPT 3.5",
"version": 1,
"protocol": "http",
"parameters": {
"endpoint": "api.openai.com",
"model": "gpt-3.5-turbo"
},
"credential": {
"openAI_key": "..."
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://${parameters.endpoint}/v1/chat/completions",
"headers": {
"Authorization": "Bearer ${credential.openAI_key}"
},
"request_body": "{ \"model\": \"${parameters.model}\", \"messages\": ${parameters.messages} }"
}
]
}
为特定模型创建连接器
要为特定模型创建连接器，请在向 models/_register 端点发出的请求的 connector 对象中提供 连接器蓝图 中描述的所有参数。
POST /_plugins/_ml/models/_register
{
"name": "openAI-GPT-3.5 model with a connector",
"function_name": "remote",
"model_group_id": "lEFGL4kB4ubqQRzegPo2",
"description": "test model",
"connector": {
"name": "OpenAI Connector",
"description": "The connector to public OpenAI model service for GPT 3.5",
"version": 1,
"protocol": "http",
"parameters": {
"endpoint": "api.openai.com",
"max_tokens": 7,
"temperature": 0,
"model": "text-davinci-003"
},
"credential": {
"openAI_key": "..."
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://${parameters.endpoint}/v1/completions",
"headers": {
"Authorization": "Bearer ${credential.openAI_key}"
},
"request_body": "{ \"model\": \"${parameters.model}\", \"prompt\": \"${parameters.prompt}\", \"max_tokens\": ${parameters.max_tokens}, \"temperature\": ${parameters.temperature} }"
}
]
}
}
连接器示例
以下部分包含流行 ML 平台的连接器示例。有关支持的连接器的完整列表，请参阅支持的连接器。
OpenAI 聊天连接器
您可以使用以下示例请求创建独立 OpenAI 聊天连接器
POST /_plugins/_ml/connectors/_create
{
"name": "OpenAI Chat Connector",
"description": "The connector to public OpenAI model service for GPT 3.5",
"version": 1,
"protocol": "http",
"parameters": {
"endpoint": "api.openai.com",
"model": "gpt-3.5-turbo"
},
"credential": {
"openAI_key": "..."
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://${parameters.endpoint}/v1/chat/completions",
"headers": {
"Authorization": "Bearer ${credential.openAI_key}"
},
"request_body": "{ \"model\": \"${parameters.model}\", \"messages\": ${parameters.messages} }"
}
]
}
Amazon SageMaker 连接器
您可以使用以下示例请求创建独立 Amazon SageMaker 连接器
POST /_plugins/_ml/connectors/_create
{
"name": "sagemaker: embedding",
"description": "Test connector for Sagemaker embedding model",
"version": 1,
"protocol": "aws_sigv4",
"credential": {
"access_key": "...",
"secret_key": "...",
"session_token": "..."
},
"parameters": {
"region": "us-west-2",
"service_name": "sagemaker"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"url": "https://runtime.sagemaker.${parameters.region}.amazonaws.com/endpoints/lmi-model-2023-06-24-01-35-32-275/invocations",
"request_body": "[\"${parameters.inputs}\"]"
}
]
}
credential 参数包含以下为 aws_sigv4 认证保留的选项
access_key：必需。提供 AWS 实例的访问密钥。secret_key：必需。提供 AWS 实例的 secret key。session_token：可选。提供 AWS 实例的临时凭证集。
使用 aws_sigv4 认证时，parameters 部分需要以下选项
region：AWS 实例所在的 AWS 区域。service_name：连接器的 AWS 服务名称。
Cohere 连接器
您可以使用以下示例请求创建使用 Embed V3 模型的独立 Cohere 连接器。有关更多信息，请参阅Cohere 连接器蓝图。
POST /_plugins/_ml/connectors/_create
{
"name": "Cohere Embed Model",
"description": "The connector to Cohere's public embed API",
"version": "1",
"protocol": "http",
"credential": {
"cohere_key": "<ENTER_COHERE_API_KEY_HERE>"
},
"parameters": {
"model": "embed-english-v3.0",
"input_type":"search_document",
"truncate": "END"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://api.cohere.ai/v1/embed",
"headers": {
"Authorization": "Bearer ${credential.cohere_key}",
"Request-Source": "unspecified:opensearch"
},
"request_body": "{ \"texts\": ${parameters.texts}, \"truncate\": \"${parameters.truncate}\", \"model\": \"${parameters.model}\", \"input_type\": \"${parameters.input_type}\" }",
"pre_process_function": "connector.pre_process.cohere.embedding",
"post_process_function": "connector.post_process.cohere.embedding"
}
]
}
Amazon Bedrock 连接器
您可以使用以下示例请求创建独立 Amazon Bedrock 连接器
POST /_plugins/_ml/connectors/_create
{
"name": "Amazon Bedrock Connector: embedding",
"description": "The connector to the Bedrock Titan embedding model",
"version": 1,
"protocol": "aws_sigv4",
"parameters": {
"region": "<YOUR AWS REGION>",
"service_name": "bedrock"
},
"credential": {
"access_key": "<YOUR AWS ACCESS KEY>",
"secret_key": "<YOUR AWS SECRET KEY>",
"session_token": "<YOUR AWS SECURITY TOKEN>"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/amazon.titan-embed-text-v1/invoke",
"headers": {
"content-type": "application/json",
"x-amz-content-sha256": "required"
},
"request_body": "{ \"inputText\": \"${parameters.inputText}\" }",
"pre_process_function": "\n StringBuilder builder = new StringBuilder();\n builder.append(\"\\\"\");\n String first = params.text_docs[0];\n builder.append(first);\n builder.append(\"\\\"\");\n def parameters = \"{\" +\"\\\"inputText\\\":\" + builder + \"}\";\n return \"{\" +\"\\\"parameters\\\":\" + parameters + \"}\";",
"post_process_function": "\n def name = \"sentence_embedding\";\n def dataType = \"FLOAT32\";\n if (params.embedding == null || params.embedding.length == 0) {\n return params.message;\n }\n def shape = [params.embedding.length];\n def json = \"{\" +\n \"\\\"name\\\":\\\"\" + name + \"\\\",\" +\n \"\\\"data_type\\\":\\\"\" + dataType + \"\\\",\" +\n \"\\\"shape\\\":\" + shape + \",\" +\n \"\\\"data\\\":\" + params.embedding +\n \"}\";\n return json;\n "
}
]
}
更新连接器凭证
在某些情况下，您可能需要更新用于连接外部托管模型的凭证，例如 access_key。为此，无需卸载模型，只需在更新请求中提供新凭证即可。
特定模型的连接器
要更新链接到特定模型的连接器的凭证，请在以下请求中提供新凭证
PUT /_plugins/_ml/models/<model_id>
{
"connectors": {
"credential": {
"openAI_key": "YOUR NEW OPENAI KEY"
}
}
}
独立连接器
要更新独立连接器的凭证，请在以下请求中提供新凭证
PUT /_plugins/_ml/connectors/<connector_id>
{
"credential": {
"openAI_key": "YOUR NEW OPENAI KEY"
}
}
后续步骤
- 有关 OpenSearch 提供的完整连接器蓝图列表，请参阅支持的连接器。
- 要了解有关连接到外部模型的更多信息，请参阅连接到外部托管模型。
- 要了解有关模型访问控制和模型组的更多信息，请参阅模型访问控制。