« Machine learning anomaly detection APIs Machine learning trained model APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

机器学习数据框分析API

edit

机器学习数据框分析API

edit

您可以使用以下API来执行机器学习数据框分析活动：

创建数据框分析作业 API

edit

实例化一个数据框分析任务。

请求

edit

PUT _ml/data_frame/analytics/

先决条件

edit

需要以下权限：

  • 集群: manage_ml (内置角色 machine_learning_admin 授予此权限)
  • 源索引: read, view_index_metadata
  • 目标索引: read, create_index, manage 和 index

数据框分析作业会记住创建它的用户在创建时所拥有的角色。当你启动作业时，它会使用这些相同的角色进行分析。如果你提供了二次授权头，则使用这些凭证。

描述

edit

此API创建一个数据框分析作业，该作业对源索引执行分析，并将结果存储在目标索引中。

如果目标索引不存在，当您开始作业时，它将自动创建。请参阅启动数据框分析作业。

如果您仅提供回归或分类参数的子集， 超参数优化将会发生。它 会为每个未定义的参数确定一个值。

路径参数

edit
<data_frame_analytics_id>
(必需，字符串) 数据框分析作业的标识符。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

请求体

edit
allow_lazy_start
(可选, 布尔值) 指定当没有足够的机器学习节点容量立即将其分配到节点时，此作业是否可以启动。默认值为false；如果无法立即找到具有运行作业容量的机器学习节点，API将返回错误。然而，这也受集群范围的xpack.ml.max_lazy_ml_nodes设置的影响。请参阅高级机器学习设置。如果此选项设置为true，API不会返回错误，作业将在starting状态下等待，直到有足够的机器学习节点容量可用。
analysis

(必需, 对象) 分析配置, 其中包含执行以下任一分析类型所需的信息: 分类、异常检测或回归。

Properties of analysis
classification

(必需*，对象) 执行 分类 所需的配置信息。

高级参数用于微调分类分析。它们由超参数优化自动设置，以给出最小的验证误差。强烈建议使用默认值，除非您完全理解这些参数的功能。

Properties of classification
alpha
(可选, 双精度) 高级配置选项。机器学习使用损失引导的树生长，这意味着决策树在正则化损失下降最快的地方生长。此参数通过作为树深度的乘数来影响损失计算。较高的alpha值会导致较浅的树和更快的训练时间。默认情况下，此值在超参数优化期间计算。它必须大于或等于零。
class_assignment_objective
(可选, 字符串) 定义在分配类别标签时要优化的目标： maximize_accuracy 或 maximize_minimum_recall。当最大化准确性时，类别标签被选择以最大化正确预测的数量。当最大化最小召回率时，标签被选择以最大化任何类别的最小召回率。默认为 maximize_minimum_recall。
dependent_variable

(必需，字符串)

定义文档中要预测的字段。 此参数通过字段名称提供，并且必须与用于训练的索引中的字段之一匹配。如果此字段在文档中缺失，则该文档将不会用于训练，但会使用训练好的模型为其生成预测。它也被称为连续目标变量。

字段的数据类型必须是数值型（integer、short、long、byte）、 分类型（ip 或 keyword）或布尔型。该字段中不能有超过 100 个不同的值。

downsample_factor
(可选, 双精度) 高级配置选项。控制用于计算损失函数导数的数据的分数。较小的值导致使用较少的数据。如果此值设置为小于 1，通常会提高准确性。然而，太小的值可能导致集成收敛不良，因此需要更多的树。有关收缩的更多信息，请参阅 此维基文章。 默认情况下，此值在超参数优化期间计算。它必须大于零且小于或等于 1。
early_stopping_enabled
(可选, 布尔值) 高级配置选项。 指定如果训练过程没有找到任何性能更好的模型，是否应该结束。如果禁用，训练过程可能会显著延长，并且找到性能更好的模型的机会不大。 默认情况下，早期停止是启用的。
eta
(可选, 双精度) 高级配置选项。应用于权重的收缩。较小的值会导致更大的森林，具有更好的泛化误差。然而，更大的森林会导致更慢的训练。有关收缩的更多信息，请参阅 此维基文章。 默认情况下，此值在超参数优化期间计算。它必须是 0.001 到 1 之间的值。
eta_growth_rate_per_tree
(可选, 双精度) 高级配置选项。指定 eta 在每棵新树添加到森林时增加的速率。例如，速率为 1.05 会使 eta 每增加一棵树增加 5%。默认情况下，此值在超参数优化期间计算。它必须在 0.5 到 2 之间。
feature_bag_fraction
(可选, 双精度) 高级配置选项。定义在为每个候选分割选择随机包时将使用的特征的分数。默认情况下，此值在超参数优化期间计算。
feature_processors

(可选, 列表) 高级配置选项。一组特征预处理器，用于修改一个或多个包含的字段。分析使用生成的一个或多个特征，而不是原始文档字段。然而，这些特征是短暂的；它们不会存储在目标索引中。多个feature_processors条目可以引用相同的文档字段。对于未被自定义处理器处理的或具有分类值的字段，仍会进行自动分类特征编码。仅当您想要覆盖指定字段的自动特征编码时，才使用此属性。请参阅数据框分析特征处理器以了解更多信息。

Properties of feature_processors
frequency_encoding

(对象) 执行频率编码所需的配置信息。

Properties of frequency_encoding
feature_name
(必需, 字符串) 生成的特征名称。
field
(必需, 字符串) 要编码的字段名称。
frequency_map
(必需, 对象) 字段值的频率映射。如果字段值在 frequency_map 中缺失，则生成的值为 0。
multi_encoding

(对象) 执行多重编码所需的配置信息。它允许多个处理器一起更改。这样，一个处理器的输出可以作为另一个处理器的输入。

Properties of multi_encoding
processors
(必需, 数组) 要执行的自定义处理器的顺序数组。必须多于 1 个。
n_gram_encoding

(对象) 执行n-gram编码所需的配置信息。此编码器创建的特征具有以下名称格式： <特征前缀>.<字符串位置>。例如，如果 特征前缀是f，则字符串中第二个unigram的特征名称为 f.11。

Properties of n_gram_encoding
feature_prefix
(可选, 字符串) 特征名称前缀。默认为 ngram__。
field
(必需, 字符串) 要编码的文本字段名称。
length
(可选, 整数) 指定n-gram子字符串的长度。默认为 50。必须大于 0。
n_grams
(必需, 数组) 指定要收集的n-gram。它是一个整数值数组，最小值为 1，最大值为 5。
start
(可选, 整数) 指定n-gram子字符串的零索引起始位置。允许负值用于编码字符串后缀的n-gram。默认为 0。
one_hot_encoding

(对象) 执行独热编码所需的配置信息。

Properties of one_hot_encoding
field
(必需, 字符串) 要编码的字段名称。
hot_map
(必需, 字符串) 将字段值映射到列名称的独热映射。
target_mean_encoding

(对象) 执行目标均值编码所需的配置信息。

