ai_forecast 函式

適用於：已勾選「是」 Databricks SQL

重要

此功能的第 1 版已公開 預覽 並符合 HIPAA 規範。 推薦版本 2 目前為 測試版。

ai_forecast() 是一個表值函數，能將時間序列資料向前推推。 如需設定此函式的可用引數，請參閱引數。

此函式有兩個版本。 第二版採用研究優化的時間序列基礎模型，提升開箱即用的準確度，第二版則新增假日、外部協變量及非負預報支援。 用參數 version 選擇執行的版本。 詳情請參見 論證 。

要求

  • Pro 或 無伺服器 SQL 資料倉儲
  • 將您的工作空間註冊到 預測 AI 功能 預覽（推薦版本 2 為必備）。 請參閱 管理 Azure Databricks 預覽。

語法

Tip

Azure Databricks recommends version 2 for ai_forecast. 版本 2 相較於版本 1 提供了以下改進：

  • 一個研究優化的時間序列基礎模型，旨在提升開箱即用的準確度
  • 內建節日支援 holiday_region
  • 外部協變量，包括未來與僅過去的協變量，且 covariate_col
  • 非負預報 positive_only

使用版本 2 時，請傳遞 version => '2'。 請確保您已啟用 預測 AI 功能 預覽。 請參閱 管理 Azure Databricks 預覽。

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, covariate_col] [, prediction_interval_width]
  [, frequency] [, holiday_region] [, positive_only] [, version])

第 1 版

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, prediction_interval_width] [, frequency]
  [, seed] [, parameters] [, version])

引數

ai_forecast() 可以預測任意數目的群組 (請參閱 group_col) 和每個群組中最多 100 個計量 (請參閱 value_col)。 同一群組中所有指標的預測頻率相同，但不同群組間可能有所不同（參見 frequency）。

  • observed 是用作預測程序訓練數據的表格數據輸入。
    • 此輸入關係必須包含一個「時間」欄位及一個或多個「值」欄位。 「群組」與「協變量」欄位為可選。 輸入關聯中的任何額外數據行會被忽略。
  • horizon 是一個可轉換為時間戳記的數量，表示預測結果的唯一正確結束時間。 在一個群組 (請參閱 group_col) 中，預測結果的時間範圍是從上次觀測到預測期。 如果邊際小於上次觀測時間，則不會產生任何結果。
  • time_col 是參考 中 observed「時間欄位」的字串。 所 time_col 參考的欄位必須是 a DATE 或 TIMESTAMP。
  • value_col 是字串或字串陣列，參考 observed中的數值列。 此參數所參考的欄位必須可鑄造成 DOUBLE。
  • group_col （選擇性） 是字串或字串陣列，代表 observed中的群組數據行。 如果指定，則會使用群組數據行做為分割準則，而且會針對每個群組獨立產生預測。 如果未指定，則完整輸入資料將視為單一群組。
  • covariate_col （可選）是參考外部共變量欄位 observed的字串或字串陣列。 協變數是影響預報的其他變數，例如價格、行銷支出或天氣。 支援兩種協變量：
    • 未來協變數：預測期內的數值已知，例如計畫定價或排程廣告活動。 要以此方式使用協變數，請在中加入涵蓋預測視界（最後一次觀測之後的日期，最多到 observed）的列horizon，並填入協變量，value_col欄位則留在 NULL。 ai_forecast 預測這些 NULL-target 列，並以其協變數值為條件。
    • 僅過去的協變量：數值僅適用於歷史期間，例如觀測到的天氣或宏觀經濟指標。 只在歷史列中填充協變數。 如果你沒有在預測範圍內提供協變數值，而是 ai_forecast 僅將協變數作為過去值使用;這不是錯誤。
  • prediction_interval_width (選用) 是一個介於 0 和 1 之間的值，表示預測間隔的寬度。 預測值有 prediction_interval_width % 機率落在 {v}_upper 與 {v}_lower之間。
  • frequency（可選）是 pandas 偏移別名字串（例如 'D'， ， 'W''ME'， 'H'） 用以指定預報結果的時間細節。 如果未指定，則會自動為每個群組單獨推斷預測細微性。 若指定，必須與各組內輸入資料的推斷細度相符。
    • 群組內推斷的頻率是最近觀測的模式。 這種推論是一種方便操作，使用者無法調整。
    • 例如，一個包含99個「星期一」和1個「星期二」的時間序列，推斷出的「週」即為頻率。
  • holiday_region （可選）是一個區域代碼，能自動模擬該區域的節日效應，例如 'US'。 若未指定，則不模擬假日效應。
  • positive_only （可選）當設為 TRUE時，會限制預測值為非負值。 這個論點可以用在不能為負的指標上，例如銷售、盤點或庫存。 預設值為 FALSE。
  • version （可選）：版本切換以支援遷移（'1' 針對版本 1 行為， '2' 針對版本 2 行為）。 若未指定，則預設為版本 1。 版本 2 的參數 （covariate_col， holiday_region， positive_only） 需要 version => '2'。

