atai-newton-fusion-model

Newton C 2.6 Fusion Model — マルチモーダルな /query を1回のリクエストで

C 2.6 fusion チェックポイントを使い、テキスト、画像、動画について推論するための、ステートレスな /query への POST を1回実行します。Lens セッションも、バッチパイプラインも、SSE もありません。1回の呼び出し → 1つの応答です。

適用するケース

• 画像について、1回の API 呼び出しで説明、分類、構造の抽出を行いたい場合
• 短い動画について、1回の /query 呼び出しで同様の処理を行いたい場合
• ステートレスなマルチモーダル推論を行いたい場合（セッションごとのウォームアップや、孤立したリソースのクリーンアップが不要）
• マルチモーダル入力から JSON 出力を得たい場合（プロンプトがスキーマです）
• ストリーミング Lens セッションでは適さない、サーバーレスまたはリクエスト単位のハンドラーを構築している場合

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

• 長時間稼働するカメラフィードから、ライブのストリーミング動画をテキストに変換するワークロードの場合 — ステートレスな /query ではなく、セッションベースのアクティビティモニターが適しています
• 複数の大容量ファイルを扱うバッチジョブの場合
• 埋め込みを使った時系列分類（KNN／異常検知）の場合

モデル識別子

Newton::c2_6_8b_fp8_260424d7a55d5e

Newton:: プレフィックス全体と _fp8_ セグメントの両方が必須です。いずれかを省略したバリアントは 400 invalid_model_version で拒否されます：

c2_6_8b_fp8_260424d7a55d5e            ❌ missing Newton:: prefix
Newton::c2_6_8b_260424d7a55d5e        ❌ missing _fp8_
c2_6_8b_260424d7a55d5e                ❌ both missing

これは、本番環境の https://platform.u1.archetypeai.app/api/lens/query に対して、エンドツーエンドで検証済みです。

エンドポイント

POST {ATAI_API_ENDPOINT}/api/lens/query
Authorization: Bearer <API_KEY>
Content-Type: application/json

ATAI_API_KEY と ATAI_API_ENDPOINT の両方が必須です — デフォルトのエンドポイントはありません。そのため、デプロイ先を間違えた場合は、クエリ時に気付かないまま失敗するのではなく、起動時にはっきりとエラーになります。本番環境のエンドポイントは https://platform.u1.archetypeai.app/api です。以下の3つのモダリティすべてで同じエンドポイントを使います — 変わるのはリクエスト本文です。

リクエスト形式

テキスト + JSON

{
  "query": "Classify the operational state. Respond with ONLY the JSON object.",
  "instruction_prompt": "You output {\"state\": \"...\", \"confidence\": <0..1>}.",
  "file_ids": [],
  "model": "Newton::c2_6_8b_fp8_260424d7a55d5e",
  "max_new_tokens": 300
}

• システムターンは instruction_prompt に指定します。C 2.6 が認識するのはこのフィールドだけです — 旧式の system_prompt フィールドだけに指示を指定しても、無視されます（Newton::c2_6_8b_fp8_260424d7a55d5e で検証済み。同じ指示が instruction_prompt では守られ、system_prompt では無視されます）。そのため、system_prompt は完全に省略してください。
• JSON 出力の場合：スキーマを instruction_prompt に、入力を query に指定し、Markdown のコードフェンスで囲まないよう、モデルに明示的に伝えてください。そうしないと、モデルはしばしば json ... の形式で返します。

添付したテキストファイルを使って推論する場合は、/api/files 経由で text/plain（.txt ファイル）としてアップロードし、ファイル名を file_ids に指定します。すると、モデルはファイルの内容をプロンプトのコンテキストで参照できます。重要： これは text/plain の場合にのみ機能します。text/csv（.csv）としてアップロードしたファイルは受け付けられ、バイト単位で同一のまま保存されますが、その内容は /query でモデルに渡されません — モデルは何も通知せず、事前知識に基づいて内容を作り出します（以下の注意点と csv_vs_txt_proof.py を参照）。application/json のアップロードは明示的に拒否されます。そのため、表形式のデータは .txt に入れるか、query に直接記述してください。

