连接器蓝图

2.9 版本引入

每个连接器都由一个连接器蓝图指定。该蓝图定义了创建连接器时需要提供的所有参数。

例如，以下蓝图是 Amazon SageMaker 连接器的规范

{
  "name": "<YOUR CONNECTOR NAME>",
  "description": "<YOUR CONNECTOR DESCRIPTION>",
  "version": "<YOUR CONNECTOR VERSION>",
  "protocol": "aws_sigv4",
  "credential": {
    "access_key": "<YOUR AWS ACCESS KEY>",
    "secret_key": "<YOUR AWS SECRET KEY>",
    "session_token": "<YOUR AWS SECURITY TOKEN>"
  },
  "parameters": {
    "region": "<YOUR AWS REGION>",
    "service_name": "sagemaker"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "headers": {
        "content-type": "application/json"
      },
      "url": "<YOUR SAGEMAKER MODEL ENDPOINT URL>",
      "request_body": "<YOUR REQUEST BODY. Example: ${parameters.inputs}>"
    }
  ]
}

OpenSearch 提供的连接器蓝图

OpenSearch 为多个机器学习（ML）平台和模型提供了连接器蓝图。有关 OpenSearch 提供的所有连接器蓝图的列表，请参阅支持的连接器。

作为一名 ML 开发者，你可以为其他平台构建连接器蓝图。使用这些蓝图，管理员和数据科学家可以为托管在这些平台上的模型创建连接器。

配置参数

字段	数据类型	必需	描述
`名称`	字符串	是	连接器的名称。
`description`	字符串	是	连接器的描述。
`version`	整数	是	连接器版本。
`protocol`	字符串	是	连接协议。对于 Amazon SageMaker 和 Amazon Bedrock 等 AWS 服务，请使用 `aws_sigv4`。对于所有其他服务，请使用 `http`。
`parameters`	JSON 对象	是	默认连接器参数，包括 `endpoint`、`model` 和 `skip_validating_missing_parameters`。此字段中指示的任何参数都可以被预测请求中指定的参数覆盖。
`credential`	JSON 对象	是	定义连接到所选端点所需的任何凭证变量。ML Commons 使用 AES/GCM/NoPadding 对称加密来加密您的凭证。当集群连接启动时，OpenSearch 会创建一个随机的 32 字节加密密钥，该密钥保留在 OpenSearch 的系统索引中。因此，您无需手动设置加密密钥。
`actions`	JSON 数组	是	定义连接器内可以运行的操作。如果您是创建连接的管理员，请添加所需连接的蓝图。
`backend_roles`	JSON 数组	是	OpenSearch 后端角色列表。有关设置后端角色的更多信息，请参阅将后端角色分配给用户。
`access_mode`	字符串	是	设置模型的访问模式，可以是 `public`、`restricted` 或 `private`。默认为 `private`。有关 `access_mode` 的更多信息，请参阅模型组。
`add_all_backend_roles`	布尔型	是	当设置为 `true` 时，将所有 `backend_roles` 添加到访问列表中，只有具有管理员权限的用户才能调整。当设置为 `false` 时，非管理员可以添加 `backend_roles`。
`client_config`	JSON 对象	否	客户端配置对象，提供控制连接器使用的客户端连接行为的设置。这些设置允许您管理连接限制和超时，确保高效可靠的通信。
`parameters.skip_validating_missing_parameters`	布尔型	否	当设置为 `true` 时，此选项允许您使用连接器发送请求，而无需验证任何缺失的参数。默认为 `false`。

actions 参数支持以下选项。

