« Machine learning data frame analytics APIs Migration APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

机器学习训练模型API

edit

机器学习训练模型API

edit

您可以使用以下API来执行模型管理操作：

您可以将训练好的模型部署到摄取管道或聚合中以进行预测。请参阅以下文档以了解更多信息：

清除训练模型部署缓存 API

edit

清除分配部署的所有节点上的推理缓存。

请求

edit

POST _ml/trained_models//deployment/cache/_clear

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

已训练的模型部署可能启用了推理缓存。当请求由每个分配的节点处理时，它们的响应可能会在该节点上缓存。调用此API可以清除缓存而不重启部署。

路径参数

edit
deployment_id
(必需, 字符串) 模型的部署的唯一标识符。

示例

edit

以下示例清除了为训练模型 elastic__distilbert-base-uncased-finetuned-conll03-english 的新部署的缓存：

POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/cache/_clear

API返回以下结果：

{
   "cleared": true
}

创建或更新训练模型别名 API

edit

创建或更新训练模型别名。

训练模型别名是用于引用单个训练模型的逻辑名称。

请求

edit

PUT _ml/trained_models//model_aliases/

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

您可以使用别名来代替训练模型的标识符，以便更容易引用您的模型。例如，您可以在推理聚合和处理器中使用别名。

别名必须是唯一的，并且只能引用一个训练好的模型。然而，每个训练好的模型可以有多个别名。

API 限制：

  • 您不允许更新别名，使其引用不同的训练模型ID，并且模型使用不同类型的数据框分析。例如，如果您有一个用于回归分析的训练模型和一个用于分类分析的训练模型；您不能将别名从一个类型的训练模型重新分配到另一个类型。
  • 您不能从pytorch模型和数据框分析模型更新别名。
  • 您不能从未部署的pytorch模型更新别名到当前未部署的模型。

如果您使用此API更新别名，并且旧的和新的训练模型之间在输入字段方面几乎没有共同点，则API会返回警告。

路径参数

edit
model_alias
(必需, 字符串) 要创建或更新的别名。此值不能以数字结尾。
model_id
(必需, 字符串) 别名所引用的训练模型的标识符。

查询参数

edit
reassign
(可选, 布尔值) 指定如果别名已经分配给不同的模型，是否将其重新分配给指定的训练模型。如果别名已经分配且此参数为false，API将返回错误。默认为false。

示例

edit

创建训练模型别名

edit

以下示例展示了如何为一个训练好的模型（flight-delay-prediction-1574775339910）创建别名（flight_delay_model）：

PUT _ml/trained_models/flight-delay-prediction-1574775339910/model_aliases/flight_delay_model

更新训练模型别名

edit

以下示例展示了如何将别名（flight_delay_model）重新分配给不同的训练模型（flight-delay-prediction-1580004349800）：

PUT _ml/trained_models/flight-delay-prediction-1580004349800/model_aliases/flight_delay_model?reassign=true

创建训练模型定义部分 API

edit

创建部分训练模型定义。

请求

edit

PUT _ml/trained_models//definition/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit
<model_id>
(必需，字符串) 训练模型的唯一标识符。
<part>
(必需, 数字) 定义部分编号。当定义被加载用于推理时，定义部分将按其part_num的顺序流式传输。 第一个部分必须是0，最后一部分必须是total_parts - 1。

请求体

edit
definition
(必需, 字符串) 模型的定义部分。必须是base64编码的字符串。
total_definition_length
(必需，数字) 总未压缩定义长度，以字节为单位。未进行base64编码。
total_parts
(必需，数字) 将要上传的总部分数。必须大于0。

示例

edit

以下示例为先前存储的模型配置创建一个模型定义部分。该定义部分存储在由location.index.name配置的索引中。

由于definition对象的值是一个非常大的base64编码字符串，因此在示例中省略了它的值。

PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/definition/0
{
    "definition": "...",
    "total_definition_length": 265632637,
    "total_parts": 64
}

API返回以下结果：

{
    "acknowledged": true
}

创建训练模型 API

edit

创建一个训练好的模型。

在版本7.8.0中创建的模型与旧版本的节点不兼容。如果在混合集群环境中，所有节点必须至少为7.8.0才能使用由7.8.0节点存储的模型。

请求

edit

PUT _ml/trained_models/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

创建训练模型API使您能够提供一个不是由数据框分析创建的训练模型。

路径参数

edit
<model_id>
(必需，字符串) 训练模型的唯一标识符。

查询参数

edit
defer_definition_decompression
(可选, 布尔值) 如果设置为 true 并且提供了 compressed_definition，请求将推迟定义解压缩并跳过相关的验证。 这种推迟对于知道其模型字节大小估计且知道其模型有效且在推理过程中不太可能失败的系统和用户非常有用。
wait_for_completion
(可选，布尔值) 是否在返回之前等待所有子操作（如模型下载）完成。默认为false。

请求体

edit
compressed_definition
(必需，字符串) 模型的压缩（GZipped 和 Base64 编码）推理定义。 如果指定了 compressed_definition，则不能指定 definition。
definition

(必需, 对象) 模型的推理定义。如果指定了definition，则不能指定compressed_definition。

Properties of definition
preprocessors

(可选, 对象) 预处理器的集合。请参阅预处理器示例。

Properties of preprocessors
frequency_encoding

(必需，对象) 定义字段的频率编码。

Properties of frequency_encoding
feature_name
(必需, 字符串) 结果特征的名称。
field
(必需, 字符串) 要编码的字段名称。
frequency_map
(必需, 字符串到双精度浮点数的对象映射) 将字段值映射到频率编码值的对象。
custom
(可选, 布尔值) 布尔值，指示分析作业是否创建了预处理器，或者是否由用户提供。这会调整特征重要性计算。当true时，特征重要性计算返回处理后的特征的重要性。当false时，返回原始字段的总重要性。默认值为false。
one_hot_encoding

(必需，对象) 定义字段的独热编码映射。

Properties of one_hot_encoding
field
(必需, 字符串) 要编码的字段名称。
hot_map
(必需, 字符串映射对象) 字符串映射，格式为"字段值: 独热列名称"。
custom
(可选, 布尔值) 布尔值，指示分析作业是否创建了预处理器，或者是否由用户提供。这会调整特征重要性计算。当true时，特征重要性计算返回处理后的特征的重要性。当false时，返回原始字段的总重要性。默认值为false。
target_mean_encoding

(必需，对象) 定义字段的平均编码目标。

Properties of target_mean_encoding
default_value
(必需, 双精度浮点数) 如果字段值不在target_map中，则特征值。
feature_name
(必需, 字符串) 结果特征的名称。
field
(必需, 字符串) 要编码的字段名称。
target_map

(必需的，字符串到双精度浮点数的对象映射) 将字段值映射到目标平均值的对象。

custom
(可选, 布尔值) 布尔值，指示分析作业是否创建了预处理器，或者是否由用户提供。这会调整特征重要性计算。当true时，特征重要性计算返回处理后的特征的重要性。当false时，返回原始字段的总重要性。默认值为false。
trained_model

(必需, 对象) 训练模型的定义。

Properties of trained_model
tree

(必需的, 对象) 二叉决策树的定义。

Properties of tree
classification_labels
(可选, 字符串) 分类标签的数组（用于classification）。
feature_names
(必需, 字符串) 树期望的特征，按其期望的顺序排列。
target_type
(必需, 字符串) 指示模型目标类型的字符串；regression或classification。
tree_structure
(必需, 对象) tree_node对象的数组。节点必须按其tree_node.node_index值的顺序排列。
tree_node

(必需的, 对象) 树中节点的定义。

有两种主要类型的节点：叶节点和非叶节点。

  • 叶节点只需要定义node_index和leaf_value。
  • 所有其他节点需要定义split_feature、left_child、right_child、threshold、decision_type和default_left。
