vmanomaly-config

vmanomaly 配置构建器

将已知的监控意图转换为经过验证的 vmanomaly v1.30+ 配置。ML 必须证明其运营成本合理：首先判断静态规则能否更清晰地表达故障条件。

选择模型或其参数前，请阅读 references/model-selection.md。生成持续运行的部署时，还需阅读 references/deployment-readiness.md，并仅应用符合条件的控制措施。

环境

export VM_ANOMALY_URL="https://vmanomaly.example.com"
# Use /dev/null without authentication. For authenticated instances, point this to a mode-0600
# curl config containing: header = "Authorization: Bearer <token>"
export VM_CURL_CONFIG="${VM_CURL_CONFIG:-/dev/null}"

在 VM_ANOMALY_URL 中包含任何已配置的路径前缀。绝不打印或创建凭据文件。如果无法获取 URL，请询问用户。

工作流

1. 明确意图并获取准确查询

收集或推断：

• 准确的 PromQL/MetricsQL 或 LogsQL 表达式；
• 要检测的尖峰、下降、水平偏移、季节性中断或趋势中断；
• 方向：above_expected、below_expected 或两者；
• 期望的响应时间和查询步长；
• 生产查询和日历配置文件使用的 IANA 时区；
• 已知的物理边界，以及不显著的绝对／相对偏差；
• 灵敏度偏好和可接受的最高检测率。

如果模型查询字段为空，但用户已提供查询，请使用该查询进行分析，并建议将其填入 UI 查询输入框。如果没有查询，请向用户索取。不要根据指标描述臆造生产查询。

如果已安装，victoriametrics-query 或 victorialogs-query 可用于发现名称、标签和有效表达式。未安装这些工具不应阻碍本技能的执行。

2. 权衡静态告警与 ML

如果存在明确的异常值，优先使用静态 VMAlert 规则：

信号形态	更适合作为首选方案
接近零的错误／重启计数	> threshold for duration
单调增长的容量占用	百分比阈值加上 predict_linear
二元／上下状态	直接阈值、absent() 或 changes()
到期时间或硬性安全限值	直接阈值

当正常情况会随时间、实例、工作负载或不断漂移的基线而变化时；当每日、每周、每月或节假日模式很重要时；或当信号是跨序列关系时，使用 vmanomaly。在消耗自动调优预算前，先说明这一判断。

3. 运行运行时预检

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/health" | jq .
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/server/buildinfo" | jq .
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/compatibility" | jq .

将兼容性响应视为预检，而不是清理操作：

• 没有已存储状态属于正常情况；
• 报告 drop_everything、待清除的模型或读取器数据清理；
• 未经用户明确批准，绝不删除状态；
• 计划升级时使用 ?version_to=X.Y.Z。

兼容性检查涵盖 vmanomaly 管理的状态、受支持的读取器和内置模型，不涵盖自定义模型代码、依赖项或状态；升级到 v1.30.3+ 前，依赖 is_multivariate = True 的自定义 many-to-one 模型必须声明 topology = ModelTopology.MANY_TO_ONE。

v1.30 中仅支持 GET 兼容性检查。

4. 分析真实数据

使用与最终任务／配置相同的 step：

QUERY='<exact-query>'
TIMEZONE='<IANA-timezone>'
curl -q --config "$VM_CURL_CONFIG" -sG \
  --data-urlencode "query=$QUERY" \
  --data-urlencode 'start=<unix-seconds>' \
  --data-urlencode 'end=<unix-seconds>' \
  --data-urlencode 'step=5m' \
  --data-urlencode "timezone=$TIMEZONE" \
  --data-urlencode 'limit=100' \
  "$VM_ANOMALY_URL/api/v1/timeseries/characteristics" | jq .

依据测得的趋势、每日／每周／每月模式、形态、适用性和覆盖范围，而不是根据指标名称猜测。有限结果仅代表样本。如果有限读取返回 split-chunk 422，请缩短时间范围或使用更粗的步长。

5. 发现并选择受支持的模型

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/models" | jq .
curl -q --config "$VM_CURL_CONFIG" -sG \
  --data-urlencode 'model_class=temporal_envelope' \
  "$VM_ANOMALY_URL/api/v1/model/schema" | jq .

以实时别名列表和架构为准。更改类别时，重新构建模型规格；不要沿用其他类别的过时参数。

默认层级：

