工作流集成

n8n 节点

将 Alephant AI Gateway 和 analytics 连接到 n8n 工作流

以 Markdown 格式查看

Alephant 提供两个用于工作流自动化的 n8n 社区节点软件包：

软件包节点用途
@alephantai/n8n-nodes-alephant-aiAlephant Cost Control通过 Alephant 发送聊天补全请求，使用 Virtual Key 身份验证、模型路由、token 跟踪、请求归因和成本控制策略。
@alephantai/n8n-nodes-alephant-analyticsAlephant AI Analytics从 Alephant 读取 Virtual Key 范围的用量、预算、成本、近期请求和请求日志数据。

当您希望工作流发起 AI 请求后检查其用量或请求日志详情时，请同时安装两个软件包。两个节点使用相同的 Alephant Virtual Key 凭据。

安装

在 n8n 中：

  1. 前往 Settings > Community nodes。
  2. 选择 Install。
  3. 安装 @alephantai/n8n-nodes-alephant-ai。
  4. 安装 @alephantai/n8n-nodes-alephant-analytics。
  5. 如果您的部署要求在安装社区节点后重启，请重启 n8n。

对于自托管的 n8n 部署，请确保社区软件包已启用：

$N8N_COMMUNITY_PACKAGES_ENABLED=true

如果您的部署通过 npm 安装社区软件包，请安装两个软件包：

$npm install @alephantai/n8n-nodes-alephant-ai
$npm install @alephantai/n8n-nodes-alephant-analytics

凭据

两个软件包都会注册并使用 Alephant Virtual Key 凭据。

在配置 n8n 前，先在 Alephant 中创建一个 Virtual Key：

  1. 打开 Alephant dashboard 并登录您的工作区。
  2. 添加上游提供商 API key 作为 Master Key。
  3. 为将发送 AI 流量的 n8n 工作流或应用程序创建一个 Agent。
  4. 复制该 Agent 的 Virtual Key。
  5. 在 n8n 中新建 Alephant Virtual Key 凭据，并将密钥粘贴到 Virtual Key。
字段必填默认值说明
Virtual Key是None完整的 Alephant Virtual Key 值。它会作为 Bearer token 发送。
Workspace ID否Empty用于 Request Log Detail 查询。若为空，analytics 节点会依次尝试传入项和 Alephant Scope API。
Gateway Base URL否https://ai.alephant.io/v1由 Alephant Cost Control 和凭据测试使用。
SaaS Base URL否https://alephant.io由 Virtual Key 范围的 Cockpit 用量 API 使用。
Analytics Base URL否https://analytics.alephant.io用于请求日志详情查询。

生产环境请保留默认基础 URL。仅在预发布、本地、自托管或专用 Alephant 部署中覆盖它们。

凭据测试会使用您的 Virtual Key 调用 Alephant Gateway /models 端点。测试成功表示 n8n 可以向网关进行身份验证。

Alephant Cost Control

Alephant Cost Control 节点由 @alephantai/n8n-nodes-alephant-ai 提供。

它通过 Alephant 发送 POST /chat/completions 请求。请求可采用 OpenAI 兼容格式，但 Alephant 的作用不限于代理模型调用：它为工作流或 Agent 运行处理 Virtual Key 身份验证、路由、预算强制执行、用量日志记录和请求归因。

操作

操作作用
Chat Completion通过 Alephant AI Gateway 发送聊天补全请求。

参数

参数说明
Model已配置 Alephant 工作区可用的模型名称，例如 gpt-4o-mini。
Input Mode单条用户提示词请选择 Prompt；OpenAI 兼容消息数组请选择 Messages JSON。
Prompt当 Input Mode 为 Prompt 时使用。
Messages当 Input Mode 为 Messages JSON 时使用。每条消息需要字符串 role 和 content 字段。
Temperature可选的模型温度。
Max Tokens可选的最大补全 token 数。
Response FormatText 或 JSON Object。JSON Object 会发送 response_format: { "type": "json_object" }。
Metadata可选 JSON 对象。仅当 Additional Options 包含 "store": true 时发送。
Additional Options可选 JSON 对象，将合并到聊天补全请求中，但不包括由节点管理的核心字段。

提示词示例

Write a one sentence summary of why AI cost attribution matters.

Messages JSON 示例

1[
2  {
3    "role": "system",
4    "content": "You write concise workflow summaries."
5  },
6  {
7    "role": "user",
8    "content": "Summarize the latest workflow item."
9  }
10]

输出

该节点返回一个包含原始提供商响应和便捷顶层字段的规范化对象：

1{
2  "raw": {
3    "id": "chatcmpl_...",
4    "choices": []
5  },
6  "text": "AI cost attribution matters because it shows which workflows and teams drive spend.",
7  "usage": {
8    "prompt_tokens": 18,
9    "completion_tokens": 17,
10    "total_tokens": 35
11  },
12  "model": "gpt-4o-mini",
13  "requestId": "9e3d...",
14  "requestLogId": "9e3d...",
15  "finishReason": "stop"
16}