第 1 版

  • observed 是用作預測程序訓練數據的表格數據輸入。
    • 此輸入關係必須包含一個「時間」欄位及一個或多個「值」欄位。 「群組」和「參數」欄位是可選的。 輸入關聯中的任何額外數據行會被忽略。
  • horizon 是一個可轉換為時間戳記的數量，表示預測結果的唯一正確結束時間。 在一個群組 (請參閱 group_col) 中，預測結果的時間範圍是從上次觀測到預測期。 如果邊際小於上次觀測時間，則不會產生任何結果。
  • time_col 是參考 中 observed「時間欄位」的字串。 所 time_col 參考的欄位必須是 a DATE 或 TIMESTAMP。
  • value_col 是字串或字串陣列，參考 observed中的數值列。 此參數所參考的欄位必須可鑄造成 DOUBLE。
  • group_col （選擇性） 是字串或字串陣列，代表 observed中的群組數據行。 如果指定，則會使用群組數據行做為分割準則，而且會針對每個群組獨立產生預測。 如果未指定，則完整輸入資料將視為單一群組。
  • prediction_interval_width (選用) 是一個介於 0 和 1 之間的值，表示預測間隔的寬度。 預測值有 prediction_interval_width % 機率落在 {v}_upper 與 {v}_lower之間。
  • frequency （選擇性） 是時間單位或 pandas 位移別名字符串，指定預測結果的時間粒度。 如果未指定，則會自動為每個群組單獨推斷預測細微性。 如果已指定頻率值，則會同樣套用至所有群組。
    • 群組內推斷的頻率是最近觀測的模式。 這種推論是一種方便操作，使用者無法調整。
    • 例如，一個包含99個「星期一」和1個「星期二」的時間序列，推斷出的「週」即為頻率。
  • seed （可選）是用來啟動預測過程中任何偽隨機數產生器的數字。
  • parameters （選擇性） 是字串編碼的 JSON 或數據行標識碼的名稱，代表預測程式的參數化。 任何參數組合都可以依任何順序指定，例如，{"weekly_order": 10, "global_cap": 1000}。 任何未指定的參數都會根據定型數據的屬性自動決定。 支援下列參數：
    • global_cap 和 global_floor 可以一起使用，或單獨用來定義計量值的可能定義域。 例如，{"global_floor": 0} 可用於限制成本等計量一律為正數。 這些限制適用於訓練資料與預測資料，無法僅對預測值提供嚴格約束。
    • daily_order 和 weekly_order 設定每日和每週季節性成分的傅立葉階數。
  • version （可選）：版本切換以支援遷移（'1' 針對版本 1 行為， '2' 針對版本 2 行為）。 若未指定，則預設為版本 1。 版本 2 的參數 （covariate_col， holiday_region， positive_only） 需要 version => '2'。

退貨

包含預測數據的新數據列集。 輸出結構包含時間欄與群組欄位，且其類型未變。 例如，若輸入時間欄位的型別 DATE為 ，則輸出時間欄位的類型也是 DATE。 針對每個值資料列，有三個輸出資料列具有模式 {v}_forecast、{v}_upper和 {v}_lower。 不論輸入值類型為何，預測的值資料行一律是類型 DOUBLE。 輸出表僅包含預測值，涵蓋從觀測數據結束到視界的時間範圍。

下表展示了AI_FORECAST所執行的模式推論範例：

