预测误差评估插件

Forecast Error Evaluator 插件通过比较预测值与实际观测值，来验证 InfluxDB 3 中时间序列数据的预测模型准确性。该插件会定期计算误差指标（MSE、MAE 或 RMSE），根据误差阈值检测异常，并在预测准确性下降时发送通知。它包含防抖动逻辑以抑制瞬时异常，并支持通过 Notification Sender Plugin 进行多通道通知。

配置

必需参数

参数	类型	默认	描述
`forecast_measurement`	string	必需	包含预测值的测量值
`actual_measurement`	string	必需	包含实际（真实）值的测量值
`forecast_field`	string	必需	预测值的字段名
`actual_field`	string	必需	实际值的字段名
`error_metric`	string	必需	要计算的误差指标：`"mse"`、`"mae"` 或 `"rmse"`
`error_thresholds`	string	必需	阈值级别。格式：`INFO-"0.5":WARN-"0.9":ERROR-"1.2":CRITICAL-"1.5"`
`window`	string	必需	用于数据分析的时间窗口。格式：`<number><unit>` （例如，`"1h"`）
`senders`	string	必需	点分隔的通知渠道列表（例如，`"slack.discord"`）

通知参数

参数	类型	默认	描述
`notification_text`	string	默认模板	包含变量 `$measurement`、`$level`、`$field`、`$error`、`$metric`、`$tags` 的通知消息模板
`notification_path`	string	“notify”	通知发送插件的 URL 路径
`port_override`	integer	8181	InfluxDB 接受请求的端口号

Timing parameters

参数	类型	默认	描述
`min_condition_duration`	string	none	触发通知前异常条件需要持续的最短时间
`rounding_freq`	string	“1s”	用于对齐时间戳的频率

Authentication parameters

参数	类型	默认	描述
`influxdb3_auth_token`	string	环境变量	InfluxDB 3 的 API 令牌。可以通过 `INFLUXDB3_AUTH_TOKEN` 设置
`config_file_path`	string	none	相对于 PLUGIN_DIR 的 TOML 配置文件路径

Sender-specific parameters

Slack notifications

参数	类型	默认	描述
`slack_webhook_url`	string	必需	来自 Slack 的 Webhook URL
`slack_headers`	string	none	Base64 编码的 HTTP 头部

Discord notifications

参数	类型	默认	描述
`discord_webhook_url`	string	必需	来自 Discord 的 Webhook URL
`discord_headers`	string	none	Base64 编码的 HTTP 头部

HTTP notifications

参数	类型	默认	描述
`http_webhook_url`	string	必需	用于 POST 请求的自定义 Webhook URL
`http_headers`	string	none	Base64 编码的 HTTP 头部

SMS notifications (via Twilio)

参数	类型	默认	描述
`twilio_sid`	string	环境变量	Twilio 账户 SID（或 `TWILIO_SID` 环境变量）
`twilio_token`	string	环境变量	Twilio 认证令牌（或 `TWILIO_TOKEN` 环境变量）
`twilio_from_number`	string	必需	Twilio 发送号码（例如，`"+1234567890"`）
`twilio_to_number`	string	必需	收件人号码（例如，`"+0987654321"`）

TOML 配置

参数	类型	默认	描述
`config_file_path`	string	none	相对于 `PLUGIN_DIR` 的 TOML 配置文件路径 (TOML 配置必需)

要使用 TOML 配置文件，请设置 PLUGIN_DIR 环境变量并在触发器参数中指定 config_file_path。 这与启动 InfluxDB 3 时的 --plugin-dir 标志是附加的。

示例 TOML 配置

forecast_error_config_scheduler.toml

有关使用 TOML 配置文件，请参阅 influxdb3_plugins /README.md 中的“使用 TOML 配置文件”部分。

安装步骤

启用处理引擎来启动 InfluxDB 3 核心（--plugin-dir /path/to/plugins）

influxdb3 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --plugin-dir ~/.plugins

安装必需的 Python 包

pandas（用于数据处理）
requests（用于 HTTP 通知）

influxdb3 install package pandas
influxdb3 install package requests

安装 Notification Sender Plugin（必需）

# Ensure notifier plugin is available in ~/.plugins/

触发器设置

Scheduled forecast validation

定期运行预测误差评估

influxdb3 create trigger \
  --database weather_forecasts \
  --plugin-filename gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py \
  --trigger-spec "every:30m" \
  --trigger-arguments 'forecast_measurement=temperature_forecast,actual_measurement=temperature_actual,forecast_field=predicted_temp,actual_field=temp,error_metric=rmse,error_thresholds=INFO-"0.5":WARN-"1.0":ERROR-"2.0",window=1h,senders=slack,slack_webhook_url="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"' \
  forecast_validation

