用途
Omega 是一个时间序列编码器：输入一段传感器读数窗口，返回固定大小的嵌入向量，可用于后续机器学习。该技能调用云端 Omega 模型，使用与 Newton 融合模型相同的 /query 端点——每个窗口一次无状态 POST，返回嵌入，无需批处理作业或会话生命周期。
主要能力
- 将多变量传感器窗口（振动、压力、流量、网络等）嵌入为向量。
- 在客户端基于这些向量构建轻量级下游 ML：KNN 分类、异常评分、相似性搜索、PCA/UMAP 投影。
- 无需搭建托管批处理管道即可进行原型分类。
模型与端点
- 模型 ID：
OmegaEncoder::omega_embeddings_1_4（注意前缀是OmegaEncoder::，不是Newton::）。 - 每个通道输出 768 维嵌入。
- 端点：
POST {ATAI_API_ENDPOINT}/v0.5/query，请求头需Authorization: Bearer <API_KEY>和Content-Type: application/json。 - 必须同时提供
ATAI_API_KEY和ATAI_API_ENDPOINT，没有默认端点。生产环境端点为https://api.u1.archetypeai.app/v0.5。
请求与响应
推荐每个通道单独请求并并行扇出。每个请求携带一个 data.numeric_array 事件，contents 为 [[/* 单通道：w 个浮点数 */]]。不使用 file_ids，不使用 prompt。
请求示例：
{
"query": "",
"model": "OmegaEncoder::omega_embeddings_1_4",
"normalize_input": false,
"events": [
{ "type": "data.numeric_array", "event_data": { "contents": [[/* 单通道：w 个浮点数 */]] } }
]
}
单通道请求返回的 768 维向量平铺在 response.response 中，需在客户端按通道顺序重组。多通道请求返回 [channels x 768] 形状。
窗口长度
编码器训练支持 16 至 1024 个时间步。小于 1024 的窗口会被填充并掩码，掩码告知模型哪些时间样本是真实的、哪些是填充，因此填充被忽略而非当作信号。不要默认使用 1024，应选择匹配信号动态特性的窗口长度。低于 16 会收到“模型可能表现不佳”的警告；高于 1024 输入会被截断到最后 1024 个点。
normalize_input
当为 true 时，编码器对每个窗口独立进行 z 标准化。这通常不适合比较窗口，因为它会消除跨窗口的幅度差异。对于分类/异常/相似性任务，应在训练池上拟合每个通道的缩放器，应用于每个窗口，并调用时设置 normalize_input=false。仅在一次性单窗口编码且只关心窗口内形状时使用 normalize_input=true。
每通道嵌入
Omega 独立嵌入每个通道。要获得多通道窗口的单一指纹，可将各通道向量拼接成联合多通道状态（例如 4 通道 → 3072 维特征），可选 L2 归一化。该单一向量用于 KNN/异常/投影。
下游模式：嵌入 → KNN 分类
- 准备与归一化：在 n-shot 训练池上拟合每通道缩放器（均值/标准差），应用于每个窗口，调用 /query 时
normalize_input=false。 - 构建 n-shot 库：每类嵌入若干带标签窗口（如健康/退化），将每个窗口的各通道向量折叠为一个联合特征，L2 归一化。
- 对新窗口同样处理，在 k 个最近库特征（欧几里得距离）上多数投票。
几十个带标签嵌入即可构成可用的分类器，无需训练、无需批处理作业。
延迟
- 单窗口嵌入（4 通道 × 1024，每通道并行）：约 2 秒。
- n-shot 库（8 窗口）：约 8 次嵌入，几秒。
- 留出评估（1000 窗口，8 路并行）：约 26 分钟（约 4000 次每通道调用）。
每次嵌入是独立的无状态调用，可通过 --workers 提高并行度，或降低 --max-windows 以权衡吞吐量与预算/时间。
常见陷阱
- 通道优先，不是行优先。
contents是[channels x timesteps]（每个传感器一个列表），不是[timesteps x channels]。转置会产生垃圾嵌入。 - 丢弃时间戳列。时间戳会被解析为数字，朴素地“使用所有数值列”会将其作为假通道包含，若类别文件时间范围不相交，下游分类器可能作弊。
- 时间连续性很重要。Omega 将窗口读取为有序序列；随机采样或跨间隙的行会产生无意义嵌入。应采样连续块。
- 模型 ID 前缀是
OmegaEncoder::，不是Newton::。 - 每个模型只使用一种嵌入约定。每通道请求（推荐）和全通道单请求对相同数据产生略有不同的向量（每坐标约 2e-2）。构建 n-shot 库和嵌入推理窗口必须使用相同方式，否则 KNN 距离会微妙地错误且无任何报错。
- “padding with zeros”警告是信息性的，不是错误。16–1024 范围内的窗口原生处理（填充+掩码）。需要处理的警告是“小于 16”（低于训练范围）和“大于 1024，截断到最后 1024 个点”（会静默丢失最后 1024 个样本之前的所有内容，应自行窗口化数据）。
本地设置
# 在虚拟环境中（系统 Python 常为 PEP 668 "externally managed"）：
python3 -m venv .venv && source .venv/bin/activate
pip install -r skills/atai-newton-omega-model/references/requirements.txt
# 在仓库根目录（或运行目录上方的任意位置）放置 .env 文件。
# 两个变量都是必需的——没有默认端点：
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 # 嵌入基础
python classify_knn.py # n-shot KNN 分类
脚本基于官方 Archetype AI Python 客户端（pip install archetypeai）：每个脚本通过 make_client() 创建一个客户端并传入辅助函数，/query POST 通过客户端的重试传输。若安装了 python-dotenv 会自动加载 .env（find_dotenv() 从当前工作目录向上查找）；否则需导出 ATAI_API_KEY 和 ATAI_API_ENDPOINT。classify_knn.py 需要 numpy。
文件布局
skills/atai-newton-omega-model/
├── SKILL.md ← 本文件
├── references/
│ ├── _common.py ← 官方客户端设置、Omega 嵌入调用、CSV/窗口辅助函数
│ ├── embed_query.py ← 嵌入基础（调用、窗口长度、normalize_input）
│ ├── classify_knn.py ← 嵌入 → n-shot KNN 分类（留出评估）
│ ├── requirements.txt ← 运行时依赖（pip install -r requirements.txt）
│ ├── .env.example ← 复制为 .env 并填写
│ └── sample_data/
│ ├── bearing_healthy.csv ← n-shot 库：健康（4 通道）
│ ├── bearing_degraded.csv ← n-shot 库：退化
│ ├── bearing_inference.csv ← 留出测试输入，仅传感器（约 1000 窗口，无标签列）
│ ├── bearing_labels.csv ← 真实标签（timestamp,label），仅用于评分
│ └── README.md ← 数据集归属 + 留出布局
└── tests/
└── test_references.py ← 无网络单元测试（python -m unittest）
适用场景
- 将多变量传感器窗口嵌入为向量。
- 在客户端基于嵌入构建轻量级下游 ML。
- 无需托管批处理管道即可原型分类。
限制
- 不适用于文本、图像或视频输入——那是 Newton 融合模型（/query 配合
Newton::c2_6_8b_fp8_...）。 - 不适用于需要全托管、服务端对数百万行进行分类的场景。
- 窗口长度限制在 16–1024 时间步。
- 必须提供 API 密钥和端点，无默认端点。
- 每通道请求与全通道单请求的嵌入略有差异，需保持一致约定。