3つのパターンすべてを実行できるデモについては、text_query.py を参照してください。例はスマートホームの WiFi フロー分析を題材にしています。例3の添付フローログは、GHOST-IoT dataset（Anagnostopoulos ほか、Sensors 2020、DOI:10.3390/s20226600）の実データです — 詳細な出典については、スクリプトの docstring を参照してください。

画像

どちらの添付方法でも同じ融合モデルを利用できます。用途に応じて選択してください。また、複数の画像を一度に送信するためのフラグもあります。

(a) アップロードして、file_ids でファイル名を参照する — 同じ画像を複数のクエリで再利用する場合に最適です（1回アップロードし、複数回 /query を呼び出します）。

curl -X POST $ATAI_API_ENDPOINT/api/files \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -F "[email protected];type=image/png"

{
  "query": "Describe this image in three bullets.",
  "instruction_prompt": "...",
  "file_ids": ["dashboard.png"],
  "model": "Newton::c2_6_8b_fp8_260424d7a55d5e",
  "max_new_tokens": 300
}

(b) data.base64_img イベントに base64 をインラインで指定する — アップロードの往復が無駄になる、1回限りの呼び出しに最適です。

{
  "query": "What is in this image? One sentence.",
  "instruction_prompt": "...",
  "file_ids": [],
  "model": "Newton::c2_6_8b_fp8_260424d7a55d5e",
  "max_new_tokens": 200,
  "events": [
    {
      "type": "data.base64_img",
      "event_data": {
        "contents": "<base64 string>",
        "mime_type": "image/png"
      }
    }
  ]
}

(c) 複数の画像 — multi_image: true を設定することで、複数画像モードになります。添付画像は動画のフレームではなく、それぞれが独立した画像として扱われます（前後の比較、複数視点、「これらの画像に写っているのは同じ人物ですか？」など）。プラットフォームの上限は、リクエストあたり最大16枚です。multi_image: true を設定しない場合、画像リストは「1つの動画のフレーム」を意味し、query_metadata が必要です（「動画」セクションを参照）。どちらもない場合、リクエストは 400 query_failed で失敗します。

{
  "query": "Image 1 is the bench BEFORE the task; image 2 is DURING. What changed?",
  "instruction_prompt": "...",
  "file_ids": ["assembly_before.png", "assembly_after.png"],
  "model": "Newton::c2_6_8b_fp8_260424d7a55d5e",
  "max_new_tokens": 400,
  "multi_image": true
}

3つの方法すべての実行可能なデモについては、image_query.py を参照してください。

動画

C 2.6 は /query で動画を2つの方法で推論します。この点が、.mp4 を受け付けてもフレームを無視し、「動画を見ることはできません」と返す C 2.4 / 2.5 のテキストチェックポイントとの違いです。

(a) .mp4 + max_frames — クリップをアップロードすると、モデルにフレームが渡される前に GPQ がサーバー側でデコードし、均等にサンプリングします。クライアント側で動画処理ツールを使う必要はありません。

curl -X POST $ATAI_API_ENDPOINT/api/files \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -F "[email protected];type=video/mp4"

{
  "query": "Evaluate the assembly steps shown in the attached video.",
  "instruction_prompt": "<task / inspection prompt>",
  "file_ids": ["clip.mp4"],
  "model": "Newton::c2_6_8b_fp8_260424d7a55d5e",
  "max_new_tokens": 500,
  "max_frames": 32
}

(b) クライアント側でサンプリングしたフレーム + query_metadata — フレームを自分で送信し（フレームごとに data.base64_img イベントを1つ送るか、画像の file_ids を使います）、multi_image: false を設定し、動画メタデータの3項目を含む query_metadata ブロックを指定します。これを機能させるのは query_metadata ブロックです。これがない場合、リクエストは 400 query_failed で失敗します。