requestId 和 requestLogId 由节点生成，并作为 x-request-id 发送至 Alephant Gateway。将 requestLogId 传入 Alephant AI Analytics，以查询匹配的请求日志。

Alephant AI Analytics

Alephant AI Analytics 节点由 @alephantai/n8n-nodes-alephant-analytics 提供。

它从 Alephant 读取 Virtual Key 范围的用量和请求日志数据。该节点也被标记为可作为 n8n tool 使用，因此 Agent 工作流在需要用量或请求上下文时可调用它。

操作

操作参数读取内容
ScopeNone来自 /api/v1/cockpit/scope 的工作区和 Virtual Key 范围。
Budget StatusPeriod所选周期的预算状态。
Usage SummaryPeriod所选周期的用量、请求、token 和成本摘要。
Daily CostsPeriod所选周期的每日成本序列。
Cost by ModelPeriod按模型分组的所选周期成本。
Recent RequestsLimit, OffsetVirtual Key 范围内近期 Gateway 请求。
Request Log DetailRequest Log ID, Workspace ID, Request Log Max AttemptsAnalytics API 中单条请求日志的详情。

Period 支持 24 Hours、7 Days、30 Days 和 90 Days。

请求日志详情

当您在 AI 请求后需要请求级成本、延迟、token、模型或提供商数据时，请使用 Request Log Detail。

默认的 Request Log ID 表达式为：

{{$json.requestLogId || $json.requestId || ""}}

Workspace ID 按以下顺序解析：

  1. 节点的 Workspace ID 参数。
  2. 传入项的 workspaceId、workspace_id 或 xWorkspaceId。
  3. 保存在 Alephant Virtual Key 凭据中的 Workspace ID。
  4. Alephant Scope API。

如果这些来源均未返回 workspace ID，节点会报错，因为 Analytics 请求日志端点需要工作区范围。若工作流在 AI 请求后立即查询而日志摄取尚未完成，请在请求日志详情查询前添加 Wait 节点。

示例工作流模板

安装两个软件包后，请使用这些工作流 JSON 文件快速试用节点。每个模板都可导入 n8n，然后使用您自己的 Alephant Virtual Key 凭据进行配置。

模板文件演示内容
Alephant Cost Control + AI Analytics Examplesalephant-example-workflow.json手动触发器同时运行 Alephant Cost Control 聊天补全和 7 天 analytics 摘要。
Alephant Cost Control Request Cost Trackingalephant-ai-request-cost-workflow.json完整流程：构造 AI 请求、等待请求日志、获取请求日志详情，并汇总 token 和成本字段。

Alephant Cost Control + AI Analytics Examples

该模板是确认已安装社区节点可连接到 Alephant 的最快方式。它从手动触发器开始，并运行两个独立的 Alephant 节点：

  • Alephant Cost Control - Chat Completion： 使用 gpt-4o-mini 向 Alephant Gateway 发送示例提示词。
  • Alephant AI Analytics - 7 Day Summary： 读取过去 7 天的近期 Virtual Key 用量数据。

Alephant Cost Control Request Cost Tracking

此模板演示如何将 AI 请求关联到其匹配的 Alephant 请求日志，并在请求完成后提取成本信息。工作流按以下顺序运行：

  1. Build AI Request 创建提示词和模型负载。
  2. Alephant Cost Control - Chat Completion 通过 Alephant Gateway 发送请求。
  3. Wait for Request Log 短暂暂停，以便写入网关请求日志。
  4. Alephant AI Analytics - Request Log Detail 通过 requestLogId 或 requestId 获取匹配请求日志。
  5. Summarize Cost 返回包含请求日志 ID、模型、提示词、响应文本、token 用量、成本、货币和原始请求日志的紧凑对象。

当您希望围绕单个 AI 请求构建预算感知工作流、成本仪表板、审批流程或告警时，请使用此模板。在两个 Alephant 节点上选择相同的 Alephant Virtual Key 凭据。若工作流未从前一节点获得 workspace ID，analytics 节点会从已配置凭据或 Scope API 解析工作区范围。

在 n8n 中使用模板：

  1. 安装 @alephantai/n8n-nodes-alephant-ai。
  2. 安装 @alephantai/n8n-nodes-alephant-analytics。
  3. 将工作流 JSON 文件导入 n8n。
  4. 打开每个 Alephant 节点并选择所需的 Alephant Virtual Key 凭据。
  5. 使用 Test workflow 运行工作流，或一次执行一个节点。

常见工作流

  • 使用 Alephant Cost Control 节点从 n8n 通过 Alephant Gateway 路由 AI 任务。
  • 在高成本工作流分支前运行 Alephant AI Analytics，以检查近期支出或预算状态。
  • 将 AI 节点的 requestLogId 与 Request Log Detail 关联，以创建成本感知通知、审计跟踪、审批流程或仪表板。