› › ›

更新异常检测作业 API

编辑

更新异常检测作业 API编辑

更新异常检测作业的某些属性。

请求编辑

POST _ml/anomaly_detectors/<job_id>/_update

先决条件编辑

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

路径参数编辑

<job_id>: (必需，字符串) 异常检测作业的标识符。

请求正文编辑

以下属性可以在作业创建后更新

allow_lazy_open

(布尔值) 高级配置选项。指定此作业是否可以在机器学习节点容量不足以立即将其分配给节点的情况下打开。默认值为 false；如果无法立即找到具有运行作业容量的机器学习节点，则打开异常检测作业 API 将返回错误。但是，这也受集群范围的 xpack.ml.max_lazy_ml_nodes 设置的影响；请参阅高级机器学习设置。如果将此选项设置为 true，则打开异常检测作业 API 不会返回错误，并且作业将在 opening 状态下等待，直到有足够的机器学习节点容量可用。

如果在进行更新时作业已打开，则必须停止数据馈送，关闭作业，然后重新打开作业并重新启动数据馈送才能使更改生效。

analysis_limits

(可选，对象) 可以对用于在内存中保存数学模型所需的资源应用限制。这些限制是近似的，可以针对每个作业设置。它们不控制其他进程使用的内存，例如 Elasticsearch Java 进程。

您只能在作业关闭时更新 analysis_limits。

analysis_limits 的属性

model_memory_limit

(长整型或字符串) 用于分析处理的近似最大内存资源量。当接近此限制时，数据修剪将变得更加积极。超过此限制后，将不再对新实体进行建模。在 6.1 及更高版本中创建的作业的默认值为 1024mb。但是，如果 xpack.ml.max_model_memory_limit 设置的值大于 0 且小于 1024mb，则使用该值。如果未设置 xpack.ml.max_model_memory_limit，但设置了 xpack.ml.use_auto_machine_memory_percent，则默认 model_memory_limit 将设置为可以在集群中分配的最大大小，上限为 1024mb。默认值相对较小，以确保高资源使用是经过深思熟虑的决定。如果您有预计要分析高基数字段的作业，则可能需要使用更高的值。

从 Elasticsearch 8.10.0 开始，使用新的版本号来跟踪机器学习插件中的配置和状态更改。此新的版本号与产品版本分离，并将独立递增。

如果您指定数字而不是字符串，则假定单位为 MiB。建议指定字符串以确保清晰度。如果您指定 b 或 kb 的字节大小单位，并且数字不等于离散的兆字节数，则将其向下舍入到最接近的 MiB。最小有效值为 1 MiB。如果您指定的值小于 1 MiB，则会发生错误。有关支持的字节大小单位的更多信息，请参阅字节大小单位。

如果您为 xpack.ml.max_model_memory_limit 设置指定了值，则尝试创建 model_memory_limit 值大于该设置值的作业时会发生错误。有关更多信息，请参阅机器学习设置。

您无法将 model_memory_limit 值降低到当前使用量以下。要确定当前使用量，请参考获取作业统计信息 API 中的 model_bytes 值。
如果 model_size_stats 对象中的 memory_status 属性的值为 hard_limit，则表示它无法处理某些数据。您可能需要使用增加的 model_memory_limit 重新运行作业。

background_persist_interval

(时间单位) 高级配置选项。模型每次定期持久化之间的时间间隔。默认值为 3 到 4 小时之间的随机值，这可以避免所有作业在完全相同的时间持久化。允许的最小值为 1 小时。

对于非常大的模型（几 GB），持久化可能需要 10-20 分钟，因此不要将 background_persist_interval 值设置得太低。

如果在进行更新时作业已打开，则必须停止数据馈送，关闭作业，然后重新打开作业并重新启动数据馈送才能使更改生效。

custom_settings

(对象) 高级配置选项。包含有关作业的自定义元数据。例如，它可以包含自定义 URL 信息，如将自定义 URL 添加到机器学习结果中所示。

daily_model_snapshot_retention_after_days

(长整型) 高级配置选项，它会影响此作业的旧模型快照的自动删除。它指定一段时间（以天为单位），在此时间段后，每天只保留第一个快照。此时间段相对于此作业的最新快照的时间戳。有效值范围为 0 到 model_snapshot_retention_days。对于新作业，默认值为 1。对于在 7.8.0 版本之前创建的作业，默认值与 model_snapshot_retention_days 相匹配。有关更多信息，请参阅模型快照。