1. 对于任何非平凡的时间特征，均从 temporal_envelope 开始：趋势、日历模式、节假日、持续性变化、预测，或不确定简单的平稳基线是否足够。
2. 只有在分析确认数据简单、无季节性且相对稳定时，才使用 mad_online 或 zscore_online。对于偏斜、重尾或受异常值污染的数据，优先使用 MAD；只有在分布稳定、尾部较轻且标准差的幅度有意义时，才使用 Z-score。
3. 对于关系本身就是异常的对齐通道，从 temporal_envelope_multivariate 开始。
4. 在常规推荐流程中，不要引入离线模型。只有在审查旧配置、用户明确要求，或受控比较已证实离线模型能带来在线模型无法实现的显著收益时，才讨论离线模型。

6. 将领域知识映射到公开控制项

• 业务意图明确时，固定 detection_direction，并将不重要的绝对／相对偏差映射到 min_dev_from_expected 和 min_rel_dev_from_expected。
• 在 v1.30.2+ 可部署 YAML 中，将 data_range、detection_direction、min_dev_from_expected 和 min_rel_dev_from_expected 放在 reader.queries.<alias> 下。查询值对所有关联模型均具有权威性；模型级值仍可作为本地回退值兼容使用，但已弃用。
• 对于 VMUI，检查已连接的建议契约。当 suggest_query_config 提供 queries 和 expected_revision 时，应用包含别名、启用状态和各查询策略的完整命名查询行，复制当前版本，并保留未修改的行。未指定／省略的策略会继承；显式设置为零、both 和无界值则会覆盖。较旧的单查询契约无法应用命名查询集；不要悄悄丢弃其策略。模型级默认值应单独保留。
• 仅当预测和区间输出应限制在该范围内时，才设置模型级 clip_predictions。
• 使用 min_n_samples_seen 在冷启动期间抑制评分。将其时长表示为样本数乘以查询步长。
• 对于稳定的 MAD、Z-score 或在线分位数数据，可考虑使用 history_strength > 1，而不是增加许多拟合周期；历史数据应足以覆盖每个所需的季节阶段。
• 只选择分析结果支持的日历预设。Temporal Envelope 配置文件支持时区和夏令时感知；将 reader.queries.<alias>.tz（或读取器级 tz）设为分析时使用的相同 IANA 时区。
• 除非用户需要未来状态预测或容量规划，否则将 forecast_at 留空。
• 自动调优期间，固定多变量 groupby、节假日和其他领域结构。

7. 选择直接配置或共享自动调优

对于直接配置，从架构默认值开始，只更改有充分理由调整的控制项。

对于共享自动调优，先选择模型类别。说明试验／时间预算，然后创建一个有界任务。在线模型使用因果精确验证：

jq -n --arg query "$QUERY" --arg timezone "$TIMEZONE" '{
    query:$query,
    "tuned_class_name":"temporal_envelope",
    "anomaly_percentage":0.02,
    "start":1710000000,
    "end":1711209600,
    "step":"5m",
    timezone:$timezone,
    "limit":100,
    "use_profile_hints":true,
    "optimization_params":{"n_trials":64,"timeout":30,"exact":true,"optimize_complexity":true},
    "frozen_params":{"detection_direction":"above_expected"}
  }' | curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' --data-binary @- \
  "$VM_ANOMALY_URL/api/v1/autotune/tasks" | jq .

按顺序轮询 GET /api/v1/autotune/tasks/{task_id}。成功后，使用具体的 result_data.data.modelConfig，并对其进行验证和测试。不要替换为 class: auto；该封装会在每次拟合时重新调优，属于单独选择的生命周期。自动调优仍会返回模型规格：为 VMUI／临时测试保留其中冻结的业务字段，但在组装 v1.30.2+ 部署 YAML 时，将这些字段移至对应的查询中。

8. 验证和测试

验证模型规格：

curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' \
  -d @model.json "$VM_ANOMALY_URL/api/v1/model/validate" | jq .

验证完整 YAML，但不应用：

curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/yaml' --data-binary @config.yaml \
  "$VM_ANOMALY_URL/api/v1/config/validate" | jq .

然后检查容量，并使用已验证的模型运行有界检测任务。v1.30.3 任务契约要求显式指定 datasource_url；适用时复用已配置的数据源 URL：

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/anomaly_detection/limits" | jq .

DATASOURCE_URL='<configured-or-explicit-datasource-url>'
jq -n --arg query "$QUERY" --arg datasource_url "$DATASOURCE_URL" --slurpfile model model.json '{
    query:$query,
    datasource_url:$datasource_url,
    step:"5m",
    fit_window:"30d",
    fit_every:"1000w",
    start_infer_s:1710000000,
    end_infer_s:1710086400,
    exact:true,
    model_spec:$model[0]
  }' | curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' --data-binary @- \
  "$VM_ANOMALY_URL/api/v1/anomaly_detection/tasks" | jq .

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/anomaly_detection/tasks/<task_id>" | jq .

