IBM Granite 時系列基盤モデルモデルと予測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日を意味するのか？ ISO 8601 形式で協定世界時（UTC）オフセット付きの日付を指定することで（ 2024-11-12T15:06:35+0000 ）、生成された予測結果におけるタイムスタンプの重複や欠落を回避することができます。

• 一定の頻度でデータをサンプリングする。 例えば、データは1分、1時間、1日単位で観測できる。 タイムスタンプが一様でなくてもエラーは発生しませんが、結果の質は悪くなるかもしれません。 生成された予測データは、「freqパラメータで指定した頻度でフォーマットされる。

  たとえば、頻度を1日（"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",
  ...
  ]
  

  頻度パラメータにおける日付と時刻の省略形のサポート対象の値については、pandasライブラリのドキュメントの 「期間の別名」 を参照してください。

• 分析のために複数のソースからデータポイントを含める場合、各データポイントは、それがどのシリーズ、または観測値の集合に属するかを表す固有の識別子を提供しなければなりません。

  例えば、ショッピングの傾向を分析する場合、ホリデーシーズン中の複数店舗の売上高に興味を持つかもしれない。 次の表は、AとBの2つのシリーズを示しています。 シリーズAはロケーションAの1日あたりの売上を示し、シリーズBはロケーションBの1日あたりの売上を示しています。

  表 1. サンプル販売データ

  日付	シリーズID	売上合計（米ドル）
  7 2023年12月	A	$24,988
  7 2023年12月	B	$63,788
  2023年12月8日	A	$41,855
  2023年12月8日	B	$105,678
  ...	...	...

  表は2日間のオブザベーションを示していますが、使用するモデルによって、リクエストには512から1,536のデータポイントを含める必要があります。 テーブルのデータがAPIに送信されると、以下のようにフォーマットされる：

  ...
  "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つのチャンネル、または記録されたデータの異なる次元や側面からのいくつかのエントリーを示しています。 一方のチャンネルには1日あたりの売上高が表示され、もう一方のチャンネルには1日あたりの返品数が表示されます。

  表 2. 売上と返品データのサンプル

  日付	売上高（米ドル）	リターン（米ドル）
  7 2023年12月	$63,788	$14,788
  2023年12月8日	$105,678	$25,678
  ...	...	...

  表は2日間のオブザベーションを示していますが、使用するモデルによって、リクエストには512から1,536のデータポイントを含める必要があります。 id_columnフィールドは省略されています。なぜなら、データは同じ系列、つまり単一の店舗からの観測値の集合から取得されているからです。 テーブルのデータがAPIに送信されると、以下のようにフォーマットされる：

  ...
  "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の両方の売上と返品を予測するために、前の2つのシナリオを効果的に組み合わせることができます。

  リクエスト内のデータは、以下のようなものになるかもしれません

  "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日までのポルトガルにおける1時間ごとの総エネルギー需要を予測します。 この例で使用されているデータセットは、 欧州送電系統運用者ネットワーク（ENTSO-E） のウェブサイトから取得されています。 データをご覧になるには、ENTSO-Eサイトのこのページにアクセスし、国としてポルトガルを選択し、日付として2024年9月29日、デフォルトのタイムゾーン（CET）を選択してください。

APIリクエストには prediction_length パラメータが指定されていません。 したがって、デフォルトの長さが基盤モデルに使用され、時系列モデルは今後96時間分のエネルギー需要の将来値を予測することになります。

リクエストボディは2つのセクションに分かれている：

• スキーマ：どのデータセットを含み、どのフィールドを分析するかを指定する。
• データ：分析するデータ。

schema のセクションは次のようになります

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

id_columns オブジェクトがスキーマに含まれていないことに気づくかもしれません。 この例では、観測データの1つの系列からのデータのみが送信されるため、 id_columns オブジェクトはスキーマから省略することができます。 ただし、リクエストに複数のソースからのデータが含まれる場合は、各データポイントのソースを識別するための id_columns オブジェクトを含める必要があります。

data のセクションには、ポルトガルという国における1時間ごとのエネルギー需要に関する情報が含まれています。次の表に示されているとおりです。

granite-ttm-1536-96-r2 モデルでは、モデルが将来の値を予測するのに十分なデータがあることを保証するために、リクエストにはチャンネルごとに少なくとも1,536のデータポイントが必要です。 表には3つのデータポイントが示されていますが、リクエスト本文には1,536のデータポイントが含まれています。

以下の例では、独自のベアラートークンとプロジェクトIDを追加します。

curl -X POST \
  'https://{region}.ml.cloud.ibm.com/ml/v1/time_series/forecast?version=2025-02-10' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQiOi...' \
  --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時間におけるポルトガルのエネルギー需要の将来値を予測した。

次のスクリーンショットのグラフは、同じ期間における実際のエネルギー需要と予測されたエネルギー需要を比較したものです。