@carpediemnn/node-red-ai-gateway

@carpediemnn/node-red-ai-gateway

一个面向 OpenAI-compatible 网关的 Node-RED AI 节点包。核心目标是：

• API Key 不暴露在 flow JSON、节点输出和日志里。
• 把常见 AI 能力收敛到一个主节点里，画布更干净。
• 请求结构对 provider-side prompt cache 更友好。
• 把 cached_tokens、token usage、prefix hash 等诊断信息输出到 msg.ai。

安装

在 Node-RED 编辑器中打开：

菜单 -> Manage palette -> Install

搜索并安装：

@carpediemnn/node-red-ai-gateway

也可以在 Node-RED 用户目录中安装：

cd ~/.node-red
npm install @carpediemnn/node-red-ai-gateway

Docker 版 Node-RED 通常在容器的 /data 目录安装：

cd /data
npm install @carpediemnn/node-red-ai-gateway

安装后重启 Node-RED。

当前设计

推荐的新 flow 结构是：

AI Provider  ->  AI Gateway

AI Provider

配置节点，只负责连接和安全：

• API Base，例如 https://api.openai.com/v1 或自己的网关 /v1 地址。
• API Key，使用 Node-RED credentials 的 password 字段保存。
• 鉴权方式：Bearer Token、自定义 Header 原始值、无鉴权。
• 默认模型。
• prompt_cache_key 开关。
• prompt_cache_retention 设置。

API Key 不会作为普通节点配置保存，导出 flow 时也不会出现在 JSON 里。

AI Gateway

推荐主节点。一个节点里通过 Mode 选择能力：

• Text / Chat：普通文本生成、总结、分析。
• JSON：让模型输出 JSON，并解析成对象。
• Classify：输出 { label, confidence, reason }。
• Router：先分类，再按 label 顺序发到对应 output。
• Request：高级模式，直接请求任意 OpenAI-compatible endpoint。
• Cache Probe：用同一个稳定前缀连续请求两次，检查真实 provider cache 是否命中。

当前包只暴露这两个节点：AI Provider 和 AI Gateway。

Prompt Cache 友好策略

节点会尽量把稳定内容放在请求前缀里：

• System prompt
• Few-shot examples
• JSON schema / labels / routing rules
• 动态输入，例如 msg.payload

这样相同任务的前缀更稳定，更容易命中 AI 服务商侧 prompt cache。

当 Provider 开启 prompt_cache_key 时，节点会根据稳定前缀、模型、API Base 生成稳定 key。

运行时输出

AI Gateway 会把诊断信息写到 msg.ai：

msg.ai = {
  provider: "openai-compatible",
  model: "openai/gpt-5.4-mini",
  endpoint: "/chat/completions",
  cache: {
    providerCachedTokens: 8448,
    promptTokens: 9036,
    cacheHitRate: 0.9349,
    prefixHash: "69298b89cea6bbe2"
  },
  usage: {
    promptTokens: 9036,
    completionTokens: 5,
    totalTokens: 9041,
    raw: {}
  }
}

如果是 AI Gateway 的 Cache Probe 模式，输出会包含：

msg.payload = {
  prefixHash: "...",
  warmed: true,
  first: {
    cache: { providerCachedTokens: 0 }
  },
  second: {
    cache: { providerCachedTokens: 8448 }
  }
}

安全设计

• API Key 存在 AI Provider 的 credentials password 字段里。
• 运行时服务端代码负责组装鉴权 Header。
• msg 输出不包含 API Key。
• 错误信息和请求摘要会脱敏。
• 导出 flow JSON 不包含 API Key。

示例

仓库内置了一个基础示例 flow：

examples/gateway-basic-flow.json

导入后，打开 AI Provider，填写自己的 API Base、模型和 API Key 即可运行。

本地开发

npm test
npm run validate

安装到本地 Node-RED：

cd ~/.node-red
npm install /Users/shiyanan/Documents/nodered-ai-node

发布前检查：

npm run validate
npm publish --dry-run

当前测试覆盖：

• 节点注册。
• API Key credentials 声明。
• AI Gateway 的 Text、JSON、Request、Cache Probe、Router 模式。
• prompt 前缀稳定性。
• cached token 解析。
• 错误脱敏。