Properties of target_mean_encoding
default_value
(必需, 整数) 如果字段值在 target_map 中未找到，则使用默认值。
feature_name
(必需, 字符串) 生成的特征名称。
field
(必需, 字符串) 要编码的字段名称。
target_map
(必需, 对象) 字段值到目标均值的映射。
gamma
(可选, 双精度) 高级配置选项。正则化参数，用于防止在训练数据集上过拟合。乘以与森林中单个树的大小相关的线性惩罚。较高的gamma值会导致训练倾向于较小的树。较小的gamma值会导致较大的单个树和较慢的训练。默认情况下，此值在超参数优化期间计算。它必须是非负值。
lambda
(可选, 双精度) 高级配置选项。正则化参数，用于防止在训练数据集上过拟合。乘以应用于森林中单个树的叶权重的L2正则化项。较高的lambda值会导致训练倾向于较小的叶权重。这种行为使得预测函数更加平滑，但可能会导致无法捕捉特征与因变量之间的相关关系。较小的lambda值会导致较大的单个树和较慢的训练。默认情况下，此值在超参数优化期间计算。它必须是非负值。
max_optimization_rounds_per_hyperparameter
(可选, 整数) 高级配置选项。 一个乘数，负责确定贝叶斯优化过程中超参数优化的最大步骤数。最大步骤数是根据未定义的超参数数量乘以每个超参数的最大优化轮数来确定的。默认情况下，此值在超参数优化期间计算。
max_trees
(可选, 整数) 高级配置选项。定义森林中决策树的最大数量。最大值为 2000。默认情况下，此值在超
analyzed_fields

(可选, 对象) 指定 includes 和/或 excludes 模式以选择哪些字段将包含在分析中。在 excludes 中指定的模式最后应用，因此 excludes 优先。换句话说，如果同一个字段在 includes 和 excludes 中都被指定，那么该字段将不会包含在分析中。

每种分析类型支持的字段如下：

  • 异常检测需要数值或布尔数据进行分析。算法不支持缺失值，因此具有除数值或布尔之外的数据类型的字段将被忽略。包含缺失值、空值或数组的文档中的字段也将被忽略。因此，dest 索引可能包含没有异常分数的文档。
  • 回归支持数值、boolean、text、keyword 和 ip 字段。它也能容忍缺失值。支持的字段将包含在分析中，其他字段将被忽略。包含两个或更多值的数组的文档中的字段也将被忽略。dest 索引中不包含结果字段的文档将不包含在回归分析中。
  • 分类支持数值、boolean、text、keyword 和 ip 字段。它也能容忍缺失值。支持的字段将包含在分析中，其他字段将被忽略。包含两个或更多值的数组的文档中的字段也将被忽略。dest 索引中不包含结果字段的文档将不包含在分类分析中。通过将序数变量值映射到一个数字，可以改进分类分析。例如，在年龄范围的情况下，可以将值建模为 "0-14" = 0, "15-24" = 1, "25-34" = 2，依此类推。

如果未设置analyzed_fields，则只会包含相关字段。例如，异常检测的所有数值字段。有关字段选择的更多信息，请参阅解释数据框分析。

Properties of analyzed_fields
excludes
(可选, 数组) 定义将从分析中排除的字段的字符串数组。您不需要将不支持的数据类型的字段添加到 excludes 中，这些字段会自动从分析中排除。
includes
(可选, 数组) 定义将包含在分析中的字段的字符串数组。
description
(可选, 字符串) 作业的描述。
dest

(必需，对象) 目标配置，包括 index 和可选的 results_field（默认为 ml）。

Properties of dest
index
(必需，字符串) 定义存储数据框分析作业结果的目标索引。
results_field
(可选，字符串) 定义存储分析结果的字段的名称。默认为 ml。
max_num_threads
(可选, 整数) 用于分析的最大线程数。 默认值是 1。使用更多线程可能会减少完成分析所需的时间，但会消耗更多CPU。 请注意，该过程可能会使用额外的线程用于分析本身以外的操作功能。
_meta
(可选, 对象) 高级配置选项。包含关于作业的自定义元数据。例如，它可以包含自定义URL信息。
model_memory_limit
(可选，字符串) 允许用于分析处理的大致最大内存资源。数据框分析作业的默认值是1gb。如果你为xpack.ml.max_model_memory_limit设置指定了一个值，当你尝试创建model_memory_limit值大于该设置值的作业时，会发生错误。更多信息，请参阅机器学习设置。
source

(对象) 分析数据来源的配置。它需要一个index。 可选地，可以指定query、runtime_mappings和_source。

Properties of source
index

(必需，字符串或数组) 要执行分析的索引或索引。它可以是单个索引或索引模式，也可以是索引或模式的数组。

如果您的源索引包含具有相同ID的文档，则只有最后索引的文档会出现在目标索引中。

query
(可选, 对象) Elasticsearch 查询领域特定语言 (DSL)。 此值对应于 Elasticsearch 搜索 POST 体中的查询对象。所有受 Elasticsearch 支持的选项都可以使用，因为此对象是原样传递给 Elasticsearch 的。默认情况下，此属性具有以下值： {"match_all": {}}。
runtime_mappings
(可选, 对象) 定义将成为目标索引映射一部分的运行时字段。
_source

(可选, 对象) 指定 includes 和/或 excludes 模式以选择哪些字段将出现在目标中。被排除的字段不能包含在分析中。

Properties of _source
includes
(数组) 定义将在目标中包含的字段的字符串数组。
excludes
(数组) 定义将从目标中排除的字段的字符串数组。

示例

edit

预处理操作示例

edit

以下示例展示了如何将分析范围限制在某些字段，在目标索引中指定排除的字段，并在分析前使用查询过滤数据。

PUT _ml/data_frame/analytics/model-flight-delays-pre
{
  "source": {
    "index": [
      "kibana_sample_data_flights" 
    ],
    "query": { 
      "range": {
        "DistanceKilometers": {
          "gt": 0
        }
      }
    },
    "_source": { 
      "includes": [],
      "excludes": [
        "FlightDelay",
        "FlightDelayType"
      ]
    }
  },
  "dest": { 
    "index": "df-flight-delays",
    "results_field": "ml-results"
  },
  "analysis": {
  "regression": {
    "dependent_variable": "FlightDelayMin",
    "training_percent": 90
    }
  },
  "analyzed_fields": { 
    "includes": [],
    "excludes": [
      "FlightNum"
    ]
  },
  "model_memory_limit": "100mb"
}

要分析的源索引。

此查询过滤掉不会出现在目标索引中的整个文档。

The _source 对象定义了数据集中将在目标索引中包含或排除的字段。

定义包含分析结果的目标索引以及在 _source 对象中指定的源索引的字段。还定义了 results_field 的名称。

指定要包含在分析中或从分析中排除的字段。这不会影响字段是否存在于目标索引中，只会影响它们是否在分析中使用。

在这个例子中，我们可以看到源索引的所有字段都包含在目标索引中，除了FlightDelay和FlightDelayType，因为这些字段被_source对象的excludes参数定义为排除字段。FlightNum字段包含在目标索引中，但由于analyzed_fields对象的excludes参数明确指定为排除字段，因此它不包含在分析中。

