用途
本技能在已有的 Omega + KNN 流水线上增加一个解释层。Omega 将传感器窗口转换为嵌入向量，客户端 KNN 将嵌入向量与 n-shot 库比对后给出判定（健康/故障、正常/攻击等）。判定虽然准确，但不会说明原因。本技能引入 NVIDIA Nemotron，当 Omega 标记异常时，Nemotron 读取判定结果和窗口统计信息，生成面向操作员的文字说明：发生了什么变化、可能原因、需要检查什么。
主要能力
- 将 Omega 的判定结果与 KNN 投票结果、窗口统计信息（均值/最小值/最大值、RMS、峰值、峰度等）以及参考基线或健康同类数据组合，发送给 NVIDIA Nemotron。
- 通过 NVIDIA 托管 API（
https://integrate.api.nvidia.com/v1/chat/completions）调用 Nemotron，接口兼容 OpenAI 客户端。 - 默认模型为
nvidia/nemotron-3-super-120b-a12b，可通过NEMOTRON_MODEL环境变量覆盖。 - 通过
chat_template_kwargs: {"enable_thinking": false}关闭推理轨迹（系统提示中的/no_think会被忽略）。 - 输出固定 JSON 结构（如
observation、likely_cause、checks），并在代码中进行字段校验和领域规则检查。 - 支持按异常签名缓存结果，避免重复调用并降低延迟。
- 支持异步/线程池方式调用，不阻塞传感循环。
使用方式
- 创建 NVIDIA API 密钥：在
https://build.nvidia.com/settings/api-keys创建（免费 NVIDIA Developer Program）。注意：用于拉取 NVIDIA 容器的 NGC 密钥也以nvapi-开头，但调用托管模型会返回 403。 - 本地安装：
python3 -m venv .venv && source .venv/bin/activate pip install -r skills/atai-newton-omega-nvidia-nemotron/references/requirements.txt cp skills/atai-newton-omega-nvidia-nemotron/references/.env.example .env # 填写 ATAI_API_KEY、ATAI_API_ENDPOINT、NVIDIA_API_KEY cd skills/atai-newton-omega-nvidia-nemotron/references python check_nemotron.py # 密钥 + 模型预检 python explain_knn.py # 在轴承样本上运行 Omega + KNN + Nemotron 简报 - 调用示例：
POST https://integrate.api.nvidia.com/v1/chat/completions Authorization: Bearer $NVIDIA_API_KEY Content-Type: application/json { "model": "nvidia/nemotron-3-super-120b-a12b", "messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}], "temperature": 0.2, "max_tokens": 800, "chat_template_kwargs": {"enable_thinking": false} }
适用场景
- 已有 Omega + KNN 流水线并需要生成面向操作员的文字说明（故障简报、建议操作、告警摘要）。
- 用户明确希望使用 NVIDIA Nemotron（托管于 build.nvidia.com）作为推理模型。
- 资产具有已知结构（阶段、线路、拓扑），需要生成操作卡片（如 SWaT 演示）。
- 存在健康同类或基线可供比较，需要生成故障简报（如风力涡轮机演示）。
限制
- 不适用于需要 Omega 调用、窗口化或 KNN 库的场景，这些属于
atai-newton-omega-model（以及之前的atai-newton-omega-model-data-prep）。本技能假设这些已正常工作。 - 不适用于希望在
/query上使用 Newton 自身推理模型的场景，应使用atai-newton-fusion-model。 - 不要将嵌入向量发送给 Nemotron，语言模型无法理解 768 维向量。
- 模型可能被退役，例如
nvidia/nvidia-nemotron-nano-9b-v2自 2026-08-26 起返回 410 Gone。部分列出的模型对特定账户返回 404。构建前应运行check_nemotron.py。 - 免费层约每分钟 40 次请求，适用于开发和原型。
- 诊断信息不能证明密钥有效：
GET /v1/models无需密钥，退役模型在检查密钥前就返回 410。只有成功的聊天调用才能证明密钥有效。 - 状态码含义：401/403 密钥错误或类型错误（NGC 密钥）；404 模型对账户不可用；410 模型已退役；429 速率限制。
- Nemotron 输出应视为不可信输入，必须经过校验后再展示。
- 密钥仅限服务端使用，切勿将
NVIDIA_API_KEY或ATAI_API_KEY发送到浏览器。
提示词与校验要点
- 要求仅返回固定结构的 JSON，无散文或代码围栏；解析时仍应提取第一个
{…}或[…]。 - 要求引用输入中的数值，并说明“为便于阅读取整”。
likely_cause应表述为假设（“与……一致”/“提示……”），UI 应标注为建议。- 避免仅复述判定结果。
- 可提供领域阅读提示（如“桨距接近 90° = 叶片顺桨”），但不要提示预期的具体故障。
- 只提供存在的名称列表，并检查输出是否引用了列表外的名称。
- 校验形状（必填字段非空、列表长度上限）和领域规则（如 SWaT 演示中每张卡片的 origin/direction 必须映射到预期目标阶段）。
- 失败时显示“Nemotron 不可用”，并保持 Omega 判定可见。判定不依赖 Nemotron。
缓存与延迟
- 按异常签名缓存（如标记的阶段集合 "P2,P3" 或 turbine + window_start），重复请求立即返回。
- 不要阻塞传感循环，将 Nemotron 调用提交到线程池/异步任务，结果到达后附加到告警。
文件布局
skills/atai-newton-omega-nvidia-nemotron/
├── SKILL.md
├── references/
│ ├── _common.py ← Omega embed helpers + Nemotron chat (stdlib), parse/validate, window stats, brief
│ ├── check_nemotron.py ← preflight: list models, one call, latency + reasoning tokens, error hints
│ ├── explain_knn.py ← Omega + KNN + Nemotron brief on the bearing sample
│ ├── requirements.txt
│ ├── .env.example
│ └── sample_data/
│ ├── bearing_healthy.csv
│ ├── bearing_degraded.csv
│ ├── bearing_incoming.csv
│ └── README.md
└── tests/
└── test_references.py ← network-free unit tests (python -m pytest)
常见陷阱
- 将嵌入向量发送给 LLM。
- 使用 NGC 密钥而非 build.nvidia.com 密钥。
- 在 Nemotron 3 上使用
/no_think（会被忽略）。 - 硬编码模型 ID 导致退役后失效。
- 没有参考基线或同类数据，简报只会复述窗口。
- 渲染未校验的输出。
- 在 LLM 上阻塞传感循环。