atai-newton-omega-model

Newton Omega Encoder — /query を介した時系列埋め込み

Omega は時系列エンコーダーです。センサーデータのウィンドウを入力すると、機械学習に利用できる固定サイズの埋め込みが返されます。このスキルは、Newton の融合モデルと同じ /query エンドポイントを使ってクラウド上の Omega モデルを呼び出します。ウィンドウごとにステートレスな POST を 1 回行い、埋め込みを受け取るため、バッチジョブもセッションのライフサイクル管理も不要です。

適用する場面

• 多変量センサーデータのウィンドウ（振動、圧力、流量、ネットワークなど）をベクトルに埋め込む場合
• それらのベクトルを使った軽量な下流機械学習をクライアント側で行う場合：KNN 分類、異常スコアリング、類似検索、PCA／UMAP 射影
• マネージドのバッチパイプラインを立ち上げずに分類のプロトタイプを作成する場合

次の場合はこのスキルを使用しないでください。

• 入力がテキスト、画像、動画の場合 — その場合は Newton 融合モデルを使用してください（Newton::c2_6_8b_fp8_... を指定して /query を呼び出します）
• 数百万行に対する完全マネージドのサーバー側分類が必要な場合

生のセンサー CSV を準備する方法（タイムスタンプの規則性、ギャップを考慮したブロック、時間順の訓練／テスト分割、結合状態の特徴行列）については、atai-newton-omega-model-data-prep を参照してください。

モデル

OmegaEncoder::omega_embeddings_1_4

Newton:: ではなく OmegaEncoder:: のプレフィックスであることに注意してください。出力はチャネルごとに 768 次元の埋め込みです。

エンドポイント

POST {ATAI_API_ENDPOINT}/v0.5/query
Authorization: Bearer <API_KEY>
Content-Type: application/json

融合モデルと同じ /query エンドポイントです。モデル ID によって Omega エンコーダーが選択されます。ATAI_API_KEY と ATAI_API_ENDPOINT の両方が必須です。デフォルトのエンドポイントはないため、デプロイ先を誤ると起動時に明確なエラーが発生します。本番環境は https://api.u1.archetypeai.app/v0.5 です。

リクエスト形式

推奨：チャネルごとに 1 件のリクエストを並列で送信します。 各リクエストには、単一チャネルを含む data.numeric_array イベントを指定します。contents は [[/* one channel: w floats */]] です。file_ids もプロンプトも不要です。チャネルごとにリクエストを分けることで、リクエスト／レスポンスのペイロードサイズを抑えられます（多数のチャネルを含む単一のリクエストは、いずれ REST のペイロード上限を超えて転送中に破損します）。スレッドプールまたは非同期の並列送信を使えば、所要時間を単一の呼び出しに近づけられます。詳しくは _common.py の embed() を参照してください。

{
  "query": "",
  "model": "OmegaEncoder::omega_embeddings_1_4",
  "normalize_input": false,
  "events": [
    { "type": "data.numeric_array", "event_data": { "contents": [[/* one channel: w floats */]] } }
  ]
}

（API はすべてのチャネルを 1 件のリクエストにまとめる形式（contents[channel][t]）にも対応していますが、上記のペイロード上の理由から使用しないでください。また、下流モデルでこの 2 つの形式を混在させないでください。同じデータでも、チャネルごとの埋め込みと全チャネル一括の埋め込みにはわずかな差があり、測定値では各座標がおよそ 2e-2 異なります。そのため、一方の形式で構築した KNN ライブラリでは、もう一方の形式で埋め込んだウィンドウをスコアリングできません。）

応答 — チャネルごとに768次元ベクトルを1つ返します

単一チャネルのリクエストでは、768次元ベクトルがresponse.responseにフラットな形式で返されます。チャネルごとの結果は、クライアント側でチャネル順に再構成してください（複数チャネルのリクエストでは、代わりに[channels x 768]が返されます。これは2つの規約間におけるもう1つの形状の違いです）。

{
  "response": {
    "response": [0.45, -0.32, ...768...],
    "warning_messages": []
  }
}