异常检测示例

edit

以下示例创建了 loganalytics 数据帧分析作业，分析类型为 outlier_detection：

PUT _ml/data_frame/analytics/loganalytics
{
  "description": "Outlier detection on log data",
  "source": {
    "index": "logdata"
  },
  "dest": {
    "index": "logdata_out"
  },
  "analysis": {
    "outlier_detection": {
      "compute_feature_influence": true,
      "outlier_fraction": 0.05,
      "standardization_enabled": true
    }
  }
}

API返回以下结果：

{
  "id" : "loganalytics",
  "create_time" : 1656364565517,
  "version" : "8.4.0",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "description" : "Outlier detection on log data",
  "source" : {
    "index" : [
      "logdata"
    ],
    "query" : {
      "match_all" : { }
    }
  },
  "dest" : {
    "index" : "logdata_out",
    "results_field" : "ml"
  },
  "analysis" : {
    "outlier_detection" : {
      "compute_feature_influence" : true,
      "outlier_fraction" : 0.05,
      "standardization_enabled" : true
    }
  },
  "model_memory_limit" : "1gb",
  "allow_lazy_start" : false,
  "max_num_threads" : 1
}

回归示例

edit

以下示例创建了 house_price_regression_analysis 数据框分析作业，分析类型为 regression：

PUT _ml/data_frame/analytics/house_price_regression_analysis
{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "dest": {
    "index": "house_price_predictions"
  },
  "analysis":
    {
      "regression": {
        "dependent_variable": "price"
      }
    }
}

API返回以下结果：

{
  "id" : "house_price_regression_analysis",
  "create_time" : 1656364845151,
  "version" : "8.4.0",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "source" : {
    "index" : [
      "houses_sold_last_10_yrs"
    ],
    "query" : {
      "match_all" : { }
    }
  },
  "dest" : {
    "index" : "house_price_predictions",
    "results_field" : "ml"
  },
  "analysis" : {
    "regression" : {
      "dependent_variable" : "price",
      "prediction_field_name" : "price_prediction",
      "training_percent" : 100.0,
      "randomize_seed" : -3578554885299300212,
      "loss_function" : "mse",
      "early_stopping_enabled" : true
    }
  },
  "model_memory_limit" : "1gb",
  "allow_lazy_start" : false,
  "max_num_threads" : 1
}

以下示例创建一个作业并指定训练百分比：

PUT _ml/data_frame/analytics/student_performance_mathematics_0.3
{
 "source": {
   "index": "student_performance_mathematics"
 },
 "dest": {
   "index":"student_performance_mathematics_reg"
 },
 "analysis":
   {
     "regression": {
       "dependent_variable": "G3",
       "training_percent": 70,  
       "randomize_seed": 19673948271  
     }
   }
}

用于训练模型的数据集的百分比。

用于随机选择用于训练的数据的种子。

以下示例使用自定义特征处理器将DestWeather的分类值转换为数值，使用独热编码、目标均值编码和频率编码技术：

PUT _ml/data_frame/analytics/flight_prices
{
  "source": {
    "index": [
      "kibana_sample_data_flights"
    ]
  },
  "dest": {
    "index": "kibana_sample_flight_prices"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "AvgTicketPrice",
      "num_top_feature_importance_values": 2,
      "feature_processors": [
        {
          "frequency_encoding": {
            "field": "DestWeather",
            "feature_name": "DestWeather_frequency",
            "frequency_map": {
              "Rain": 0.14604811155570188,
              "Heavy Fog": 0.14604811155570188,
              "Thunder & Lightning": 0.14604811155570188,
              "Cloudy": 0.14604811155570188,
              "Damaging Wind": 0.14604811155570188,
              "Hail": 0.14604811155570188,
              "Sunny": 0.14604811155570188,
              "Clear": 0.14604811155570188
            }
          }
        },
        {
          "target_mean_encoding": {
            "field": "DestWeather",
            "feature_name": "DestWeather_targetmean",
            "target_map": {
              "Rain": 626.5588814585794,
              "Heavy Fog": 626.5588814585794,
              "Thunder & Lightning": 626.5588814585794,
              "Hail": 626.5588814585794,
              "Damaging Wind": 626.5588814585794,
              "Cloudy": 626.5588814585794,
              "Clear": 626.5588814585794,
              "Sunny": 626.5588814585794
            },
            "default_value": 624.0249512020454
          }
        },
        {
          "one_hot_encoding": {
            "field": "DestWeather",
            "hot_map": {
              "Rain": "DestWeather_Rain",
              "Heavy Fog": "DestWeather_Heavy Fog",
              "Thunder & Lightning": "DestWeather_Thunder & Lightning",
              "Cloudy": "DestWeather_Cloudy",
              "Damaging Wind": "DestWeather_Damaging Wind",
              "Hail": "DestWeather_Hail",
              "Clear": "DestWeather_Clear",
              "Sunny": "DestWeather_Sunny"
            }
          }
        }
      ]
    }
  },
  "analyzed_fields": {
    "includes": [
      "AvgTicketPrice",
      "Cancelled",
      "DestWeather",
      "FlightDelayMin",
      "DistanceMiles"
    ]
  },
  "model_memory_limit": "30mb"
}

这些自定义特征处理器是可选的；对于所有分类特征，仍然会发生自动 特征编码。

分类示例

edit

以下示例创建了 loan_classification 数据帧分析作业，分析类型为 classification：

PUT _ml/data_frame/analytics/loan_classification
{
  "source" : {
    "index": "loan-applicants"
  },
  "dest" : {
    "index": "loan-applicants-classified"
  },
  "analysis" : {
    "classification": {
      "dependent_variable": "label",
      "training_percent": 75,
      "num_top_classes": 2
    }
  }
}

删除数据框分析作业 API

edit

删除一个现有的数据帧分析任务。

请求

edit

DELETE _ml/data_frame/analytics/

前提条件

edit

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

路径参数

edit
<data_frame_analytics_id>
(必需, 字符串) 数据框分析任务的标识符。

查询参数

edit
force
(可选，布尔值) 如果为 true，则删除一个未停止的作业；此方法比先停止再删除作业更快。
timeout
(可选，时间单位) 等待作业被删除的时间。 默认为1分钟。

示例

edit

以下示例删除了 loganalytics 数据框架分析作业：

DELETE _ml/data_frame/analytics/loganalytics

API返回以下结果：

{
  "acknowledged" : true
}

评估数据框分析 API

edit

评估用于带注释索引的数据框分析。

请求

edit

POST _ml/data_frame/_evaluate

先决条件

edit

需要以下权限：

  • 集群: monitor_ml (内置角色 machine_learning_user 授予此权限)
  • 目标索引: read

描述

edit

API将各种类型的机器学习特征常用的评估指标打包在一起。这是为在数据框分析创建的索引上使用而设计的。评估需要同时存在一个真实值字段和一个分析结果字段。

请求体

edit
evaluation

(必需，对象) 定义您想要执行的评估类型。 请参阅 数据框分析评估资源。