示例用法

示例 1：温度预测验证和 Slack 警报

验证温度预测准确性并发送 Slack 通知

# Create the trigger
influxdb3 create trigger \
  --database weather_db \
  --plugin-filename gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py \
  --trigger-spec "every:15m" \
  --trigger-arguments 'forecast_measurement=temp_forecast,actual_measurement=temp_actual,forecast_field=predicted,actual_field=temperature,error_metric=rmse,error_thresholds=INFO-"0.5":WARN-"1.0":ERROR-"2.0":CRITICAL-"3.0",window=30m,senders=slack,slack_webhook_url="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",min_condition_duration=10m' \
  temp_forecast_check

# Write forecast data
influxdb3 write \
  --database weather_db \
  "temp_forecast,location=station1 predicted=22.5"

# Write actual data  
influxdb3 write \
  --database weather_db \
  "temp_actual,location=station1 temperature=21.8"

# Check logs after trigger runs
influxdb3 query \
  --database _internal \
  "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'temp_forecast_check'"

Expected behavior

插件计算预测值和实际值之间的 RMSE
如果 RMSE > 0.5，发送 INFO 级别通知
如果 RMSE > 1.0，发送 WARN 级别通知
仅在条件持续 10 分钟以上时触发（防抖动）

Notification example

[WARN] Forecast error alert in temp_forecast.predicted: rmse=1.2. Tags: location=station1

示例 2：多指标验证和多个通道

监控多个预测指标并使用不同的通知渠道

# Create trigger with Discord and HTTP notifications
influxdb3 create trigger \
  --database analytics \
  --plugin-filename gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py \
  --trigger-spec "every:1h" \
  --trigger-arguments 'forecast_measurement=sales_forecast,actual_measurement=sales_actual,forecast_field=predicted_sales,actual_field=sales_amount,error_metric=mae,error_thresholds=WARN-"1000":ERROR-"5000":CRITICAL-"10000",window=6h,senders=discord.http,discord_webhook_url="https://discord.com/api/webhooks/YOUR/WEBHOOK",http_webhook_url="https://your-api.com/alerts",notification_text="[$$level] Sales forecast error: $$metric=$$error (threshold exceeded)",rounding_freq=5min' \
  sales_forecast_monitor

示例 3：关键预测失败的 SMS 警报

为关键的预测准确性问题设置 SMS 通知

# Set environment variables (recommended for sensitive data)
export TWILIO_SID="your_twilio_sid"
export TWILIO_TOKEN="your_twilio_token"

# Create trigger with SMS notifications
influxdb3 create trigger \
  --database production_forecasts \
  --plugin-filename gh:influxdata/forecast_error_evaluator/forecast_error_evaluator.py \
  --trigger-spec "every:5m" \
  --trigger-arguments 'forecast_measurement=demand_forecast,actual_measurement=demand_actual,forecast_field=predicted_demand,actual_field=actual_demand,error_metric=mse,error_thresholds=CRITICAL-"100000",window=15m,senders=sms,twilio_from_number="+1234567890",twilio_to_number="+0987654321",notification_text="CRITICAL: Production demand forecast error exceeded threshold. MSE: $$error",min_condition_duration=2m' \
  critical_forecast_alert

使用 TOML 配置文件

该插件支持使用 TOML 配置文件进行复杂配置。

重要要求

要使用 TOML 配置文件，您必须在 InfluxDB 3 主机环境中设置 PLUGIN_DIR 环境变量

PLUGIN_DIR=~/.plugins influxdb3 serve --node-id node0 --object-store file --data-dir ~/.influxdb3 --plugin-dir ~/.plugins

Example TOML Configuration

# forecast_error_config_scheduler.toml
forecast_measurement = "temperature_forecast"
actual_measurement = "temperature_actual"
forecast_field = "predicted_temp"
actual_field = "temperature"
error_metric = "rmse"
error_thresholds = 'INFO-"0.5":WARN-"1.0":ERROR-"2.0":CRITICAL-"3.0"'
window = "1h"
senders = "slack"
slack_webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
min_condition_duration = "10m"
rounding_freq = "1min"
notification_text = "[$$level] Forecast validation alert: $$metric=$$error in $$measurement.$$field"

# Authentication (use environment variables instead when possible)
influxdb3_auth_token = "your_token_here"

使用 TOML 配置创建触发器