• ウィンドウ長：16～1024タイムステップ。 エンコーダーは、16～1024の信号長に対応するようにトレーニングされています。内部では、1024未満のウィンドウはパディングされ、マスクされます。マスクによって、どの時間サンプルが実データで、どれがパディングかをモデルに伝えるため、パディングは信号として読み取られず、無視されます。デフォルトで1024を選ばないでください。信号の動態に合ったウィンドウ長を選んでください。より短いウィンドウのほうが適切で、パフォーマンスも高い場合があります。境界値の動作（実環境で検証済み）：1024未満の長さでは、チャネルごとに情報提供用のwarning_messages項目が返されます（"Data length N is less than 1024, padding with zeros" — 16～1024の範囲内では品質上の警告ではありません）。16未満では*"the model may not perform well"*が返されます（トレーニング範囲未満）。1024を超えると、入力は末尾の1024点に切り詰められます（警告あり）。
• normalize_input — trueの場合、エンコーダーは各ウィンドウを個別にZ正規化します。ウィンドウ同士を比較する場合、通常これは望ましくありません。ウィンドウ間の振幅差が失われるためです（流量の少ないウィンドウと多いウィンドウが同じように見えることがあります）。分類／異常検知／類似度判定では、トレーニングデータ全体を使ってチャネルごとに1つのスケーラーを適合させ、それをすべてのウィンドウに適用し、normalize_input=falseで呼び出してください（下流での使用パターンを参照）。normalize_input=trueは、ウィンドウ内の形状のみが重要となる単一ウィンドウの単発エンコードに使用してください。
• チャネルごとの埋め込み。 Omegaは各チャネルを個別に埋め込みます。複数チャネルのウィンドウから1つのフィンガープリントを得るには、チャネルごとのベクトルを連結して複数チャネルの共同状態を作成します（例：4チャネルなら3072次元の特徴量）。必要に応じてL2正規化してください。この単一ベクトルをKNN／異常検知／射影に入力します。

基本的な呼び出し方法、16～1024の範囲におけるウィンドウ長の動作、normalize_inputについては、embed_query.pyを参照してください。

下流のパターン — 埋め込み → KNN 分類

管理対象のバッチパイプラインで行われる処理を、/query の埋め込みを使ってクライアント側で再現したものです。

0. 一度だけ前処理と正規化を行う — n-shot の学習プールでチャンネルごとのスケーラー（平均／標準偏差）を適合させ、すべてのウィンドウに適用します。その際、normalize_input=false を指定して /query を呼び出します。これはデータ準備／事前確認の規約です。まず omega-1-4-preflight でショットファイルを検証し、atai-newton-omega-model-data-prep で生の CSV を準備してください。
1. n-shot ライブラリを構築する — 各クラス（例：healthy／degraded）について、ラベル付きウィンドウをいくつか埋め込みます。各ウィンドウのチャンネルごとのベクトルを1つの結合特徴量にまとめ、L2 正規化します。
2. 分類する — 新しいウィンドウも同じ方法で処理し、ライブラリ内の特徴量のうちユークリッド距離が近い k 個で多数決を取ります。

ラベル付き埋め込みが数十個あれば、実用的な分類器を構築できます。学習もバッチジョブも不要です。classify_knn.py を参照してください。このスクリプトは、ラベル付きショットファイルからライブラリを構築し、bearing_inference.csv に対して正真正銘のホールドアウト評価を実行します（センサー情報のみで、label 列はなく、タイムスタンプもショットファイルとは重複しないため、二重の意味でリークが起こり得ません）。予測を bearing_labels.csv と照合してスコアを算出します。

完全な二値分類のメトリクスレポート（degraded を陽性として扱います）を出力します。また、--window-size には1つ以上の長さを指定できます。それぞれ個別の完全な評価として実行され（各長さに合わせてライブラリとテストのウィンドウをまとめて再分割します）、最後に比較表が表示されます。長さごとにホールドアウトウィンドウ1000個（healthy 500個＋degraded 500個）を使った場合、--window-size 16 256 1024 の全長さでのスイープ結果は次のとおりです。

 window  library  windows  accuracy  precision  recall     f1
-------------------------------------------------------------
     16       16     1000     0.671      0.858   0.410  0.555
    256       14     1000     0.973      0.949   1.000  0.974
   1024        8     1000     0.944      0.899   1.000  0.947

この表の傾向が教訓です。16では、ウィンドウがベアリングの欠陥のインパルス特徴より短いため、再現率が大きく低下します。このズームレベルでは、劣化したウィンドウの大半に実際に証拠が含まれていません。256では特徴を捉えられ、劣化したウィンドウをすべて検出でき、誤警報も最少（healthy のウィンドウで27件）になります。1024では再現率を維持できますが、適合率が低下します（誤警報56件）。コンテキストを増やすと欠陥がより鮮明になるのではなく、薄まってしまいます。このデータセットでは、ウィンドウごとのデータ量が4分の1となる256のほうが1024より優れています。これが上記のウィンドウ長に関する指針の実証例です。デフォルトで1024を使わず、いくつかの長さを試して、ホールドアウト F1 に選ばせてください。

各評価では約1000個のウィンドウを埋め込みます。チャンネルごとの API 呼び出しは約4000回で、デフォルトの8並列ウィンドウ処理では約26分かかります。各長さをすばやくプレビューするには、--max-windows 50 を使用してください。

レイテンシー