可用的评估类型：

  • outlier_detection
  • regression
  • classification
index
(必需的, 对象) 定义将在其中执行评估的 索引。
query
(可选，对象) 从源索引中检索数据子集的查询子句。请参阅 查询DSL。

数据框分析评估资源

edit

异常检测评估对象

edit

异常检测评估异常检测分析的结果，输出每个文档是异常的概率。

actual_field
(必需，字符串) index 中包含 ground truth 的字段。 该字段的数据类型可以是布尔型或整型。如果数据类型是 整型，则值必须为 0 (假) 或 1 (真)。
predicted_probability_field
(必需，字符串) index 中定义项目是否属于所讨论类别的概率的字段。它是包含分析结果的字段。
metrics

(可选，对象) 指定用于评估的指标。如果没有指定指标，默认返回以下内容：

  • auc_roc (include_curve: false),
  • precision (at: [0.25, 0.5, 0.75]),
  • recall (at: [0.25, 0.5, 0.75]),

  • confusion_matrix (at: [0.25, 0.5, 0.75])。

    auc_roc
    (可选，对象) AUC ROC (接收者操作特征曲线下面积) 分数，并可选择包含曲线。默认值为 {"include_curve": false}。
    confusion_matrix
    (可选，对象) 设置异常分数的不同阈值，在这些阈值处计算指标 (tp - 真阳性, fp - 假阳性, tn - 真阴性, fn - 假阴性)。默认值为 {"at": [0.25, 0.50, 0.75]}。
    precision
    (可选，对象) 设置异常分数的不同阈值，在这些阈值处计算指标。默认值为 {"at": [0.25, 0.50, 0.75]}。
    recall
    (可选，对象) 设置异常分数的不同阈值，在这些阈值处计算指标。默认值为 {"at": [0.25, 0.50, 0.75]}。

回归评估对象

edit

回归评估用于评估回归分析的结果，该分析输出值的预测。

actual_field
(必需，字符串) index 中包含 ground truth 的字段。 此字段的数据类型必须是数值型。
predicted_field
(必需，字符串) index 中包含预测值的字段，即回归分析的结果。
metrics

(可选，对象) 指定用于评估的指标。有关 mse、msle 和 huber 的更多信息，请参阅 回归损失函数的 Jupyter 笔记本。 如果未指定指标，默认情况下将返回以下内容：

  • mse,
  • r_squared,

  • huber (delta: 1.0).

    mse
    (可选, 对象) 预测值与实际值 (ground truth) 之间的平均平方差。欲了解更多信息，请阅读 这篇维基百科文章。
    msle

    (可选, 对象) 预测值的对数与实际值 (ground truth) 的对数之间的平均平方差。

    offset
    (可选, 双精度) 定义从最小化二次误差切换到最小化二次对数误差的过渡点。默认为 1。
    huber

    （可选，对象）伪Huber损失函数。欲了解更多信息，请阅读 这篇维基百科文章。

    delta
    (可选, 双精度) 对于远小于 delta 的值，近似于 1/2 (预测值 - 实际值)2，对于远大于 delta 的值，近似于斜率为 delta 的直线。默认为 1。Delta 需要大于 0。
    r_squared
    (可选, 对象) 因变量中可由自变量预测的方差比例。欲了解更多信息，请阅读 这篇维基百科文章。

分类评估对象

edit

分类评估评估分类分析的结果，该分析输出一个预测，用于识别每个文档属于哪个类别。

actual_field
(必需，字符串) index 中包含 ground truth 的字段。 此字段的数据类型必须是分类类型。
predicted_field
(可选，字符串) index 中包含预测值的字段， 换句话说，即分类分析的结果。
top_classes_field
(可选, 字符串) index 字段，它是一个文档数组，格式为 { "class_name": XXX, "class_probability": YYY }。 此字段必须在映射中定义为 nested。
metrics

(可选, 对象) 指定用于评估的指标。如果没有指定指标，默认返回以下内容：

  • accuracy,
  • multiclass_confusion_matrix,
  • precision,

  • 召回率.

    accuracy
    (可选, 对象) 预测的准确性（每个类别和总体）。
    auc_roc

    (可选, 对象) AUC ROC（接收者操作特征曲线下面积）分数和可选的曲线。 它是为特定类别（作为 "class_name" 提供）视为正类计算的。

    class_name
    (必需, 字符串) 在AUC ROC计算期间唯一被视为正类的类名。其他类被视为负类（“一对一”策略）。所有被评估的文档必须在它们的顶级类列表中包含class_name。
    include_curve
    (可选, 布尔值) 是否除了分数外还应返回曲线。默认值为false。
    multiclass_confusion_matrix

    （可选，对象）多类混淆矩阵。

    size
    (可选, 双精度) 指定多类混淆矩阵的大小。默认为10，结果是一个10x10的矩阵。
    precision
    (可选, 对象) 预测的精确度（每个类别和平均值）。
    recall
    (可选, 对象) 预测的召回率（每个类别和平均值）。

示例

edit

异常检测

edit
POST _ml/data_frame/_evaluate
{
  "index": "my_analytics_dest_index",
  "evaluation": {
    "outlier_detection": {
      "actual_field": "is_outlier",
      "predicted_probability_field": "ml.outlier_score"
    }
  }
}

API返回以下结果：

{
  "outlier_detection": {
    "auc_roc": {
      "value": 0.92584757746414444
    },
    "confusion_matrix": {
      "0.25": {
          "tp": 5,
          "fp": 9,
          "tn": 204,
          "fn": 5
      },
      "0.5": {
          "tp": 1,
          "fp": 5,
          "tn": 208,
          "fn": 9
      },
      "0.75": {
          "tp": 0,
          "fp": 4,
          "tn": 209,
          "fn": 10
      }
    },
    "precision": {
        "0.25": 0.35714285714285715,
        "0.5": 0.16666666666666666,
        "0.75": 0
    },
    "recall": {
        "0.25": 0.5,
        "0.5": 0.1,
        "0.75": 0
    }
  }
}

回归

edit
POST _ml/data_frame/_evaluate
{
  "index": "house_price_predictions", 
  "query": {
      "bool": {
        "filter": [
          { "term":  { "ml.is_training": false } } 
        ]
      }
  },
  "evaluation": {
    "regression": {
      "actual_field": "price", 
      "predicted_field": "ml.price_prediction", 
      "metrics": {
        "r_squared": {},
        "mse": {},
        "msle": {"offset": 10},
        "huber": {"delta": 1.5}
      }
    }
  }
}

数据框分析回归分析的输出目标索引。

在这个例子中，为回归分析定义了一个测试/训练分割（training_percent）。此查询限制评估仅在测试分割上执行。

实际房价的真实值。这是为了评估结果所必需的。

通过回归分析计算出的房价预测值。

以下示例计算训练误差：

