利用时间序列基础模型和 watsonx.ai 预测API预测未来值

使用时间序列预测API和 IBM Granite 时间序列模型（可从 watsonx.ai 获取），基于历史数据预测未来值。

所需权限: 若要根据历史数据预测未来数据点，您必须在项目中拥有 “管理员 ”或 “编辑 ”角色。
所需凭证: 您必须生成凭据，以便对 watsonx.ai API进行身份验证。详情请参阅 “生成 Bearer 令牌 ”。

发展途径

您必须生成凭据，以便对 watsonx.ai API进行身份验证。详情请参阅 “生成 Bearer 令牌 ”。

您可以使用以下编程方法，从时间序列基础模型中生成预测：

REST API
Python
Node.js

概述

使用时间序列预测API将历史数据观测传递给时间序列基础模型，该模型可通过零样本推断预测未来值。例如，您可以使用这种方法根据以下几类数据的定时观测值来预测未来值：

股票价格和交易量
心电图 (EKG) 数据或多导睡眠图 (PSG) 记录
温度或地震数据
网络性能测量

展示时间序列法预测股票价格未来值的示例

支持的基础模型

在使用API之前，您的管理员必须安装以下时间序列基础模型之一：

ibm/granite-ttm-512-96-r2：请求中每个通道至少需要512个数据点。
ibm/granite-ttm-1024-96-r2：请求中每个通道至少需要1024个数据点。
ibm/granite-ttm-1536-96-r2：请求中每个通道至少需要1536个数据点。

Granite 时间序列模型是 IBM Research的多变量时间序列预测的预训练模型，也称为微型时间混合器（TTM）。

Granite 时间序列模型最适合处理以分钟或小时为间隔的数据点，并生成一个预测数据集，默认情况下每个通道有96个数据点。为了获得最佳结果，请根据现有数据使用数据点最多的模型。

更多信息，请参阅车型卡。

要编程获取可用的时间序列模型列表，您可以使用 watsonx.ai API中的列出可用基础模型方法。指定 "filters=function_time_series_forecast参数，只返回可用的时间序列模型。

例如：

curl -X GET \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/foundation_model_specs?version=2024-11-14&filters=function_time_series_forecast'

REST API

使用 watsonx.ai REST API的时间序列预测方法，根据历史数据预测未来值。

详情请参阅 watsonx.ai API 参考文档。

审查数据要求，并从示例请求中获取更多信息。

数据需求
请求示例

REST API数据要求

时间序列是在一段时间内收集的数据点集合。

您可以使用以下模式描述 API 请求有效负载中包含的数据：

"schema": {
    "timestamp_column": "{date-column-name}",
    "id_columns": [
      "{series-name}",
      "{series-name}"
    ]
    "freq":"{time-interval}",
    "target_columns": [
      "{channel-name}",
      "{channel-name}",
      "{channel-name}"
    ]
  },

要使用Granite时间序列模型预测未来值，您提交的分析数据必须满足以下要求：

记录的数据必须是数值数据，如温度或股票价格。
您的数据必须包含足够多的历史背景数据点，以便模型能够做出预测。每个时间序列基础模型在请求中指定了每个通道所需的最低数据点数量。如果指定的数据点数多于要求，模型将使用最近的数据点，直至达到模型要求，而忽略其余数据点。
请求正文中指定的 date 、 id_columns 和 target_columns 数组中的项目数量必须相等。不能跳过数据点或指定 "null为数据点。提交申请前，请检查您的数据。
虽然该服务接受最常见的日期和时间格式，但如果您使用ISO 8601格式（ 2024-11-12T15:06:35 ）指定带有时间戳的日期，则可以避免因日期格式约定不同而导致的混乱。例如，11/12/2024 是指 11 月 12 日还是 12 月 11 日？请使用协调世界时（UTC）偏移量（ 2024-11-12T15:06:35+0000 ）按照ISO 8601格式指定日期，以避免生成的预测结果中出现明显的重复或时间戳缺失。
以统一频率对数据进行采样。例如，可以 1 分钟、1 小时或 1 天为增量观察数据。如果时间戳不一致，则不会产生错误，但结果质量可能较差。生成的预报数据也会按照使用 "freq参数指定的频率进行格式化。