{
  "query": "This is a short video. Describe the sequence of actions in order.",
  "instruction_prompt": "...",
  "model": "Newton::c2_6_8b_fp8_260424d7a55d5e",
  "multi_image": false,
  "max_new_tokens": 150,
  "events": [
    {"type": "data.base64_img", "event_data": {"contents": "<frame_0 base64>"}},
    {"type": "data.base64_img", "event_data": {"contents": "<frame_1 base64>"}}
  ],
  "query_metadata": {"raw_fps": 1.0, "frames_indices": [0, 1], "total_num_frames": 2}
}

どちらの形式も実際の環境で検証済みです（(b) の file_ids 形式も動作します）。注意事項：

• max_frames — モデルに渡す前に GPQ が動画から均等にサンプリングするフレーム数です。デフォルトは32、プラットフォームの上限は64です。長いクリップや詳細なクリップでは増やし、レイテンシを抑えるには減らしてください。64を超える値はエラーなしで失敗します。リクエストは200を返しますが、動画は破棄され、モデルは事前知識に基づいてシーンを作り上げます（検証済み：組み立て作業のクリップで max_frames: 80 を指定したところ、「スマートフォンを持っている人」と説明されました）。64以下にしてください。
• タイムアウト — クライアントのリクエストタイムアウトは最低600秒に設定してください。動画のレイテンシは max_frames とクリップの長さに応じて増加します。デフォルトの30～60秒では、ある程度長さのあるクリップでタイムアウトします。
• C 2.6 での .mp4 直接指定は、プラットフォームの最近の変更です。 以前は既知の GPQ のバグにより、すべてのモデルで .mp4 のフレームが破棄されていたため、古い説明では「/query では動画は使えない」とされています。現在の C 2.6 では max_frames を使って動画を処理できます。
• multi_image で動画モードと複数画像モードを切り替えます。 multi_image: false（query_metadata を指定）では、添付画像は1つの動画のフレームとして扱われます。multi_image: true では複数画像モードになり、画像は独立した画像として扱われます（前後の比較、複数視点）。この場合、query_metadata は不要です。

ワーカーの組み立て作業を PASS/FAIL で検査するプロンプトを使った、両方の方法（mp4 の直接指定、max_frames の調整例、フレームリストのデモ）の実行可能なデモについては、video_query.py を参照してください。

生成パラメーター

/query 経由のすべての C-model 生成では、リクエスト本文でサンプリングを制御できます（C 2.6 で本番環境にて受け付けられ、反映されることを確認済みです）。

パラメーター	デフォルト	備考
max_new_tokens	256	生成されるトークン数の上限（約4文字ずつ）です。上限に達すると文の途中で停止します
temperature	—	0.0 は貪欲デコード（ほぼ決定論的）、創造的な出力には 0.7～1.0 を指定します。上限は 2.0 です
do_sample	true	全体スイッチです。false にすると貪欲デコードが強制されます（temperature → 0、top_p／top_k は除去）。再現性が必要な場合に使用します
repetition_penalty	1.0	すでに出力されたトークンに対する乗算方式のロジットペナルティです。同じフレーズを繰り返したり、数字を反復したりする場合は 1.1～1.3 を試してください
presence_penalty	0.0	一度でも出現したすべてのトークンに対する加算方式のペナルティです（頻度には依存しません）。範囲は約 −2～+2 です。C 2.6 のみ
top_p	0.8	ニュークリアスサンプリングです。累積確率が top_p 以上になる最小のトークン集合を保持します
top_k	—	ステップごとの候補トークン数の上限です（top_p の適用前）。0 にすると無効になります

「X を抽出する」形式のタスクでは、do_sample: false（または temperature: 0.0）と、厳しめに設定した max_new_tokens から始めるのが適切です。

**再現性に関する注意（確認済み）：**サンプリング設定は反映されます。同じプロンプトを使用したところ、貪欲デコード（do_sample: false）では5回の実行で2種類、デフォルト設定では3種類、temperature: 1.9 では5種類の異なる出力が得られました。しかし、このデプロイ環境では、プラットフォームの注記にある「do_sample: false の出力はプロンプトが同じなら決定論的です」という説明に反して、貪欲デコードはビット単位で決定論的ではありません（fp8 の数値処理／バッチ処理がデコーダーの外部で行われるためです）。境界的な判定では、わずかな揺らぎによって回答が変わることがあります。同じ貪欲デコードによる組み立て検査の本文で、ある実行ではすべて PASS、別の実行では FAIL が2件返されました。判定が重要な場合は、1回の結果を信頼せず、数回の呼び出し結果を集約してください。