POST _ml/data_frame/_evaluate
{
  "index": "student_performance_mathematics_reg",
  "query": {
    "term": {
      "ml.is_training": {
        "value": true 
      }
    }
  },
  "evaluation": {
    "regression": {
      "actual_field": "G3", 
      "predicted_field": "ml.G3_prediction", 
      "metrics": {
        "r_squared": {},
        "mse": {},
        "msle": {},
        "huber": {}
      }
    }
  }
}

在这个例子中，为回归分析定义了一个测试/训练分割（training_percent）。此查询限制了仅在训练分割上执行评估。这意味着将计算训练误差。

包含实际学生表现的真实值的字段。这是为了评估结果所必需的。

包含通过回归分析计算出的学生表现预测值的字段。

下一个示例计算测试误差。与前一个示例相比，唯一的区别是这次将ml.is_training设置为false，因此查询排除了训练集部分。

POST _ml/data_frame/_evaluate
{
  "index": "student_performance_mathematics_reg",
  "query": {
    "term": {
      "ml.is_training": {
        "value": false 
      }
    }
  },
  "evaluation": {
    "regression": {
      "actual_field": "G3", 
      "predicted_field": "ml.G3_prediction", 
      "metrics": {
        "r_squared": {},
        "mse": {},
        "msle": {},
        "huber": {}
      }
    }
  }
}

在这个例子中，为回归分析定义了一个测试/训练分割（training_percent）。此查询限制了仅在测试分割上执行评估。这意味着将计算测试误差。

包含实际学生表现的真实值的字段。这是为了评估结果所必需的。

包含通过回归分析计算的学生表现预测值的字段。

分类

edit
POST _ml/data_frame/_evaluate
{
   "index": "animal_classification",
   "evaluation": {
      "classification": { 
         "actual_field": "animal_class", 
         "predicted_field": "ml.animal_class_prediction", 
         "metrics": {
           "multiclass_confusion_matrix" : {} 
         }
      }
   }
}

评估类型。

包含实际动物分类的真实值的字段。这是为了评估结果所必需的。

该字段包含分类分析预测的动物分类值。

指定评估的指标。

API返回以下结果：

{
   "classification" : {
      "multiclass_confusion_matrix" : {
         "confusion_matrix" : [
         {
            "actual_class" : "cat", 
            "actual_class_doc_count" : 12, 
            "predicted_classes" : [ 
              {
                "predicted_class" : "cat",
                "count" : 12 
              },
              {
                "predicted_class" : "dog",
                "count" : 0 
              }
            ],
            "other_predicted_class_doc_count" : 0 
          },
          {
            "actual_class" : "dog",
            "actual_class_doc_count" : 11,
            "predicted_classes" : [
              {
                "predicted_class" : "dog",
                "count" : 7
              },
              {
                "predicted_class" : "cat",
                "count" : 4
              }
            ],
            "other_predicted_class_doc_count" : 0
          }
        ],
        "other_actual_class_count" : 0
      }
    }
  }

分析试图预测的实际类别的名称。

索引中属于actual_class的文档数量。

此对象包含预测类别的列表以及与每个类别相关联的预测数量。

数据集中被正确识别为猫的猫的数量。

数据集中被错误分类为狗的猫的数量。

被分类为未列出的类别的文档数量。

 
POST _ml/data_frame/_evaluate
{
   "index": "animal_classification",
   "evaluation": {
      "classification": { 
         "actual_field": "animal_class", 
         "metrics": {
            "auc_roc" : { 
              "class_name": "dog" 
            }
         }
      }
   }
}

评估类型。

包含实际动物分类的真实值的字段。这是为了评估结果所必需的。

指定评估的指标。

指定在评估过程中被视为正类的类名，所有其他类都被视为负类。

API返回以下结果：

{
  "classification" : {
    "auc_roc" : {
      "value" : 0.8941788639536681
    }
  }
}

解释数据框分析 API

edit

解释数据框分析配置。

请求

edit

GET _ml/data_frame/analytics/_explain

POST _ml/data_frame/analytics/_explain

GET _ml/data_frame/analytics//_explain

POST _ml/data_frame/analytics//_explain

先决条件

edit

需要以下权限：

  • 集群: monitor_ml (内置角色 machine_learning_user 授予此权限)
  • 源索引: read, view_index_metadata

描述

edit

此API为数据框分析配置提供解释，无论该配置已经存在还是尚未创建。提供的解释如下：

  • 分析中包含或不包含哪些字段以及原因，
  • 估计需要多少内存。该估计值可用于在稍后决定model_memory_limit设置的适当值时使用。

如果你有对象字段或通过源过滤排除的字段，它们不会包含在解释中。

路径参数

edit
<data_frame_analytics_id>
(可选, 字符串) 数据框分析任务的标识符。

请求体

edit

如在创建数据框分析作业中所述的数据框分析配置。 请注意，在此 API 的上下文中，不需要提供 id 和 dest。

响应体

edit

API返回的响应包含以下内容：

field_selection

(数组) 一个对象数组，解释每个字段的选择，按字段名称排序。

Properties of field_selection objects
is_included
(布尔值) 该字段是否被选中以包含在分析中。
is_required
(布尔值) 该字段是否为必需。
feature_type
(字符串) 该字段在分析中的特征类型。可能是 categorical 或 numerical。
mapping_types
(字符串) 该字段的映射类型。
name
(字符串) 字段名称。
reason
(字符串) 该字段未被选中以包含在分析中的原因。
memory_estimation

(对象) 一个包含内存估计的对象。

Properties of memory_estimation
expected_memory_with_disk
(字符串) 在假设允许数据溢出到磁盘的情况下，估计的内存使用量。expected_memory_with_disk 通常比 expected_memory_without_disk 小，因为使用磁盘可以限制执行数据框分析所需的主内存。
expected_memory_without_disk
(字符串) 在假设整个数据框分析应在内存中进行的情况下，估计的内存使用量（即不允许溢出到磁盘）。

示例

edit
POST _ml/data_frame/analytics/_explain
{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "price"
    }
  }
}

API返回以下结果：

{
  "field_selection": [
    {
      "field": "number_of_bedrooms",
      "mappings_types": ["integer"],
      "is_included": true,
      "is_required": false,
      "feature_type": "numerical"
    },
    {
      "field": "postcode",
      "mappings_types": ["text"],
      "is_included": false,
      "is_required": false,
      "reason": "[postcode.keyword] is preferred because it is aggregatable"
    },
    {
      "field": "postcode.keyword",
      "mappings_types": ["keyword"],
      "is_included": true,
      "is_required": false,
      "feature_type": "categorical"
    },
    {
      "field": "price",
      "mappings_types": ["float"],
      "is_included": true,
      "is_required": true,
      "feature_type": "numerical"
    }
  ],
  "memory_estimation": {
    "expected_memory_without_disk": "128MB",
    "expected_memory_with_disk": "32MB"
  }
}

获取数据框分析作业 API

edit

检索数据框分析作业的配置信息。

请求

edit

GET _ml/data_frame/analytics/

GET _ml/data_frame/analytics/,

GET _ml/data_frame/analytics/

GET _ml/data_frame/analytics/_all

先决条件

edit

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

描述

edit