从 Elasticsearch 8.10.0 开始，使用新的版本号来跟踪机器学习插件中的配置和状态更改。此新的版本号与产品版本分离，并将独立递增。

description

(字符串) 作业的描述。

detectors

(数组) 检测器更新对象的数组。

detectors 的属性

custom_rules

(数组) 自定义规则对象的数组，这些对象使您能够自定义检测器的工作方式。例如，规则可能会指示检测器在哪些条件下应跳过结果。Kibana 将自定义规则称为作业规则。有关更多示例，请参阅使用自定义规则自定义检测器。

custom_rules 的属性

actions

(数组) 当规则适用时要触发的操作集。如果指定了多个操作，则所有操作的效果将合并。可用的操作包括

skip_result：不会创建结果。这是默认值。除非您还指定了 skip_model_update，否则模型将按预期使用相应的系列值进行更新。
skip_model_update：该系列的值不会用于更新模型。除非您还指定了 skip_result，否则将按预期创建结果。此操作适用于预期某些值始终异常且它们以负面影响其余结果的方式影响模型的情况。

conditions

(数组) 当规则适用时的可选数字条件数组。规则必须具有非空的范围或至少一个条件。多个条件将使用逻辑 AND 组合在一起。条件具有以下属性

conditions 的属性

applies_to: (字符串) 指定条件适用的结果属性。可用的选项是 actual、typical、diff_from_typical、time。如果您的检测器使用 lat_long、metric、rare 或 freq_rare 函数，则您只能指定适用于 time 的条件。
operator: (字符串) 指定条件运算符。可用的选项是 gt（大于）、gte（大于或等于）、lt（小于）和 lte（小于或等于）。
value: (双精度型) 使用 operator 与 applies_to 字段进行比较的值。

scope

(对象) 规则适用的系列的可选范围。规则必须具有非空的范围或至少一个条件。默认情况下，范围包括所有系列。范围允许用于在 by_field_name、over_field_name 或 partition_field_name 中也指定的任何字段。要为字段添加范围，请在范围对象中添加字段名称作为键，并将它的值设置为具有以下属性的对象

scope 的属性

filter_id: (字符串) 要使用的过滤器的 ID。
filter_type: (字符串) include（规则适用于过滤器中的值）或 exclude（规则适用于过滤器中不存在的值）。默认为 include。

description

(字符串) 检测器的描述。例如，事件速率低。

detector_index

(整数) 检测器的唯一标识符。此标识符基于 analysis_config 中检测器的顺序，从零开始。

如果要更新特定检测器，则必须使用此标识符。但是，您无法更改检测器的 detector_index 值。

groups

(字符串数组) 作业组列表。一个作业可以不属于任何组，也可以属于多个组。

model_plot_config

(对象) 此高级配置选项将模型信息与结果一起存储。它提供了对异常检测的更详细视图。

如果启用模型绘图，它可能会给系统性能带来相当大的开销；对于具有许多实体的作业来说，这是不可行的。

模型绘图提供了模型及其边界的简化和指示性视图。它不显示诸如多元相关性或多模态数据之类的复杂特征。因此，有时可能会报告模型绘图中看不到的异常。

模型绘图配置可以在创建作业时或稍后更新时进行配置。如果遇到性能问题，则必须禁用它。

model_plot_config 的属性