操作	実測値
1つのウィンドウの埋め込み（4チャンネル × 1024、チャンネルごとに並列）	約2秒
n-shot ライブラリ（ウィンドウ8個）	約8回の埋め込み、数秒
ホールドアウト評価（ウィンドウ1000個、8並列）	約26分（チャンネルごとの呼び出し約4000回）

各埋め込みは独立したステートレス呼び出しであるため、classify_knn.py は --workers を使って並列処理します。値を大きくする（または --max-windows を小さくする）ことで、スループットと予算／所要時間のバランスを調整できます。

よくある落とし穴

• 行優先ではなく、チャネル優先です。 contents は [channels x timesteps]（センサーごとに1つのリスト）であり、[timesteps x channels] ではありません。転置すると、意味のない埋め込みになります。
• タイムスタンプ列を除外してください。 timestamp は数値として解析されるため、単純に「すべての数値列を使う」と、偽のチャネルとして含まれてしまいます。また、クラスごとのファイルで時間範囲が重ならない場合、後続の分類器がその値を利用して不正に判別できてしまいます。時間列を除外してください（ヘルパーはヘッダー名から timestamp／time／…を除外します。データで異なる名前を使っている場合は、独自の time_columns セットを渡してください）。
• 時間的な連続性が重要です。 Omega はウィンドウを順序付きの時系列として読み取ります。ランダムにサンプリングした行や、間にギャップのある行からは、意味のない埋め込みが生成されます。連続したブロックをサンプリングしてください。（ギャップを考慮したウィンドウ分割については、atai-newton-omega-model-data-prep を参照してください。）
• プレフィックスは OmegaEncoder:: です。 モデル ID は Newton::... ではなく、OmegaEncoder::omega_embeddings_1_4 です。
• モデルごとに埋め込みの方式を統一してください。 チャネルごとのリクエスト（推奨）と、すべてのチャネルを1つのリクエストにまとめる方式では、同じデータでもベクトルがわずかに異なります（座標ごとに約2e-2）。nショットのライブラリを構築するときと推論ウィンドウを埋め込むときは、同じ方式を使ってください。そうしないと、エラーが表示されないままKNNの距離にわずかな誤差が生じます。
• 「ゼロでパディングする」という警告は情報提供であり、エラーではありません。 学習済みの16～1024の範囲内のウィンドウは、（パディング＋マスクによって）ネイティブに処理されます。対処が必要な警告は、"less than 16"（学習範囲未満）と、"greater than 1024, truncating to the last 1024 points"（最後の1024サンプルより前のデータがすべて通知されずに失われます。代わりに、ご自身でデータをウィンドウに分割してください）です。

ローカルセットアップ

# In a virtualenv (system pythons are often PEP 668 "externally managed"):
python3 -m venv .venv && source .venv/bin/activate
pip install -r skills/atai-newton-omega-model/references/requirements.txt

# Drop a .env at the repo root (or anywhere up the tree from the run dir).
# BOTH variables are required — there is no default endpoint:
cat > .env <<EOF
ATAI_API_KEY=sk_...
ATAI_API_ENDPOINT=https://api.u1.archetypeai.app/v0.5
EOF

cd skills/atai-newton-omega-model/references
python embed_query.py     # embedding basics
python classify_knn.py    # n-shot KNN classification

スクリプトは公式のArchetype AI Pythonクライアント（pip install archetypeai）をベースにしています。各スクリプトは make_client() でクライアントを1つ作成してヘルパーに渡し、/query へのPOSTはクライアントの再試行機能付きトランスポートを経由します。python-dotenv がインストールされている場合は .env を自動的に読み込みます（find_dotenv() がcwdから親ディレクトリをたどります）。それ以外の場合は、ATAI_API_KEY と ATAI_API_ENDPOINT をエクスポートしてください。classify_knn.py には numpy が必要です。

ファイル構成

skills/atai-newton-omega-model/
├── SKILL.md                  ← this file
├── references/
│   ├── _common.py            ← official-client setup, the Omega embed call, CSV/window helpers
│   ├── embed_query.py        ← embedding basics (call, window lengths, normalize_input)
│   ├── classify_knn.py       ← embeddings → n-shot KNN classification (held-out eval)
│   ├── requirements.txt      ← runtime deps (pip install -r requirements.txt)
│   ├── .env.example          ← copy to .env and fill in
│   └── sample_data/
│       ├── bearing_healthy.csv          ← n-shot library: healthy (4 channels)
│       ├── bearing_degraded.csv         ← n-shot library: degraded
│       ├── bearing_inference.csv        ← held-out test input, sensors only (~1000 windows, NO label column)
│       ├── bearing_labels.csv           ← ground-truth labels (timestamp,label), scoring only
│       └── README.md                    ← dataset attribution + held-out layout
└── tests/
    └── test_references.py    ← network-free unit tests (python -m unittest)