Properties of tree_node
decision_type
(可选, 字符串) 指示正数值（即何时选择左节点）决策类型。支持的类型有lt、lte、gt、gte。默认值为lte。
default_left
(可选, 布尔值) 指示当特征缺失时是否默认选择左节点。默认值为true。
leaf_value
(可选, 双精度浮点数) 节点的叶值，如果该节点是叶节点（即没有子节点）。
left_child
(可选, 整数) 左子节点的索引。
node_index
(整数) 当前节点的索引。
right_child
(可选, 整数) 右子节点的索引。
split_feature
(可选, 整数) 特征数组中特征值的索引。
split_gain
(可选, 双精度浮点数) 从分裂中获得的信息增益。
threshold
(可选, 双精度浮点数) 与特征值比较的决策阈值。
ensemble

(可选, 对象) 集成模型的定义。请参阅模型示例。

Properties of ensemble
aggregate_output

(必需，对象) 一个聚合输出对象，定义如何聚合trained_models的输出。支持的对象有weighted_mode、weighted_sum和logistic_regression。请参阅聚合输出示例。

Properties of aggregate_output
logistic_regression

(可选, 对象) 这个aggregated_output类型适用于二元分类（针对值[0, 1]的分类）。它将输出（在ensemble模型的情况下，推理模型的值）乘以提供的weights。结果向量被求和并传递给sigmoid函数。sigmoid函数的结果被视为类别1的概率(P_1)，因此，类别0的概率为1 - P_1。然后返回具有最高概率的类别（0或1）。有关逻辑回归的更多信息，请参阅此维基文章。

Properties of logistic_regression
weights
(必需, 双精度浮点数) 要乘以输入值（训练模型的推理值）的权重。
<code
description
(可选, 字符串) 推理训练模型的可读描述。
estimated_heap_memory_usage_bytes
(可选, 整数) [7.16.0] 在7.16.0中已弃用。由model_size_bytes替代
estimated_operations
(可选，整数) 在推理过程中使用训练模型的估计操作次数。 仅当 defer_definition_decompression 为 true 或 未提供模型定义时，才支持此属性。
inference_config

(必需, 对象) 推理的默认配置。这可以是: 回归, 分类, 填充掩码, 命名实体识别, 问答, 文本分类, 文本嵌入 或 零样本分类。 如果 回归 或 分类, 它必须与底层 definition.trained_model 的 目标类型 匹配。如果 填充掩码, 命名实体识别, 问答, 文本分类, 或 文本嵌入; 则 模型类型 必须是 pytorch。

Properties of inference_config
classification

（可选，对象） 推理的分类配置。

Properties of classification inference
num_top_classes
(可选, 整数) 指定返回的顶级类别预测的数量。默认为 0。
num_top_feature_importance_values
(可选, 整数) 指定每个文档的最大特征重要性值数量。默认为 0，表示不进行特征重要性计算。
prediction_field_type
(可选, 字符串) 指定要写入的预测字段类型。 有效值为: string, number, boolean。当提供 boolean 时，1.0 转换为 true，0.0 转换为 false。
results_field
(可选, 字符串) 添加到传入文档中以包含推理预测的字段。默认为 predicted_value。
top_classes_results_field
(可选, 字符串) 指定写入顶级类别的字段。默认为 top_classes。
fill_mask

(可选, 对象) 用于填充掩码自然语言处理 (NLP) 任务的配置。填充掩码任务适用于经过优化以执行掩码填充操作的模型。例如，对于 BERT 模型，可以提供以下文本：“法国的首都是 [MASK]。”。响应指示最有可能替换 [MASK] 的值。在这种情况下，最可能的标记是 paris。

Properties of fill_mask inference
num_top_classes
(可选, 整数) 返回用于替换掩码标记的顶级预测标记的数量。默认为 0。
results_field
(可选, 字符串) 添加到传入文档中以包含推理预测的字段。默认为 predicted_value。
tokenization

(可选, 对象) 指示要执行的分词以及所需的设置。 默认的分词配置是 bert。有效的分词值包括

  • bert: 用于 BERT 风格的模型
  • deberta_v2: 用于 DeBERTa v2 和 v3 风格的模型
  • mpnet: 用于 MPNet 风格的模型
  • roberta: 用于 RoBERTa 风格和 BART 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 xlm_roberta: 用于 XLMRoBERTa 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 bert_ja: 用于为日语训练的 BERT 风格模型

请参阅分词的属性以查看tokenization对象的属性。

ner

(可选, 对象) 配置一个命名实体识别 (NER) 任务。NER 是标记分类的一种特殊情况。序列中的每个标记根据提供的分类标签进行分类。目前，NER 任务需要 classification_labels 内部-外部-开始 (IOB) 格式的标签。仅支持人、组织、地点和其他。

Properties of ner inference
classification_labels
(可选, 字符串) 分类标签的数组。NER 仅支持内部-外部-开始标签 (IOB)，仅支持人、组织、地点和其他。 示例: ["O", "B-PER", "I-PER", "B-ORG", "I-ORG", "B-LOC", "I-LOC", "B-MISC", "I-MISC"]
results_field
(可选, 字符串) 添加到传入文档中以包含推理预测的字段。默认为 predicted_value。
tokenization

(可选, 对象) 指示要执行的分词以及所需的设置。 默认的分词配置是 bert。有效的分词值包括

  • bert: 用于 BERT 风格的模型
  • deberta_v2: 用于 DeBERTa v2 和 v3 风格的模型
  • mpnet: 用于 MPNet 风格的模型
  • roberta: 用于 RoBERTa 风格和 BART 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 xlm_roberta: 用于 XLMRoBERTa 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 bert_ja: 用于为日语训练的 BERT 风格模型

请参阅 分词的属性 以查看 tokenization 对象的属性。

pass_through

(可选, 对象) 配置一个pass_through任务。此任务对于调试非常有用，因为不对推理输出进行后处理，并且原始池化层结果会返回给调用者。

Properties of pass_through inference
results_field
(可选, 字符串) 添加到传入文档中以包含推理预测的字段。默认为 predicted_value。
tokenization

(可选, 对象) 指示要执行的分词以及所需的设置。 默认的分词配置是 bert。有效的分词值包括

  • bert: 用于 BERT 风格的模型
  • deberta_v2: 用于 DeBERTa v2 和 v3 风格的模型
  • mpnet: 用于 MPNet 风格的模型
  • roberta: 用于 RoBERTa 风格和 BART 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 xlm_roberta: 用于 XLMRoBERTa 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 bert_ja: 用于为日语训练的 BERT 风格模型

请参阅分词的属性以查看tokenization对象的属性。

question_answering

(可选, 对象) 配置一个问答自然语言处理(NLP)任务。问答功能有助于从大量文本语料库中提取特定问题的答案。

Properties of question_answering inference
max_answer_length
(可选, 整数) 答案中的最大单词数量。默认为 15。
results_field
(可选, 字符串) 添加到传入文档中以包含推理预测的字段。默认为 predicted_value。
tokenization

(可选, 对象) 指示要执行的分词以及所需的设置。 默认的分词配置是 bert。有效的分词值包括

  • bert: 用于 BERT 风格的模型
  • deberta_v2: 用于 DeBERTa v2 和 v3 风格的模型
  • mpnet: 用于 MPNet 风格的模型 </
input

(必需, 对象) 模型定义的输入字段名称。

Properties of input
field_names
(必需, 字符串) 模型输入字段名称的数组。
location

(可选, 对象) 模型定义的位置。如果未指定 definition 或 compressed_definition，则需要指定 location。

Properties of location
index
(必需, 对象) 表示模型定义存储在索引中。此对象必须为空，因为存储模型定义的索引是自动配置的。
metadata
(可选, 对象) 一个包含模型元数据的对象映射。
model_size_bytes
(可选, 整数) 在内存中保持训练模型所需的估计内存使用量（以字节为单位）。此属性仅在 defer_definition_decompression 为 true 或未提供模型定义时才受支持。
model_type

