Prophet 预测插件
Prophet 预测插件利用 Facebook 的 Prophet 库，为 InfluxDB 3 中的时间序列数据实现预测。该插件可根据季节性、趋势和自定义事件等历史模式，生成对未来数据点的预测。它支持计划批处理预测和按需 HTTP 触发的预测，并具备模型持久化和验证功能。
配置
计划触发器参数
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
measurement | string | 必需 | 包含历史数据的源测量 |
字段 | string | 必需 | 要预测的字段名称 |
window | string | 必需 | 历史数据窗口。格式：<数字><单位>（例如，"30d"） |
forecast_horizont | string | 必需 | 预测时长。格式：<数字><单位>（例如，"2d"） |
tag_values | string | 必需 | 点分隔的标签过滤器（例如，"region:us-west.device:sensor1"） |
target_measurement | string | 必需 | 预测结果的目标测量 |
model_mode | string | 必需 | 操作模式：“train” 或 “predict” |
unique_suffix | string | 必需 | 用于版本控制的唯一模型标识符 |
HTTP 触发器参数
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
measurement | string | 必需 | 包含历史数据的源测量 |
字段 | string | 必需 | 要预测的字段名称 |
forecast_horizont | string | 必需 | 预测时长。格式：<数字><单位>（例如，"7d"） |
tag_values | object | 必需 | 标签过滤器（JSON 对象格式，例如 {“region”:“us-west”}） |
target_measurement | string | 必需 | 预测结果的目标测量 |
unique_suffix | string | 必需 | 用于版本控制的唯一模型标识符 |
start_time | string | 必需 | 历史窗口开始时间（ISO 8601 格式） |
end_time | string | 必需 | 历史窗口结束时间（ISO 8601 格式） |
高级参数
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
seasonality_mode | string | “additive” | Prophet 季节性模式：“additive” 或 “multiplicative” |
changepoint_prior_scale | 数字 | 0.05 | 趋势变化点的灵活性 |
changepoints | 字符串/数组 | none | 变化点日期（ISO 格式） |
holiday_date_list | 字符串/数组 | none | 自定义节假日日期（ISO 格式） |
holiday_names | 字符串/数组 | none | 与日期对应的节假日名称 |
holiday_country_names | 字符串/数组 | none | 内置节假日所属国家代码 |
inferred_freq | string | auto | 手动指定频率（例如，"1D"，"1H"） |
validation_window | string | “0s” | 验证期时长 |
msre_threshold | 数字 | infinity | 可接受的最大均方相对误差 |
target_database | string | current | 存储预测结果的数据库 |
save_mode | string | “false” | 是否保存/加载模型（仅限 HTTP） |
通知参数
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
is_sending_alert | string | “false” | 在验证失败时启用警报 |
notification_text | string | template | 自定义警报消息模板 |
senders | string | none | 点分隔的通知通道 |
notification_path | string | “notify” | 通知终结点路径 |
influxdb3_auth_token | string | env var | 身份验证令牌 |
TOML 配置
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
config_file_path | string | none | 相对于 PLUGIN_DIR 的 TOML 配置文件路径 (TOML 配置必需) |
要使用 TOML 配置文件，请设置 PLUGIN_DIR 环境变量并在触发器参数中指定 config_file_path。 这与启动 InfluxDB 3 时的 --plugin-dir 标志是附加的。
示例 TOML 配置
prophet_forecasting_scheduler.toml
有关使用 TOML 配置文件，请参阅 influxdb3_plugins /README.md 中的“使用 TOML 配置文件”部分。
安装
启用处理引擎来启动 InfluxDB 3 核心（
--plugin-dir /path/to/plugins）安装必需的 Python 包
influxdb3 install package pandas influxdb3 install package numpy influxdb3 install package requests influxdb3 install package prophet
创建计划触发器
创建用于定期预测的触发器
influxdb3 create trigger \
--database mydb \
--plugin-filename prophet_forecasting.py \
--trigger-spec "every:1d" \
--trigger-arguments "measurement=temperature,field=value,window=30d,forecast_horizont=2d,tag_values=region:us-west.device:sensor1,target_measurement=temperature_forecast,model_mode=train,unique_suffix=20250619_v1" \
prophet_forecast_trigger创建 HTTP 触发器
创建用于按需预测的触发器
influxdb3 create trigger \
--database mydb \
--plugin-filename prophet_forecasting.py \
--trigger-spec "request:forecast" \
prophet_forecast_http_trigger启用触发器
influxdb3 enable trigger --database mydb prophet_forecast_trigger
influxdb3 enable trigger --database mydb prophet_forecast_http_trigger示例
计划预测
用于按需预测的示例 HTTP 请求
curl -X POST https://:8181/api/v3/engine/forecast \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"measurement": "temperature",
"field": "value",
"forecast_horizont": "7d",
"tag_values": {"region":"us-west","device":"sensor1"},
"target_measurement": "temperature_forecast",
"unique_suffix": "model_v1_20250722",
"start_time": "2025-05-20T00:00:00Z",
"end_time": "2025-06-19T00:00:00Z",
"seasonality_mode": "additive",
"changepoint_prior_scale": 0.05,
"validation_window": "3d",
"msre_threshold": 0.05
}'带节假日的高级预测
curl -X POST https://:8181/api/v3/engine/forecast \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"measurement": "sales",
"field": "revenue",
"forecast_horizont": "30d",
"tag_values": {"store":"main_branch"},
"target_measurement": "revenue_forecast",
"unique_suffix": "retail_model_v2",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2025-06-01T00:00:00Z",
"holiday_country_names": ["US"],
"holiday_date_list": ["2025-07-04"],
"holiday_names": ["Independence Day"],
"changepoints": ["2025-01-01", "2025-03-01"],
"inferred_freq": "1D"
}'新功能
- 双重触发模式：支持计划批处理预测和按需 HTTP 请求
- 模型持久化：保存并重用训练好的模型以获得一致的预测
- 预测验证：使用均方相对误差 (MSRE) 进行内置准确性评估
- 节假日支持：内置节假日日历和自定义节假日配置
- 高级季节性：可配置的季节性模式和变化点检测
- 通知集成：通过多个通道发送验证失败的警报
- 灵活的时间间隔：支持秒、分钟、小时、天、周、月、季度和年
输出数据结构
预测结果将以以下结构写入目标测量
标签
model_version：来自 unique_suffix 参数的模型标识符- 来自原始测量查询过滤器的附加标签
字段
forecast：预测值 (Prophet 模型的 yhat)yhat_lower：置信区间下限yhat_upper：置信区间上限run_time：预测执行时间戳 (ISO 8601 格式)
Timestamp
time：预测时间戳 (纳秒)
故障排除
常见问题
模型训练失败
- 确保指定窗口内有足够多的历史数据点
- 验证数据包含必需的时间列和预测字段
- 检查可能影响频率推断的数据缺失情况
- 如果自动检测失败，请手动设置
inferred_freq
验证失败
- 检查 MSRE 阈值设置 - 值过低可能导致频繁失败
- 确保验证窗口提供足够的数据进行比较
- 检查验证数据在时间上是否与预测期对齐
HTTP 触发器问题
- 验证 JSON 请求体格式是否与预期架构匹配
- 检查身份验证令牌和数据库权限
- 确保 start_time 和 end_time 为有效的 ISO 8601 格式，并包含时区信息
模型持久化问题
- 验证插件目录的模型存储权限
- 检查插件目录中的可用磁盘空间
- 确保 unique_suffix 值在不同模型版本之间不冲突
模型存储
- 位置：模型存储在插件目录下的
prophet_models/目录中 - 命名：文件命名为
prophet_model_{unique_suffix}.json - 版本控制：使用描述性的 unique_suffix 值进行模型管理
时间格式支持
支持窗口、forecast_horizont 和 validation_window 的时间单位
s(秒),min(分钟),h(小时)d(天),w(周)m(月 ≈30.42天),q(季度 ≈91.25天),y(年 = 365天)
验证过程
当设置了 validation_window 时
- 训练数据：
current_time - window到current_time - validation_window - 验证数据：
current_time - validation_window到current_time - MSRE 计算：
mean((actual - predicted)² / actual²) - 阈值比较和可选警报分发
报告问题
有关插件问题，请参阅插件存储库的 issues 页面。
查找 InfluxDB 3 Core 的支持
InfluxDB Discord 服务器 InfluxDB Discord server 是获取 InfluxDB 3 Core 支持的最佳场所。对于其他 InfluxDB 版本，请参阅 支持和反馈 选项。
此页面是否有帮助？
感谢您的反馈！
支持和反馈
感谢您成为我们社区的一员！我们欢迎并鼓励您对 InfluxDB 3 Core 和本文档提供反馈和错误报告。要获得支持，请使用以下资源
具有年度合同或支持合同的客户可以 联系 InfluxData 支持。