注册模型

特定模型的所有版本都保存在一个模型组中。您可以在将模型注册到组之前注册一个模型组，或者注册模型的第一个版本，从而创建该组。集群中的每个模型组名称都必须是全局唯一的。

如果您在未首先注册模型组的情况下注册模型的第一个版本，则将自动创建一个新的模型组，其名称和访问级别如下：

名称：新模型组将与模型同名。由于模型组名称必须唯一，请确保您的模型名称与集群中的任何模型组名称不同。
访问级别：新模型组的访问级别由您在请求中传递的access_mode、backend_roles和add_all_backend_roles参数决定。如果您未提供这三个参数中的任何一个，则如果集群上启用了模型访问控制，新模型组将为private；如果禁用了模型访问控制，则为public。新注册的模型是分配给该模型组的第一个模型版本。

模型组创建后，提供其model_group_id以将新模型版本注册到该模型组。在这种情况下，模型名称无需唯一。

如果您正在使用 OpenSearch 提供的预训练模型，我们建议您首先为这些模型注册一个具有唯一名称的模型组。然后将预训练模型作为版本注册到该模型组。这可确保每个模型组都具有全局唯一的模型组名称。

有关此 API 的用户访问信息，请参阅模型访问控制注意事项。

如果模型大小超过 10 MB，ML Commons 会将其分成更小的块，并将这些块保存在模型的索引中。

端点

POST /_plugins/_ml/models/_register

查询参数

下表列出了可用的查询参数。所有查询参数都是可选的。

参数	数据类型	描述
`部署`	布尔型	注册模型后是否部署该模型。部署操作通过调用部署模型 API 执行。默认为`false`。

注册 OpenSearch 提供的预训练模型

OpenSearch 提供了多种预训练模型。有关更多信息，请参阅OpenSearch 提供的预训练模型。

注册预训练文本嵌入模型

要注册预训练文本嵌入模型，唯一必需的参数是name、version和model_format。

请求正文字段

下表列出了可用的请求字段。

字段	数据类型	必需/可选	描述
`名称`	字符串	必需	模型名称。
`版本`	字符串	必需	模型版本。
`模型格式`	字符串	必需	模型文件的可移植格式。有效值为`TORCH_SCRIPT`和`ONNX`。
`描述`	字符串	可选	模型描述。
`模型组 ID`	字符串	可选	要注册模型的模型组的 ID。

请求示例：OpenSearch 提供的文本嵌入模型

POST /_plugins/_ml/models/_register
{
  "name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b",
  "version": "1.0.3",
  "model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
  "model_format": "TORCH_SCRIPT"
}

注册预训练稀疏编码模型

要注册预训练稀疏编码模型，必须将函数名称设置为SPARSE_ENCODING或SPARSE_TOKENIZE。

请求正文字段

下表列出了可用的请求字段。

字段	数据类型	必需/可选	描述
`名称`	字符串	必需	模型名称。
`版本`	字符串	必需	模型版本。
`模型格式`	字符串	必需	模型文件的可移植格式。有效值为`TORCH_SCRIPT`和`ONNX`。
`函数名称`	字符串	必需	对于文本嵌入模型，将此参数设置为`TEXT_EMBEDDING`。对于稀疏编码模型，将此参数设置为`SPARSE_ENCODING`或`SPARSE_TOKENIZE`。对于交叉编码器模型，将此参数设置为`TEXT_SIMILARITY`。对于问答模型，将此参数设置为`QUESTION_ANSWERING`。
`模型内容哈希值`	字符串	必需	使用 SHA-256 哈希算法生成的模型内容哈希。
`URL`	字符串	必需	包含模型的 URL。
`描述`	字符串	可选	模型描述。
`模型组 ID`	字符串	可选	要注册此模型的模型组的 ID。

请求示例：OpenSearch 提供的稀疏编码模型

POST /_plugins/_ml/models/_register
{
    "name": "amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-distill",
    "version": "1.0.0",
    "model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
    "model_format": "TORCH_SCRIPT"
}

注册自定义模型

要在 OpenSearch 集群中本地使用自定义模型，您需要提供该模型的 URL 和配置对象。有关更多信息，请参阅自定义本地模型。

