ai-ml-timeseries

時系列予測 — 本番運用パターン

モデリングの前に予測カットオフを定義します。その時点で利用可能な情報だけを特徴量やベースラインに使用できます。意思決定に用いる現在の予測と、意思決定の対象となる予測期間でモデルを比較します。

対象範囲

• 一般的な EDA、テーブルデータのモデリング、実験設計、再利用可能なデータサイエンスのワークフロー → ai-ml-data-science
• デプロイアーキテクチャ、監視スタック、リリースゲート、インシデント対応手順 → ai-mlops
• 汎用的な LLM のライフサイクル、プロンプト作成、プロバイダー選定 → ai-llm
• RAG と検索システム → ai-rag

ワークフロー

1. まず、予測対象、予測期間、カットオフのタイムスタンプ、粒度、ビジネス上の損失の形状を定義します。
2. 予測に関する掘り下げが主な目的でない場合は、汎用的なデータサイエンスのワークフローや本番運用全般の作業を隣接するスキルに振り分けます。
3. 意思決定ツリーに基づいて、ベースライン、特徴量のパターン、モデルファミリーを選びます。
4. リークを防止したバックテストを実施し、予測期間を考慮した指標を比較します。不確実性を考慮した意思決定が必要な場合は、区間予測やキャリブレーションのチェックも追加します。
5. パッケージやチェックポイントを選ぶ前に、data/sources.json から公式ドキュメントを開き、インストール済み API、対応する共変量、コンテキストと予測期間の制限、重みのライセンスを確認します。TSFM を比較する場合は、モデルの役割と検索手順を読み込み、引用する順位の横にベンチマークのスナップショットを記録します。MAPIE のコードを使う場合は、確率的予測のパターンを読み込み、例をインストール済みリリースのドキュメントと照合します。

クイックリファレンス

予測パターンを選ぶ

Need to build or review a forecast:
    ├─ One series or a small local portfolio?
    │   ├─ Few covariates, interpretability first -> naive/seasonal naive + ETS/SARIMAX baseline
    │   └─ Nonlinear effects or richer covariates -> feature-based boosting
    │
    ├─ Many related series?
    │   ├─ Need one shared model with covariates -> global/panel forecasting
    │   └─ Need rollups to add up across levels -> hierarchical forecasting + reconciliation
    │
    ├─ Intermittent or zero-heavy demand?
    │   ├─ Very sparse and operationally simple -> Croston/SBA/ADIDA baseline
    │   └─ Need richer covariates or scale -> global boosting with zero-aware features
    │
    ├─ Need uncertainty, service levels, or inventory decisions?
    │   └─ Add quantiles, conformal intervals, or distributional forecasts
    │
    ├─ Long horizon or low-feature setup?
    │   ├─ Need strong zero-shot baseline -> TS foundation models
    │   └─ Need supervised optimization on many series -> global/deep forecasting
    │
    └─ Need production handoff?
        └─ Record cutoff timestamp, feature contract, fallback, lineage, and retraining trigger

基本原則

1. 特徴量より先にカットオフのタイムスタンプを決める

• ラベルや特徴量を作成する前に、正確な予測タイムスタンプを定義します。
• すべてのラグ、ローリング集計、カレンダーフラグ、外部シグナルについて、そのカットオフ時点で何が分かっているかを基準に妥当性を確認します。
• 既知の将来共変量と、将来時点では不明な共変量は、異なるものとして扱う必要があります。

2. まずはベースラインから

• 各予測起点で把握できている値を使い、同じ予測期間でスコアを算出したナイーブベースラインと季節ナイーブベースラインを必ず比較します。後の実績値を使って作成したベースラインは、未来の情報が漏洩しています。
• 解釈しやすさが重要な場合は、ETS／SARIMAX などの局所的な古典的ベースラインも追加します。
• 単純なベースラインをわずかに上回るだけの候補モデルを、本番環境に導入してはいけません。
• ナイーブと季節ナイーブは最低ラインです。昇格の基準は、プランナーによる調整も含め、意思決定に現在使われている予測です。同じ予測起点でスコアを算出します。調整の価値も測定できるよう、調整内容は別個の予測として記録します。
• 点予測のスキル向上はスクリーニングであり、昇格の根拠ではありません。意思決定の予測期間における、予測起点ごとの損失差に対する対応のある検定でゼロが除外された場合にのみ昇格させます（対応のある昇格検定）。

3. 予測期間とセグメント別の評価

