> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# n8n 节点

> Alephant n8n 社区节点的安装、凭据、节点参数和工作流模板

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

| 软件包                                        | 节点                        | 用途                                                                  |
| ------------------------------------------ | ------------------------- | ------------------------------------------------------------------- |
| `@alephantai/n8n-nodes-alephant-ai`        | **Alephant Cost Control** | 通过 Alephant 发送聊天补全请求，使用 Virtual Key 身份验证、模型路由、token 跟踪、请求归因和成本控制策略。 |
| `@alephantai/n8n-nodes-alephant-analytics` | **Alephant 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 部署，请确保社区软件包已启用：

```bash
N8N_COMMUNITY_PACKAGES_ENABLED=true
```

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

```bash
npm install @alephantai/n8n-nodes-alephant-ai
npm install @alephantai/n8n-nodes-alephant-analytics
```

## 凭据

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

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

1. 打开 [Alephant dashboard](https://alephant.io/) 并登录您的工作区。
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 Format`    | `Text` 或 `JSON Object`。`JSON Object` 会发送 `response_format: { "type": "json_object" }`。 |
| `Metadata`           | 可选 JSON 对象。仅当 `Additional Options` 包含 `"store": true` 时发送。                             |
| `Additional Options` | 可选 JSON 对象，将合并到聊天补全请求中，但不包括由节点管理的核心字段。                                                 |

### 提示词示例

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

### Messages JSON 示例

```json
[
  {
    "role": "system",
    "content": "You write concise workflow summaries."
  },
  {
    "role": "user",
    "content": "Summarize the latest workflow item."
  }
]
```

### 输出

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

```json
{
  "raw": {
    "id": "chatcmpl_...",
    "choices": []
  },
  "text": "AI cost attribution matters because it shows which workflows and teams drive spend.",
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 17,
    "total_tokens": 35
  },
  "model": "gpt-4o-mini",
  "requestId": "9e3d...",
  "requestLogId": "9e3d...",
  "finishReason": "stop"
}
```

`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 工作流在需要用量或请求上下文时可调用它。

### 操作

| 操作                   | 参数                                                           | 读取内容                                             |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------ |
| `Scope`              | None                                                         | 来自 `/api/v1/cockpit/scope` 的工作区和 Virtual Key 范围。 |
| `Budget Status`      | `Period`                                                     | 所选周期的预算状态。                                       |
| `Usage Summary`      | `Period`                                                     | 所选周期的用量、请求、token 和成本摘要。                          |
| `Daily Costs`        | `Period`                                                     | 所选周期的每日成本序列。                                     |
| `Cost by Model`      | `Period`                                                     | 按模型分组的所选周期成本。                                    |
| `Recent Requests`    | `Limit`, `Offset`                                            | Virtual Key 范围内近期 Gateway 请求。                    |
| `Request Log Detail` | `Request Log ID`, `Workspace ID`, `Request Log Max Attempts` | Analytics API 中单条请求日志的详情。                        |

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

### 请求日志详情

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

默认的 **Request Log ID** 表达式为：

```text
{{$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 Examples | `alephant-example-workflow.json`         | 手动触发器同时运行 Alephant Cost Control 聊天补全和 7 天 analytics 摘要。 |
| Alephant Cost Control Request Cost Tracking   | `alephant-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 用量数据。

下载示例工作流 JSON

### 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 解析工作区范围。

下载请求成本工作流 JSON

在 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** 关联，以创建成本感知通知、审计跟踪、审批流程或仪表板。