レイテンシの目安

references/sample_assets/ のサンプルアセットを使い、本番環境で観測した値です。

モダリティ	本文	p50	備考
テキストのみ	{"query": "...", "file_ids": []}	約500 ms	モデル識別子の調査中に確認
テキスト＋JSON 出力	指示プロンプトにスキーマを含める	約600 ms	同じ形式ですが、スキーマが詳細な場合はやや長くなります
file_ids 経由の画像	1.9 MB の PNG 1枚	約1.3～1.9 s	観測値（wind-turbines.png）
インライン base64 経由の画像	同上	約0.8～2.5 s	base64 によりリクエストが大きくなり、画像サイズに応じて増加します
2枚の画像、multi_image: true	約400 KB の PNG × 2	約2.9 s	前後の比較（組み立てフレーム）
動画、mp4 ＋ max_frames=32	約31秒の組み立てクリップ	約2～6 s	サーバー側でデコード／サンプリング
動画、2フレーム ＋ query_metadata	約400 KB の PNG × 2	約1.9 s	クライアント側でサンプリングしたフレームリストの経路

数値はスモークテストで得た概算です。本番データの負荷は5～10倍になる場合があり、それに応じて処理も遅くなります。

レスポンスの形式

{
  "query_id": "...",
  "status": "completed",
  "inference_time_sec": 0.42,
  "query_response_time_sec": 0.49,
  "response": {
    "response": ["<the model output as a string>"]
  }
}

標準的な抽出経路として payload["response"]["response"][0] をたどってください。リファレンススクリプトの extract_text() ヘルパーは、これまでに確認したすべての形式のバリエーションに対応しています。

よくある落とし穴

• モデル識別子が間違っています。 Newton:: を付けずに c2_6_8b_fp8_260424d7a55d5e を指定すると、400 invalid_model_version が返されます。_fp8_ を含まないバリアントも同様です。必ず完全な Newton::c2_6_8b_fp8_260424d7a55d5e を使用してください。
• JSON が Markdown のコードフェンスで囲まれます。 明示的に指示していても、モデルが json ... を返すことがあります。防御的に解析する（text.strip().removeprefix("```json").removesuffix("```")）か、instruction_prompt だけでなくユーザークエリにもコードフェンスを付けないルールを記載してください。
• 動画のタイムアウト。 デフォルトの requests.post のタイムアウトである 30～60 秒では、ごく短いクリップ以外は失敗します。タイムアウトを 600 秒以上に設定してください。
• multi_image: true を指定せずに複数の画像を使う場合は、query_metadata の 3 つの値が必要です。 画像のリストはデフォルトで「1 本の動画のフレーム」として扱われますが、この方法ではリクエスト本文に query_metadata: {"raw_fps": ..., "frames_indices": [...], "total_num_frames": N} が必要です。指定しないと 400 query_failed でリクエストが失敗します（エラーメッセージには不足しているフィールドが示されません）。独立した画像（前後比較やマルチビュー）の場合は、代わりに multi_image: true を設定してください。画像は最大 16 枚で、query_metadata は不要です。
• max_frames を 64 より大きくすると、エラーなく失敗します。 プラットフォームの上限は 64 です。max_frames: 80 を指定しても 200 が返されますが、動画はモデルに届かず、事前学習の知識から場面を捏造します（下記の CSV に関する落とし穴と同じ失敗モードです）。max_frames は 64 以下にしてください。
• 「動画は /query では機能しない」という情報は古いものです。 古い記述では、C 2.6（および 2.4／2.5）は動画を認識できないとされています。これは、どのモデルにも渡される前に .mp4 のフレームを黙って破棄する GPQ のバグでした。現在は C 2.6 が .mp4 と max_frames を使って動画を読み取れます（検証済み）。2.4／2.5 の テキスト チェックポイントは、現在もフレームを無視します。
• file_ids に指定するのはファイル名であり、fil_... の uid ではありません。 アップロード時に、API は {"file_id": "<filename>", "file_uid": "fil_..."} の両方を返します。/query は file_ids を ファイル名（file_id の値。例："dashboard.png"）で解決し、fil_... の file_uid では解決しません。file_uid を渡すと、誤解を招く 400 unsupported_file_type（「Found unsupported file type with file: fil_…」）が返されます。コンテンツタイプの問題に見えますが、実際は識別子が間違っています。検証結果：file_ids=["wind-turbines.png"] → 200、file_ids=["fil_…"] → 400。
• テキスト添付ファイルには text/csv ではなく text/plain を指定してください。 .csv のアップロード（text/csv）は受け付けられ、バイト単位で保存され、status: completed が返されますが、内容は /query でモデルに 届きません。モデルは事前学習の知識から黙って捏造します（例：SSH のみのファイルに対して「TCP」や「port 80」と回答します）。同一のバイト列を .txt（text/plain）としてアップロードすると、内容は正確に読み取られます。警告はありません。失敗は黙って発生するため、回答を検証しないと気付けません。表形式／テキストデータは .txt としてアップロードするか、query に直接記述してください。csv_vs_txt_proof.py で自分でも確認できます（同じ内容で .txt は 5/5、.csv は 0/5 を読み取ります）。application/json のアップロードは 400 invalid_file_type で拒否されます。
• 複数モダリティの呼び出し。 画像と動画の両方の file_id を添付できますが、フュージョンモデルの注意機構には限りがあります。予測しやすい結果を得るには、1 回の呼び出しで 1 つのモダリティだけを使用してください。