• 単一の全体スコアだけでなく、予測期間ごとに精度を報告します。
• セグメント、地域、SKU ファミリー、販売量の区分、その他ビジネス上重要なコホートごとに分けて評価します。
• ゼロまたはゼロに近い値がある場合は、間欠系列を除き、MAPE よりも MASE／WAPE／MAE を優先します。
• 期間の半分を超える値がゼロの場合、MAE、WAPE、MASE では全期間ゼロの予測が有利になります（これらの指標は中央値で最小化されます）。平均値の予測は RMSSE で、在庫補充の意思決定はピンボール損失で選びます。MAE や WAPE だけを根拠に選んではいけません（間欠需要で標準的な指標が誤解を招く場合）。
• 各予測期間について、その期間のベースラインに対するスキルで評価します。予測期間が長くなるにつれて誤差が大きくなるのは想定内であり、それだけで欠陥とはなりません。

4. 系列ごとの複雑なモデルより、グローバル／パネル方式を優先

• 関連する系列が多数ある場合は、個別に専用モデルを構築する前に、共有のグローバル／パネル方式をまず検討します。
• 予測の階層間の整合性を保つ必要がある場合は、階層的な整合化を使用します。
• 精度、キャリブレーション、または運用の簡素化に貢献する場合にのみ、複雑さを高めます。

5. 意思決定にリスクが伴う場合は確率的予測を使用

• 不確実性が下流のアクションに影響する場合は、分位点、コンフォーマル予測区間、または完全な予測分布を使用します。
• カバレッジと鋭さの両方を評価します。公称カバレッジを満たす幅の広い区間が、必ずしも有用とは限りません。
• 独立したカバレッジ結果が共通の確率に従う場合に限り、Wilson 区間を使って各予測期間のカバレッジをスクリーニングします。異なる予測起点があるだけでは、独立性は確認できません。残差に依存性がある場合は、採用前にブロック単位または系列単位の根拠が必要です。プールしたカバレッジは記述的なものとして扱い、集中して発生する予測誤差を確認します（ノイズに対するカバレッジ）。
• 意思決定コストから意思決定分位点 q* = c_u / (c_u + c_o) を設定し、ピンボール損失と予測期間ごとのカバレッジで評価します（コストから求める意思決定分位点）。
• 再学習やモデルの大幅な変更のたびに、キャリブレーションを再評価します。

6. 予測に特化した引き継ぎ

• 予測パッケージには、カットオフ時刻、予測期間の定義、特徴量の契約、指標の定義、フォールバックルール、系譜メタデータを含める必要があります。これらがなければ不完全です。
• 予測に特化した引き継ぎのガイダンスはここに記載し、デプロイアーキテクチャ全体については ai-mlops を参照します。

予測の意思決定ゲート

バックテストの各フォールドについて、学習の終了時点、予測起点、予測期間、特徴量の利用可能性、再学習ポリシー、改訂または公開の遅延を記録したカットオフ台帳を作成します。集約する前に、予測期間ごと、および意思決定上重要なセグメントごとに、誤差と区間品質を報告します。現在使用中の予測（プランナーによる調整を含む）と比べて、ビジネス上の重み付け損失が改善し、予測起点をまたいだ対応のある検定で改善が確認され、かつ阻害要因となるセグメントを隠していない場合にのみ、予測を採用します。共変量が欠損または遅延した場合のフォールバックもテストする必要があります。ナイーブまたは季節ナイーブな基準を上回ることは必要ですが、それだけでは決して十分ではありません。

既知の落とし穴

• 将来既知の共変量と将来未知の共変量を、予測時点で実際に利用できる値を文書化しないまま、同じ特徴量経路に混在させること。
• 予測期間によって誤差の挙動が大きく異なるにもかかわらず、単一のグローバルなバックテストスコアをデプロイの根拠にすること。
• ゼロが多い、間欠的、またはゼロに近い系列に MAPE を使用し、不安定なパーセンテージでモデルを比較すること。
• 関連する系列に対して強力なグローバルまたはパネルのベースラインを試す前に、系列ごとの専用モデルを構築すること。
• 下流の利用者がロールアップの合計一致を期待しているにもかかわらず、階層と整合性を無視すること。

よくあるアンチパターン

• ローリング起点評価や拡張ウィンドウ評価ではなく、汎用的な表形式 ML の IID 検証の習慣を流用すること。
• 分解の可視化を、本番環境でのシグナルの証拠として扱い、実際の意思決定期間をバックテストしないこと。
• 将来の共変量が利用できない、または運用上の維持コストが高すぎる、特徴量の多いモデルを使用すること。
• TS 基盤モデルを弱いベースラインと比較し、その結果を戦略的な証明と見なすこと。
• チェックポイントの重みのライセンスを確認し、非公開データまたはカットオフ後のデータで再テストする前に、TSFM のゼロショットの勝利を信頼すること（TSFM の信頼ゲート）。

ナビゲーション：主要リファレンス

データの完全性と特徴量

• TS EDA のベストプラクティス - タイムスタンプの完全性、欠損、分解、安定性のチェック
• ラグとローリングのパターン - リークを防ぐラグ、ローリングウィンドウ、カレンダーパターン
• グローバル予測とパネル予測のパターン - 共有モデル、パネルスキーマ、既知の将来共変量、グループ化評価