annotations_enabled: (布尔值) 如果为 true，则启用对正在分析的每个实体的模型更改注释的计算和存储。默认为 enabled。
enabled: (布尔值) 如果为 true，则启用对正在分析的每个实体的模型边界的计算和存储。默认情况下，它未启用。
terms: [预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 (字符串) 将数据收集限制为此逗号分隔的分区或按字段值列表。如果未指定 terms 或它为空字符串，则不应用任何过滤。例如，“CPU,NetworkIn,DiskWrites”。不支持通配符。使用单指标查看器时，只能查看指定的 terms。

model_prune_window

(时间单位) 高级配置选项。影响对在给定时间段内未更新的模型的修剪。该值必须设置为 bucket_span 的倍数。如果设置得太低，可能会从模型中删除重要信息。通常，设置为 30d 或更长。如果未设置，则仅当模型内存状态达到软限制或硬限制时，才会进行模型修剪。对于在 8.1 及更高版本中创建的作业，默认值为 30d 或 bucket_span 的 20 倍中的较大者。

model_snapshot_retention_days

(长整数) 高级配置选项，影响此作业的旧模型快照的自动删除。它指定保留快照的最长时间段（以天为单位）。此时间段相对于此作业的最新快照的时间戳。默认值为 10，这意味着比最新快照早十天的快照将被删除。有关更多信息，请参阅模型快照。

per_partition_categorization

(对象) 与分类如何与分区字段交互相关的设置。

per_partition_categorization 的属性

enabled: (布尔值) 要启用此设置，您还必须将 partition_field_name 属性设置为使用关键字 mlcategory 的每个检测器中的相同值。否则，作业创建将失败。
stop_on_warn: (布尔值) 此设置只能在启用每分区分类时设置为 true。如果为 true，则分类和随后的异常检测将停止，对于分区，其分类状态更改为 warn。此设置使拥有一个作业变得可行，在该作业中，预计分类对某些分区有效，但对其他分区无效；您不会永远为分类效果不好的分区支付成本。

renormalization_window_days: (长整数) 高级配置选项。随着新数据的出现，对分数进行调整的期间。默认值为 30 天或 100 个 bucket_spans 中的较大者。

如果在进行更新时作业已打开，则必须停止数据馈送，关闭作业，然后重新打开作业并重新启动数据馈送才能使更改生效。

results_retention_days: (长整数) 高级配置选项。保留结果的时间段（以天为单位）。年龄相对于最新桶结果的时间戳计算。如果此属性具有非空值，则每天在 00:30（服务器时间）进行一次，比最新桶结果早指定天数的结果将从 Elasticsearch 中删除。默认值为 null，这意味着保留所有结果。系统生成的注释也被视为保留目的的结果；它们将在与结果相同的天数后被删除。用户添加的注释将永远保留。

示例编辑

response = client.ml.update_job(
  job_id: 'low_request_rate',
  body: {
    description: 'An updated job',
    detectors: {
      detector_index: 0,
      description: 'An updated detector description'
    },
    groups: [
      'kibana_sample_data',
      'kibana_sample_web_logs'
    ],
    model_plot_config: {
      enabled: true
    },
    renormalization_window_days: 30,
    background_persist_interval: '2h',
    model_snapshot_retention_days: 7,
    results_retention_days: 60
  }
)
puts response

POST _ml/anomaly_detectors/low_request_rate/_update
{
  "description":"An updated job",
  "detectors": {
    "detector_index": 0,
    "description": "An updated detector description"
  },
  "groups": ["kibana_sample_data","kibana_sample_web_logs"],
  "model_plot_config": {
    "enabled": true
  },
  "renormalization_window_days": 30,
  "background_persist_interval": "2h",
  "model_snapshot_retention_days": 7,
  "results_retention_days": 60
}

更新异常检测作业时，您将收到作业配置信息的摘要，包括更新的属性值。例如

{
  "job_id" : "low_request_rate",
  "job_type" : "anomaly_detector",
  "job_version" : "8.4.0",
  "create_time" : 1656105950893,
  "finished_time" : 1656105965744,
  "model_snapshot_id" : "1656105964",
  "custom_settings" : {
    "created_by" : "ml-module-sample",
    "custom_urls" : [
      {
        "url_name" : "Raw data",
        "url_value" : "discover#/?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(index:'90943e30-9a47-11e8-b64d-95841ca0b247')"
      },
      {
        "url_name" : "Data dashboard",
        "url_value" : "dashboards#/view/edf84fe0-e1a0-11e7-b6d5-4dc382ef7f5b?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(filters:!(),query:(language:kuery,query:''))"
      }
    ]
  },
  "groups" : [
    "kibana_sample_data",
    "kibana_sample_web_logs"
  ],
  "description" : "An updated job",
  "analysis_config" : {
    "bucket_span" : "1h",
    "summary_count_field_name" : "doc_count",
    "detectors" : [
      {
        "detector_description" : "An updated detector description",
        "function" : "low_count",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ],
    "model_prune_window" : "30d"
  },
  "analysis_limits" : {
    "model_memory_limit" : "11mb",
    "categorization_examples_limit" : 4
  },
  "data_description" : {
    "time_field" : "timestamp",
    "time_format" : "epoch_ms"
  },
  "model_plot_config" : {
    "enabled" : true,
    "annotations_enabled" : true
  },
  "renormalization_window_days" : 30,
  "background_persist_interval" : "2h",
  "model_snapshot_retention_days" : 7,
  "daily_model_snapshot_retention_after_days" : 1,
  "results_retention_days" : 60,
  "results_index_name" : "custom-low_request_rate",
  "allow_lazy_open" : false
}

« 更新过滤器 API 更新模型快照 API »