Elasticsearch…

当 Elasticsearch ML 异常检测的分数偏高、偏低或与预期不符时，用来解释分数含义、模型行为并定位原因。

适用场景

解决思路

1. 先判断是直接解释用户提供的记录，还是需要从集群拉取数据：若记录中已包含 record_score、initial_record_score、actual、typical 和 function，就直接基于领域知识解释，不要重复调用 API；否则先补齐缺失字段。
2. 调用集群前先验证连通性：执行 GET /（CLI：elastic es info），若失败则停止并报告连接错误，不要猜测端点或凭据。
3. 解析 job ID 并加载配置：未知 job ID 时调用 GET /_ml/anomaly_detectors（CLI：elastic es ml get-jobs）列出候选；再调用 GET /_ml/anomaly_detectors/{job_id}（CLI：elastic es ml get-jobs --job-id '<job_id>'）获取 analysis_config（bucket_span、detectors、custom_rules、use_null、model_plot_config），并用 GET /_ml/anomaly_detectors/{job_id}/_stats（CLI：elastic es ml get-job-stats --job-id '<job_id>'）获取 state、model_size_stats.memory_status 和数据量。解释分数前先确认检测器函数与方向是否与用户问题一致（low_count 会在下降时触发，high_count 不会）。
4. 检索时间范围内的异常记录：调用 POST /.ml-anomalies-*/_search（CLI：elastic es search --index '.ml-anomalies-*' --input-file '<search-body.json>'），指定 result_type: record、job ID、时间范围和可选的 record_score 过滤，读取 initial_record_score、record_score、actual、typical、function、multi_bucket_impact 和 anomaly_score_explanation。始终同时展示 initial_record_score 与 record_score，两者差距就是重归一化的故事。
5. 在推测原因前先对分数模式分类：initial_record_score 远大于 record_score 表示重归一化（后续出现更极端的异常把该记录分数压低），这是健康行为而非模型故障，告警严重度应使用 initial_record_score；两者相等表示检测后未发生重归一化；actual 远小于 typical 且函数为 low_count、count 或 low_mean 表示缺失/下降异常，高分是合理的（检测到中断、管道停滞或服务故障），不是误报，应建议排查事故而非调分数；actual 远大于 typical 且函数为 high_count 或 high_mean 表示尖峰异常，可用 single_bucket_impact 确认。
6. 只引用记录中实际存在的 anomaly_score_explanation 因子：若 high_variance_penalty 为 false 就不要归因于方差；若某因子缺失，说明它未被返回，不要凭空编造。
7. 可选：量化整个 job 的重归一化程度。重新查询 POST /.ml-anomalies-*/_search 获取时间范围内按 timestamp 升序排列的记录，逐条计算 score_drift = initial_record_score − record_score，筛选 |score_drift| ≥ 20 的记录；大幅负漂移（initial 远大于 record）确认后续出现更极端异常后发生了重归一化。
8. 当用户问“是什么导致的”或“为什么这么低/高”时补充上下文：若 model_plot_config.enabled 为 true，调用 POST /.ml-anomalies-*/_search 并指定 result_type: model_plot，对比 actual 与 model_lower / model_upper；调用同一接口指定 result_type: influencer 并按 influencer_score 降序排列，找出贡献最大的实体；对分类任务调用 result_type: category_definition 列出学习到的日志模式（每个 category_id 的 terms、regex、examples）。
9. 需要聚合、跨 job 查询、桶级结果或超出分数与时间的自定义过滤时，参考 references/explainer-reference.md。
10. 按常见多步工作流执行：解释特定异常 = job 配置 → 记录（job + 精确时间）→ 展示 initial_record_score 与 record_score 及分数因子；分数为何低 = job 配置 → 记录 → 重归一化检查 → 模型图（若启用）→ 解释分数因子；分数为何高 = job 配置 → 记录 → 检查函数方向、历史不足、use_null、基数；重归一化漂移 = 记录按时间排序 → 计算 score_drift → 列出 initial 远大于 record 的记录；哪些实体有贡献 = influencers（job + 时间范围）按 influencer_score 排序；可视化模型边界 = model plot（job + 时间范围）对比 model_lower/model_upper 与 actual；分类任务模式 = category_definition（job_id）查看每个类别的 terms、regex、examples。
11. 遵循关键原则：先取记录（或使用用户提供的记录），没有 initial_record_score、record_score、actual、typical、function 就不要解释分数；重归一化是健康的；方向很重要；先解释因子再推测；job 配置至关重要（bucket_span、检测器函数、custom_rules、use_null、内存状态都会影响分数）；模型图是最直观的解释；job 健康问题（缺失文档、内存限制、datafeed 未运行）改用 elasticsearch-anomaly-detection 技能。
12. 按分数排查协议执行：列出 job（GET /_ml/anomaly_detectors）→ 获取 job 配置与统计（GET /_ml/anomaly_detectors/{job_id} 和 /_stats，核对 bucket_span、检测器函数、custom_rules、use_null、job 状态、memory_status）→ 检索记录（POST /.ml-anomalies-*/_search，result_type: record）→ 检查重归一化（对比 initial_record_score 与 record_score，必要时按时间排序计算 score_drift）→ 可视化模型边界（result_type: model_plot）→ 查询 influencers（result_type: influencer，按 influencer_score 排序）→ 解释记录中实际存在的因子（high_variance_penalty、incomplete_bucket_penalty、anomaly_length、single_bucket_impact、multi_bucket_impact），不要引用缺失的因子。
13. 只报告 API 或用户提供记录中实际存在的内容，不要编造分数、时间戳、实体值或解释因子；解释记录时始终同时展示 initial_record_score 和 record_score，并明确说明是否发生重归一化；因子缺失时不要断言，说明该字段未返回；当 high_variance_penalty 或 incomplete_bucket_penalty 为 false 或缺失时，不要将低分归因于它们。

适用边界 · 注意事项

• 需要 Elasticsearch 8.x+ 或 Elastic Cloud Serverless 并启用 ML 异常检测，自管集群需 Platinum 级许可证，调用者需 monitor_ml 权限；不满足这些条件时无法使用。
• Serverless 环境下 _ml/.../results/* REST 端点返回 HTTP 410，必须改用 POST /.ml-anomalies-*/_search 查询结果。
• 本技能只解释分数与模型行为，不负责 job 生命周期（创建、启动、停止）或 job 健康问题（缺失文档、内存限制、datafeed 未运行），这些应使用 elasticsearch-anomaly-detection 技能。