例如，如果您指定的频率是一天（"freq":"1D"），您的时间戳可能是这样的：
```
"date": [
      "2024-11-15T15:06:35",
      "2024-11-16T15:06:35",
...
]
```
如果频率为 5 分钟（"freq":"5min"），则每个日期时间戳可能相隔 5 分钟。
```
"date": [
      "2024-11-15T15:06:35",
      "2024-11-15T15:11:35",
...
]
```
有关频率参数中日期和时间缩写的支持值，请参阅熊猫库文档中的周期别名。

如果将多个来源的数据点用于分析，则每个数据点必须提供一个唯一的标识符，以表明它属于哪个系列或观察集合。

例如，如果您要分析购物趋势，您可能会对假日期间多家商店的销售数据感兴趣。下表显示的是A和B两个系列。 A系列显示A地点的每日销售额，B系列显示B地点的每日销售额。

表 1. 销售数据样本
日期	系列编号	销售总额（美元）
2023 年 12 月 7 日	A	24,988美元
2023 年 12 月 7 日	B	63,788美元
2023 年 12 月 8 日	A	41,855美元
2023 年 12 月 8 日	B	105,678美元
...	...	...

虽然表格显示的是两天的观测数据，但您的请求必须包括 512 到 1,536 个数据点，具体取决于您使用的模型。将表格中的数据提交给应用程序接口时，其格式如下：

...
"data": {
"date": [
  "2024-12-07T00:00:00",
  "2024-12-07T00:00:00",
  "2024-12-08T00:00:00",
  "2024-12-08T00:00:00",
  ...
],
"ids": [
  "A",
  "B",
  "A",
  "B",
  ...
],
"sales-usd": [
  24988,
  63788,
  41855,
  105678,
  ...
]
}

您可以使用多元数据点进行预测，即在同一时间间隔内测量不同因素的数据点。

例如，您可能会对一家商店在节假日期间的销售和退货情况感兴趣。下表显示了两个通道中的一些条目，或记录数据的不同维度或方面。一个频道显示每天的销售额，另一个频道显示每天的退货率。

表2。销售和退货数据样本
日期	销售额（美元）	回报（美元）
2023 年 12 月 7 日	63,788美元	14,788美元
2023 年 12 月 8 日	105,678美元	25,678美元
...	...	...

虽然表格显示的是两天的观测数据，但您的请求必须包括 512 到 1,536 个数据点，具体取决于您使用的模型。 id_column字段被省略，因为数据来自同一系列，即来自单个商店的观察结果集合。将表格中的数据提交给应用程序接口时，其格式如下：

...
"data": {
"date": [
  "2024-12-07T00:00:00",
  "2024-12-07T00:00:00",
  "2024-12-08T00:00:00",
  "2024-12-08T00:00:00",
  ...
],
"sales": [
  63788,
  105678,
  ...
],
"returns": [
  14788,
  25678
  ...
]
}

您可以使用多个系列观测的多变量数据点进行预测。例如，您可以有效地将前两种情况结合起来，预测A店和B店的销售和回报。

请求中的数据可能如下所示：

"data": {
"date": [
  "2024-12-07T00:00:00",
  "2024-12-07T00:00:00",
  "2024-12-08T00:00:00",
  "2024-12-08T00:00:00",
  ...
],
"ids": [
  "A",
  "B",
  "A",
  "B",
  ...
],
"sales-usd": [
  24988, // sales for store A on 7 December 2024
  63788, // sales for store B on 7 December 2024
  41855,
  105678,
  ...
],
"returns": [
  3997, // returns for store A on 7 December 2024
  14788, // returns for store B on 7 December 2024
  5768,
  25678,
  ...
]

REST API示例

本例使用 granite-ttm-1536-96-r2 模型预测2024年9月30日至2024年12月2日期间葡萄牙每小时的总能源需求。示例中使用的数据集来自欧洲电力传输系统运营商网络（ENTSO-E）网站。要查看数据，请访问欧洲输电运营商协会（ENTSO-E）网站上的此页面，选择葡萄牙作为国家，然后选择2024年9月29日作为日期，并使用默认时区（CET）。

API请求未指定 prediction_length 参数。因此，使用基础模型的默认长度，这意味着时间序列模型将预测未来96小时内的能源需求值。

请求正文分为两部分：

模式：指定包含哪些数据集以及分析哪些字段。
数据：要分析的数据。

schema 部分如下所示：

"schema": {
      "freq": "1h",
      "timestamp_column": "Time (CET/CEST)",
      "target_columns": [
         "Actual Total Load [MW]"
      ]
   },

您可能会注意到，模式中不包含任何 id_columns 对象。在这个例子中，只提交了一个系列观测数据中的数据，这意味着可以从模式中省略 id_columns 对象。但是，如果您的请求包含来自多个来源的数据，则必须包含 id_columns 对象，以识别每个数据点的来源。

data 部分包含葡萄牙国家每小时能源需求量的信息，如下表所示。

表 3. 能耗数据样本
日期和时间（日期）	总能源需求（兆瓦）
2024-09-30T00:00:00	4941
2024-09-30T01:00:00	4640
2024-09-30T02:00:00	4443

granite-ttm-1536-96-r2 模型要求每个通道至少1536个数据点，以确保模型有足够的数据来预测未来的值。虽然表格中显示的是3个数据点，但请求正文中包含1536个数据点。

在下面的示例中，请添加您自己的承载令牌和项目ID。

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/time_series/forecast?version=2025-02-10' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${TOKEN}' \
  --data '{
    ...
    }'