您可以通过使用逗号分隔的数据框分析作业列表或通配符表达式，在单个API请求中获取多个数据框分析作业的信息。

路径参数

edit
<data_frame_analytics_id>

(可选, 字符串) 数据框分析作业的标识符。如果您不指定此选项，API将返回前一百个数据框分析作业的信息。

您可以通过使用_all，通过指定*作为，或者通过省略来获取所有数据框分析作业的信息。

查询参数

edit
allow_no_match

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

  • 包含通配符表达式且没有匹配的数据框分析作业。
  • 包含 _all 字符串或没有标识符且没有匹配项。
  • 包含通配符表达式且只有部分匹配项。

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

exclude_generated
(可选，布尔值) 指示是否应在检索时从配置中移除某些字段。这允许配置以可接受的格式被检索，然后添加到另一个集群中。默认值为 false。
from
(可选，整数) 跳过指定数量的数据框分析作业。默认值为 0。
size
(可选，整数) 指定要获取的数据框架分析作业的最大数量。默认值为100。

响应体

edit
data_frame_analytics

(数组) 一个数据框分析作业资源的数组，这些资源按 id 值的升序排序。

数据框分析作业资源的属性
analysis
(对象) 对 source 执行的分析类型。
analyzed_fields

(对象) 包含 includes 和/或 excludes 模式，用于选择哪些字段包含在分析中。

analyzed_fields 的属性
excludes
(可选, 数组) 定义从分析中排除的字段的字符串数组。
includes
(可选, 数组) 定义包含在分析中的字段的字符串数组。
authorization

(对象) 作业用于运行其查询的安全权限。如果在最近一次更新作业时禁用了Elastic Stack安全功能，则省略此属性。

authorization 的属性
api_key

(对象) 如果最近一次更新作业时使用了API密钥，其名称和标识符将列在响应中。

api_key 的属性
id
(字符串) API密钥的标识符。
name
(字符串) API密钥的名称。
roles
(字符串数组) 如果最近一次更新作业时使用了用户ID，其角色将在更新时列在响应中。
service_account
(字符串) 如果最近一次更新作业时使用了服务账户，账户名称将列在响应中。
dest

(字符串) 分析的目标配置。

dest 的属性
index
(字符串) 存储数据框分析作业结果的 目标索引。
results_field
(字符串) 存储分析结果的字段的名称。默认为 ml。
id
(字符串) 数据框分析作业的唯一标识符。
model_memory_limit
(字符串) 为数据框分析作业设置的 model_memory_limit。
source

(对象) 分析数据来源的配置。它有一个 index 参数，并且可以选择性地包含 query 和 _source。

source 的属性
index
(数组) 执行分析的索引或索引。它可以是单个索引或索引模式，也可以是索引或模式的数组。
query
(对象) 为数据框分析作业指定的查询。Elasticsearch查询特定领域语言 (DSL)。此值对应于Elasticsearch搜索POST正文中的查询对象。默认情况下，此属性具有以下值：{"match_all": {}}。
_source

(对象) 包含指定的 includes 和/或 excludes 模式，用于选择哪些字段出现在目标中。被排除的字段不能包含在分析中。

_source 的属性
excludes
(数组) 定义从目标中排除的字段的字符串数组。
includes
(数组) 定义包含在目标中的字段的字符串数组。

响应代码

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

示例

edit

以下示例获取loganalytics数据框分析作业的配置信息：

GET _ml/data_frame/analytics/loganalytics

API返回以下结果：

{
  "count" : 1,
  "data_frame_analytics" : [
    {
      "id" : "loganalytics",
      "create_time" : 1656364565517,
      "version" : "8.4.0",
      "authorization" : {
        "roles" : [
          "superuser"
        ]
      },
      "description" : "Outlier detection on log data",
      "source" : {
        "index" : [
          "logdata"
        ],
        "query" : {
          "match_all" : { }
        }
      },
      "dest" : {
        "index" : "logdata_out",
        "results_field" : "ml"
      },
      "analysis" : {
        "outlier_detection" : {
          "compute_feature_influence" : true,
          "outlier_fraction" : 0.05,
          "standardization_enabled" : true
        }
      },
      "model_memory_limit" : "1gb",
      "allow_lazy_start" : false,
      "max_num_threads" : 1
    }
  ]
}

获取数据框分析作业统计信息 API

edit

检索数据框分析作业的使用信息。

请求

edit

GET _ml/data_frame/analytics//_stats

GET _ml/data_frame/analytics/,/_stats

GET _ml/data_frame/analytics/_stats

GET _ml/data_frame/analytics/_all/_stats