请求正文字段

下表列出了可用的请求字段。

字段	数据类型	必需/可选	描述
`名称`	字符串	必需	模型名称。
`版本`	字符串	必需	模型版本。
`模型格式`	字符串	必需	模型文件的可移植格式。有效值为`TORCH_SCRIPT`和`ONNX`。
`函数名称`	字符串	必需	将此参数设置为`TEXT_EMBEDDING`、`SPARSE_ENCODING`、`SPARSE_TOKENIZE`、`TEXT_SIMILARITY`或`QUESTION_ANSWERING`。
`模型内容哈希值`	字符串	必需	使用 SHA-256 哈希算法生成的模型内容哈希。
`模型配置`	对象	必需	模型的配置，包括`model_type`、`embedding_dimension`和`framework_type`。可选的`all_config` JSON 字符串包含所有模型配置。`additional_config`对象包含预训练模型对应的`space_type`或自定义模型的指定`space_type`。请参阅空间类型。
`URL`	字符串	必需	包含模型的 URL。
`描述`	字符串	可选	模型描述。
`模型组 ID`	字符串	可选	要将此模型注册到的模型组的模型组 ID。
`是否启用`	布尔型	可选	指定模型是否启用。禁用模型将使其无法用于预测 API 请求，无论模型的部署状态如何。默认为`true`。
`限速器`	对象	可选	限制任何用户可以在模型上调用预测 API 的次数。有关更多信息，请参阅推断调用限速。
`接口`	对象	可选	模型的接口。有关更多信息，请参阅接口。

`model_config` 对象

字段	数据类型	描述
`模型类型`	字符串	模型类型，例如`bert`。对于 Hugging Face 模型，模型类型在`config.json`中指定。有关示例，请参阅`all-MiniLM-L6-v2` Hugging Face 模型`config.json`。必填。
`嵌入维度`	整数	模型生成的稠密向量的维度。对于 Hugging Face 模型，维度在模型卡中指定。例如，在`all-MiniLM-L6-v2` Hugging Face 模型卡中，语句`384 dimensional dense vector space`将 384 指定为嵌入维度。必填。
`框架类型`	字符串	模型使用的框架。目前，OpenSearch 支持`sentence_transformers`和`huggingface_transformers`框架。`sentence_transformers`模型直接输出文本嵌入，因此 ML Commons 不执行任何后处理。对于`huggingface_transformers`，ML Commons 通过应用均值池化来获取文本嵌入。有关更多详细信息，请参阅示例`all-MiniLM-L6-v2` Hugging Face 模型。必填。
`所有配置`	字符串	此字段用于参考目的。您可以在此字段中指定所有模型配置。例如，如果您正在使用 Hugging Face 模型，可以将`config.json`文件压缩到一行，并将其内容保存在`all_config`字段中。模型上传后，您可以使用获取模型 API 操作来获取存储在此字段中的所有模型配置。可选。
`附加配置`	对象	附加模型配置。包含`space_type`，用于指定 k-NN 搜索的距离度量。对于 OpenSearch 提供的预训练模型，此值会自动设置为相应的度量（例如，`huggingface/sentence-transformers/all-distilroberta-v1`的`l2`）。对于自定义模型，请指定您偏好的空间类型。可选。请参阅空间类型。

您可以使用model_config对象中的以下可选字段进一步自定义预训练句子转换器模型的后处理逻辑。

字段	数据类型	描述
`池化模式`	字符串	后处理模型输出，可以是`mean`、`mean_sqrt_len`、`max`、`weightedmean`或`cls`。
`归一化结果`	布尔型	当设置为 `true` 时，模型输出将进行标准化，以缩放到模型的标准范围。

请求示例：自定义模型

以下请求示例注册了一个名为 all-MiniLM-L6-v2 的 NLP 句子转换模型的 1.0.0 版本。