数据有效载荷包含以下 JSON 代码段：

{
   "model_id": "ibm/granite-ttm-1536-96-r2",
   "project_id": "51f3a990-4372-4ac3-9ddb-ed99d9b50840",
   "schema": {
      "freq": "1h",
      "timestamp_column": "Time (CET/CEST)",
      "target_columns": [
         "Actual Total Load [MW]"
      ]
   },
   "data": {
      "Time (CET/CEST)": [
         "2024-09-30T00:00:00",
         "2024-09-30T01:00:00",
         "2024-09-30T02:00:00",
         "2024-09-30T03:00:00",
         "2024-09-30T04:00:00",
         "2024-09-30T05:00:00",
         "2024-09-30T06:00:00",
         "2024-09-30T07:00:00",
         "2024-09-30T08:00:00",
         "2024-09-30T09:00:00",
         "2024-09-30T10:00:00",
         "2024-09-30T11:00:00",
         "2024-09-30T12:00:00",
         ...
         < 1,536 input data points >
      ],
      "Actual Total Load [MW]": [
         4941.0,
         4640.0,
         4443.0,
         4259.0,
         4179.0,
         4132.0,
         4247.0,
         4706.0,
         5321.0,
         5989.0,
         6187.0,
         6073.0,
         6161.0,
         ...
         < 1,536 input data points >
      ]
   }
}

针对示例请求返回以下响应：

{
  "model_id": "ibm/granite-ttm-1536-96-r2",
  "created_at": "2025-02-05T14:00:53.597Z",
  "results": [
    {
      "Actual Total Load [MW]": [
        6465.83154296875,
        5847.07080078125,
        5351.2109375,
        5033.18212890625,
        4876.1064453125,
        4780.388671875,
        4784.177734375,
        4964.26171875,
        5416.59375,
        6017.84619140625,
        6571.35986328125,
        6776.26318359375,
        6817.2890625,
        ...
        < 96 output data points >
      ],
      "Time (CET/CEST)": [
        "2024-12-02T23:00:00",
        "2024-12-03T00:00:00",
        "2024-12-03T01:00:00",
        "2024-12-03T02:00:00",
        "2024-12-03T03:00:00",
        "2024-12-03T04:00:00",
        "2024-12-03T05:00:00",
        "2024-12-03T06:00:00",
        "2024-12-03T07:00:00",
        "2024-12-03T08:00:00",
        "2024-12-03T09:00:00",
        "2024-12-03T10:00:00",
        "2024-12-03T11:00:00",
        ...
        < 96 output data points >
      ]
    }
  ],
  "input_data_points": 1536,
  "output_data_points": 96
}

时间序列模型预测了未来96小时内葡萄牙能源需求的变化。

以下截图中的图表显示了同一时间段内预测能源需求与实际能源需求的对比。

显示实际与预计的每小时能源需求。

Python

您可以使用watsonx.ai Python库编写使用时间序列模型预测数据的代码。更多信息，请参阅以下参考资料：

要开始操作，请参阅以下示例笔记本：

使用 watsonx.ai 时间序列预测API预测能源需求

Node.js

您可以使用 watsonx.ai Node.js SDK 编写使用时间序列模型预测数据的代码。有关更多信息，请参阅以下资源：

TimeSeriesForecastParams 班级
timeseriesForecast 方法

要了解更多信息，请参阅代码示例。