ローカル環境のセットアップ

# 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-fusion-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://platform.u1.archetypeai.app
EOF

python skills/atai-newton-fusion-model/references/text_query.py
python skills/atai-newton-fusion-model/references/image_query.py
python skills/atai-newton-fusion-model/references/video_query.py

スクリプトは公式の Archetype AI Python クライアント（pip install archetypeai）をベースにしています。アップロードには client.files.local.upload(...)、base64 エンコードには archetypeai.utils.base64_encode(...)（utf-8）を使用し、各スクリプトはクライアントを 1 つ作成してヘルパーに渡します。python-dotenv がインストールされている場合は、.env を自動的に読み込みます。find_dotenv() は cwd から上位のディレクトリをたどるため、リポジトリのルート、プロジェクトのルート、または references/ 内のいずれにファイルがあっても機能します。python-dotenv がない場合、スクリプトは通常の環境変数（export ATAI_API_KEY=... ATAI_API_ENDPOINT=...）にフォールバックします。

ファイル構成

skills/atai-newton-fusion-model/
├── SKILL.md                  ← this file
├── references/
│   ├── _common.py            ← shared helpers on the official archetypeai client
│   ├── text_query.py         ← 3 text patterns (plain, JSON output, .txt flow-log attachment)
│   ├── image_query.py        ← 4 image patterns (file_ids, base64, JSON extraction, multi-image)
│   ├── video_query.py        ← 3 video patterns (mp4 direct, max_frames tradeoff, frame list + query_metadata)
│   ├── csv_vs_txt_proof.py   ← diagnostic: proves text/csv attachments aren't read, text/plain are
│   ├── requirements.txt      ← runtime deps (pip install -r requirements.txt)
│   ├── .env.example          ← copy to .env and fill in
│   └── sample_assets/
│       ├── wind-turbines.png ← AI-generated photo (default for image_query.py)
│       ├── assembly_before.png / assembly_after.png ← frames from the clip below (multi-image demo)
│       ├── 1_pass_2_pass_3_pass_B.mp4 ← assembly-inspection clip (default for video_query.py)
│       └── README.md         ← provenance of the samples
└── tests/
    └── test_references.py    ← network-free unit tests (python -m unittest)