輸入數據表 引數 輸出數據表
ts: TIMESTAMP
val: DOUBLE		 time_col => 'ts'
value_col => 'val'		 ts: TIMESTAMP
val_forecast: DOUBLE
val_upper: DOUBLE
val_lower: DOUBLE
ds: DATE
val BIGINT		 time_col => 'ds'
value_col => 'val'		 ds: DATE
val_forecast: DOUBLE
val_upper: DOUBLE
val_lower: DOUBLE
ts: TIMESTAMP
dim1: STRING
dollars: DECIMAL(10, 2)		 time_col => 'ts'
value_col => 'dollars'
group_col => 'dim1'		 ts: TIMESTAMP
dim1: STRING
dollars_forecast: DOUBLE
dollars_upper: DOUBLE
dollars_lower: DOUBLE
ts: TIMESTAMP
dim1: STRING
dim2: BIGINT
dollars: DECIMAL(10, 2)
users: BIGINT		 time_col => 'ts'
value_col => ARRAY('dollars', 'users')
group_col => ARRAY('dim1', 'dim2')		 ts: TIMESTAMP
dim1: STRING
dim2: BIGINT
dollars_forecast: DOUBLE
dollars_upper: DOUBLE
dollars_lower: DOUBLE
users_forecast: DOUBLE
users_upper: DOUBLE
users_lower: DOUBLE

第 1 版

包含預測數據的新數據列集。 輸出結構包含時間欄與群組欄位，且其類型未變。 例如，若輸入時間欄位的型別 DATE為 ，則輸出時間欄位的類型也是 DATE。 針對每個值資料列，有三個輸出資料列具有模式 {v}_forecast、{v}_upper和 {v}_lower。 不論輸入值類型為何，預測的值資料行一律是類型 DOUBLE。 輸出表僅包含預測值，涵蓋從觀測數據結束到視界的時間範圍。

下表展示了AI_FORECAST所執行的模式推論範例：

輸入數據表 引數 輸出數據表
ts: TIMESTAMP
val: DOUBLE		 time_col => 'ts'
value_col => 'val'		 ts: TIMESTAMP
val_forecast: DOUBLE
val_upper: DOUBLE
val_lower: DOUBLE
ds: DATE
val BIGINT		 time_col => 'ds'
value_col => 'val'		 ds: DATE
val_forecast: DOUBLE
val_upper: DOUBLE
val_lower: DOUBLE
ts: TIMESTAMP
dim1: STRING
dollars: DECIMAL(10, 2)		 time_col => 'ts'
value_col => 'dollars'
group_col => 'dim1'		 ts: TIMESTAMP
dim1: STRING
dollars_forecast: DOUBLE
dollars_upper: DOUBLE
dollars_lower: DOUBLE
ts: TIMESTAMP
dim1: STRING
dim2: BIGINT
dollars: DECIMAL(10, 2)
users: BIGINT		 time_col => 'ts'
value_col => ARRAY('dollars', 'users')
group_col => ARRAY('dim1', 'dim2')		 ts: TIMESTAMP
dim1: STRING
dim2: BIGINT
dollars_forecast: DOUBLE
dollars_upper: DOUBLE
dollars_lower: DOUBLE
users_forecast: DOUBLE
users_upper: DOUBLE
users_lower: DOUBLE

範例

以下範例使用版本2預測至指定日期：


WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  version => '2'
)

以下範例模擬了美國的假期效應，並將預測限制為非負值：


WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  holiday_region => 'US',
  positive_only => true,
  version => '2'
)

以下範例使用外部協變量。 observed表格（daily_sales）包含promotion一個同時填充歷史期間與預報視界的欄位，revenue預報視界列中左側NULL，因此promotion用作未來協變數：


SELECT * FROM AI_FORECAST(
  TABLE(daily_sales),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  covariate_col => 'promotion',
  version => '2'
)

第 1 版

下列範例預測截止指定日期之前的情況：


WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue'
)

以下是更複雜的範例：


WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    dropoff_zip,
    SUM(fare_amount) AS revenue,
    COUNT(*) AS n_trips
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1, 2
),
spine AS (
  SELECT all_dates.ds, all_zipcodes.dropoff_zip
  FROM (SELECT DISTINCT ds FROM aggregated) all_dates
  CROSS JOIN (SELECT DISTINCT dropoff_zip FROM aggregated) all_zipcodes
)
SELECT * FROM AI_FORECAST(
  TABLE(
    SELECT
      spine.*,
      COALESCE(aggregated.revenue, 0) AS revenue,
      COALESCE(aggregated.n_trips, 0) AS n_trips
    FROM spine LEFT JOIN aggregated USING (ds, dropoff_zip)
  ),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => ARRAY('revenue', 'n_trips'),
  group_col => 'dropoff_zip',
  prediction_interval_width => 0.9,
  parameters => '{"global_floor": 0}'
)

注意

ai_forecast 不會將表格中缺失的或 NULL 條目的值填補為 0。 如果能推斷出缺失元素的正確值，則必須在呼叫 ai_forecast 函數前將它們合併。 如果值確實遺失或未知，您可以將值保留為 NULL 或移除這些值。

對於稀疏資料，最佳做法是整合缺失值或明確提供頻率值，以避免「自動」頻率推論產生意外輸出。 例如，對兩個相隔14天的條目進行「自動」頻率推斷，即使「真實」頻率可能是每週一次且缺失1個值，也會推斷出「14D」頻率。 合併遺失的項目會消除這種歧義。

以下範例展示了輸入表中不同群組如何應用不同的預報參數。 此範例使用 parameters 自變數作為數據行標識符。 此方法讓使用者能將先前確定的參數 JSON 儲存在資料表中，並在新資料中重複使用。

WITH past AS (
  SELECT
    CASE
      WHEN fare_amount < 30 THEN 'Under $30'
      ELSE '$30 or more'
    END AS revenue_bucket,
    CASE
      WHEN fare_amount < 30 THEN '{"daily_order": 0}'
      ELSE '{"daily_order": "auto"}'
    END AS parameters,
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM samples.nyctaxi.trips
  GROUP BY ALL
)
SELECT * FROM AI_FORECAST(
  TABLE(past),
  horizon => (SELECT MAX(ds) + INTERVAL 30 DAYS FROM past),
  time_col => 'ds',
  value_col => 'revenue',
  group_col => ARRAY('revenue_bucket'),
  parameters => 'parameters'
)

限制

測試期間適用以下限制：

  • 版本 2 目前還在 Beta 階段，並非預設版本。 要使用版本 2，請透過設定 version => '2'選擇加入。 版本 1 目前處於公開預覽階段，仍是預設版本。
  • 預設的預測程序是時間序列基礎模型。 此模型是目前唯一被支援的預測程序。
  • 錯誤訊息透過 Python UDTF 引擎傳遞，並包含 Python 回溯資訊。 回溯結尾包含實際的錯誤訊息。
  • 每次呼叫 的 ai_forecast 執行獨立推理。 如果你多次呼叫 ai_forecast 不同 prediction_interval_width 值以產生巢狀預測區間，所得區間無法保證巢狀。 比較預測區間時，使用一個值的ai_forecast單一prediction_interval_width呼叫。

第 1 版

公開預覽期間適用以下限制：

  • 版本 1 目前為公開預覽版，為預設版本。 版本 2 目前為 Beta 版，可透過設定 version => '2'取得。
  • 版本 1 正在棄用路徑上。 在即將推出的版本中，預設版本會改為版本 2，而版本 1 則被棄用。 若要在預設變更後繼續使用版本 1 的行為，請透過設定 version => '1'釘選 。
  • 預設的預測操作使用了一種類似 Prophet 的分段線性與季節性模型。 此模型是目前唯一被支援的預測程序。
  • 錯誤訊息透過 Python UDTF 引擎傳遞，並包含 Python 回溯資訊。 回溯結尾包含實際的錯誤訊息。
  • 每次呼叫 都會 ai_forecast 執行獨立的分位數迴歸。 如果你多次呼叫 ai_forecast 不同 prediction_interval_width 值以產生巢狀預測區間，所得區間無法保證正確巢狀，因為分位數是跨呼叫獨立計算，且沒有約束來驗證正確排序。 比較預測區間時，使用一個值的ai_forecast單一prediction_interval_width呼叫。
  • 上次更新時間：