依次轮询返回的任务 ID，直到状态为 done、error 或 canceled。对于在线模型，使用 exact:true，并将 fit_every: 1000w 等设为实际上禁用的默认拟合频率，让初始拟合在推理过程中因果演进。仅在明确需要时配置定期重新拟合。

结合已知事件，目视评估检测结果。没有真实标签时，应将观测到的比例称为检测率，而非误报率。在收紧模型之前，先询问用户哪些检测结果有用。

9. 提供可部署的产物

提供：

• 静态规则或完整的 vmanomaly YAML；
• 针对生成的异常分数的 VMAlert 规则；
• 基于画像证据和业务意图的理由；
• 查询步长、拟合窗口／频率、预热时间、预期响应时间和资源注意事项；
• 验证／测试结果，以及需要在生产环境中确认的假设；
• 自监控集成；生产环境建议使用官方仪表板和告警规则，而非依赖某一时点的健康检查。
• 根据 references/deployment-readiness.md 中的说明，合理选择状态恢复、保留期限、热重载、持久化和工作负载分布方案。

生成的 /api/vmanomaly/config.yaml 和 /api/vmanomaly/example-alert-rule.yaml 只是起点，并不能证明配置正确。该配置端点保留了与 VMUI／模型规格兼容的结构；提供 v1.30.2+ 部署 YAML 之前，应将四项稳定的业务策略移至 reader.queries.<alias>，在适用时添加 reader.workers，并验证最终配置。

高效利用 Copilot 上下文

重用已有的架构、画像和已完成任务的结果。使用明确且较小的 top-k 值（通常为 3–5）进行有针对性的文档搜索；结果可能只是摘录。检查其来源 URI、偏移量和截断标记，然后使用 vmanomaly_read_doc_section 获取缺失的上下文，再据此作出判断。不要因为摘录中未提及，就认定某个参数或限制不存在。避免重复进行宽泛搜索，也避免在对话历史中加入完整文档。

每项拟议配置只通过其审批卡展示一次；只有收到明确的导出请求时，才单独提供 YAML。解释应简洁。切勿通过删除查询别名、表达式、禁用行、业务策略继承、验证约束或待审批数据来减少上下文。UI 应用命名查询并不意味着支持共享命名查询自动调参；请检查实际的工具架构。

后端可能会精简重复的已完成工具结果，并独立于服务提供商实施本地上下文预算限制。预算拒绝时，保留当前 UI 状态，并说明如何通过更聚焦的请求或新对话继续；不要声称尚未应用的建议已成功。Token 上限是允许的最大输出量，不是目标。使用量计数器和字节对比有助于衡量，但不能证明服务提供商的计费节省是精确的。

命名查询的联合自动调优

当连接的自动调优模式公开 queries 时，请发送一个映射，其中包含有效别名、精确表达式和明确的业务策略，并省略旧版 query 字段。保留 null／省略继承与显式零值、两者及无界覆盖之间的区别。在一个任务中调优实际的多变量模型类，并将模型分组设置在 frozen_params.groupby 中。每个候选配置都会在独立拟合且对齐的分组上进行评估，从而生成一份共享配置。切勿合并分别调优的单变量配置，并将结果描述为经过联合调优的多变量检测。可能需要提高每个表达式的样本上限，以纳入每个查询中匹配的所有分组；分组不完整时会明确报错。

对于不支持此约定的旧版服务，请说明限制，而不是悄悄丢弃查询或其策略。将 anomaly_percentage 描述为调优目标，而不是有保证的异常比例或误报上限。应用生成的模型建议时，沿用现有的命名查询和策略状态；切勿意外将查询局部策略提升为共享默认值。

安全

• API 验证和任务不会部署或热重载配置。
• 应用配置、创建持久化告警规则或删除状态之前，必须获得批准。
• 限制样本量、时间范围、序列数量上限、试验次数和并发任务数。
• 在检查查询和标签之前，切勿仅凭数据为空就推断指标不存在。

UI 模型选项

适用于 vmanomaly v1.30.7 及更高版本。

server.ui_allowed_models 仅用于筛选手动模型选择器和 Auto 目标。它不会限制 Copilot、已配置模型、共享链接或 API 执行；请勿将其用作授权边界。