API ドキュメント

予測以外

異常検知、欠損補完、埋め込みを使い、時系列データを分析します。

異常検知

系列の各時点に異常スコアを付けます。しきい値のルールを人が作らなくても、正常な区間の振る舞いから外れた時点を数値で示します。

POST /v1/anomaly

リクエストボディ

フィールド	型	説明
model	string	使用するモデル。省略時は yoft
series	object[]	対象の系列（1 系列あたり 16〜2048 点）
test_start	integer	スコアを付け始める位置。これより前は「正常の参照区間」として扱う（省略時は 0 = 全区間）

curl

curl -X POST https://YOUR_API_BASE/v1/anomaly \
  -H "Authorization: Bearer $YOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test_start": 8, "series": [{"name": "s1", "values": [1.0, 1.2, 1.1, 1.4, 1.3, 1.5, 1.4, 1.6, 1.5, 1.7, 1.6, 1.8, 1.7, 1.9, 1.8, 9.9]}]}'

レスポンス

フィールド	説明
pit	分布的な驚きの度合い。大きいほど「その時点の値がモデルの予測分布から外れている」
crps	予測分布と実測のズレの量。大きいほど外れ幅が大きい
test_start	スコア配列が対応する開始位置（リクエストのエコーバック）

200 レスポンス

{
  "request_id": "req_7b2c48...",
  "model": "yoft",
  "model_version": "v1",
  "test_start": 8,
  "series": [
    {
      "name": "s1",
      "pit": [
        0.62,
        0.71,
        0.55,
        0.83,
        0.64,
        0.79,
        0.6,
        41.2
      ],
      "crps": [
        0.05,
        0.06,
        0.04,
        0.07,
        0.05,
        0.06,
        0.05,
        6.83
      ]
    }
  ],
  "usage": {
    "input_points": 16,
    "output_points": 16,
    "series_count": 1
  }
}

スコアは test_start 以降の各時点に 1 つずつ返ります（配列長 = 系列長 − test_start）。鋭いスパイクや水準の変化に強く、カレンダー要因のゆるやかな変動には反応しにくい特性があります。

欠損補完

欠損を含む系列を送ると、欠損位置の値を推定して返します。通信断や保守停止で穴が開いたデータの復元に使えます。

POST /v1/impute

欠損は JSON の null で表します。各系列に少なくとも 1 つの null と 1 つの観測値が必要です（すべて欠測・欠測なしはいずれも 400）。

curl

curl -X POST https://YOUR_API_BASE/v1/impute \
  -H "Authorization: Bearer $YOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"series": [{"name": "s1", "values": [1.0, 1.2, 1.1, 1.4, null, null, 1.4, 1.6, 1.5, 1.7, 1.6, 1.8, 1.7, 1.9, 1.8, 2.0]}]}'

レスポンス

フィールド	説明
values	全長の系列。観測位置は入力値そのまま、欠損位置は推定値（中央値）
missing_indices	補完した位置の index
quantiles	欠損位置の分位点（0.1 / 0.2 / 0.3 / 0.4 / 0.5 / 0.6 / 0.7 / 0.8 / 0.9）。missing_indices と同じ並び

200 レスポンス

{
  "request_id": "req_9e14c3...",
  "model": "yoft",
  "model_version": "v1",
  "series": [
    {
      "name": "s1",
      "values": [
        1,
        1.2,
        1.1,
        1.4,
        1.32,
        1.38,
        1.4,
        1.6,
        …
      ],
      "missing_indices": [
        4,
        5
      ],
      "quantiles": {
        "0.1": [
          1.19,
          1.24
        ],
        "0.5": [
          1.32,
          1.38
        ],
        "0.9": [
          1.46,
          1.53
        ]
      }
    }
  ],
  "usage": {
    "input_points": 16,
    "output_points": 2,
    "series_count": 1
  }
}

埋め込み（類似検索・分類）

系列を固定長のベクトルに変換します。返ったベクトルを使って、類似系列の検索や、手元の軽量な分類器の学習ができます。

POST /v1/embed

yoft では 3840 次元です。次元はモデル（チェックポイント）によって変わるため、クライアントはレスポンスの dim を参照してください。

curl

curl -X POST https://YOUR_API_BASE/v1/embed \
  -H "Authorization: Bearer $YOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"series": [{"name": "s1", "values": [1.0, 1.2, 1.1, 1.4, 1.3, 1.5, 1.4, 1.6, 1.5, 1.7, 1.6, 1.8, 1.7, 1.9, 1.8, 2.0]}]}'

200 レスポンス

{
  "request_id": "req_0d5f1a...",
  "model": "yoft",
  "model_version": "v1",
  "dim": 3840,
  "embeddings": [
    {
      "name": "s1",
      "vector": [
        0.0121,
        -0.0384,
        …
      ]
    }
  ],
  "usage": {
    "input_points": 16,
    "output_points": 0,
    "series_count": 1
  }
}

使い道

類似検索: ベクトル間のコサイン類似度で「似た形の系列 / 似た日」を探す
分類: ラベル付きの少数データでロジスティック回帰などを学習し、以降はベクトルだけで分類する
クラスタリング: 設備・店舗・回線などを振る舞いでグループ分けする

実務上の注意: 生のベクトル同士のコサイン類似度は 0.98 以上に飽和しやすく差が見えません。比較対象の平均ベクトルを引いて（中心化してから）類似度を取ると、違いがはっきり出ます。