atai-newton-fusion-model

Newton C 2.6 Fusion 模型——一次调用完成多模态 /query

通过一次无状态 POST 请求调用 /query，即可基于 C 2.6 Fusion 检查点进行文本、图像或视频推理。无需 Lens 会话、批处理流水线或 SSE。一次调用 → 一个响应。

适用场景

• 用户想通过一次 API 调用描述图像、对图像进行分类或提取图像结构
• 用户想通过一次 /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。以下三种模态共用同一个端点，变化的是请求正文。

请求格式

文本 + 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 中。

参见 text_query.py，其中提供了这三种模式的可运行示例。示例围绕智能家居 WiFi 流量分析展开；示例 3 中附加的流量日志来自 GHOST-IoT 数据集（Anagnostopoulos 等人，Sensors 2020，DOI:10.3390/s20226600）——完整出处请参阅脚本的文档字符串。

图像

有两种附件路径，都会使用同一个融合模型——根据使用场景选择——另有一个标志可用于一次发送多张图像：

（a）上传 + 在 file_ids 中通过文件名引用 — 适合在多个查询中重复使用同一张图像（一份上传，多次调用 /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 — 适合一次性调用，避免不必要的上传往返：

{
  "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，图像列表就表示“同一段视频的帧”，并且需要 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
}

参见 image_query.py，其中提供了这三种路径的可运行示例。

视频

C 2.6 可通过两种方式在 /query 上对视频进行推理。这也是它与 C 2.4 / 2.5 文本检查点的区别：后者虽然接受 .mp4，却会忽略视频帧并回复 “我看不到视频。”

（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 事件，或使用图像 file_ids），设置 multi_image: false，并添加包含视频元数据三元组的 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。
• 超时 — 将客户端请求超时设为至少 600s。视频延迟会随 max_frames 和视频片段长度变化；默认的 30–60s 超时会导致非简单视频片段的请求超时。
• C 2.6 上直接使用 .mp4 是平台近期的一项变更。 之前，.mp4 路径对所有模型都会静默丢弃视频帧（这是已知的 GPQ 错误），所以较早的说明会写“/query 上无法处理视频”。如今 C 2.6 可以通过 max_frames 处理视频。
• multi_image 用于选择视频模式或多图像模式。 multi_image: false（同时设置 query_metadata）= 附加图像是同一段视频的帧。multi_image: true = 多图像模式——图像是彼此独立的（前后对比、多视角），无需 query_metadata。

参见 video_query.py，其中提供了两种路径的可运行示例（直接使用 mp4、展示 max_frames 的取舍，以及帧列表示例），并使用了针对工作装配的 PASS/FAIL 检查提示词。

生成参数

通过 /query 进行的所有 C-model 生成都可在请求体中使用采样控制参数（已验证这些参数在生产环境中由 C 2.6 接受并生效）：

参数	默认值	说明
max_new_tokens	256	生成 token 数量的硬上限（每个约 4 个字符）——达到上限时会在句子中途停止
temperature	—	0.0 = 贪心／近似确定性；创意输出可用 0.7–1.0。上限为 2.0
do_sample	true	总开关：false 会强制使用贪心解码（将 temperature 设为 0，并移除 top_p／top_k）——适用于需要可复现性的场景
repetition_penalty	1.0	对已生成 token 施加的乘法 logit 惩罚；如果模型反复输出某个短语或重复数字，可尝试 1.1–1.3
presence_penalty	0.0	对至少出现过一次的任意 token 施加的加法惩罚（与出现频率无关）。范围约为 −2..+2。仅适用于 C 2.6
top_p	0.8	核采样——保留累积概率 ≥ top_p 的最小 token 集合
top_k	—	每个步骤的候选 token 数量硬上限（先于 top_p 应用）；0 表示禁用

对于“提取 X”这类任务，建议从 do_sample: false（或 temperature: 0.0）加上较小的 max_new_tokens 开始。

关于可复现性的注意事项（已验证）：采样参数确实生效——使用相同提示词运行 5 次，贪心模式（do_sample: false）产生了 2 种不同的输出，默认参数下产生了 3 种，temperature: 1.9 时产生了 5 种；但在此部署中，贪心模式并非位级确定性（fp8 数值计算／批处理不受解码器控制），这与平台说明中“给定提示词时，do_sample: false 的输出是确定的”相矛盾。对于临界判断，残余波动足以改变答案：同一个贪心模式下的装配检查请求体，一次运行全部返回 PASS，另一次则返回两个 FAIL。如果判定结果很重要，请汇总几次调用的结果，而不要只相信一次调用。

延迟预算

使用 references/sample_assets/ 中的示例素材在生产环境中观测到的数据：

模态	请求体	p50	说明
仅文本	{"query": "...", "file_ids": []}	约 500 ms	在模型标识符探测期间确认
文本 + JSON 输出	指令提示词中包含架构	约 600 ms	结构相同，架构较冗长时延迟略长
通过 file_ids 传入图片	一张 1.9 MB PNG	约 1.3–1.9 s	实测（wind-turbines.png）
通过内联 base64 传入图片	同上	约 0.8–2.5 s	base64 会增大请求体；耗时随图片大小增长
两张图片，multi_image: true	2 张约 400 KB 的 PNG	约 2.9 s	前后对比（装配帧）
视频，mp4 + max_frames=32	约 31 s 的装配片段	约 2–6 s	服务端解码／采样
视频，2 帧 + query_metadata	2 张约 400 KB 的 PNG	约 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–60s，处理稍复杂的视频片段时就会失败。将超时设为 ≥ 600s。
• 多个图像未设置 multi_image: true 时，需要提供 query_metadata 三元组。 图像列表默认会被视为“同一个视频的帧”，但这一路径要求在请求体中提供 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）无法查看视频。这是 GPQ 的一个 bug，会在任何模型处理之前静默丢弃 .mp4 帧。现在 C 2.6 可以通过 .mp4 + max_frames 读取视频——已验证。2.4/2.5 的文本检查点仍会忽略帧。
• file_ids 接受的是文件名，而不是 fil_... uid。 上传时，API 会同时返回 {"file_id": "<filename>", "file_uid": "fil_..."}。/query 会根据文件名（file_id 的值，例如 "dashboard.png"）解析 file_ids，而不是 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/plain，不能是 text/csv。 .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，但融合模型的注意力有限。为获得可预测的结果，每次调用只使用一种模态。

本地设置

# 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(...) 上传文件，通过 archetypeai.utils.base64_encode(...)（utf-8）进行 base64 编码，每个脚本都会创建一个客户端并将其传递给辅助函数。如果安装了 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)