POST /_plugins/_ml/models/_register
{
    "name": "all-MiniLM-L6-v2",
    "version": "1.0.0",
    "description": "test model",
    "model_format": "TORCH_SCRIPT",
    "function_name": "TEXT_EMBEDDING",
    "model_group_id": "FTNlQ4gBYW0Qyy5ZoxfR",
    "model_content_hash_value": "c15f0d2e62d872be5b5bc6c84d2e0f4921541e29fefbef51d59cc10a8ae30e0f",
    "model_config": {
        "model_type": "bert",
        "embedding_dimension": 384,
        "framework_type": "sentence_transformers",
       "all_config": "{\"_name_or_path\":\"nreimers/MiniLM-L6-H384-uncased\",\"architectures\":[\"BertModel\"],\"attention_probs_dropout_prob\":0.1,\"gradient_checkpointing\":false,\"hidden_act\":\"gelu\",\"hidden_dropout_prob\":0.1,\"hidden_size\":384,\"initializer_range\":0.02,\"intermediate_size\":1536,\"layer_norm_eps\":1e-12,\"max_position_embeddings\":512,\"model_type\":\"bert\",\"num_attention_heads\":12,\"num_hidden_layers\":6,\"pad_token_id\":0,\"position_embedding_type\":\"absolute\",\"transformers_version\":\"4.8.2\",\"type_vocab_size\":2,\"use_cache\":true,\"vocab_size\":30522}"
    },
    "url": "https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/all-MiniLM-L6-v2/1.0.1/torch_script/sentence-transformers_all-MiniLM-L6-v2-1.0.1-torch_script.zip"
}

注册托管在第三方平台的模型

要注册托管在第三方平台的模型，您可以先创建一个独立连接器并提供该连接器的 ID，或者为模型指定一个内部连接器。更多信息，请参阅为第三方 ML 平台创建连接器。

请求正文字段

下表列出了可用的请求字段。

字段	数据类型	必需/可选	描述
`名称`	字符串	必需	模型名称。
`函数名称`	字符串	必需	将此参数设置为 `SPARSE_ENCODING` 或 `SPARSE_TOKENIZE`。
`连接器 ID`	可选	必需	托管在第三方平台上的模型的独立连接器的连接器 ID。更多信息，请参阅独立连接器。您必须提供 `connector_id` 或 `connector` 之一。
`连接器`	对象	必需	包含托管在第三方平台上的模型的连接器规范。更多信息，请参阅为特定模型创建连接器。您必须提供 `connector_id` 或 `connector` 之一。
`描述`	字符串	可选	模型描述。
`模型组 ID`	字符串	可选	要将此模型注册到的模型组的模型组 ID。
`是否启用`	布尔型	可选	指定模型是否启用。禁用模型将使其无法用于预测 API 请求，无论模型的部署状态如何。默认为`true`。
`限速器`	对象	可选	限制任何用户可以在模型上调用预测 API 的次数。有关更多信息，请参阅推断调用限速。
`安全护栏`	对象	可选	模型输入的安全护栏。更多信息，请参阅安全护栏。
`接口`	对象	可选	模型的接口。有关更多信息，请参阅接口。

请求示例：使用独立连接器外部托管

POST /_plugins/_ml/models/_register
{
    "name": "openAI-gpt-3.5-turbo",
    "function_name": "remote",
    "model_group_id": "1jriBYsBq7EKuKzZX131",
    "description": "test model",
    "connector_id": "a1eMb4kBJ1eYAeTMAljY"
}

请求示例：将连接器指定为模型一部分的外部托管

POST /_plugins/_ml/models/_register
{
    "name": "openAI-GPT-3.5: internal 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} }"
            }
        ]
    }
}

示例响应

OpenSearch 返回 task_id、任务 status 和 model_id

{
  "task_id" : "ew8I44MBhyWuIwnfvDIH", 
  "status" : "CREATED",
  "model_id": "t8qvDY4BChVAiNVEuo8q"
}

`guardrails` 参数

安全护栏是大型语言模型 (LLM) 的安全措施。它们提供了一套规则和边界，用于控制 LLM 的行为方式以及生成何种类型的输出。

要注册具有安全护栏的外部托管模型，请提供 guardrails 参数，该参数支持以下字段。所有字段都是可选的。