influxdb3 create trigger \
  --database weather_db \
  --plugin-filename forecast_error_evaluator.py \
  --trigger-spec "every:30m" \
  --trigger-arguments config_file_path=forecast_error_config_scheduler.toml \
  forecast_validation_trigger

代码概述

文件

forecast_error_evaluator.py：包含预测验证调度程序处理程序的主要插件代码
forecast_error_config_scheduler.toml：示例 TOML 配置文件

日志记录

日志存储在 _internal 数据库（或创建触发器的数据库）的 system.processing_engine_logs 表中。要查看日志

influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'"

日志列

event_time：日志事件的时间戳
trigger_name：生成日志的触发器名称
log_level：严重性级别（INFO、WARN、ERROR）
log_text：描述验证结果或错误的日志消息

主函数

`process_scheduled_call(influxdb3_local, call_time, args)`

处理计划的预测验证任务。查询预测和实际测量值，计算误差指标，并触发通知。

关键操作

从参数或 TOML 文件解析配置
在时间窗口内查询预测和实际测量值
使用舍入频率对齐时间戳
计算指定的误差指标（MSE、MAE 或 RMSE）
评估阈值并应用防抖动逻辑
通过配置的通道发送通知

`compute_error_metric(forecast_values, actual_values, metric_type)`

计算预测准确性指标的核心误差计算引擎。

Supported error metrics

mse：均方误差
mae：平均绝对误差
rmse：均方根误差（MSE 的平方根）

`evaluate_thresholds(error_value, threshold_config)`

根据配置的阈值评估计算出的误差，以确定警报级别。

根据阈值范围返回警报级别

INFO：信息阈值已超过
WARN：警告阈值已超过
ERROR：错误阈值已超过
CRITICAL：严重阈值已超过

故障排除

常见问题

问题：预测和实际数据之间没有重叠的时间戳

解决方案：检查两个测量值在指定时间窗口内都有数据，并使用 rounding_freq 进行对齐

influxdb3 query --database mydb "SELECT time, field_value FROM forecast_measurement WHERE time >= now() - 1h"
influxdb3 query --database mydb "SELECT time, field_value FROM actual_measurement WHERE time >= now() - 1h"

问题：通知未发送

解决方案：验证 Notification Sender Plugin 已安装且 Webhook URL 正确

# Check if notifier plugin exists
ls ~/.plugins/notifier_plugin.py

# Test webhook URL manually
curl -X POST "your_webhook_url" -d '{"text": "test message"}'

问题：未识别误差阈值格式

解决方案：使用带有级别前缀的正确阈值格式

--trigger-arguments 'error_thresholds=INFO-"0.5":WARN-"1.0":ERROR-"2.0":CRITICAL-"3.0"'

问题：未加载环境变量

解决方案：在启动 InfluxDB 之前设置环境变量

export INFLUXDB3_AUTH_TOKEN="your_token"
export TWILIO_SID="your_sid"
influxdb3 serve --plugin-dir ~/.plugins

调试技巧

检查数据可用性（两个测量值中）

influxdb3 query --database mydb \
  "SELECT COUNT(*) FROM forecast_measurement WHERE time >= now() - window"

验证时间戳对齐（使用舍入频率）
```
--trigger-arguments 'rounding_freq=5min'
```

使用更短的窗口进行测试以加快调试速度

--trigger-arguments 'window=10m,min_condition_duration=1m'

监控通知传递（在日志中）

influxdb3 query --database _internal \
  "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%notification%'"

性能注意事项

数据对齐：使用适当的 rounding_freq 来平衡准确性和性能
窗口大小：较大的窗口会增加计算时间，但能提供更可靠的误差估计
防抖动时长：在噪声抑制和警报响应之间取得平衡
通知限流：内置重试逻辑可防止通知泛滥
内存使用：插件使用 pandas DataFrame 处理数据 - 对于大型数据集，请考虑内存

报告问题

有关插件问题，请参阅插件存储库的 issues 页面。

查找 InfluxDB 3 Core 的支持

加入 InfluxDB Discord 服务器是获取 InfluxDB 3 Core 和 InfluxDB 3 Enterprise 支持的最佳途径。对于其他 InfluxDB 版本，请参阅支持和反馈选项。

此页面是否有帮助？

感谢您的反馈！

支持和反馈

感谢您成为我们社区的一员！我们欢迎并鼓励您对 InfluxDB 3 Core 和本文档提供反馈和错误报告。要获得支持，请使用以下资源

具有年度合同或支持合同的客户可以联系 InfluxData 支持。

Edit this page Submit docs issue Submit InfluxDB 3 Core issue