字段	数据类型	描述
`action_type`	字符串	必需。设置连接时要使用的 ML Commons API 操作。截至 OpenSearch 2.9，仅支持 `predict`。
`method`	字符串	必需。定义 API 调用的 HTTP 方法。支持 `POST` 和 `GET`。
`url`	字符串	必需。指定发生操作的连接端点。这必须与添加受信任端点时使用的连接的正则表达式匹配。
`request_body`	字符串	必需。设置操作请求正文中包含的参数。参数必须包含 `\"inputText\`，它指定连接器的用户应如何为 `action_type` 构造请求负载。
`pre_process_function`	字符串	可选。用于预处理输入数据的内置或自定义 Painless 脚本。OpenSearch 提供了以下可以直接调用的内置预处理函数 - 用于 Cohere 嵌入模型的 `connector.pre_process.cohere.embedding` - 用于 OpenAI 嵌入模型的 `connector.pre_process.openai.embedding` - `connector.pre_process.default.embedding`，可用于在神经搜索请求中预处理文档，使其格式与 ML Commons 可使用默认预处理器处理的格式一致（OpenSearch 2.11 或更高版本）。有关更多信息，请参阅内置函数。
`post_process_function`	字符串	可选。用于后处理模型输出数据的内置或自定义 Painless 脚本。OpenSearch 提供了以下可以直接调用的内置后处理函数 - 用于 Cohere 文本嵌入模型的 `connector.post_process.cohere.embedding` - 用于 OpenAI 文本嵌入模型的 `connector.post_process.openai.embedding` - `connector.post_process.default.embedding`，可用于后处理模型响应中的文档，使其格式与神经搜索预期的格式一致（OpenSearch 2.11 或更高版本）。有关更多信息，请参阅内置函数。
`headers`	JSON 对象	指定请求或响应正文中使用的标头。默认为 `ContentType: application/json`。如果您的第三方 ML 工具需要访问控制，请在 `headers` 参数中定义所需的 `credential` 参数。

client_config 参数支持以下选项。

字段	数据类型	描述
`max_connection`	整数	客户端可以与服务器建立的最大并发连接数。某些远程服务（如 SageMaker）限制最大并发连接数，如果并发连接数超过阈值，则会抛出限流异常。OpenSearch 的最大并发连接数是 `max_connection` * `node_number_for_connector`。为了缓解此问题，请尝试减小此参数的值并修改 `client_config` 中的重试设置。默认为 `30`。
`connection_timeout`	整数	客户端在尝试与服务器建立连接时将等待的最长时间（以秒为单位）。超时可防止客户端无限期等待，并允许客户端在遇到无法访问的网络终结点时恢复。
`read_timeout`	整数	客户端在发送请求后等待服务器响应的最长时间（以秒为单位）。当服务器响应缓慢或在处理请求时遇到问题时，这很有用。
`retry_backoff_policy`	字符串	远程连接器重试的退避策略。当流量激增导致节流异常时，这很有用。支持的策略包括 `constant`、`exponential_equal_jitter` 和 `exponential_full_jitter`。默认值为 `constant`。
`max_retry_times`	整数	单个远程推理请求的最大重试次数。当流量激增导致节流异常时，这很有用。当设置为 `0` 时，重试被禁用。当设置为 `-1` 时，OpenSearch 不限制 `retry_times` 的数量。将其设置为正整数指定最大重试尝试次数。默认值为 `0`。
`retry_backoff_millis`	整数	重试策略的基本退避时间（以毫秒为单位）。两次重试之间的暂停时间由该参数和 `retry_backoff_policy` 确定。默认值为 `200`。
`retry_timeout_seconds`	整数	重试的超时值，以秒为单位。如果重试在指定时间内无法成功，连接器将停止重试并抛出异常。默认值为 `30`。

内置预处理和后处理函数

当连接到以下文本嵌入模型或部署在远程服务器（例如 Amazon SageMaker）上的您自己的文本嵌入模型时，请调用内置的预处理和后处理函数，而不是编写自定义的 Painless 脚本。

OpenSearch 提供以下预处理和后处理函数

OpenAI: connector.pre_process.openai.embedding 和 connector.post_process.openai.embedding
Cohere: connector.pre_process.cohere.embedding 和 connector.post_process.cohere.embedding
用于神经网络搜索的 Amazon SageMaker 默认函数：connector.pre_process.default.embedding 和 connector.post_process.default.embedding

用于神经网络搜索的 Amazon SageMaker 默认预处理和后处理函数

当您使用神经网络搜索执行向量搜索时，神经网络搜索请求首先路由到 ML Commons，然后路由到模型。如果模型是 OpenSearch 提供的预训练模型之一，它可以解析 ML Commons 请求并以 ML Commons 期望的格式返回响应。但是，对于托管在外部平台的模型，其期望格式可能与 ML Commons 格式不同。默认的预处理和后处理函数在模型期望的格式与神经网络搜索期望的格式之间进行转换。

要应用默认函数，模型的输入和输出必须采用以下部分中描述的格式。

请求示例

以下示例请求创建了一个 SageMaker 文本嵌入连接器并调用了默认的后处理函数

POST /_plugins/_ml/connectors/_create
{
  "name": "Sagemaker text embedding connector",
  "description": "The connector to Sagemaker",
  "version": 1,
  "protocol": "aws_sigv4",
  "credential": {
    "access_key": "<YOUR SAGEMAKER ACCESS KEY>",
    "secret_key": "<YOUR SAGEMAKER SECRET KEY>",
    "session_token": "<YOUR AWS SECURITY TOKEN>"
  },
  "parameters": {
    "region": "ap-northeast-1",
    "service_name": "sagemaker"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "url": "sagemaker.ap-northeast-1.amazonaws.com/endpoints/",
      "headers": {
        "content-type": "application/json"
      },
      "post_process_function": "connector.post_process.default.embedding",
      "request_body": "${parameters.input}"
    }
  ]
}

request_body 模板必须是 ${parameters.input}。

预处理函数

connector.pre_process.default.embedding 默认预处理函数解析神经网络搜索请求并将其转换为模型期望的输入格式。

ML Commons 预测 API 提供以下格式的参数

{
  "parameters": {
    "input": ["hello", "world"]
  }
}

默认预处理函数将 input 字段内容发送到模型。因此，模型输入格式必须是字符串列表，例如

["hello", "world"]

后处理函数

connector.post_process.default.embedding 默认后处理函数解析模型响应并将其转换为神经网络搜索期望的输入格式。

远程文本嵌入模型的输出必须是一个二维浮点数组，其中每个元素代表输入列表中字符串的嵌入。例如，以下二维数组对应于列表 ["hello", "world"] 的嵌入

[
  [
    -0.048237994,
    -0.07612697,
    ...
  ],
  [
    0.32621247,
    0.02328475,
    ...
  ]
]

自定义预处理和后处理函数

您可以根据您的模型格式编写自己的预处理和后处理函数。例如，以下 Amazon Bedrock 连接器定义包含适用于 Amazon Bedrock Titan 嵌入模型的自定义预处理和后处理函数

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

后续步骤

要了解有关连接到外部模型的更多信息，请参阅连接到外部托管模型。
有关连接器示例，请参阅连接器。

OpenSearch 提供的连接器蓝图
配置参数
内置预处理和后处理函数
自定义预处理和后处理函数
后续步骤

此页面有帮助吗？

✔ 是 ✖ 否

告诉我们原因

剩余 350 字符

有问题？在 OpenSearch 论坛上提问。

想要贡献？编辑此页面或创建问题。