字段	数据类型	描述
`类型`	字符串	护栏类型。有效值包括 `local_regex` 和 `model`。使用 `local_regex`，您可以指定正则表达式或停用词。使用 `model`，您可以指定护栏模型。更多信息，请参阅安全护栏。
`输入护栏`	对象	模型输入的护栏。
`输出护栏`	对象	模型输出的护栏。
`停用词`	对象	包含用于模型输入/输出验证的停用词的索引列表。如果模型提示/响应包含任何索引中包含的停用词，则模型的预测请求将被拒绝。
`索引名称`	对象	存储停用词的索引名称。
`源字段`	对象	存储停用词的字段名称。
`正则表达式`	对象	用于输入/输出验证的正则表达式。如果模型提示/响应与正则表达式匹配，则模型的预测请求将被拒绝。
`模型 ID`	字符串	用于验证用户输入和 LLM 输出的护栏模型。
`响应过滤器`	字符串	包含护栏模型响应的字段的点路径。
`响应验证正则表达式`	字符串	用于验证护栏模型响应的正则表达式。

示例

以下示例配置了一个带有安全护栏的外部托管模型。

请求示例：正则表达式和停用词验证

以下示例使用正则表达式和一组停用词来验证 LLM 响应

POST /_plugins/_ml/models/_register
{
  "name": "openAI-gpt-3.5-turbo",
  "function_name": "remote",
  "model_group_id": "1jriBYsBq7EKuKzZX131",
  "description": "test model",
  "connector_id": "a1eMb4kBJ1eYAeTMAljY",
  "guardrails": {
    "type": "local_regex",
    "input_guardrail": {
      "stop_words": [
        {
          "index_name": "stop_words_input",
          "source_fields": ["title"]
        }
      ],
      "regex": ["regex1", "regex2"]
    },
    "output_guardrail": {
      "stop_words": [
        {
          "index_name": "stop_words_output",
          "source_fields": ["title"]
        }
      ],
      "regex": ["regex1", "regex2"]
    }
  }
}

有关完整示例，请参阅使用停用词和正则表达式验证输入/输出。

请求示例：护栏模型验证

以下示例使用护栏模型来验证 LLM 响应

POST /_plugins/_ml/models/_register?deploy=true
{
    "name": "Bedrock Claude V2 model with guardrails model",
    "function_name": "remote",
    "model_group_id": "ppSmpo8Bi-GZ0tf1i7cD",
    "description": "Bedrock Claude V2 model with guardrails model",
    "connector_id": "xnJjDZABNFJeYR3IPvTO",
    "guardrails": {
        "input_guardrail": {
            "model_id": "o3JaDZABNFJeYR3I2fRV",
            "response_validation_regex": "^\\s*\"[Aa]ccept\"\\s*$"
        },
        "output_guardrail": {
            "model_id": "o3JaDZABNFJeYR3I2fRV",
            "response_validation_regex": "^\\s*\"[Aa]ccept\"\\s*$"
        },
        "type": "model"
    }
}

有关完整示例，请参阅使用护栏模型验证输入/输出。

示例响应

OpenSearch 返回 task_id、任务 status 和 model_id

{
    "task_id": "tsqvDY4BChVAiNVEuo8F",
    "status": "CREATED",
    "model_id": "t8qvDY4BChVAiNVEuo8q"
}

`interface` 参数

模型接口提供了一种高度灵活的方式，以 JSON 模式语法为所有本地深度学习模型和外部托管模型添加任意元数据注解。此注解在模型调用期间启动对模型输入和输出字段的验证检查。该验证检查确保在模型执行推理之前和之后，输入和输出字段都采用正确的格式。

要注册具有模型接口的模型，请提供 interface 参数，该参数支持以下字段。

字段	数据类型	描述
`输入`	对象	模型输入的 JSON 模式。
`输出`	对象	模型输出的 JSON 模式。

输入和输出字段根据提供的 JSON 模式进行评估。您无需同时提供这两个字段。

连接器模型接口

为了简化您的工作流程，您可以使用连接器蓝图格式之一的连接器注册外部托管模型。如果这样做，此连接器的预定义模型接口将在模型注册期间自动生成。预定义模型接口是根据连接器蓝图和模型的元数据生成的，因此在创建连接器时必须严格遵循蓝图以避免错误。

以下连接器蓝图目前支持创建预定义模型接口