モデルと戦略の選択

• モデル選択ガイド - モデルファミリーの選択マトリクス
• LightGBM の時系列パターン - 特徴量ベース／グローバルなブースティングのパターン、MLForecast／skforecast のワークフロー
• 複数ステップ予測のパターン - ダイレクト、再帰、seq2seq のトレードオフ
• 間欠需要のパターン - スパース需要のベースラインとゼロを考慮したモデリング

検証、不確実性、高度な予測

• バックテストのパターン - ローリングオリジン評価、パネルを考慮したバックテスト、指標設計
• 確率的予測 - 分位点、コンフォーマル手法、キャリブレーション、スコアリングルール
• 階層的予測 - 整合性のある予測と調整手法
• 時系列基盤モデルのパターン - TSFM の役割、信頼性ゲート（ライセンス、汚染）、ゼロショットベンチマーク
• 異常検知のパターン - 残差および区間ベースの異常検知ワークフロー

引き継ぎと予測運用

• 予測ガバナンスのパターン - カットオフのタイムスタンプ、系統、フォールバックルール、予測契約
• 本番環境での予測運用 - バックテストに対する予測期間を一致させたライブ監視、実績値の遅延、正式な予測、フォールバックの段階的適用

テンプレート

データの準備

• TS EDA テンプレート - タイムスタンプと季節性をレビューするための再現可能な構成
• リサンプリングと補完のテンプレート - リサンプリング、ギャップのルール、補完ポリシー

特徴量とモデルの設計

• ラグとローリング特徴量 - リークを防ぐ特徴量仕様
• カレンダー特徴量 - 既知の将来の業務カレンダーとイベント特徴量の仕様
• 予測モデルテンプレート - ローカル、グローバル、階層型モデル向けの予測パッケージ契約
• 複数ステップ戦略 - ダイレクト、再帰、seq2seq 戦略の契約

評価と不確実性

• バックテストテンプレート - ローリングオリジンまたは拡張ウィンドウによる評価仕様
• TS 指標テンプレート - 予測期間、スライス、業務上の損失、確率的指標の契約

基盤モデル

• TS 基盤モデルテンプレート - ゼロショット TSFM ベンチマークと評価のひな形

スクリプト

スクリプト	目的
scripts/ts_evaluator.py	標準ライブラリのみを使用する CLI：origin_value を基にした予測期間別の指標と naive／seasonal-naive に対するスキル（起点が 6 未満の場合は判定なし）、独立性を仮定した予測期間別の Wilson スクリーニング、説明的なプール済みカバレッジ、Markdown レポートを出力します。入力が無効な場合、区間レベルが一部のみ指定された場合、または --output に書き込めない場合は 2 で終了します。「ベースラインを上回る」はスクリーニングであり、採用前に対応のある検定を実行してください

# Horizon-wise accuracy: MAE, RMSE, MAPE, MASE, skill vs the baseline at the same horizon (invalid input exits 2)
python scripts/ts_evaluator.py backtest --input data/sample-forecast-results.json

# Per-horizon calibration screen for 50%, 80%, 90% prediction intervals; pooled coverage is descriptive
python scripts/ts_evaluator.py calibration --input data/sample-forecast-results.json

# Full Markdown evaluation report written to file
python scripts/ts_evaluator.py report --input data/sample-forecast-results.json --output /tmp/ts-eval-report.md

データファイル

ファイル	説明
data/sources.json	古典的な予測、MLForecast、skforecast、AutoGluon、TSFM リポジトリ、fev-bench、MAPIE の厳選された一次情報源
data/sample-forecast-results.json	日次売上予測の合成ローリングオリジン・バックテスト。予測期間は 1、7、14、30 日、48 行、12 個のオリジンで、origin_value と MASE 用のインサンプル履歴を含みます

外部ソース

現在の一次情報源については、data/sources.json を参照してください。次の内容が含まれています。

• 古典的な予測に関する参考資料
• MLForecast、HierarchicalForecast、skforecast、AutoGluon TimeSeries、LightGBM、MAPIE の公式ドキュメント
• 公式 TSFM リポジトリおよびモデルカード
• 高影響度のデプロイで使用する fev-bench のベンチマークおよびガバナンスに関する参考資料

関連スキル

• ai-ml-data-science - 一般的な DS ワークフロー、実験設計、およびより幅広いモデリングパターン
• ai-mlops - デプロイアーキテクチャ、モニタリング、リリース運用
• ai-llm - 時系列予測以外のプロバイダー／モデルのライフサイクルに関する質問
• data-sql-optimization - 時系列データマートのストレージとクエリの設計

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替手段としてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶に残す価値のあるパターン、再発を防ぐべきミス、または意外だったドメイン知識があれば、agents-skills-feedback-loop/scripts/append_learning.py を使用して、日付付きの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。