📓
Node-AI モデルAPIサービス よくあるご質問（FAQ）
1. AIモデルの不変性と再学習の仕様Q1-1. 推論APIを呼び出すたびに、AIモデルは自動的に再学習されますか？Q1-2. 学習APIでは何ができますか？どこまでが固定されるのでしょうか？2. 推論APIで実行される前処理とNode-AI分析ツリーの対応Q2-1. 推論API実行時に、Node-AI上のどの前処理カードが実行されますか？Q2-2. 学習時にだけ有効な前処理（データ分割、ラグ特徴量、欠損値線形補間、統計量追加など）はどう扱えばよいですか？3. APIに送るデータの形式Q3-1. 学習APIにはどのようなCSV／データを送ればよいですか？Q3-2. 推論APIにはどのようなCSV／データを送ればよいですか？Q3-3. 推論APIに目的変数のカラムは送る必要がありますか？Q3-4. 推論したい時刻の1行だけ送ればよいですか？それとも過去データも必要ですか？Q3-5. APIに送れるデータサイズに上限はありますか？4. レスポンス内の時刻の意味Q4. 推論APIのレスポンスに含まれる時刻は何を表していますか？5. ジョブのポーリング（処理時間・間隔）Q5-1. 推論ジョブ・学習ジョブの完了までどれくらい時間がかかりますか？Q5-2. ポーリングはどのように設計すべきですか？マニュアルのwhile文サンプルをそのまま使ってよいですか？Q5-3. 同期的なレスポンス（リクエスト即時に結果）を返すモードはありますか？
このページは Node-AI モデルAPIサービス（学習API・推論API） をご利用いただく際に、お客様からよくいただくご質問をまとめたものです。基本的な利用手順は「Node-AI モデルAPIサービスの概要 」をあわせてご参照ください。
1. AIモデルの不変性と再学習の仕様
Q1-1. 推論APIを呼び出すたびに、AIモデルは自動的に再学習されますか？
A. いいえ、推論APIの呼び出しだけでは再学習は行われません。
- Node-AI上で「AIモデルを作成」した時点で、学習済みパラメータ（重み）と前処理パイプラインが固定されます。
- 推論APIは、その固定されたモデルを呼び出して推論結果を返すだけであり、入力データを使った追加学習は一切行いません。
- 新しいデータでモデルを更新したい場合は、学習APIを使って明示的に再学習を実行するか、Node-AIのアプリ画面上であらためてAIモデルを作り直してください。
Q1-2. 学習APIでは何ができますか？どこまでが固定されるのでしょうか？
A. 学習APIは、AIモデル作成時に決めたハイパーパラメータと前処理パイプラインをそのまま使用し、学習データだけを差し替えてモデルを再生成するための仕組みです。
学習APIでできること
- 新しい学習データを使ってモデルを再学習する
- 再学習したモデルを、同じ推論APIエンドポイントから呼び出せる状態にする
学習APIではできないこと
- ハイパーパラメータの探索・変更
- 分析ツリー（前処理パイプライン）の構造変更
- 説明変数・目的変数のカラム構成の変更
モデルの精度劣化（コンセプトドリフト）への対策として「同じツリー構成で定期的にデータだけ差し替えて再学習」したいケースでは学習APIが適しています。ハイパーパラメータを見直したい場合やツリー構造を変えたい場合は、Node-AIのアプリ画面上でAIモデルを作り直してください。
2. 推論APIで実行される前処理とNode-AI分析ツリーの対応
Q2-1. 推論API実行時に、Node-AI上のどの前処理カードが実行されますか？
A. AIモデル作成時に指定した「学習カード」から遡り、その祖先にあたる一連の前処理カード（データカード〜学習カードまでの一本のパス）が実行されます。
- AIモデルは「学習カード」を指定して作成します。
- 推論時には、その学習カードの上流（祖先）に連なる前処理カード群が、学習時と同じ順序で実行されます。
- データカードから学習カードまでの一本のパイプラインが、推論時の前処理パスです。
- 学習APIについても同様で、同じ「学習カードの祖先パス」が学習データに適用されます。
分析ツリーが複雑に見える理由
- データカードやデータ分割カードから複数の枝が分岐して分析ツリーを構築できるため、画面上の見た目は複雑になりがちです。
- API実行時に実行されるのは 「学習カードの祖先」だけ であり、他の枝に置いた前処理はAPIには反映されません。
Q2-2. 学習時にだけ有効な前処理（データ分割、ラグ特徴量、欠損値線形補間、統計量追加など）はどう扱えばよいですか？
A. 学習時と推論時で振る舞いが異なるカードがあるため、モデルAPI用の分析ツリーからは外す、または推論時にも成立する処理に置き換えてください。
| 処理の種類 | 推論時の挙動 | 推奨対応 |
|---|---|---|
| データ分割カード | 推論時は無視されます（学習APIにとっては有効） | 残しても推論上の害はありませんが、バッチ単位の閾値削除で学習/検証を分けている場合は要見直し |
| 目的変数を使う前処理（ラグ特徴量など） | 推論用データに目的変数が無いためエラーになる可能性 | 推論API用ツリーから外す、または説明変数のみで成立する処理に置換 |
| 大量データを前提とする処理（欠損値線形補間・統計量追加など） | 推論時は1〜数行のデータしか無いため正常動作しない可能性 | 学習時に同等の前処理を済ませた上でCSVを再アップロードする等の対応 |
| 直近データ抽出など推論時のみ有効な処理 | 学習時に逆に悪影響 | 学習用ツリーには含めない |
→ 基本方針: 学習用ツリーとモデルAPI用ツリーを分けることを推奨します。
3. APIに送るデータの形式
Q3-1. 学習APIにはどのようなCSV／データを送ればよいですか？
A. 当初のAIモデル作成時に使用したデータと同じカラム構成（説明変数＋目的変数）で、再学習に使いたいデータを送ってください。
必須要件
- 時刻カラム
- 説明変数の全カラム
- 目的変数のカラム
- データ分割カードやバッチ閾値削除で必要な期間・レコード数を十分に含むこと
Q3-2. 推論APIにはどのようなCSV／データを送ればよいですか？
A. 学習時に使用したデータと同じカラム構成で、推論したい時刻の行を含めてください。
必須要件
- 時刻カラム
- 学習時に説明変数として使った全カラム
- 推論したい時刻の行
任意／不要
- 学習時に使っていなかった追加カラムは含めない方が安全です。
確認のコツ: いきなり本番データで推論せず、まずは学習データの一部をそのまま流用してテスト推論を行い、想定通りの結果が返ってくることを確認してから本番運用に切り替えることを推奨いたします。
Q3-3. 推論APIに目的変数のカラムは送る必要がありますか？
A. 基本的に推論用データには目的変数は不要ですが、前処理ツリーの構成によって挙動が変わるため、注意が必要です。
- 目的変数カラムを 含めなくても 推論APIは動作するように設計されています（実行時に内部でダミーが補われます）。
- ただし、学習用ツリーに目的変数を参照する前処理（正規化・ラグ特徴量・線形補間など）が残っていると、ダミー値が想定外の値に置き換わって推論結果が崩れたり、エラーになる可能性があります。
- そのため、目的変数カラムを送るかどうかよりも、「目的変数を参照する前処理が推論用ツリーに残っていないこと」を確認する方が重要です。
推奨: 目的変数を使う前処理は推論API用ツリーから外し、推論用CSVには目的変数カラムを含めない構成を基本としてください。
Q3-4. 推論したい時刻の1行だけ送ればよいですか？それとも過去データも必要ですか？
A. 学習時の前処理に「時間窓切り出し」「ラグ特徴量」「移動平均」など過去データを参照する処理がある場合、その期間分のデータも含めて送る必要があります。
- 例: 窓幅120レコードで時間窓切り出しを行っている場合、推論したい時刻の直前120レコード分のセンサーデータが必要です。
- 必要なデータ量が不足していると、推論結果がNullになる／前処理段階でエラーになる等の事象が起こります。
- 必要なデータ量は学習時のツリー構成によって変わるため、あらかじめ「推論1回あたりに必要な最低レコード数」をご確認いただき、仕様として定めておくことを推奨いたします。
Q3-5. APIに送れるデータサイズに上限はありますか？
A. リクエストサイズには上限があります（目安: 150MB程度）。
- 上限を超える場合の対応例：
- 推論API: 推論対象の時刻範囲を分割して複数回リクエストする
- 学習API: 学習用データの間引きや期間限定によるデータ量調整を検討する
4. レスポンス内の時刻の意味
Q4. 推論APIのレスポンスに含まれる時刻は何を表していますか？
A. リクエスト時に送信したCSV（推論用データ）内の時刻カラムの値です。推論処理が実行されたシステム側の時刻（サーバ時刻）ではありません。
- レスポンスの各予測値には、対応する入力データの時刻がそのまま付与されます。
- システムが推論ジョブを実行した時刻とは無関係です。
- N時点先予測（例: 0分先＝現在時刻予測）の場合、送ったデータの末尾の時刻がレスポンスのタイムスタンプとなります。
自社システム等に組み込まれる際は、入力CSVの時刻フォーマット（タイムゾーン含む）を明確に定義しておくことを推奨いたします。レスポンス時刻はその仕様にそのまま従います。
5. ジョブのポーリング（処理時間・間隔）
Q5-1. 推論ジョブ・学習ジョブの完了までどれくらい時間がかかりますか？
A. 処理時間はモデルの種類・前処理の複雑さ・送信データ量に依存します。明確な保証値は無いため、本導入前に実際のデータを用いて実測し、ご確認いただくことを推奨いたします。
Q5-2. ポーリングはどのように設計すべきですか？マニュアルのwhile文サンプルをそのまま使ってよいですか？
A. マニュアルのサンプルはあくまで動作確認用です。自社システム等に組み込まれる際は、必ずタイムアウト・異常終了時の脱出条件・最大リトライ回数を実装してください。
Q5-3. 同期的なレスポンス（リクエスト即時に結果）を返すモードはありますか？
A. 現時点では、学習API・推論APIともに非同期（ジョブ投入 → ポーリングで結果取得）の構成です。同期的に結果を返すモードは提供していません。
- したがって、システム等に組み込まれる際は 「ジョブ投入 → ステータスポーリング → 結果取得」の3ステップを前提とした実装が必要です。
- 同期API相当の使い勝手をクライアント側で実現したい場合は、上記Q5-2のポーリングロジックをラップした関数として実装することを推奨します。