Amazon Comprehend
Amazon Textract（请注意，预定义模型接口仅适用于 DetectDocumentText API；目前不支持 DetectEnities API）。
Amazon Bedrock AI21 Labs Jurassic
Amazon Bedrock Anthropic Claude 3
Amazon Bedrock Anthropic Claude
Amazon Bedrock Cohere Embed English v3
Amazon Bedrock Cohere Embed Multilingual v3
Amazon Bedrock Titan Text Embeddings
Amazon Bedrock Titan Multimodal Embeddings

要了解有关连接器蓝图的更多信息，请参阅连接器蓝图。

请求示例：带接口的外部托管模型

POST /_plugins/_ml/models/_register
{
    "name": "openAI-gpt-3.5-turbo",
    "function_name": "remote",
    "description": "test model",
    "connector_id": "A-j7K48BZzNMh1sWVdJu",
    "interface": {
        "input": {
            "properties": {
                "parameters": {
                    "properties": {
                        "messages": {
                            "type": "string",
                            "description": "This is a test description field"
                        }
                    }
                }
            }
        },
        "output": {
            "properties": {
                "inference_results": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "output": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "name": {
                                            "type": "string",
                                            "description": "This is a test description field"
                                        },
                                        "dataAsMap": {
                                            "type": "object",
                                            "description": "This is a test description field"
                                        }
                                    }
                                },
                                "description": "This is a test description field"
                            },
                            "status_code": {
                                "type": "integer",
                                "description": "This is a test description field"
                            }
                        }
                    },
                    "description": "This is a test description field"
                }
            }
        }
    }
}

示例响应

OpenSearch 返回 task_id、任务 status 和 model_id

{
    "task_id": "tsqvDY4BChVAiNVEuo8F",
    "status": "CREATED",
    "model_id": "t8qvDY4BChVAiNVEuo8q"
}

检查模型注册状态

要查看模型注册状态并检索为新模型版本创建的模型 ID，请将 task_id 作为路径参数传递给任务 API

GET /_plugins/_ml/tasks/<task_id>

响应包含模型版本的模型 ID

{
  "model_id": "Qr1YbogBYOqeeqR7sI9L",
  "task_type": "DEPLOY_MODEL",
  "function_name": "TEXT_EMBEDDING",
  "state": "COMPLETED",
  "worker_node": [
    "N77RInqjTSq_UaLh1k0BUg"
  ],
  "create_time": 1685478486057,
  "last_update_time": 1685478491090,
  "is_async": true
}

此页面有帮助吗？

✔ 是 ✖ 否

告诉我们原因

剩余 350 字符

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

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

注册模型

端点

查询参数

注册 OpenSearch 提供的预训练模型

注册预训练文本嵌入模型

请求正文字段

请求示例：OpenSearch 提供的文本嵌入模型

注册预训练稀疏编码模型

请求正文字段

请求示例：OpenSearch 提供的稀疏编码模型

注册自定义模型

请求正文字段

`model_config` 对象

请求示例：自定义模型

注册托管在第三方平台的模型

请求正文字段

请求示例：使用独立连接器外部托管

请求示例：将连接器指定为模型一部分的外部托管

示例响应

`guardrails` 参数

示例

请求示例：正则表达式和停用词验证

请求示例：护栏模型验证

示例响应

`interface` 参数

连接器模型接口

请求示例：带接口的外部托管模型

示例响应

检查模型注册状态

OpenSearch 链接

参与其中

资源

联系我们

注册模型

端点

查询参数

注册 OpenSearch 提供的预训练模型

注册预训练文本嵌入模型

请求正文字段

请求示例：OpenSearch 提供的文本嵌入模型

注册预训练稀疏编码模型

请求正文字段

请求示例：OpenSearch 提供的稀疏编码模型

注册自定义模型

请求正文字段

model_config 对象

请求示例：自定义模型

注册托管在第三方平台的模型

请求正文字段

请求示例：使用独立连接器外部托管

请求示例：将连接器指定为模型一部分的外部托管

示例响应

guardrails 参数

示例

请求示例：正则表达式和停用词验证

请求示例：护栏模型验证

示例响应

interface 参数

连接器模型接口

请求示例：带接口的外部托管模型

示例响应

检查模型注册状态

`model_config` 对象

`guardrails` 参数

`interface` 参数