开始前的准备工作
n8n 实例(云端或自托管)以及来自此服务的 API 密钥。如果你还没有密钥,API 密钥页面将引导你通过 Google 或电子邮件和密码完成注册。新用户可以在该页面上一键领取 $0.50 的试用额度,有效期 7 天,无需信用卡。
三个值输入到 n8n:
- Base URL:
https://api.onekeyllmapi.com/v1 - API 密钥: 作为
Authorization: Bearer <key>发送,n8n 会自动为你处理 - 模型 ID:
uncensored
该服务是一个托管的纯文本 LLM API,遵循 OpenAI 请求格式,支持 /v1/chat/completions、/v1/responses 和 /v1/models。它并非任何模型厂商的官方 API,因此只要 n8n 发送的是文本请求,发送到 OpenAI 聊天端点的任何内容均可在此使用。
步骤 1:创建凭据
在 n8n 中打开 凭据,选择 创建凭据 并搜索 OpenAI API。按如下方式填写:
- 将你的密钥粘贴到 API 密钥 字段中。
- 留空 Organization ID。
- 将默认的 Base URL 替换为
https://api.onekeyllmapi.com/v1。保留末尾的/v1,不要添加/chat/completions。 - 保存。n8n 在保存时会运行一个小测试调用;如果失败,请跳转到下面的故障排除部分。
每个环境保留一个凭据。如果你同时运行测试环境和生产环境的 n8n,请为每个环境提供各自的密钥,以便你可以分别查看支出,并在不影响另一个的情况下撤销其中一个。
步骤 2:构建简单的聊天工作流
从证明连接的最小事物开始:手动触发器和一次模型调用。
- 添加一个 Manual Trigger 节点。
- 添加一个 OpenAI 节点(或在 Basic LLM Chain 内的 OpenAI Chat Model 子节点,取决于你的 n8n 版本),并选择步骤 1 中的凭据。
- 对于模型,寻找手动输入 ID 的方法。较新的 n8n 版本在列表旁边提供 By ID 模式。在那里输入
uncensored。列表可能为空或仅显示 OpenAI 名称,因为 n8n 在其端过滤它。 - 添加一个提示词,例如 用两句话总结这个支持工单 并运行该节点。
如果你的 n8n 版本坚持从列表中选择,请使用下一节中的 HTTP Request 方法。它始终有效,因为你控制整个请求。
使用 HTTP Request 节点调用 API
HTTP Request 节点是从 n8n 调用此 API 的最可预测方式,它暴露了 API 接受的所有参数,包括 seed、stop、top_p 和 tools。按如下方式配置:
- 方法:
POST - URL:
https://api.onekeyllmapi.com/v1/chat/completions - 认证方式:通用凭证类型 配合 Header 认证,名称为
Authorization,值为Bearer YOUR_KEY - 发送正文:开启,内容类型 JSON
正文(如果你想插入来自之前节点的数据,将字段切换为 Expression):
{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Summarize this support ticket in two sentences."}
],
"temperature": 0.4
}
回复文本位于 choices[0].message.content。在下一个节点中,你可以使用 {{ $json.choices[0].message.content }} 引用它。
要首先在 n8n 之外测试相同的请求,请在终端中运行此命令:
curl https://api.onekeyllmapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello in five words."}]}'
如果 curl 有效但 n8n 无效,问题出在节点设置中,而不是你的密钥或余额。
用于解析输出的 JSON 模式
当模型将数据包装在友好的文本中时,工作流会中断。JSON 模式要求 API 返回一个有效的 JSON 对象,你可以直接将其传递给 Set 或 IF 节点。将 response_format 添加到正文:
{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Reply only with a JSON object with keys sentiment and summary."},
{"role": "user", "content": "The delivery was late but support fixed it fast."}
]
}
两个习惯使这变得可靠。首先,在提示词中说出单词 JSON 并命名键,因为 JSON 模式保证语法,而不是你的模式。其次,回复仍然作为字符串出现在 message.content 中,所以在读取字段之前添加一个 Code 节点或带有 JSON.parse() 的表达式。在 OpenAI 节点中,相同的开关出现在节点选项下的 Response Format 选项中。
处理 429 及其他错误
n8n 并行运行项目,因此 50 行的批次可能会很快达到限制。完整密钥允许 8 个并发请求和每分钟 300 个请求;试用密钥允许 2 个和 60 个。超过限制时,API 会返回 HTTP 429 状态码,错误代码为 rate_limited(每分钟请求过多)或 concurrency(同时请求过多)。在临时过载时,你会收到带有 Retry-After: 5 标头的 429 响应。
n8n 中的实用设置:
- 打开节点,转到 Settings,启用 Retry On Fail,设置 Max Tries 为 3 或 4,Wait Between Tries 为 5000 毫秒。
- 在模型调用之前添加一个 Loop Over Items 节点(批处理大小为 4 到 6),以便你保持在 8 个并行请求以下。
- 在节点 Settings 下,On Error 可以设置为以错误输出继续,因此一个坏行不会停止运行。
深入了解两种限制,请阅读 API 文档。其他错误很简单:401 意味着密钥错误或标头缺少单词 Bearer,404 通常意味着基础 URL 有拼写错误或额外的路径段。
故障排除清单
大多数故障来自简短的原因列表。在怀疑服务之前,从上到下逐一检查。
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 保存或运行时出现 401 | 密钥错误,或标头缺少 Bearer | 再次粘贴密钥;在 Header Auth 中,值必须以 Bearer 开头 |
| 404 | 基础 URL 有拼写错误或多余路径 | 在凭证中精确使用 https://api.onekeyllmapi.com/v1 |
| 未找到模型 | 模型 ID 没有输入为 uncensored | 切换为按 ID 模式,或使用 HTTP 请求节点 |
| 429 且 concurrency | 超过 8 个并行运行(试用密钥上为 2 个) | 使用循环遍历项进行批处理并添加重试 |
| 下游 JSON 解析错误 | 回复是字符串,或者提示词未指定键名 | 使用 JSON.parse() 解析,并在系统提示词中描述键名 |
联系支持时,请包含失败调用的 X-Request-Id 响应头。在 n8n 中,你可以在 HTTP 请求节点选项中开启 包含响应头和状态 来查看响应头。
无需大量花费即可进行测试
在构建过程中使用试用额度。在 2 个并行请求和每分钟 60 个请求的限制下,试用密钥对于批量处理来说速度较慢,但用于检查凭证、提示词和解析逻辑则绰绰有余。当将工作流移至计划任务时,请切换到完整密钥。
成本与合理的工作流设计
定价为按量付费:输入 token 每 100 万 $0.15,输出 token 每 100 万 $0.50,从预付额度中扣除。每天处理 1,000 封邮件的工作流,每封邮件 600 个输入 token 和 100 个输出 token,将消耗 0.6M 输入 token($0.09)和 0.1M 输出 token($0.05),每天约 $0.14。失败或被拒绝的请求不会收费,因此错误重试不会使费用翻倍。详情请见 定价页面。
保持提示词简短,仅发送模型所需的字段,并在确定答案简短时设置 max_tokens。如果你还在自己的机器上运行模型,请参阅关于通过 OpenAI 风格 API 使用本地 LLM的文章,其客户端设置相同。
