› › ›

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

(long или строка) Примерный максимальный объём ресурсов памяти, необходимых для аналитической обработки. Когда этот предел приближается, агрессивность обрезки данных возрастает. При превышении этого предела новые сущности не моделируются. Значение по умолчанию для задач, созданных в версии 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 ниже текущего значения использования. Для определения текущего значения использования см. значение model_bytes в API получения статистики задач.
Если свойство memory_status в объекте model_size_stats имеет значение hard_limit, это означает, что обработка некоторых данных не удалась. Возможно, необходимо перезапустить задачу с увеличенным значением model_memory_limit.

background_persist_interval

(единицы измерения времени) Дополнительный параметр конфигурации. Время между периодическим сохранением модели. Значение по умолчанию — случайное значение от 3 до 4 часов, что предотвращает одновременное сохранение всех задач. Минимальное разрешённое значение — 1 час.

Для очень больших моделей (несколько ГБ) сохранение может занять 10-20 минут, поэтому не устанавливайте значение параметра background_persist_interval слишком низким.

custom_settings

(объект) Дополнительный параметр конфигурации. Содержит пользовательские метаданные о задаче. Например, может содержать информацию о пользовательских URL, как показано в Добавление пользовательских URL в результаты машинного обучения.

daily_model_snapshot_retention_after_days

(long) Дополнительный параметр конфигурации, влияющий на автоматическое удаление старых моментальных снимков модели для этой задачи. Указывает период времени (в днях) после которого сохраняется только первый снимок за день. Этот период относится к метке времени самого последнего моментального снимка для данной задачи. Допустимые значения от 0 до model_snapshot_retention_days. Для новых задач значение по умолчанию — 1. Для задач, созданных до версии 7.8.0, значение по умолчанию соответствует model_snapshot_retention_days. Более подробная информация в Моментальные снимки моделей.

description

(строка) Описание задачи.

detectors

(массив) Массив объектов обновления детектора.

Свойства detectors

custom_rules

(массив) Массив объектов пользовательских правил, позволяющих настроить работу детекторов. Например, правило может диктовать детекторам условия, при которых результаты следует пропускать. Kibana называет пользовательские правила правилами задач. Более подробные примеры см. в Настройка детекторов с помощью пользовательских правил.

Свойства custom_rules

actions

(массив) Набор действий, которые будут выполняться при применении правила. Если указано более одного действия, эффекты всех действий объединяются. Доступные действия включают:

skip_result: Результат не будет создан. Это значение по умолчанию. Если вы также не укажете skip_model_update, модель будет обновлена как обычно со соответствующим значением ряда.
skip_model_update: Значение для данного ряда не будет использоваться для обновления модели. Если вы также не укажете skip_result, результаты будут созданы как обычно. Это действие подходит, когда определенные значения ожидаются как постоянно аномальные, и они влияют на модель таким образом, что отрицательно сказывается на остальных результатах.
force_time_shift: Это действие сместит время внутри детектора аномалий на заданное количество. Это полезно, например, для быстрого адаптации к событиям перехода на летнее время, которые известны заранее. Для этого действия требуется параметр force_time_shift в объекте params.

params

(объект) Набор объектов параметров, которые настраивают действия, определенные в массиве действий пользовательских правил. Доступные параметры (в зависимости от указанных действий) включают: force_time_shift.

Свойства params

force_time_shift: (объект) Установите time_shift_amount на целое число секунд, на которое вы хотите сдвинуть время.

conditions

(массив) Необязательный массив числовых условий, при которых правило применяется. Правило должно иметь либо непустой диапазон, либо хотя бы одно условие. Несколько условий объединяются с помощью логического AND. Условие имеет следующие свойства:

Свойства conditions

applies_to: (строка) Указывает свойство результата, к которому применяется условие. Доступные варианты: actual, typical, diff_from_typical, time. Если ваш детектор использует функции lat_long, metric, rare или freq_rare, вы можете указать только условия, которые применяются к time.
operator: (строка) Указывает оператор условия. Доступные варианты: gt (больше), gte (больше или равно), lt (меньше) и lte (меньше или равно).
value: (двойное) Значение, которое сравнивается со свойством applies_to с помощью operator.

scope