(可选, 字符串) 创建的模型类型。默认的模型类型是 tree_ensemble。 适当的类型包括：

  • tree_ensemble: 模型定义是一个决策树的集成模型。
  • lang_ident: 一种为语言识别模型保留的特殊类型。
  • pytorch: 存储的定义是一个PyTorch（特别是TorchScript）模型。目前仅支持NLP模型。更多信息，请参阅 自然语言处理。
platform_architecture
(可选, 字符串) 如果模型仅适用于一个平台，因为它针对特定的处理器架构和操作系统组合进行了深度优化， 那么此字段指定是哪个平台。字符串的格式必须与Elasticsearch使用的平台标识符匹配，因此可以是linux-x86_64、 linux-aarch64、darwin-x86_64、darwin-aarch64或windows-x86_64之一。 对于可移植模型（那些不依赖于处理器架构或操作系统特性的模型），请保留此字段为空。
prefix_strings

(可选, 对象) 某些NLP模型在训练时需要对输入文本应用前缀字符串，然后才能对其进行评估。前缀可能因意图不同而异。对于诸如信息检索等非对称任务，在索引段落时应用的前缀可能与搜索这些段落时应用的前缀不同。

prefix_strings 有2个选项，一个是在搜索上下文中始终应用的前缀字符串，另一个是在摄取文档时始终应用的前缀字符串。两者都是可选的。

Properties of prefix_strings
search
(可选, 字符串) 用于搜索查询请求的输入文本前缀字符串。
ingest
(可选, 字符串) 用于在摄取时使用推理摄取处理器请求的输入文本前缀字符串。
tags
(可选, 字符串) 用于组织模型的标签数组。

tokenizaton的属性

edit

The tokenization 对象具有以下属性。

bert

(可选, 对象) BERT风格的标记化将使用包含的设置进行。

bert的属性
do_lower_case
(可选, 布尔值) 指定在构建标记时，分词器是否将文本序列转换为小写。
max_sequence_length
(可选, 整数) 指定分词器输出的最大标记数量。
span

(可选, 整数) 当 truncate 为 none 时，您可以为推理划分较长的文本序列。该值表示每个子序列之间重叠的标记数量。

默认值为 -1，表示不进行窗口化或跨度操作。

当您的典型输入仅略大于 max_sequence_length 时，最好直接截断；第二个子序列中的信息将非常少。

truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。BERT风格的分词通常包含的标记有：

  • [CLS]: 被分类的序列的第一个标记。
  • [SEP]: 表示序列分离。
deberta_v2

(可选, 对象) DeBERTa风格的标记化将使用包含的设置进行。

deberta_v2 的属性
do_lower_case

(可选, 布尔值) 指定在构建标记时，标记化是否将文本序列转换为小写。

默认为 false。

max_sequence_length
(可选, 整数) 指定标记器输出的最大标记数量。
span

(可选, 整数) 当 truncate 为 none 时，您可以为推理划分较长的文本序列。该值表示每个子序列之间重叠的标记数量。

默认值为 -1，表示不进行窗口化或跨度操作。

当您的典型输入仅略大于 max_sequence_length 时，最好直接截断；第二个子序列中的信息将非常少。

truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • balanced: 第一个和第二个序列中的一个或两个可能会被截断，以便平衡两个序列中包含的标记。
  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。
with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。DeBERTa风格的分词通常包括以下标记：

  • [CLS]: 被分类的序列的第一个标记。
  • [SEP]: 表示序列分隔和序列结束。
roberta

(可选, 对象) 将使用封闭的设置执行RoBERTa风格的标记化。

roberta的属性
add_prefix_space
(可选, 布尔值) 指定是否应在模型的标记化输入前添加一个空格。
max_sequence_length
(可选, 整数) 指定标记器允许输出的最大标记数量。
span

(可选, 整数) 当 truncate 为 none 时，您可以为推理划分较长的文本序列。该值表示每个子序列之间重叠的标记数量。

默认值为 -1，表示不进行窗口化或跨度操作。

当您的典型输入仅略大于 max_sequence_length 时，最好直接截断；第二个子序列中的信息将非常少。

truncate

(可选，字符串) 指示当令牌超过max_sequence_length时如何截断它们。 默认值是first。

  • none: 不发生截断；推理请求收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列， 则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。RoBERTa风格的分词通常包含的标记有：

  • : 被分类的序列的第一个标记。
  • : 表示序列分离。
mpnet

(可选, 对象) MPNet 风格的标记化将使用包含的设置进行。

mpnet 的属性
do_lower_case
(可选, 布尔值) 指定在构建标记时，标记化是否将文本序列转换为小写。
max_sequence_length
(可选, 整数) 指定标记器允许输出的最大标记数量。
span

(可选, 整数) 当 truncate 为 none 时，您可以为推理划分较长的文本序列。该值表示每个子序列之间重叠的标记数量。

默认值为 -1，表示不进行窗口化或跨度操作。

当您的典型输入仅略大于 max_sequence_length 时，最好直接截断；第二个子序列中的信息将非常少。

truncate