GET _ml/data_frame/analytics/*/_stats

先决条件

edit

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

路径参数

edit
<data_frame_analytics_id>
(可选，字符串) 数据框分析作业的标识符。如果您不指定此选项，API将返回前一百个数据框分析作业的信息。

查询参数

edit
allow_no_match

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

  • 包含通配符表达式且没有匹配的数据框分析作业。
  • 包含 _all 字符串或没有标识符且没有匹配项。
  • 包含通配符表达式且只有部分匹配项。

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

from
(可选，整数) 跳过指定数量的数据框分析作业。默认值为 0。
size
(可选，整数) 指定要获取的数据框架分析作业的最大数量。默认值为100。
verbose
(可选，布尔值) 定义统计响应是否应为详细模式。默认值为 false。

响应体

edit
data_frame_analytics

(数组) 包含数据框分析作业使用信息的对象数组，这些对象按 id 值的升序排序。

数据框分析作业使用资源的属性
analysis_stats

(对象) 包含有关分析作业信息的对象。

analysis_stats 的属性
classification_stats

(对象) 包含有关分类分析作业信息的对象。

classification_stats 的属性
hyperparameters

(对象) 包含分类分析作业参数的对象。

hyperparameters 的属性
alpha
(double) 高级配置选项。机器学习使用损失引导的树生长，这意味着决策树在正则化损失下降最快的地方生长。此参数通过作为树深度的乘数来影响损失计算。较高的 alpha 值会导致较浅的树和更快的训练时间。默认情况下，此值在超参数优化期间计算。它必须大于或等于零。
class_assignment_objective
(string) 定义在分配类别标签时要优化的目标： maximize_accuracy 或 maximize_minimum_recall。当最大化准确性时，类别标签被选择以最大化正确预测的数量。当最大化最小召回率时，标签被选择以最大化任何类别的最小召回率。默认值为 maximize_minimum_recall。
downsample_factor
(double) 高级配置选项。控制用于计算损失函数导数的数据比例，以便进行树训练。较小的值会导致使用较少的数据。如果此值设置为小于 1，通常会提高准确性。然而，太小的值可能会导致集成收敛不良，从而需要更多的树。有关收缩的更多信息，请参阅 此维基文章。 默认情况下，此值在超参数优化期间计算。它必须大于零且小于或等于 1。
eta
(double) 高级配置选项。应用于权重的收缩。较小的值会导致更大的森林，具有更好的泛化误差。然而，更大的森林会导致更慢的训练。有关收缩的更多信息，请参阅 此维基文章。 默认情况下，此值在超参数优化期间计算。它必须是 0.001 到 1 之间的值。
eta_growth_rate_per_tree
(double) 高级配置选项。指定 eta 在每棵新树添加到森林时增加的速率。例如，速率为 1.05 会使 eta 每增加一棵树增加 5%。默认情况下，此值在超参数优化期间计算。它必须在 0.5 到 2 之间。
feature_bag_fraction
(double) 高级配置选项。定义在为每个候选分割选择随机包时将使用的特征比例。默认情况下，此值在超参数优化期间计算。
gamma
(double) 高级配置选项。正则化参数，用于防止在训练数据集上过拟合。乘以与森林中单个树的大小相关的线性惩罚。较高的 gamma 值会导致训练倾向于较小的树。较小的 gamma 值会导致较大的单个树和较慢的训练。默认情况下，此值在超参数优化期间计算。它必须是非负值。
lambda
(double) 高级配置选项。正则化参数，用于防止在训练数据集上过拟合。乘以应用于森林中单个树的叶权重的 L2 正则化项。较高的 lambda 值会导致训练倾向于较小的叶权重。这种行为使预测函数更平滑，但可能会导致无法捕捉特征与因变量之间的相关关系。较小的 lambda 值会导致较大的单个树和较慢的训练。默认情况下，此值在超参数优化期间计算。它必须是非负值。
max_attempts_to_add_tree
(integer) 如果算法无法确定非平凡的树（多于一个叶子），此参数确定可以容忍多少次连续失败。一旦尝试次数超过阈值，森林训练将停止。
max_optimization_rounds_per_hyperparameter
(integer) 高级配置选项。 一个乘数，负责确定贝叶斯优化过程中超参数优化的最大步骤数。 最大步骤数是根据未定义的超参数数量乘以每个超参数的最大优化轮数确定的。 默认情况下，此值在超参数优化期间计算。
max_trees
(integer) 高级配置选项。定义森林中决策树的最大数量。最大值为 2000。默认情况下，此值在超参数优化期间计算。
num_folds
(integer) 交叉验证过程的最大折数。
num_splits_per_feature
(integer) 确定在树训练时每个特征在决策树中可以发生的最大分割数。
soft_tree_depth_limit
(double) 高级配置选项。机器学习使用损失引导的树生长，这意味着决策树在正则化损失下降最快的地方生长。此软限制与 soft_tree_depth_tolerance 结合使用，以惩罚超过指定深度的树；超过此深度的正则化损失迅速增加。默认情况下，此值在超参数优化期间计算。它必须大于或等于 0。
soft_tree_depth_tolerance
(double) 高级配置选项。此选项控制当树深度超过 soft_tree_depth_limit 时，正则化损失增加的速度。默认情况下，此值在超参数优化期间计算。它必须大于或等于 0.01。
iteration
(integer) 分析的迭代次数。
timestamp
(date) 统计信息报告的时间戳，自纪元以来的毫秒数。
timing_stats

(对象) 包含有关数据框分析作业的时间统计信息的对象。

timing_stats 的属性
elapsed_time
(integer) 分析的运行时间，以毫秒为单位。
iteration_time
(integer) 分析的最新迭代的运行时间，以毫秒为单位。
validation_loss

(对象) 一个包含验证损失信息的对象。

validation_loss 的属性
fold_values
验证损失值，用于在森林生长过程中每添加一棵决策树。
loss_type
(string) 损失指标的类型。例如，binomial_logistic。
outlier_detection_stats

(对象) 包含有关异常检测作业信息的对象。

outlier_detection_stats 的属性
parameters

(对象) 用户指定的或由算法启发式确定的作业参数列表。

parameters 的属性
compute_feature_influence
(Boolean) 指定是否启用特征影响计算。默认值为 true。
feature_influence_threshold
(double) 文档需要具有的最小异常分数，以便计算其特征影响分数。值范围：0-1（默认值为 0.1）。
method
(string) 异常检测使用的方法。可用方法有 lof、ldof、distance_kth_nn、distance_knn 和 ensemble。默认值为 ensemble，这意味着异常检测使用不同方法的集成，并将其单独的异常分数归一化和组合，以获得总体异常分数。
n_neighbors
(integer) 定义异常检测的每个方法用于计算其异常分数的最近邻居数量。当未设置此值时，不同的集成成员使用不同的值。这种默认行为有助于提高集成的多样性；只有在您确信所选值适合数据集时才覆盖它。
outlier_fraction
(double) 在异常检测之前，假设数据集中异常的比例。例如，0.05 意味着假设 5% 的值是真实异常值，95% 是正常值。
standardization_enabled
(Boolean) 如果为 true，则在计算异常分数之前对列执行以下操作：(x_i - mean(x_i)) / sd(x_i)。默认值为 true。有关此概念的更多信息，请参阅 维基百科。
timestamp
(date) 统计信息报告的时间戳，自纪元以来的毫秒数。
timing_stats

(对象) 包含有关数据框分析作业的时间统计信息的对象。

timing_stats 的属性
elapsed_time
(integer) 分析的运行时间，以毫秒为单位。
regression_stats

响应代码

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

示例

edit

以下 API 检索用于 异常检测数据框分析作业示例 的使用信息：

GET _ml/data_frame/analytics/weblog-outliers/_stats
{
  "count" : 1,
  "data_frame_analytics" : [
    {
      "id" : "weblog-outliers",
      "state" : "stopped",
      "progress" : [
        {
          "phase" : "reindexing",
          "progress_percent" : 100
        },
        {
          "phase" : "loading_data",
          "progress_percent" : 100
        },
        {
          "phase" : "computing_outliers",
          "progress_percent" : 100
        },
        {
          "phase" : "writing_results",
          "progress_percent" : 100
        }
      ],
      "data_counts" : {
        "training_docs_count" : 1001,
        "test_docs_count" : 0,
        "skipped_docs_count" : 0
      },
      "memory_usage" : {
        "timestamp" : 1626264770206,
        "peak_usage_bytes" : 328011,
        "status" : "ok"
      },
      "analysis_stats" : {
        "outlier_detection_stats" : {
          "timestamp" : 1626264770206,
          "parameters" : {
            "n_neighbors" : 0,
            "method" : "ensemble",
            "compute_feature_influence" : true,
            "feature_influence_threshold" : 0.1,
            "outlier_fraction" : 0.05,
            "standardization_enabled" : true
          },
          "timing_stats" : {
            "elapsed_time" : 32
          }
        }
      }
    }
  ]
}

预览数据框分析API

edit

预览数据框分析配置使用的功能。

请求

edit

GET _ml/data_frame/analytics/_preview

POST _ml/data_frame/analytics/_preview

GET _ml/data_frame/analytics//_preview

POST _ml/data_frame/analytics//_preview

先决条件

edit

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

描述

edit

此API提供了数据框分析配置的提取特征的预览，该配置可能已经存在，也可能尚未创建。

路径参数

edit
<data_frame_analytics_id>
(可选, 字符串) 数据框分析任务的标识符。

请求体

edit
config
(可选，对象) 一个数据框分析配置，如创建数据框分析作业中所述。 请注意，在此 API 的上下文中，不需要提供 id 和 dest。

响应体

edit

API返回的响应包含以下内容：

feature_values
(数组) 包含特征名称和值对的数组。这些特征已经过处理，并指示将发送给模型进行训练的内容。

示例

edit
POST _ml/data_frame/analytics/_preview
{
  "config": {
    "source": {
      "index": "houses_sold_last_10_yrs"
    },
    "analysis": {
      "regression": {
        "dependent_variable": "price"
      }
    }
  }
}

API返回以下结果：

{
  "feature_values": [
    {
      "number_of_bedrooms": "1",
      "postcode": "29655",
      "price": "140.4"
    },
    ...
  ]
}

启动数据框分析作业 API

edit

启动一个数据框分析任务。

请求

edit

POST _ml/data_frame/analytics//_start

先决条件

edit

需要以下权限：

  • 集群: manage_ml (内置角色 machine_learning_admin 授予此权限)
  • 源索引: read, view_index_metadata
  • 目标索引: read, create_index, manage 和 index

描述

edit

数据框分析任务可以在其生命周期内启动和停止多次。

如果目标索引不存在，它会在您首次启动数据框分析作业时自动创建。目标索引的 index.number_of_shards 和 index.number_of_replicas 设置会从源索引复制。如果有多个源索引，目标索引会复制最高设置值。目标索引的映射也会从源索引复制。如果存在任何映射冲突，作业将无法启动。

如果目标索引存在，它将按原样使用。因此，您可以提前使用自定义设置和映射来设置目标索引。

当启用了Elasticsearch安全功能时，数据框分析作业会记住创建它的用户，并使用这些凭据运行作业。如果你在创建作业时提供了二次授权头，则使用这些凭据。

路径参数

edit
<data_frame_analytics_id>
(必需，字符串) 数据框分析作业的标识符。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

查询参数

edit
timeout
(可选，时间单位) 控制数据帧分析作业启动前的等待时间。默认为20秒。

响应体

edit
acknowledged
(布尔值) 对于成功的响应，此值始终为 true。在失败的情况下，将返回异常。
node
(字符串) 作业启动的节点的ID。 如果允许作业延迟打开且尚未分配到节点，则此值为空字符串。

示例

edit

以下示例启动了 loganalytics 数据帧分析作业：

POST _ml/data_frame/analytics/loganalytics/_start

当数据框分析作业启动时，您会收到以下结果：

{
  "acknowledged" : true,
  "node" : "node-1"
}

停止数据框分析作业 API

edit

停止一个或多个数据框分析任务。

请求

edit

POST _ml/data_frame/analytics//_stop

POST _ml/data_frame/analytics/,/_stop

POST _ml/data_frame/analytics/_all/_stop

前提条件

edit

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

描述

edit

数据框分析任务可以在其生命周期内启动和停止多次。

您可以通过使用逗号分隔的数据框分析作业列表或通配符表达式，在单个API请求中停止多个数据框分析作业。您可以使用_all或通过指定*作为来停止所有数据框分析作业。

路径参数

edit
<data_frame_analytics_id>
(必需，字符串) 数据框分析作业的标识符。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

查询参数

edit
allow_no_match

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

  • 包含通配符表达式且没有匹配的数据框分析作业。
  • 包含 _all 字符串或没有标识符且没有匹配项。
  • 包含通配符表达式且只有部分匹配项。

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

force
(可选，布尔值) 如果为 true，则数据框分析作业将被强制停止。
timeout
(可选，时间单位) 控制数据框分析作业停止前的等待时间。默认为20秒。

示例

edit

以下示例停止了 loganalytics 数据帧分析作业：

POST _ml/data_frame/analytics/loganalytics/_stop

当数据框分析任务停止时，您会收到以下结果：

{
  "stopped" : true
}

更新数据框分析作业 API

edit

更新现有的数据框分析任务。

请求

edit

POST _ml/data_frame/analytics//_update

先决条件

edit

需要以下权限：

  • 集群: manage_ml (内置角色 machine_learning_admin 授予此权限)
  • 源索引: read, view_index_metadata
  • 目标索引: read, create_index, manage 和 index

数据框分析作业会记住更新时用户所拥有的角色。当你启动作业时，它会使用相同的角色进行分析。如果你提供了二次授权头，则使用这些凭证。

描述

edit

此API更新一个现有的数据框分析任务，该任务对源索引进行分析并将结果存储在目标索引中。

路径参数

edit
<data_frame_analytics_id>
(必需，字符串) 数据框分析作业的标识符。此标识符可以包含小写字母数字字符（a-z 和 0-9）、连字符和下划线。它必须以字母数字字符开头和结尾。

请求体

edit
allow_lazy_start
(可选, 布尔值) 指定当没有足够的机器学习节点容量立即将其分配到节点时，此作业是否可以启动。默认值为false；如果无法立即找到具有运行作业容量的机器学习节点，API将返回错误。然而，这也受集群范围的xpack.ml.max_lazy_ml_nodes设置的影响。请参阅高级机器学习设置。如果此选项设置为true，API不会返回错误，作业将在starting状态下等待，直到有足够的机器学习节点容量可用。
description
(可选, 字符串) 作业的描述。
max_num_threads
(可选, 整数) 用于分析的最大线程数。 默认值是 1。使用更多线程可能会减少完成分析所需的时间，但会消耗更多CPU。 请注意，该过程可能会使用额外的线程用于分析本身以外的操作功能。
_meta
(可选, 对象) 高级配置选项。包含关于作业的自定义元数据。例如，它可以包含自定义URL信息。
model_memory_limit
(可选，字符串) 允许用于分析处理的大致最大内存资源。数据框分析作业的默认值是1gb。如果你为xpack.ml.max_model_memory_limit设置指定了一个值，当你尝试创建model_memory_limit值大于该设置值的作业时，会发生错误。更多信息，请参阅机器学习设置。

示例

edit

更新模型内存限制示例

edit

以下示例展示了如何更新现有数据框分析配置的模型内存限制。

POST _ml/data_frame/analytics/loganalytics/_update
{
  "model_memory_limit": "200mb"
}

当作业更新时，响应包含其配置以及更新后的值。例如：

{
  "id" : "loganalytics",
  "create_time" : 1656364565517,
  "version" : "8.4.0",
  "authorization" : {
    "roles" : [
      "superuser"
    ]
  },
  "description" : "Outlier detection on log data",
  "source" : {
    "index" : [
      "logdata"
    ],
    "query" : {
      "match_all" : { }
    }
  },
  "dest" : {
    "index" : "logdata_out",
    "results_field" : "ml"
  },
  "analysis" : {
    "outlier_detection" : {
      "compute_feature_influence" : true,
      "outlier_fraction" : 0.05,
      "standardization_enabled" : true
    }
  },
  "model_memory_limit" : "200mb",
  "allow_lazy_start" : false,
  "max_num_threads" : 1
}
« Machine learning anomaly detection APIs Machine learning trained model APIs »