(объект) Необязательный диапазон рядов, к которому применяется правило. По умолчанию диапазон включает все ряды. Диапазон разрешен для любых полей, также указанных в by_field_name, over_field_name или partition_field_name. Чтобы добавить диапазон для поля, добавьте имя поля в качестве ключа в объект диапазона и установите его значение в объект со следующими свойствами:

Свойства scope

filter_id: (строка) Идентификатор фильтра, который будет использоваться.
filter_type: (строка) Либо include (правило применяется для значений в фильтре), либо exclude (правило применяется для значений, не входящих в фильтр). По умолчанию include.

description

(строка) Описание детектора. Например, Low event rate.

detector_index

(целое число) Уникальный идентификатор детектора. Этот идентификатор основан на порядке детекторов в analysis_config, начиная с нуля.

Если вы хотите обновить определенный детектор, вы должны использовать этот идентификатор. Однако вы не можете изменить значение detector_index для детектора.

groups: (массив строк) Список групп задач. Задача может принадлежать к нулю или многим группам.

model_plot_config

(объект) Этот расширенный параметр конфигурации хранит информацию о модели вместе с результатами. Он предоставляет более подробный обзор обнаружения аномалий.

Если вы включите график модели, это может значительно увеличить нагрузку на производительность системы; это не подходит для задач с большим количеством сущностей.

График модели предоставляет упрощенный и ориентированный вид модели и ее границ. Он не отображает сложные функции, такие как многомерные корреляции или многомодальные данные. Поэтому иногда могут быть сообщения об аномалиях, которые невозможно увидеть на графике модели.

Конфигурацию графика модели можно настроить при создании задачи или обновить позже. Ее необходимо отключить, если наблюдаются проблемы с производительностью.

Свойства model_plot_config

annotations_enabled: (Булево) Если true, включает вычисление и хранение аннотаций изменения модели для каждой анализируемой сущности. По умолчанию enabled.
enabled: (Булево) Если true, включает вычисление и хранение границ модели для каждой анализируемой сущности. По умолчанию это не включено.
terms: [preview] Эта функциональность находится на стадии технического предварительного просмотра и может быть изменена или удалена в будущих выпусках. Elastic будет работать над устранением любых проблем, но функции на стадии технического предварительного просмотра не подпадают под SLA поддержки официальных функций GA. (строка) Ограничивает сбор данных этой запятой, разделённым списком значений раздела или по полям. Если термины не указаны или это пустая строка, фильтрация не применяется. Например, "CPU,NetworkIn,DiskWrites". Поддержка подстановочных знаков отсутствует. Только указанные terms могут быть просмотрены при использовании просмотра единственного метрического значения.

model_prune_window

(единицы времени) Расширенный параметр конфигурации. Влияет на удаление моделей, которые не обновлялись в течение заданного периода времени. Значение должно быть кратным bucket_span. Если значение слишком мало, важная информация может быть удалена из модели. Обычно устанавливается на 30d или больше. Если не задано, удаление модели происходит только в том случае, если состояние памяти модели достигает мягкого или жесткого предела. Для задач, созданных в 8.1 и более поздних версиях, значение по умолчанию равно большему из 30d или 20 раз bucket_span.

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: (long) Дополнительный параметр конфигурации. Период, в течение которого применяются корректировки к оценке по мере получения новых данных. Значение по умолчанию — большее из 30 дней или 100 bucket_spans.

Если задание открыто при внесении обновления, необходимо остановить поток данных, закрыть задание, затем снова открыть задание и перезапустить поток данных, чтобы изменения вступили в силу.

results_retention_days: (long) Дополнительный параметр конфигурации. Период времени (в днях), в течение которого сохраняются результаты. Возраст вычисляется относительно метки времени последнего результата корзины. Если это свойство имеет ненулевое значение, то раз в день в 00:30 (по серверному времени) результаты, которые старше указанного количества дней, чем последний результат корзины, удаляются из Elasticsearch. Значение по умолчанию — null, что означает сохранение всех результатов. Аннотации, сгенерированные системой, также считаются результатами для целей сохранения; они удаляются через такое же количество дней, как и результаты. Аннотации, добавленные пользователями, сохраняются навсегда.

Примеры

resp = client.ml.update_job(
    job_id="low_request_rate",
    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,
)
print(resp)

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

const response = await client.ml.updateJob({
  job_id: "low_request_rate",
  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,
});
console.log(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
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/ml-update-job.html