(可选, 字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。MPNet风格的分词通常包括的标记有：

  • : 被分类的序列的第一个标记。
  • : 表示序列分离。
xlm_roberta

(可选, 对象) [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 将使用包含的设置执行 XLMRoBERTa 风格的标记化。

xlm_roberta 的属性
max_sequence_length
(可选, 整数) 指定分词器输出的最大标记数量。
span

(可选, 整数) 当 truncate 为 none 时，您可以为推理划分较长的文本序列。该值表示每个子序列之间重叠的标记数量。

默认值为 -1，表示不进行窗口化或跨度操作。

当您的典型输入仅略大于 max_sequence_length 时，最好直接截断；第二个子序列中的信息将非常少。

truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。RoBERTa风格的分词通常包括以下标记：

  • : 被分类的序列的第一个标记。
  • : 表示序列分离。
bert_ja

(可选, 对象) [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 将使用包含的设置对日语文本执行 BERT 风格的标记化。

bert_ja 的属性
do_lower_case
(可选, 布尔值) 指定在构建标记时是否将文本序列转换为小写。
max_sequence_length
(可选, 整数) 指定标记器允许输出的最大标记数量。
span

(可选, 整数) 当 truncate 为 none 时，您可以为推理划分较长的文本序列。该值表示每个子序列之间重叠的标记数量。

默认值为 -1，表示不进行窗口化或跨度操作。

当您的典型输入仅略大于 max_sequence_length 时，最好直接截断；第二个子序列中的信息将非常少。

truncate

(可选, 字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不发生截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens
(可选, 布尔值) 如果为 true，则使用特殊标记进行标记化。

示例

edit

预处理器示例

edit

下面的示例展示了一个frequency_encoding预处理器对象：

{
   "frequency_encoding":{
      "field":"FlightDelayType",
      "feature_name":"FlightDelayType_frequency",
      "frequency_map":{
         "Carrier Delay":0.6007414737092798,
         "NAS Delay":0.6007414737092798,
         "Weather Delay":0.024573576178086153,
         "Security Delay":0.02476631010889467,
         "No Delay":0.6007414737092798,
         "Late Aircraft Delay":0.6007414737092798
      }
   }
}

下一个示例展示了一个one_hot_encoding预处理器对象：

{
   "one_hot_encoding":{
      "field":"FlightDelayType",
      "hot_map":{
         "Carrier Delay":"FlightDelayType_Carrier Delay",
         "NAS Delay":"FlightDelayType_NAS Delay",
         "No Delay":"FlightDelayType_No Delay",
         "Late Aircraft Delay":"FlightDelayType_Late Aircraft Delay"
      }
   }
}

此示例展示了一个 target_mean_encoding 预处理器对象：

{
   "target_mean_encoding":{
      "field":"FlightDelayType",
      "feature_name":"FlightDelayType_targetmean",
      "target_map":{
         "Carrier Delay":39.97465788139886,
         "NAS Delay":39.97465788139886,
         "Security Delay":203.171206225681,
         "Weather Delay":187.64705882352948,
         "No Delay":39.97465788139886,
         "Late Aircraft Delay":39.97465788139886
      },
      "default_value":158.17995752420433
   }
}

模型示例

edit

第一个示例展示了一个trained_model对象：

{
   "tree":{
      "feature_names":[
         "DistanceKilometers",
         "FlightTimeMin",
         "FlightDelayType_NAS Delay",
         "Origin_targetmean",
         "DestRegion_targetmean",
         "DestCityName_targetmean",
         "OriginAirportID_targetmean",
         "OriginCityName_frequency",
         "DistanceMiles",
         "FlightDelayType_Late Aircraft Delay"
      ],
      "tree_structure":[
         {
            "decision_type":"lt",
            "threshold":9069.33437193022,
            "split_feature":0,
            "split_gain":4112.094574306927,
            "node_index":0,
            "default_left":true,
            "left_child":1,
            "right_child":2
         },
         ...
         {
            "node_index":9,
            "leaf_value":-27.68987349695448
         },
         ...
      ],
      "target_type":"regression"
   }
}

以下示例展示了一个ensemble模型对象：

"ensemble":{
   "feature_names":[
      ...
   ],
   "trained_models":[
      {
         "tree":{
            "feature_names":[],
            "tree_structure":[
               {
                  "decision_type":"lte",
                  "node_index":0,
                  "leaf_value":47.64069875778043,
                  "default_left":false
               }
            ],
            "target_type":"regression"
         }
      },
      ...
   ],
   "aggregate_output":{
      "weighted_sum":{
         "weights":[
            ...
         ]
      }
   },
   "target_type":"regression"
}

聚合输出示例

edit

示例：一个logistic_regression对象：

"aggregate_output" : {
  "logistic_regression" : {
    "weights" : [2.0, 1.0, .5, -1.0, 5.0, 1.0, 1.0]
  }
}

加权和对象的示例：

"aggregate_output" : {
  "weighted_sum" : {
    "weights" : [1.0, -1.0, .5, 1.0, 5.0]
  }
}

加权模式对象的示例：

"aggregate_output" : {
  "weighted_mode" : {
    "weights" : [1.0, 1.0, 1.0, 1.0, 1.0]
  }
}

示例：一个指数对象：

"aggregate_output" : {
  "exponent" : {
    "weights" : [1.0, 1.0, 1.0, 1.0, 1.0]
  }
}

训练模型 JSON 架构

edit

有关训练模型的完整JSON模式， 点击这里。

创建训练模型词汇表 API

edit

创建一个训练好的模型词汇表。 这仅支持自然语言处理（NLP）模型。

请求

edit

PUT _ml/trained_models//vocabulary/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

词汇表按照训练模型定义中的 inference_config.*.vocabulary 所述存储在索引中。

路径参数

edit
<model_id>
(必需，字符串) 训练模型的唯一标识符。

请求体

edit
vocabulary
(数组) 模型词汇表。不能为空。
merges
(可选, 数组) 用于字节对编码的合并模型。合并必须是子词对，以空格分隔，并按优先顺序排列。示例: ["f o", "fo o"]。对于RoBERTa和BART风格的模型，必须提供。
scores
(可选, 数组) 句子片段分词使用的词汇值分数。必须与词汇表的长度相同。 对于像XLMRoberta和T5这样的unigram句子片段分词模型是必需的。

示例

edit

以下示例展示了如何为先前存储的训练模型配置创建模型词汇表。

PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/vocabulary
{
  "vocabulary": [
    "[PAD]",
    "[unused0]",
    ...
  ]
}

API返回以下结果：

{
    "acknowledged": true
}

删除训练模型别名 API

edit

删除一个训练好的模型别名。

请求

edit

DELETE _ml/trained_models//model_aliases/

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

此API删除指向已训练模型的现有模型别名。

如果模型别名缺失或指向的模型不是由model_id标识的模型，此API将返回错误。

路径参数

edit
model_alias
(必需，字符串) 要删除的模型别名。
model_id
(必需，字符串) 模型别名所引用的训练模型ID。

示例

edit

以下示例展示了如何删除一个模型别名（flight_delay_model） 对于一个已训练模型的ID（flight-delay-prediction-1574775339910）：

DELETE _ml/trained_models/flight-delay-prediction-1574775339910/model_aliases/flight_delay_model

删除训练模型 API

edit

删除一个现有的训练推理模型。

请求

edit

DELETE _ml/trained_models/

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

路径参数

edit
<model_id>
(可选, 字符串) 训练模型的唯一标识符。

查询参数

edit
force
(可选，布尔值) 用于强制删除一个被摄取管道引用或有已启动部署的训练模型。

响应代码

edit
409
该代码表明训练好的模型被一个摄取管道引用，因此无法删除。

示例

edit

以下示例删除了训练模型 regression-job-one-1574775307356：

DELETE _ml/trained_models/regression-job-one-1574775307356

API返回以下结果：

{
  "acknowledged" : true
}

获取训练模型 API

edit

检索有关推理训练模型的配置信息。

请求

edit

GET _ml/trained_models/

GET _ml/trained_models/

GET _ml/trained_models/_all

GET _ml/trained_models/,

GET _ml/trained_models/

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

路径参数

edit
<model_id>

(可选, 字符串) 训练模型的唯一标识符或模型别名。

您可以通过使用以逗号分隔的模型ID列表或通配符表达式，在单个API请求中获取多个已训练模型的信息。

查询参数

edit
allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

  • 包含通配符表达式且没有匹配的模型。
  • 包含 _all 字符串或没有标识符且没有匹配项。
  • 包含通配符表达式且只有部分匹配项。

默认值为 true，在没有匹配项时返回一个空数组，在有部分匹配项时返回部分结果。如果此参数为 false，在没有匹配项或只有部分匹配项时，请求将返回 404 状态码。

decompress_definition
(可选, 布尔值) 指定是否应将包含的模型定义作为JSON映射返回 (true) 或以自定义压缩格式返回 (false)。默认为 true。
exclude_generated
(可选，布尔值) 指示是否应在检索时从配置中移除某些字段。这允许配置以可接受的格式被检索，然后添加到另一个集群中。默认值为 false。
from
(可选，整数) 跳过指定数量的模型。默认值是 0。
include

(可选, 字符串) 一个以逗号分隔的字符串，包含在响应体中可选的字段。默认值为空，表示不包含任何可选字段。有效的选项包括：

  • definition: 包含模型定义。
  • feature_importance_baseline: 包含特征重要性值的基线。
  • hyperparameters: 包含用于训练模型的超参数信息。此信息包括值、超参数的绝对和相对重要性以及指示它是用户指定还是在超参数优化期间调整的。
  • total_feature_importance: 包含训练数据集的总特征重要性。
  • definition_status: 包含字段 fully_defined，指示完整模型定义是否存在。 基线和总特征重要性值在响应体的 metadata 字段中返回。
size
(可选, 整数) 指定要获取的最大模型数量。默认值为100。
tags
(可选, 字符串) 一个以逗号分隔的标签字符串。一个训练好的模型可以有很多标签，也可以没有标签。 当提供时，只会返回包含所有提供的标签的训练好的模型。

响应体

edit
trained_model_configs

(数组) 一个包含训练模型资源的数组，这些资源按 model_id 值的升序排列。

训练模型资源的属性
created_by
(字符串) 训练模型的创建者。
create_time
(时间单位) 训练模型的创建时间。
default_field_map

(对象) 一个包含默认字段映射的字符串对象，用于在推断模型时使用。例如，数据框分析可能在特定的多字段foo.keyword上训练模型。然后，分析作业将为"foo" : "foo.keyword"提供一个默认字段映射条目。

推理配置中描述的任何字段映射优先。

description
(字符串) 训练模型的自由文本描述。
model_size_bytes
(整数) 在内存中保持训练模型所需的估计模型大小（以字节为单位）。
estimated_operations
(整数) 使用训练模型所需的估计操作次数。
inference_config

(对象) 推理的默认配置。这可以是回归或分类配置。它必须与底层definition.trained_model的target_type匹配。

inference_config的属性
classification

(对象) 推理的分类配置。

分类推理的属性
num_top_classes
(整数) 指定返回的顶级类别预测的数量。默认为 0。
num_top_feature_importance_values
(整数) 指定每个文档的最大特征重要性值数量。默认为 0，表示不进行特征重要性计算。
prediction_field_type
(字符串) 指定要写入的预测字段类型。有效值为：string、number、boolean。当提供boolean时，1.0转换为true，0.0转换为false。
results_field
(字符串) 添加到传入文档中的字段，用于包含推理预测。默认为predicted_value。
top_classes_results_field
(字符串) 指定写入顶级类别的字段。默认为top_classes。
fill_mask

(可选, 对象) 用于填充掩码自然语言处理 (NLP) 任务的配置。填充掩码任务适用于经过优化以执行掩码填充操作的模型。例如，对于 BERT 模型，可以提供以下文本：“法国的首都是 [MASK]。”。响应指示最有可能替换 [MASK] 的值。在这种情况下，最可能的标记是 paris。

fill_mask 推理的属性
mask_token
(可选, 字符串) 用于从传入文档中移除并替换为推理预测的字符串/标记。在响应中，此字段包含指定模型/分词器的掩码标记。每个模型和分词器都有一个预定义的掩码标记，无法更改。因此，建议不要在请求中设置此值。但是，如果请求中存在此字段，其值必须与该模型/分词器的预定义值匹配，否则请求将失败。
tokenization

(可选, 对象) 指示要执行的分词以及所需的设置。 默认的分词配置是 bert。有效的分词值包括

  • bert: 用于 BERT 风格的模型
  • deberta_v2: 用于 DeBERTa v2 和 v3 风格的模型
  • mpnet: 用于 MPNet 风格的模型
  • roberta: 用于 RoBERTa 风格和 BART 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 xlm_roberta: 用于 XLMRoBERTa 风格的模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 bert_ja: 用于为日语训练的 BERT 风格模型
分词的属性
bert

(可选, 对象) BERT 风格的标记化将使用包含的设置进行。

bert 的属性
do_lower_case
(可选, 布尔值) 指定在构建标记时是否将文本序列转换为小写。
max_sequence_length
(可选, 整数) 指定分词器输出的最大标记数量。
truncate

(可选, 字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。BERT 风格的标记化通常包含的标记有：

  • [CLS]: 序列中用于分类的第一个标记。
  • [SEP]: 指示序列分隔。
roberta

(可选, 对象) 将使用封闭的设置执行 RoBERTa 风格的标记化。

roberta 的属性
add_prefix_space
(可选, 布尔值) 指定分词是否应在模型输入前添加空格。
max_sequence_length
(可选, 整数) 指定分词器输出的最大标记数量。
truncate

(可选, 字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

with_special_tokens

(可选, 布尔值) 使用特殊标记进行分词。RoBERTa 风格的标记化通常包括以下标记：

  • : 序列中用于分类的第一个标记。
  • : 指示序列分隔。
mpnet

(可选, 对象) MPNet 风格的标记化将使用包含的设置进行。

mpnet 的属性
do_lower_case
(可选, 布尔值) 指定在构建标记时是否将文本序列转换为小写。
max_sequence_length
(可选, 整数) 指定分词器输出的最大标记数量。
truncate

(可选, 字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

响应代码

edit
400
如果 include_model_definition 是 true，此代码表示有多个模型匹配ID模式。
404 (Missing resources)
如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

以下示例获取所有训练模型的配置信息：

GET _ml/trained_models/

获取训练模型统计信息 API

edit

检索已训练模型的使用信息。

请求

edit

GET _ml/trained_models/_stats

GET _ml/trained_models/_all/_stats

GET _ml/trained_models//_stats

GET _ml/trained_models/,/_stats

GET _ml/trained_models/,/_stats

先决条件

edit

需要 monitor_ml 集群权限。此权限包含在 machine_learning_user 内置角色中。

描述

edit

您可以通过使用以逗号分隔的模型ID列表、部署ID列表或通配符表达式，在单个API请求中获取多个训练模型或训练模型部署的使用信息。

路径参数

edit
<model_id_or_deployment_id>
(可选, 字符串) 模型的唯一标识符或部署的唯一标识符。如果一个模型有多个部署，并且其中一个部署的ID与模型ID匹配，则模型ID优先；结果将返回该模型的所有部署。

查询参数

edit
allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

  • 包含通配符表达式且没有匹配的模型。
  • 包含 _all 字符串或没有标识符且没有匹配项。
  • 包含通配符表达式且只有部分匹配项。

默认值为 true，在没有匹配项时返回一个空数组，在有部分匹配项时返回部分结果。如果此参数为 false，在没有匹配项或只有部分匹配项时，请求将返回 404 状态码。

from
(可选，整数) 跳过指定数量的模型。默认值是 0。
size
(可选, 整数) 指定要获取的最大模型数量。默认值为100。

响应体

edit
count
(整数) 匹配请求的ID模式的训练模型统计信息的总数。可能高于trained_model_stats数组中的项目数量，因为数组的大小受提供的size参数的限制。
trained_model_stats

(数组) 一个包含训练模型统计信息的数组，这些统计信息按 model_id 值的升序排列。

训练模型统计信息的属性
deployment_stats

(列表) 如果提供的model_id值之一已部署，则为部署统计信息的集合

部署统计信息的属性
allocation_status

(对象) 根据部署配置给出的详细分配状态。

分配统计信息的属性
allocation_count
(整数) 当前分配模型的节点数量。
cache_size
(字节值) 每个节点的模型推理缓存大小（JVM堆外内存）。
state

(字符串) 与节点相关的详细分配状态。

  • starting: 正在尝试分配，但当前没有节点分配模型。
  • started: 至少有一个节点已分配模型。
  • fully_allocated: 部署已完全分配，满足 target_allocation_count。
target_allocation_count
(整数) 模型分配所需的节点数量。
deployment_id
模型部署的唯一标识符。
error_count
(整数) 部署中所有节点的 error_count 总和。
inference_count
(整数) 部署中所有节点的 inference_count 总和。
model_id
(字符串) 训练模型的唯一标识符。
nodes

(对象数组) 当前分配了模型的每个节点的部署统计信息。

节点统计信息的属性
average_inference_time_ms
(双精度) 每个推理调用在此节点上完成的平均时间。 平均值是根据部署的整个生命周期计算的。
average_inference_time_ms_excluding_cache_hits
(双精度) 执行推理的平均时间，不包括从缓存中获取响应的情况。 缓存推理调用返回非常快，因为模型未被评估，通过排除缓存命中，此值是评估模型所花费的平均时间的准确度量。
average_inference_time_ms_last_minute
(双精度) 过去一分钟内每个推理调用在此节点上完成的平均时间。
error_count
(整数) 评估训练模型时的错误数量。
inference_cache_hit_count
(整数) 对此节点进行的推理调用总数，这些调用是从推理缓存中提供的。
inference_cache_hit_count_last_minute
(整数) 过去一分钟内对此节点进行的推理调用数量，这些调用是从推理缓存中提供的。
inference_count
(整数) 对此节点进行的推理调用总数。
last_access
(长整型) 此节点上模型最后一次推理调用的时间戳。
node

(对象) 与节点相关的信息。

节点的属性
attributes
(对象) 列出节点属性，如 ml.machine_memory 或 ml.max_open_jobs 设置。
ephemeral_id
(字符串) 节点的临时ID。
id
(字符串) 节点的唯一标识符。
name
(字符串) 节点名称。
transport_address
(字符串) 接受传输HTTP连接的主机和端口。
number_of_allocations
(整数) 分配给此节点的数量。
number_of_pending_requests
(整数) 排队等待处理的推理请求数量。
peak_throughput_per_minute
(整数) 1分钟内处理请求的峰值数量。
routing_state

(对象) 当前路由状态以及导致当前路由状态的原因。

routing_state的属性
reason
(字符串) 当前状态的原因。通常仅在 routing_state 为 failed 时填充。
routing_state
(字符串) 当前路由状态。
  • starting: 模型正在尝试在此节点上分配，推理调用尚未被接受。
  • started: 模型已分配并准备好接受推理请求。
  • stopping: 模型正在从此节点上取消分配。
  • stopped: 模型已完全从此节点上取消分配。
  • failed: 分配尝试失败，请参阅 reason 字段以了解潜在原因。
rejected_execution_count
(整数) 由于队列已满而未处理的推理请求数量。
start_time
(长整型) 分配开始的时间戳。
threads_per_allocation
(整数) 推理期间每个分配的线程数。 此值受节点上的硬件线程数量限制； 因此可能与 启动训练模型部署 API 中的 threads_per_allocation 值不同。
timeout_count
(整数) 在处理之前超时的推理请求数量。
throughput_last_minute
(整数) 过去1分钟内处理的请求数量。
number_of_allocations
(整数) 训练模型部署的请求分配数量。
peak_throughput_per_minute
(整数) 1分钟内处理请求的峰值数量， 所有节点中的总和。这是通过每个节点的 peak_throughput_per_minute 值的总和计算的。
priority
(字符串) 部署优先级。
rejected_execution_count
(整数) 部署中所有节点的 rejected_execution_count 总和。 如果推理队列已满，单个节点会拒绝推理请求。 队列大小由 启动训练模型部署 API 中的 queue_capacity 设置控制。
reason
(字符串) 当前部署状态的原因。 通常仅在模型未部署到节点时填充。
start_time
(长整型) 部署开始的时间戳。
state

(字符串) 部署的总体状态。可能的值包括：

  • starting: 部署最近已启动，但尚未可用，因为模型尚未在任何节点上分配。
  • started: 部署可用，因为至少有一个节点已分配模型。
  • stopping: 部署正在准备停止，并将从相关节点上取消分配模型。
threads_per_allocation
(整数) 推理过程中每个分配使用的线程数。
timeout_count
(整数) 部署中所有节点的 timeout_count 总和。
queue_capacity
(整数) 在拒绝新请求之前可以排队的推理请求数量。
inference_stats

(对象) 一组推理统计字段。

推理统计信息的属性
missing_all_fields_count
(整数) 模型所有训练特征缺失的推理调用数量。
inference_

响应代码

edit
404 (Missing resources)
如果 allow_no_match 是 false，此代码表示没有与请求匹配的资源，或者只有部分匹配的请求。

示例

edit

以下示例获取所有训练模型的使用信息：

GET _ml/trained_models/_stats

API返回以下结果：

{
  "count": 2,
  "trained_model_stats": [
    {
      "model_id": "flight-delay-prediction-1574775339910",
      "pipeline_count": 0,
      "inference_stats": {
        "failure_count": 0,
        "inference_count": 4,
        "cache_miss_count": 3,
        "missing_all_fields_count": 0,
        "timestamp": 1592399986979
      }
    },
    {
      "model_id": "regression-job-one-1574775307356",
      "pipeline_count": 1,
      "inference_stats": {
        "failure_count": 0,
        "inference_count": 178,
        "cache_miss_count": 3,
        "missing_all_fields_count": 0,
        "timestamp": 1592399986979
      },
      "ingest": {
        "total": {
          "count": 178,
          "time_in_millis": 8,
          "current": 0,
          "failed": 0
        },
        "pipelines": {
          "flight-delay": {
            "count": 178,
            "time_in_millis": 8,
            "current": 0,
            "failed": 0,
            "processors": [
              {
                "inference": {
                  "type": "inference",
                  "stats": {
                    "count": 178,
                    "time_in_millis": 7,
                    "current": 0,
                    "failed": 0
                  }
                }
              }
            ]
          }
        }
      }
    }
  ]
}

推断训练模型 API

edit

评估一个训练好的模型。该模型可以是任何通过数据框分析训练或导入的监督模型。

对于启用了缓存的模型部署，结果可能会直接从推理缓存中返回。

请求

edit

POST _ml/trained_models//_infer POST _ml/trained_models//_infer

路径参数

edit
<model_id>
(可选, 字符串) 训练模型的唯一标识符或模型别名。

如果在API调用中指定了model_id，并且该模型有多个部署，将随机使用一个部署。如果model_id与其中一个部署的ID匹配，则将使用该部署。

<deployment_id>
(可选, 字符串) 模型的部署的唯一标识符。

查询参数

edit
timeout
(可选，时间) 控制等待推理结果的时间量。默认为10秒。

请求体

edit
docs
(必需，数组) 一个对象数组，用于传递给模型进行推理。这些对象应包含与配置的训练模型输入匹配的字段。通常对于NLP模型，字段名称为text_field。在此属性中指定的每个推理输入字段必须是单个字符串，而不是字符串数组。
inference_config

(可选, 对象) 推理的默认配置。可以是：回归, 分类, 填充掩码, 命名实体识别, 问答, 文本分类, 文本嵌入 或 零样本分类。 如果为回归或分类，则必须与底层definition.trained_model的目标类型匹配。如果为填充掩码, 命名实体识别, 问答, 文本分类, 或 文本嵌入；则模型类型必须为pytorch。如果未指定，则使用创建模型时的推理配置。

Properties of inference_config
classification

（可选，对象） 推理的分类配置。

Properties of classification inference
num_top_classes
(可选, 整数) 指定返回的顶级类别预测的数量。默认为 0。
num_top_feature_importance_values
(可选, 整数) 指定每个文档的最大特征重要性值数量。默认为 0，表示不进行特征重要性计算。
prediction_field_type
(可选, 字符串) 指定要写入的预测字段类型。 有效值为：string, number, boolean。当提供boolean时，1.0转换为true，0.0转换为false。
results_field
(可选, 字符串) 添加到传入文档中的字段，用于包含推理预测。默认为predicted_value。
top_classes_results_field
(可选, 字符串) 指定顶级类别写入的字段。默认为top_classes。
fill_mask

(可选, 对象) 用于填充掩码自然语言处理 (NLP) 任务的配置。填充掩码任务适用于经过优化以执行掩码填充操作的模型。例如，对于 BERT 模型，可以提供以下文本：“法国的首都是 [MASK]。”。响应指示最有可能替换 [MASK] 的值。在这种情况下，最可能的标记是 paris。

Properties of fill_mask inference
num_top_classes
(可选, 整数) 返回替换掩码标记的顶级预测标记数量。默认为0。
results_field
(可选, 字符串) 添加到传入文档中的字段，用于包含推理预测。默认为predicted_value。
tokenization

(可选, 对象) 指示要执行的分词以及所需的设置。 默认的分词配置是 bert。有效的分词值包括

  • bert: 用于 BERT 风格模型
  • deberta_v2: 用于 DeBERTa v2 和 v3 风格模型
  • mpnet: 用于 MPNet 风格模型
  • roberta: 用于 RoBERTa 风格和 BART 风格模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 xlm_roberta: 用于 XLMRoBERTa 风格模型
  • [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 bert_ja: 用于为日语训练的 BERT 风格模型
Properties of tokenization
bert

(可选, 对象) BERT 风格的标记化将使用包含的设置进行。

Properties of bert
truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

deberta_v2

(可选, 对象) DeBERTa 风格的标记化将使用包含的设置进行。

Properties of deberta_v2
truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • balanced: 第一个和第二个序列可能会被截断，以平衡两个序列中包含的标记数量。
  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。
roberta

(可选, 对象) 将使用封闭的设置执行 RoBERTa 风格的标记化。

Properties of roberta
truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

mpnet

(可选, 对象) MPNet 风格的标记化将使用包含的设置进行。

Properties of mpnet
truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

xlm_roberta

(可选, 对象) [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 将使用包含的设置执行 XLMRoBERTa 风格的标记化。

Properties of xlm_roberta
truncate

(可选，字符串) 指示当标记超过 max_sequence_length 时如何截断它们。 默认值是 first。

  • none: 不进行截断；推理请求将收到错误。
  • first: 仅截断第一个序列。
  • second: 仅截断第二个序列。如果只有一个序列，则截断该序列。

对于zero_shot_classification，假设序列始终是第二个序列。因此，在这种情况下不要使用second。

bert_ja

(可选, 对象) <span class="Admonishment Admonishment--preview

示例

edit

响应取决于模型的类型。

例如，对于语言识别，响应是预测的语言和分数：

POST _ml/trained_models/lang_ident_model_1/_infer
{
  "docs":[{"text": "The fool doth think he is wise, but the wise man knows himself to be a fool."}]
}

以下是预测英语概率较高的结果。

{
  "inference_results": [
    {
      "predicted_value": "en",
      "prediction_probability": 0.9999658805366392,
      "prediction_score": 0.9999658805366392
    }
  ]
}

当它是文本分类模型时，响应是分数和预测的分类。

例如：

POST _ml/trained_models/model2/_infer
{
	"docs": [{"text_field": "The movie was awesome!!"}]
}

API返回预测的标签和置信度。

{
  "inference_results": [{
    "predicted_value" : "POSITIVE",
    "prediction_probability" : 0.9998667964092964
  }]
}

对于命名实体识别（NER）模型，响应包含带注释的文本输出和识别出的实体。

POST _ml/trained_models/model2/_infer
{
	"docs": [{"text_field": "Hi my name is Josh and I live in Berlin"}]
}

在这种情况下，API返回：

{
  "inference_results": [{
    "predicted_value" : "Hi my name is [Josh](PER&Josh) and I live in [Berlin](LOC&Berlin)",
    "entities" : [
      {
        "entity" : "Josh",
        "class_name" : "PER",
        "class_probability" : 0.9977303419824,
        "start_pos" : 14,
        "end_pos" : 18
      },
      {
        "entity" : "Berlin",
        "class_name" : "LOC",
        "class_probability" : 0.9992474323902818,
        "start_pos" : 33,
        "end_pos" : 39
      }
    ]
  }]
}

零样本分类模型需要额外的配置来定义类别标签。这些标签在零样本推理配置中传递。

POST _ml/trained_models/model2/_infer
{
  "docs": [
    {
      "text_field": "This is a very happy person"
    }
  ],
  "inference_config": {
    "zero_shot_classification": {
      "labels": [
        "glad",
        "sad",
        "bad",
        "rad"
      ],
      "multi_label": false
    }
  }
}

API返回预测的标签和置信度，以及最相关的类别：

{
  "inference_results": [{
    "predicted_value" : "glad",
    "top_classes" : [
      {
        "class_name" : "glad",
        "class_probability" : 0.8061155063386439,
        "class_score" : 0.8061155063386439
      },
      {
        "class_name" : "rad",
        "class_probability" : 0.18218006158387956,
        "class_score" : 0.18218006158387956
      },
      {
        "class_name" : "bad",
        "class_probability" : 0.006325615787634201,
        "class_score" : 0.006325615787634201
      },
      {
        "class_name" : "sad",
        "class_probability" : 0.0053788162898424545,
        "class_score" : 0.0053788162898424545
      }
    ],
    "prediction_probability" : 0.8061155063386439
  }]
}

问答模型需要额外的配置来定义要回答的问题。

POST _ml/trained_models/model2/_infer
{
  "docs": [
    {
      "text_field": "<long text to extract answer>"
    }
  ],
  "inference_config": {
    "question_answering": {
      "question": "<question to be answered>"
    }
  }
}

API返回类似于以下内容的响应：

{
    "predicted_value": <string subsection of the text that is the answer>,
    "start_offset": <character offset in document to start>,
    "end_offset": <character offset end of the answer,
    "prediction_probability": <prediction score>
}

文本相似度模型至少需要两个文本序列进行比较。可以提供多个文本字符串与另一个文本序列进行比较：

POST _ml/trained_models/cross-encoder__ms-marco-tinybert-l-2-v2/_infer
{
  "docs":[{ "text_field": "Berlin has a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers."}, {"text_field": "New York City is famous for the Metropolitan Museum of Art."}],
  "inference_config": {
    "text_similarity": {
      "text": "How many people live in Berlin?"
    }
  }
}

响应包含与text_similarity.text字段中提供的文本进行比较的每个字符串的预测：

{
  "inference_results": [
    {
      "predicted_value": 7.235751628875732
    },
    {
      "predicted_value": -11.562295913696289
    }
  ]
}

在调用API时，可以覆盖分词截断选项：

POST _ml/trained_models/model2/_infer
{
  "docs": [{"text_field": "The Amazon rainforest covers most of the Amazon basin in South America"}],
  "inference_config": {
    "ner": {
      "tokenization": {
        "bert": {
          "truncate": "first"
        }
      }
    }
  }
}

当输入因模型的max_sequence_length限制而被截断时，响应中会出现is_truncated字段。

{
  "inference_results": [{
    "predicted_value" : "The [Amazon](LOC&Amazon) rainforest covers most of the [Amazon](LOC&Amazon) basin in [South America](LOC&South+America)",
    "entities" : [
      {
        "entity" : "Amazon",
        "class_name" : "LOC",
        "class_probability" : 0.9505460915724254,
        "start_pos" : 4,
        "end_pos" : 10
      },
      {
        "entity" : "Amazon",
        "class_name" : "LOC",
        "class_probability" : 0.9969992804311777,
        "start_pos" : 41,
        "end_pos" : 47
      }
    ],
    "is_truncated" : true
  }]
}

启动训练模型部署 API

edit

开始一个新的训练模型部署。

请求

edit

POST _ml/trained_models//deployment/_start

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

目前仅支持部署pytorch模型。部署后，该模型可以被摄取管道中的推理处理器使用，或者直接在推断训练模型 API 中使用。

可以通过使用部署ID多次部署模型。部署ID必须是唯一的，并且不应与其他部署ID或模型ID匹配，除非它与正在部署的模型的ID相同。如果未设置deployment_id，则默认为model_id。

您可以启用自适应分配，以根据流程的实际资源需求自动扩展和缩减模型分配。

手动调整推理性能可以通过设置参数number_of_allocations和threads_per_allocation来实现。

增加 threads_per_allocation 意味着在节点上处理推理请求时使用更多的线程。这可以提高某些模型的推理速度。它还可能导致吞吐量的提升。

增加 number_of_allocations 意味着使用更多的线程来并行处理多个推理请求，从而提高吞吐量。每个模型分配使用由 threads_per_allocation 定义的多个线程。

模型分配分布在机器学习节点上。分配给一个节点的所有分配共享内存中的相同模型副本。为了避免对性能有害的线程过度订阅，模型分配以这样的方式分布，即使用的线程总数不会超过节点分配的处理器数量。

路径参数

edit
<model_id>
(必需，字符串) 训练模型的唯一标识符。

查询参数

edit
deployment_id

(可选, 字符串) 用于部署模型的唯一标识符。

默认为 model_id。

timeout
(可选, 时间) 控制等待模型部署的时间量。默认为30秒。
wait_for
(可选，字符串) 指定在返回之前等待的分配状态。默认为 started。值 starting 表示部署正在启动但尚未在任何节点上。值 started 表示模型已在至少一个节点上启动。值 fully_allocated 表示部署已在所有有效节点上启动。

请求体

edit
adaptive_allocations

(可选, 对象) 自适应分配配置对象。 如果启用，模型的分配数量将根据当前进程的负载进行设置。 当负载较高时，会自动创建新的模型分配（如果设置了max_number_of_allocations，则需遵守其值）。 当负载较低时，会自动移除模型分配（如果设置了min_number_of_allocations，则需遵守其值）。 如果启用了adaptive_allocations，请勿手动设置分配数量。

enabled
(可选, 布尔值) 如果true，则adaptive_allocations已启用。 默认为false。
max_number_of_allocations
(可选, 整数) 指定要扩展到的最大分配数量。 如果设置，则必须大于或等于min_number_of_allocations。
min_number_of_allocations
(可选, 整数) 指定要扩展到的最小分配数量。 如果设置，则必须大于或等于1。
cache_size
(可选, 字节值) 每个节点上模型的推理缓存大小（在JVM堆外内存中）。在无服务器环境中，缓存默认是禁用的。否则，默认值是模型的大小，由获取训练模型统计信息API中的model_size_bytes字段报告。要禁用缓存，可以提供0b。
number_of_allocations
(可选，整数) 该模型在机器学习节点上分配的总数。 增加此值通常会增加吞吐量。默认为 1。 如果启用了 adaptive_allocations，请不要设置此值，因为它会自动设置。
priority

(可选，字符串) 部署的优先级。默认值是 normal。 有两种优先级设置：

  • normal: 用于生产环境中的部署。部署的分配会分布开来，以确保节点处理器不会过载。
  • low: 用于测试模型功能。目的是这些部署不会接收到大量的输入。部署需要有一个仅包含一个线程的单一分配。低优先级部署可能会分配在已经使用所有处理器的节点上，但会比普通部署获得更低的CPU优先级。低优先级部署可能会被取消，以满足普通优先级部署的更多分配。

大量使用低优先级部署可能会影响正常优先级部署的性能。

queue_capacity
(可选, 整数) 控制队列中允许的推理请求数量。 集群中可以分配模型的每个机器学习节点都有一个此大小的队列；当请求数量超过总值时， 新请求将被拒绝并返回429错误。默认值为1024。允许的最大值为1000000。
threads_per_allocation
(可选, 整数) 设置推理期间每个模型分配使用的线程数。这通常会提高每个推理请求的速度。推理过程是一个计算密集型过程；threads_per_allocations 不得超过每个节点可用的分配处理器数量。默认为 1。必须是 2 的幂。最大允许值为 32。

示例

edit

以下示例为经过训练的 elastic__distilbert-base-uncased-finetuned-conll03-english 模型启动一个新的部署：

POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_start?wait_for=started&timeout=1m

API返回以下结果：

{
    "assignment": {
        "task_parameters": {
            "model_id": "elastic__distilbert-base-uncased-finetuned-conll03-english",
            "model_bytes": 265632637,
            "threads_per_allocation" : 1,
            "number_of_allocations" : 1,
            "queue_capacity" : 1024,
            "priority": "normal"
        },
        "routing_table": {
            "uckeG3R8TLe2MMNBQ6AGrw": {
                "routing_state": "started",
                "reason": ""
            }
        },
        "assignment_state": "started",
        "start_time": "2022-11-02T11:50:34.766591Z"
    }
}

使用部署ID

edit

以下示例为ID为my_model_for_ingest的训练模型my_model启动了一个新的部署。部署ID可以在推理API调用或推理处理器中使用。

POST _ml/trained_models/my_model/deployment/_start?deployment_id=my_model_for_ingest

训练好的 my_model 模型可以使用不同的ID重新部署：

POST _ml/trained_models/my_model/deployment/_start?deployment_id=my_model_for_search

设置自适应分配

edit

以下示例启动了一个新的 my_model 训练模型的部署，该模型的ID为 my_model_for_search，并启用了自适应分配，最小分配数为3，最大分配数为10。

POST _ml/trained_models/my_model/deployment/_start?deployment_id=my_model_for_search
{
  "adaptive_allocations": {
    "enabled": true,
    "min_number_of_allocations": 3,
    "max_number_of_allocations": 10
  }
}

停止训练模型部署 API

edit

停止已训练模型的部署。

请求

edit

POST _ml/trained_models//deployment/_stop

先决条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

仅针对具有 PyTorch model_type 的训练模型才需要部署。

路径参数

edit
<deployment_id>
(必需, 字符串) 模型的部署的唯一标识符。

查询参数

edit
allow_no_match

(可选, 布尔值) 指定在请求时执行的操作：

  • 包含通配符表达式且没有匹配的部署。
  • 包含 _all 字符串或没有标识符且没有匹配项。
  • 包含通配符表达式且只有部分匹配。

默认值为 true，在没有匹配项时返回一个空数组，在有部分匹配项时返回部分结果。如果此参数为 false，在没有匹配项或只有部分匹配项时，请求将返回 404 状态码。

force
(可选，布尔值) 如果为 true，即使部署或其模型别名被摄取管道引用，部署也会停止。在重新启动模型部署之前，您无法使用这些管道。
finish_pending_work
(可选，布尔值) 如果为 true，部署在任何排队的工作完成后停止。默认为 false。

示例

edit

以下示例停止了 my_model_for_search 部署：

POST _ml/trained_models/my_model_for_search/deployment/_stop

更新训练模型部署 API

edit

更新已训练模型部署的某些属性。

请求

edit

POST _ml/trained_models//deployment/_update

前提条件

edit

需要 manage_ml 集群权限。此权限包含在 machine_learning_admin 内置角色中。

描述

edit

您可以更新一个assignment_state为started的已训练模型部署。 您可以启用自适应分配来自动根据流程的实际资源需求上下调整模型分配。 或者，您可以手动增加或减少模型部署的分配数量。

路径参数

edit
<deployment_id>
(必需, 字符串) 模型的部署的唯一标识符。

请求体

edit
adaptive_allocations

(可选, 对象) 自适应分配配置对象。 如果启用，模型的分配数量将根据当前进程的负载进行设置。 当负载较高时，会自动创建新的模型分配（如果设置了max_number_of_allocations，则需遵守其值）。 当负载较低时，会自动移除模型分配（如果设置了min_number_of_allocations，则需遵守其值）。 如果启用了adaptive_allocations，请勿手动设置分配数量。

enabled
(可选, 布尔值) 如果true，则adaptive_allocations已启用。 默认为false。
max_number_of_allocations
(可选, 整数) 指定要扩展到的最大分配数量。 如果设置，则必须大于或等于min_number_of_allocations。
min_number_of_allocations
(可选, 整数) 指定要扩展到的最小分配数量。 如果设置，则必须大于或等于1。
number_of_allocations
(可选，整数) 该模型在机器学习节点上分配的总数。 增加此值通常会增加吞吐量。 如果启用了adaptive_allocations，请不要设置此值，因为它会自动设置。

示例

edit

以下示例更新了为训练模型 elastic__distilbert-base-uncased-finetuned-conll03-english 的部署，使其具有4个分配：

POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_update
{
  "number_of_allocations": 4
}

API返回以下结果：

{
    "assignment": {
        "task_parameters": {
            "model_id": "elastic__distilbert-base-uncased-finetuned-conll03-english",
            "model_bytes": 265632637,
            "threads_per_allocation" : 1,
            "number_of_allocations" : 4,
            "queue_capacity" : 1024
        },
        "routing_table": {
            "uckeG3R8TLe2MMNBQ6AGrw": {
                "current_allocations": 1,
                "target_allocations": 4,
                "routing_state": "started",
                "reason": ""
            }
        },
        "assignment_state": "started",
        "start_time": "2022-11-02T11:50:34.766591Z"
    }
}

以下示例更新了经过训练的模型 elastic__distilbert-base-uncased-finetuned-conll03-english 的部署，以启用自适应分配，最小分配数为3，最大分配数为10：

POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_update
{
  "adaptive_allocations": {
    "enabled": true,
    "min_number_of_allocations": 3,
    "max_number_of_allocations": 10
  }
}
« Machine learning data frame analytics APIs Migration APIs »