1. 项目概述当n8n遇上LLM一个低代码开发者的效率革命如果你和我一样常年混迹在低代码和自动化领域对n8n这个强大的工作流工具爱不释手同时又对当下火热的LLM大语言模型垂涎三尺那你肯定也遇到过和我一样的困境怎么把这两者优雅地结合起来是手动在n8n里一个个节点地配置HTTP请求去调用OpenAI API还是写一堆脚本去处理复杂的提示词工程和上下文管理这个过程既繁琐又容易出错更别提想规模化地测试和部署这些智能工作流了。直到我发现了n8n-llm-workflows这个项目它像是一把专门为这个场景打造的瑞士军刀让我这个习惯用图形化界面“拖拉拽”的开发者也能轻松驾驭AI智能体AI Agents和复杂的工作流编排。简单来说n8n-llm-workflows是一个基于TypeScript构建的工具包。它的核心目标不是替代n8n而是极大地增强n8n在处理LLM相关自动化任务时的能力。它提供了一套类型化的API客户端、一系列开箱即用的自动化模板以及一套用于管理、测试和部署这些工作流的脚手架。你可以把它理解为一个“n8n的LLM增强插件包”或者“智能工作流开发套件”。它的出现让构建一个能理解上下文、进行推理决策、并与其他系统交互的AI智能体工作流变得像搭积木一样直观。无论是想做一个智能客服聊天机器人一个自动分析报告并生成摘要的数据处理流水线还是一个能根据用户指令自主操作其他软件的数字员工这个工具包都提供了坚实的基础。2. 核心设计思路为什么我们需要一个专门的LLM工作流工具包在深入代码和配置之前我们先聊聊为什么单纯的n8n节点在应对LLM时显得力不从心以及n8n-llm-workflows是如何从设计上解决这些痛点的。这有助于你理解这个工具包的真正价值而不仅仅是把它当作一堆脚本的集合。2.1 传统n8n集成LLM的典型痛点在没有专用工具包时我们通常这样做使用n8n的“HTTP Request”节点调用OpenAI、Anthropic或本地部署的Hugging Face模型API。这听起来简单但实际操作中会踩无数个坑提示词Prompt管理混乱复杂的提示词模板包含变量、系统指令、少样本示例以长文本形式硬编码在节点配置里难以维护和复用。想调整一个示例得在图形界面里翻找半天。上下文Context处理繁琐LLM对话需要维护历史消息。在n8n中你需要手动设计流程来存储、读取、拼接和截断对话历史逻辑分散在多个“Function”或“Code”节点中流程图变得异常复杂。类型安全与错误处理缺失HTTP节点返回的是原始的JSON你需要手动解析choices[0].message.content。如果API响应结构变化或出错错误处理逻辑完全需要自己从头编写缺乏类型提示调试困难。工作流版本化与测试困难n8n工作流可以导出为JSON但如何对包含LLM调用的工作流进行单元测试、集成测试如何确保提示词的修改不会破坏现有功能缺乏一套标准化的测试方法。规模化部署的挑战当你拥有几十个LLM工作流时如何批量管理它们的API密钥、模型参数、速率限制如何实现蓝绿部署或金丝雀发布纯手动操作几乎不可能。2.2 n8n-llm-workflows的解决方案架构该项目正是瞄准了上述痛点提供了一个分层的解决方案底层类型化的API客户端。它封装了与n8n实例交互的所有操作如触发工作流、查询执行状态、读取数据并提供了完整的TypeScript类型定义。这意味着你在代码中调用client.workflow.execute()时编辑器能自动提示参数类型编译器能在构建时检查错误极大提升了开发体验和代码可靠性。中间层工作流定义与模板。项目提倡将工作流逻辑尤其是LLM交互部分从n8n的图形界面中部分“抽离”出来用代码进行定义和管理。它提供了示例模板展示了如何结构化地组织提示词、处理上下文、连接不同模型节点。这相当于为你的LLM工作流建立了一套“设计规范”。上层CLI工具与测试框架。这是实现“规模化”的关键。通过命令行工具你可以批量验证工作流配置、模拟输入数据运行测试、甚至与CI/CD管道集成。它把工作流从“手动点击运行的黑盒”变成了“可自动化测试的软件组件”。这种设计思路的核心是“Infrastructure as Code”理念在n8n工作流领域的实践。你的自动化逻辑不再仅仅存在于n8n服务器的数据库里也存在于受版本控制如Git管理的代码库中从而获得了可追溯、可测试、可重复部署的能力。3. 环境准备与项目初始化从零开始搭建你的开发工作站理论讲完了我们动手实操。假设你已经在本地或服务器上运行了一个n8n实例这是前提条件。接下来我们将一步步设置n8n-llm-workflows的开发环境。3.1 系统与软件 prerequisites首先确保你的开发环境满足以下要求。我强烈建议使用macOS/Linux系统或Windows下的WSL2进行开发以获得最佳的命令行体验。Node.js环境这是运行TypeScript项目的基础。要求版本在14.x或以上。我推荐使用nvmNode Version Manager来管理Node.js版本这样可以轻松切换不同项目所需的环境。# 检查当前Node.js版本 node --version # 如果未安装或版本过低使用nvm安装以安装v18为例 # 首先安装nvm然后 nvm install 18 nvm use 18包管理工具项目使用npm或yarn。通常npm随Node.js安装。确保其可用。npm --versionGit用于克隆项目代码库。这是开发者必备工具。git --version一个正在运行的n8n实例这是我们的“运行时环境”。你可以通过Docker快速启动一个本地实例这是最推荐的方式与生产环境隔离。docker run -it --rm \ --name n8n \ -p 5678:5678 \ -v ~/.n8n:/home/node/.n8n \ n8nio/n8n启动后在浏览器中访问http://localhost:5678完成n8n的初始设置。记住你设置的凭证后续API连接会用到。3.2 获取并初始化n8n-llm-workflows项目我们不从那个重复的ZIP链接下载而是直接从GitHub仓库克隆这样可以获得最新的代码和完整的Git历史方便后续贡献。克隆仓库git clone https://github.com/slayerlux/n8n-llm-workflows.git cd n8n-llm-workflows进入项目目录后你会看到标准的TypeScript项目结构src/源码目录、tests/测试目录、package.json配置文件等。安装项目依赖npm install # 或者使用 yarn yarn install这个过程会下载所有必要的依赖包包括TypeScript编译器、n8n API客户端库、测试框架等。环境变量配置项目通常需要连接你的n8n实例。创建一个.env文件参考项目根目录可能存在的.env.example文件来存储敏感配置。# .env 文件内容示例 N8N_API_BASE_URLhttp://localhost:5678/ N8N_API_KEYyour_n8n_api_key_here # 如果你的n8n实例需要Webhook URL也可能需要配置 N8N_WEBHOOK_URLhttp://your-ngrok-or-public-url.com注意N8N_API_KEY需要在你的n8n实例中生成。登录n8n后台进入“设置” - “API”创建一个新的API密钥并赋予它必要的工作流读写权限。切勿将此密钥提交到Git仓库中。构建项目由于是TypeScript项目我们需要将其编译为JavaScript才能运行。npm run build这会在项目根目录生成一个dist/文件夹里面是编译后的JS代码。完成以上步骤你的基础开发环境就准备好了。接下来我们将深入探索工具包的核心组件。4. 核心组件深度解析API客户端、工作流模板与CLI工具n8n-llm-workflows工具包主要由三大核心组件构成理解它们各自的作用和相互关系是高效使用它的关键。4.1 类型化的n8n API客户端这是与n8n实例通信的桥梁。项目内置的客户端抽象了n8n REST API的细节提供了强类型的方法调用。我们来看一个典型的使用示例假设在src/client.ts或示例中你会看到类似这样的客户端初始化import { N8nClient } from ‘./path-to-client’; // 假设的导入路径 // 从环境变量读取配置 const baseUrl process.env.N8N_API_BASE_URL; const apiKey process.env.N8N_API_KEY; // 初始化客户端 const client new N8nClient({ baseUrl, apiKey, }); // 使用客户端执行一个已知ID的工作流 async function runWorkflow(workflowId: string, inputData: any) { try { const execution await client.workflows.execute(workflowId, { data: inputData, }); console.log(‘工作流执行成功执行ID:’, execution.id); console.log(‘输出数据:’, execution.data); return execution.data; } catch (error) { console.error(‘工作流执行失败:’, error); throw error; } }为什么类型化如此重要开发效率在VS Code或WebStorm等IDE中输入client.workflows.后你会自动获得.execute,.get,.create等方法提示。错误预防如果你尝试传递一个不符合接口定义的inputDataTypeScript编译器会在你运行代码前就报错而不是在运行时才崩溃。代码可维护性所有API的请求和响应结构都有明确的类型定义新接手项目的开发者能快速理解数据流。4.2 示例自动化工作流模板这是项目的精华所在。在examples/或workflows/目录下你会找到一系列预构建的工作流模板。它们不仅仅是展示功能更是最佳实践的示范。我们来解剖一个典型的“智能问答聊天机器人”模板可能包含的结构提示词模板节点不再是硬编码文本而是通过一个“Function”节点或自定义节点从一个外部配置文件或数据库读取提示词模板。模板中使用像{{userQuestion}}、{{conversationHistory}}这样的占位符。上下文管理节点一系列节点负责从数据库如SQLite/PostgreSQL节点或内存如n8n的“Set”节点中读取上一次对话的历史将其格式化为LLM所需的消息数组格式例如[{role: “user”, content: “…”}, {role: “assistant”, content: “…”}]并智能地截断过长的历史以节省Token。LLM调用节点使用封装好的“HTTP Request”节点或自定义节点调用OpenAI API。关键点在于API密钥、模型名称如gpt-4-turbo-preview、温度temperature等参数被提取为工作流或项目的全局变量便于统一管理。输出解析与后处理节点LLM的回复可能是JSON、Markdown或纯文本。这里会包含节点来解析JSON、清理文本、或者根据回复内容触发后续动作例如如果用户说“订一张机票”则触发另一个订票工作流。实操心得不要只是导入这些模板就了事。花时间拆解每一个节点理解其配置。特别关注“错误处理”分支是如何设计的——LLM API可能因为速率限制、内容过滤或网络问题而失败一个健壮的工作流必须有重试机制和友好的失败反馈。4.3 CLI工具与测试套件对于严肃的项目可测试性至关重要。n8n-llm-workflows提供的CLI工具让你能够像测试普通函数一样测试工作流。假设项目提供了一个cli.js或通过npm scripts暴露的命令运行单个工作流测试npm run test:workflow -- --workflow-id你的工作流ID --input-file./test-data/input.json这个命令会读取input.json中的测试数据通过API触发指定工作流并断言输出是否符合output.json中的预期结果。批量测试与持续集成你可以在package.json中配置一系列测试脚本。“scripts”: { “test:all”: “npm run test:workflow -- --all”, “test:ci”: “npm run lint npm run build npm run test:all” }这样在GitHub Actions或GitLab CI中只需运行npm run test:ci就能自动完成代码风格检查、构建和所有工作流的功能测试。模拟与桩Stubbing高级用法涉及在测试中模拟LLM API的响应避免在测试时产生真实的API调用费用和不稳定性。这可能需要你结合像jest这样的测试框架并利用n8n客户端提供的拦截功能或使用像nock这样的HTTP模拟库。重要提示测试LLM工作流的输出具有挑战性因为LLM的回复是非确定性的即使温度设为0也可能有细微变化。因此测试断言往往不能是精确的字符串匹配而应该是语义匹配检查是否包含关键信息或结构化输出验证如果LLM被要求返回JSON则验证JSON的架构。项目模板应该提供这方面的示例。5. 实战构建并部署一个完整的AI客服工单分类工作流让我们结合所有知识从头构建一个实际可用的工作流。场景是一个电商平台用户通过在线表单提交客服请求。我们需要一个AI工作流来自动分析用户描述将其分类如“退货”、“投诉”、“咨询”、“表扬”并提取关键实体如订单号、产品名称然后自动分配给相应的客服团队。5.1 第一步在n8n中创建基础工作流在n8n编辑器中创建一个新的工作流命名为“AI客服工单自动分类”。设置Webhook触发器添加一个“Webhook”节点。这是为了接收从电商平台发来的工单提交数据。保存后n8n会生成一个唯一的Webhook URL如http://your-n8n.com/webhook/abc123。将这个URL配置到你的电商平台后台。设计后续节点在Webhook节点后我们暂时不连接LLM节点先连接一个“Function”节点用于将接收到的原始数据假设是JSON格式构造成发给LLM的提示词。5.2 第二步使用n8n-llm-workflows管理提示词与调用我们不把复杂的逻辑全写在n8n的图形界面里。而是在我们的TypeScript项目中创建一个服务模块。创建提示词模板文件src/prompts/ticket-classifier.tsexport const ticketClassificationPrompt 你是一个专业的电商客服工单分类AI。请分析以下用户提交的工单描述并完成以下任务 任务 1. **分类**将工单分类为以下之一[退货 投诉 咨询 表扬 其他]。 2. **提取信息**从描述中提取以下实体如果存在 - 订单号格式通常为纯数字或字母数字组合 - 产品名称 - 问题简述 3. **紧急程度**判断紧急程度[高 中 低]。高涉及人身安全、重大财务损失中影响使用需要尽快解决低一般咨询或建议。 用户描述 “{{ticketDescription}}” 请以严格的JSON格式回复且只包含JSON不要有任何额外解释。JSON格式如下 { “classification”: “分类结果”, “entities”: { “orderId”: “提取到的订单号或空字符串”, “productName”: “提取到的产品名称或空字符串”, “issueSummary”: “问题简述或空字符串” }, “urgency”: “紧急程度” } ;创建分类服务src/services/ticket-classifier.tsimport { N8nClient } from ‘../client’; import { ticketClassificationPrompt } from ‘../prompts/ticket-classifier’; import OpenAI from ‘openai’; // 假设使用OpenAI官方Node.js SDK export class TicketClassifierService { private openai: OpenAI; private n8nClient: N8nClient; constructor(apiKey: string, n8nClient: N8nClient) { this.openai new OpenAI({ apiKey }); this.n8nClient n8nClient; } async classifyAndRoute(ticketData: { id: string; description: string; customerEmail: string; }) { // 1. 构建最终提示词 const finalPrompt ticketClassificationPrompt.replace( ‘{{ticketDescription}}’, ticketData.description ); // 2. 调用OpenAI API const completion await this.openai.chat.completions.create({ model: ‘gpt-3.5-turbo-0125’, // 选用适合的、成本较低的模型 messages: [{ role: ‘user’, content: finalPrompt }], temperature: 0.1, // 低温度保证输出稳定性适合分类任务 response_format: { type: “json_object” }, // 强制JSON输出 }); const aiResponse JSON.parse(completion.choices[0].message.content || ‘{}’); // 3. 根据AI分析结果触发不同的n8n子工作流进行路由 const routingWorkflowId this.getRoutingWorkflowId(aiResponse.classification); await this.n8nClient.workflows.execute(routingWorkflowId, { data: { originalTicket: ticketData, aiAnalysis: aiResponse, }, }); return aiResponse; } private getRoutingWorkflowId(classification: string): string { const map: Recordstring, string { ‘退货’: ‘workflow_id_for_returns’, ‘投诉’: ‘workflow_id_for_complaints’, // … 其他分类映射 }; return map[classification] || ‘workflow_id_for_general’; } }修改n8n工作流中的Function节点现在n8n工作流中的“Function”节点代码可以变得非常简洁它只需调用我们这个服务。// n8n Function 节点中的代码 const { TicketClassifierService } require(‘/absolute/path/to/your/compiled/service.js’); const classifier new TicketClassifierService(process.env.OPENAI_API_KEY, n8nClient); // items是n8n传入的数据 for (const item of items) { const ticketData { id: item.json.ticketId, description: item.json.description, customerEmail: item.json.email, }; try { const result await classifier.classifyAndRoute(ticketData); item.json.aiClassification result; return [item]; // 将结果传递给下一个节点 } catch (error) { // 错误处理例如将工单路由到人工审核队列 item.json.error error.message; // 触发另一个处理错误的工作流 await n8nClient.workflows.execute(‘workflow_id_for_errors’, { data: item.json }); return []; } }5.3 第三步编写测试与部署编写单元测试在tests/services/ticket-classifier.test.ts中我们可以测试分类逻辑可以模拟OpenAI响应。import { TicketClassifierService } from ‘../../src/services/ticket-classifier’; import { mockN8nClient, mockOpenAI } from ‘../mocks’; // 假设的模拟模块 describe(‘TicketClassifierService’, () { it(‘should correctly classify a return request’, async () { const service new TicketClassifierService(‘fake-key’, mockN8nClient); // 模拟OpenAI返回一个“退货”分类的JSON mockOpenAI.chat.completions.create.mockResolvedValue(mockReturnResponse); const result await service.classifyAndRoute({ id: ‘123’, description: ‘我上周买的鞋子尺寸不对想退货。’, customerEmail: ‘testexample.com’, }); expect(result.classification).toBe(‘退货’); expect(mockN8nClient.workflows.execute).toHaveBeenCalledWith(‘workflow_id_for_returns’, expect.anything()); }); });配置部署将你的TypeScript项目构建后可以通过多种方式部署作为n8n的“自定义节点”更深入的集成方式需要按照n8n的规范打包节点。作为独立的微服务你的服务部署在单独的服务器上通过REST API与n8n的Webhook节点和HTTP Request节点通信。n8n工作流调用你的服务API你的服务处理LLM逻辑并回调n8n触发后续流程。这种方式解耦更彻底技术栈更灵活。使用n8n-llm-workflows的CLI进行批量部署如果你将工作流定义为代码可以使用CLI工具将工作流JSON同步到多个n8n实例开发、测试、生产。6. 进阶技巧与避坑指南来自实战的经验之谈在真实项目中大规模使用这类工具我积累了一些宝贵的经验和需要警惕的“坑”。6.1 成本控制与性能优化LLM API调用是按Token收费的不当的使用会导致成本失控。设置预算与告警在OpenAI等平台后台设置每月使用预算和告警阈值。缓存机制对于常见、重复性的查询例如“你们的营业时间是什么”可以将LLM的回复缓存起来使用Redis或内存缓存下次直接返回避免重复调用。可以在你的服务层或n8n的“Function”节点中实现简单的缓存逻辑。模型选型不是所有任务都需要GPT-4。分类、提取实体等任务gpt-3.5-turbo甚至更小的微调模型完全够用成本可能只有前者的十分之一。在n8n-llm-workflows的配置中将模型类型作为可配置参数。异步与批处理如果工单量巨大不要来一个处理一个。可以设计工作流将一段时间内如每分钟的工单收集起来批量发送给LLM如果API支持批处理或者使用队列如RabbitMQ、AWS SQS异步处理避免阻塞主流程和应对速率限制。6.2 错误处理与鲁棒性LLM服务是外部依赖网络、速率限制、内容政策都可能导致失败。实现重试逻辑在调用LLM API的代码中使用指数退避策略进行重试。许多HTTP客户端库如axios-retry直接支持。import axiosRetry from ‘axios-retry’; axiosRetry(openaiInstance, { retries: 3, retryDelay: (retryCount) retryCount * 1000, // 1秒2秒3秒后重试 retryCondition: (error) error.response?.status 429, // 仅在遇到429过多请求时重试 });设置超时与降级方案为LLM调用设置严格的超时如10秒。如果超时或连续失败工作流应能自动降级例如将工单路由到“待人工处理”队列并发送告警通知。输入验证与清理在将用户输入送入LLM前进行基本的清理和长度检查防止提示词注入攻击或过长的输入耗尽Token。6.3 版本管理与团队协作当你的智能工作流越来越多团队协作开发时版本管理至关重要。工作流即代码将n8n工作流的JSON定义文件也纳入Git版本控制。n8n支持导入/导出JSON。你可以建立流程在n8n图形界面设计好工作流 - 导出JSON - 提交到Git - 通过CI/CD管道自动部署到测试和生产环境。环境隔离为开发、测试、生产环境配置不同的n8n实例和不同的API密钥例如开发环境用免费的或低限额的API密钥。使用n8n-llm-workflows的CLI进行状态同步可以编写脚本使用CLI工具对比代码库中的工作流定义与线上n8n实例中的工作流实现差异化的同步更新避免手动操作出错。6.4 监控与可观测性你需要知道你的AI工作流运行得怎么样。在关键节点添加日志在你的TypeScript服务中和n8n的“Function”节点中详细记录输入、输出、耗时、Token使用量、成本估算等信息。将这些日志发送到集中式日志系统如ELK Stack、Datadog。在n8n中利用“Error Trigger”节点创建一个全局的错误处理工作流被其他工作流的错误连线触发用于收集所有失败执行的上下文并发送告警如到Slack或邮件。自定义指标使用Prometheus等工具暴露诸如llm_api_call_duration_seconds、llm_api_call_total、workflow_classification_counter等指标以便在Grafana中绘制仪表盘实时监控系统健康度和业务效果。7. 常见问题排查与解决方案速查表在实际操作中你肯定会遇到各种问题。这里我整理了一份快速排查清单覆盖了从配置到运行的常见坑点。问题现象可能原因排查步骤与解决方案n8n客户端连接失败1. n8n实例地址或端口错误。2. API密钥无效或权限不足。3. 网络防火墙或代理阻止。1. 检查.env文件中的N8N_API_BASE_URL确保末尾有/。2. 登录n8n后台在“设置”-“API”中确认密钥有效并检查其权限范围是否包含工作流操作。3. 使用curl命令测试连通性curl -H “X-N8N-API-KEY: your_key” http://localhost:5678/api/v1/workflows。工作流执行返回4041. 工作流ID不正确。2. 工作流已被删除或禁用。1. 通过n8n客户端或API先列出所有工作流确认目标工作流的准确ID。2. 登录n8n图形界面确认该工作流存在且处于“活动”状态。LLM API调用超时或无响应1. API密钥错误或余额不足。2. 网络问题或代理配置错误。3. 请求体过大或格式错误。1. 在OpenAI等平台后台检查密钥状态和余额。2. 尝试在服务器上直接使用curl或ping测试到API域名的连通性。3. 在代码中打印出即将发送的请求体检查提示词长度和JSON格式是否正确。确保未超过模型上下文长度限制。TypeScript编译错误1. Node.js或TypeScript版本不匹配。2. 依赖包未安装或版本冲突。1. 检查package.json中的engines字段使用nvm切换到指定Node版本。2. 删除node_modules和package-lock.json重新运行npm install。检查是否有类型定义包types/…缺失。工作流测试失败输出不匹配1. LLM输出的非确定性即使温度低。2. 测试断言过于严格精确字符串匹配。3. 测试环境与生产环境配置不同。1. 为测试设置更低的温度如0并使用response_format: { type: “json_object” }来稳定JSON输出。2. 将断言改为检查关键字段是否存在或符合正则表达式而不是完全相等。3. 确保测试中使用的API密钥、模型名称等配置与测试意图一致例如测试时使用模拟响应。提示词注入导致意外行为用户输入中包含了精心构造的文本试图覆盖系统指令。1.输入过滤对用户输入进行基本的清理移除或转义可能被误解为指令的字符序列。2.使用分隔符在系统指令和用户输入之间使用明确的、唯一的分隔符如### END SYSTEM ###并在指令中要求模型忽略分隔符之外的内容。3.后置验证对LLM的输出进行业务逻辑验证如果输出完全不符合预期格式或包含敏感词则触发人工审核。回顾整个探索过程n8n-llm-workflows这个项目给我的最大启发是它找到了一条将低代码的敏捷性与代码的严谨性相结合的实用路径。它没有试图用代码完全取代n8n的可视化编排而是用代码去增强和赋能那些在可视化编排中难以管理、测试和规模化的部分——尤其是涉及LLM的复杂逻辑。对于想要认真构建企业级AI自动化应用却又受限于传统开发流程的团队来说这套方法论和工具组合拳无疑提供了一个极具吸引力的新选择。我个人在后续的项目中会持续沿用这种“n8n负责流程编排与基础连接外部服务负责复杂AI逻辑与业务规则”的架构模式这让我既能享受快速原型开发的乐趣又能保证最终交付物的稳定性和可维护性。
n8n-LLM工作流开发：低代码自动化与AI智能体集成实战
1. 项目概述当n8n遇上LLM一个低代码开发者的效率革命如果你和我一样常年混迹在低代码和自动化领域对n8n这个强大的工作流工具爱不释手同时又对当下火热的LLM大语言模型垂涎三尺那你肯定也遇到过和我一样的困境怎么把这两者优雅地结合起来是手动在n8n里一个个节点地配置HTTP请求去调用OpenAI API还是写一堆脚本去处理复杂的提示词工程和上下文管理这个过程既繁琐又容易出错更别提想规模化地测试和部署这些智能工作流了。直到我发现了n8n-llm-workflows这个项目它像是一把专门为这个场景打造的瑞士军刀让我这个习惯用图形化界面“拖拉拽”的开发者也能轻松驾驭AI智能体AI Agents和复杂的工作流编排。简单来说n8n-llm-workflows是一个基于TypeScript构建的工具包。它的核心目标不是替代n8n而是极大地增强n8n在处理LLM相关自动化任务时的能力。它提供了一套类型化的API客户端、一系列开箱即用的自动化模板以及一套用于管理、测试和部署这些工作流的脚手架。你可以把它理解为一个“n8n的LLM增强插件包”或者“智能工作流开发套件”。它的出现让构建一个能理解上下文、进行推理决策、并与其他系统交互的AI智能体工作流变得像搭积木一样直观。无论是想做一个智能客服聊天机器人一个自动分析报告并生成摘要的数据处理流水线还是一个能根据用户指令自主操作其他软件的数字员工这个工具包都提供了坚实的基础。2. 核心设计思路为什么我们需要一个专门的LLM工作流工具包在深入代码和配置之前我们先聊聊为什么单纯的n8n节点在应对LLM时显得力不从心以及n8n-llm-workflows是如何从设计上解决这些痛点的。这有助于你理解这个工具包的真正价值而不仅仅是把它当作一堆脚本的集合。2.1 传统n8n集成LLM的典型痛点在没有专用工具包时我们通常这样做使用n8n的“HTTP Request”节点调用OpenAI、Anthropic或本地部署的Hugging Face模型API。这听起来简单但实际操作中会踩无数个坑提示词Prompt管理混乱复杂的提示词模板包含变量、系统指令、少样本示例以长文本形式硬编码在节点配置里难以维护和复用。想调整一个示例得在图形界面里翻找半天。上下文Context处理繁琐LLM对话需要维护历史消息。在n8n中你需要手动设计流程来存储、读取、拼接和截断对话历史逻辑分散在多个“Function”或“Code”节点中流程图变得异常复杂。类型安全与错误处理缺失HTTP节点返回的是原始的JSON你需要手动解析choices[0].message.content。如果API响应结构变化或出错错误处理逻辑完全需要自己从头编写缺乏类型提示调试困难。工作流版本化与测试困难n8n工作流可以导出为JSON但如何对包含LLM调用的工作流进行单元测试、集成测试如何确保提示词的修改不会破坏现有功能缺乏一套标准化的测试方法。规模化部署的挑战当你拥有几十个LLM工作流时如何批量管理它们的API密钥、模型参数、速率限制如何实现蓝绿部署或金丝雀发布纯手动操作几乎不可能。2.2 n8n-llm-workflows的解决方案架构该项目正是瞄准了上述痛点提供了一个分层的解决方案底层类型化的API客户端。它封装了与n8n实例交互的所有操作如触发工作流、查询执行状态、读取数据并提供了完整的TypeScript类型定义。这意味着你在代码中调用client.workflow.execute()时编辑器能自动提示参数类型编译器能在构建时检查错误极大提升了开发体验和代码可靠性。中间层工作流定义与模板。项目提倡将工作流逻辑尤其是LLM交互部分从n8n的图形界面中部分“抽离”出来用代码进行定义和管理。它提供了示例模板展示了如何结构化地组织提示词、处理上下文、连接不同模型节点。这相当于为你的LLM工作流建立了一套“设计规范”。上层CLI工具与测试框架。这是实现“规模化”的关键。通过命令行工具你可以批量验证工作流配置、模拟输入数据运行测试、甚至与CI/CD管道集成。它把工作流从“手动点击运行的黑盒”变成了“可自动化测试的软件组件”。这种设计思路的核心是“Infrastructure as Code”理念在n8n工作流领域的实践。你的自动化逻辑不再仅仅存在于n8n服务器的数据库里也存在于受版本控制如Git管理的代码库中从而获得了可追溯、可测试、可重复部署的能力。3. 环境准备与项目初始化从零开始搭建你的开发工作站理论讲完了我们动手实操。假设你已经在本地或服务器上运行了一个n8n实例这是前提条件。接下来我们将一步步设置n8n-llm-workflows的开发环境。3.1 系统与软件 prerequisites首先确保你的开发环境满足以下要求。我强烈建议使用macOS/Linux系统或Windows下的WSL2进行开发以获得最佳的命令行体验。Node.js环境这是运行TypeScript项目的基础。要求版本在14.x或以上。我推荐使用nvmNode Version Manager来管理Node.js版本这样可以轻松切换不同项目所需的环境。# 检查当前Node.js版本 node --version # 如果未安装或版本过低使用nvm安装以安装v18为例 # 首先安装nvm然后 nvm install 18 nvm use 18包管理工具项目使用npm或yarn。通常npm随Node.js安装。确保其可用。npm --versionGit用于克隆项目代码库。这是开发者必备工具。git --version一个正在运行的n8n实例这是我们的“运行时环境”。你可以通过Docker快速启动一个本地实例这是最推荐的方式与生产环境隔离。docker run -it --rm \ --name n8n \ -p 5678:5678 \ -v ~/.n8n:/home/node/.n8n \ n8nio/n8n启动后在浏览器中访问http://localhost:5678完成n8n的初始设置。记住你设置的凭证后续API连接会用到。3.2 获取并初始化n8n-llm-workflows项目我们不从那个重复的ZIP链接下载而是直接从GitHub仓库克隆这样可以获得最新的代码和完整的Git历史方便后续贡献。克隆仓库git clone https://github.com/slayerlux/n8n-llm-workflows.git cd n8n-llm-workflows进入项目目录后你会看到标准的TypeScript项目结构src/源码目录、tests/测试目录、package.json配置文件等。安装项目依赖npm install # 或者使用 yarn yarn install这个过程会下载所有必要的依赖包包括TypeScript编译器、n8n API客户端库、测试框架等。环境变量配置项目通常需要连接你的n8n实例。创建一个.env文件参考项目根目录可能存在的.env.example文件来存储敏感配置。# .env 文件内容示例 N8N_API_BASE_URLhttp://localhost:5678/ N8N_API_KEYyour_n8n_api_key_here # 如果你的n8n实例需要Webhook URL也可能需要配置 N8N_WEBHOOK_URLhttp://your-ngrok-or-public-url.com注意N8N_API_KEY需要在你的n8n实例中生成。登录n8n后台进入“设置” - “API”创建一个新的API密钥并赋予它必要的工作流读写权限。切勿将此密钥提交到Git仓库中。构建项目由于是TypeScript项目我们需要将其编译为JavaScript才能运行。npm run build这会在项目根目录生成一个dist/文件夹里面是编译后的JS代码。完成以上步骤你的基础开发环境就准备好了。接下来我们将深入探索工具包的核心组件。4. 核心组件深度解析API客户端、工作流模板与CLI工具n8n-llm-workflows工具包主要由三大核心组件构成理解它们各自的作用和相互关系是高效使用它的关键。4.1 类型化的n8n API客户端这是与n8n实例通信的桥梁。项目内置的客户端抽象了n8n REST API的细节提供了强类型的方法调用。我们来看一个典型的使用示例假设在src/client.ts或示例中你会看到类似这样的客户端初始化import { N8nClient } from ‘./path-to-client’; // 假设的导入路径 // 从环境变量读取配置 const baseUrl process.env.N8N_API_BASE_URL; const apiKey process.env.N8N_API_KEY; // 初始化客户端 const client new N8nClient({ baseUrl, apiKey, }); // 使用客户端执行一个已知ID的工作流 async function runWorkflow(workflowId: string, inputData: any) { try { const execution await client.workflows.execute(workflowId, { data: inputData, }); console.log(‘工作流执行成功执行ID:’, execution.id); console.log(‘输出数据:’, execution.data); return execution.data; } catch (error) { console.error(‘工作流执行失败:’, error); throw error; } }为什么类型化如此重要开发效率在VS Code或WebStorm等IDE中输入client.workflows.后你会自动获得.execute,.get,.create等方法提示。错误预防如果你尝试传递一个不符合接口定义的inputDataTypeScript编译器会在你运行代码前就报错而不是在运行时才崩溃。代码可维护性所有API的请求和响应结构都有明确的类型定义新接手项目的开发者能快速理解数据流。4.2 示例自动化工作流模板这是项目的精华所在。在examples/或workflows/目录下你会找到一系列预构建的工作流模板。它们不仅仅是展示功能更是最佳实践的示范。我们来解剖一个典型的“智能问答聊天机器人”模板可能包含的结构提示词模板节点不再是硬编码文本而是通过一个“Function”节点或自定义节点从一个外部配置文件或数据库读取提示词模板。模板中使用像{{userQuestion}}、{{conversationHistory}}这样的占位符。上下文管理节点一系列节点负责从数据库如SQLite/PostgreSQL节点或内存如n8n的“Set”节点中读取上一次对话的历史将其格式化为LLM所需的消息数组格式例如[{role: “user”, content: “…”}, {role: “assistant”, content: “…”}]并智能地截断过长的历史以节省Token。LLM调用节点使用封装好的“HTTP Request”节点或自定义节点调用OpenAI API。关键点在于API密钥、模型名称如gpt-4-turbo-preview、温度temperature等参数被提取为工作流或项目的全局变量便于统一管理。输出解析与后处理节点LLM的回复可能是JSON、Markdown或纯文本。这里会包含节点来解析JSON、清理文本、或者根据回复内容触发后续动作例如如果用户说“订一张机票”则触发另一个订票工作流。实操心得不要只是导入这些模板就了事。花时间拆解每一个节点理解其配置。特别关注“错误处理”分支是如何设计的——LLM API可能因为速率限制、内容过滤或网络问题而失败一个健壮的工作流必须有重试机制和友好的失败反馈。4.3 CLI工具与测试套件对于严肃的项目可测试性至关重要。n8n-llm-workflows提供的CLI工具让你能够像测试普通函数一样测试工作流。假设项目提供了一个cli.js或通过npm scripts暴露的命令运行单个工作流测试npm run test:workflow -- --workflow-id你的工作流ID --input-file./test-data/input.json这个命令会读取input.json中的测试数据通过API触发指定工作流并断言输出是否符合output.json中的预期结果。批量测试与持续集成你可以在package.json中配置一系列测试脚本。“scripts”: { “test:all”: “npm run test:workflow -- --all”, “test:ci”: “npm run lint npm run build npm run test:all” }这样在GitHub Actions或GitLab CI中只需运行npm run test:ci就能自动完成代码风格检查、构建和所有工作流的功能测试。模拟与桩Stubbing高级用法涉及在测试中模拟LLM API的响应避免在测试时产生真实的API调用费用和不稳定性。这可能需要你结合像jest这样的测试框架并利用n8n客户端提供的拦截功能或使用像nock这样的HTTP模拟库。重要提示测试LLM工作流的输出具有挑战性因为LLM的回复是非确定性的即使温度设为0也可能有细微变化。因此测试断言往往不能是精确的字符串匹配而应该是语义匹配检查是否包含关键信息或结构化输出验证如果LLM被要求返回JSON则验证JSON的架构。项目模板应该提供这方面的示例。5. 实战构建并部署一个完整的AI客服工单分类工作流让我们结合所有知识从头构建一个实际可用的工作流。场景是一个电商平台用户通过在线表单提交客服请求。我们需要一个AI工作流来自动分析用户描述将其分类如“退货”、“投诉”、“咨询”、“表扬”并提取关键实体如订单号、产品名称然后自动分配给相应的客服团队。5.1 第一步在n8n中创建基础工作流在n8n编辑器中创建一个新的工作流命名为“AI客服工单自动分类”。设置Webhook触发器添加一个“Webhook”节点。这是为了接收从电商平台发来的工单提交数据。保存后n8n会生成一个唯一的Webhook URL如http://your-n8n.com/webhook/abc123。将这个URL配置到你的电商平台后台。设计后续节点在Webhook节点后我们暂时不连接LLM节点先连接一个“Function”节点用于将接收到的原始数据假设是JSON格式构造成发给LLM的提示词。5.2 第二步使用n8n-llm-workflows管理提示词与调用我们不把复杂的逻辑全写在n8n的图形界面里。而是在我们的TypeScript项目中创建一个服务模块。创建提示词模板文件src/prompts/ticket-classifier.tsexport const ticketClassificationPrompt 你是一个专业的电商客服工单分类AI。请分析以下用户提交的工单描述并完成以下任务 任务 1. **分类**将工单分类为以下之一[退货 投诉 咨询 表扬 其他]。 2. **提取信息**从描述中提取以下实体如果存在 - 订单号格式通常为纯数字或字母数字组合 - 产品名称 - 问题简述 3. **紧急程度**判断紧急程度[高 中 低]。高涉及人身安全、重大财务损失中影响使用需要尽快解决低一般咨询或建议。 用户描述 “{{ticketDescription}}” 请以严格的JSON格式回复且只包含JSON不要有任何额外解释。JSON格式如下 { “classification”: “分类结果”, “entities”: { “orderId”: “提取到的订单号或空字符串”, “productName”: “提取到的产品名称或空字符串”, “issueSummary”: “问题简述或空字符串” }, “urgency”: “紧急程度” } ;创建分类服务src/services/ticket-classifier.tsimport { N8nClient } from ‘../client’; import { ticketClassificationPrompt } from ‘../prompts/ticket-classifier’; import OpenAI from ‘openai’; // 假设使用OpenAI官方Node.js SDK export class TicketClassifierService { private openai: OpenAI; private n8nClient: N8nClient; constructor(apiKey: string, n8nClient: N8nClient) { this.openai new OpenAI({ apiKey }); this.n8nClient n8nClient; } async classifyAndRoute(ticketData: { id: string; description: string; customerEmail: string; }) { // 1. 构建最终提示词 const finalPrompt ticketClassificationPrompt.replace( ‘{{ticketDescription}}’, ticketData.description ); // 2. 调用OpenAI API const completion await this.openai.chat.completions.create({ model: ‘gpt-3.5-turbo-0125’, // 选用适合的、成本较低的模型 messages: [{ role: ‘user’, content: finalPrompt }], temperature: 0.1, // 低温度保证输出稳定性适合分类任务 response_format: { type: “json_object” }, // 强制JSON输出 }); const aiResponse JSON.parse(completion.choices[0].message.content || ‘{}’); // 3. 根据AI分析结果触发不同的n8n子工作流进行路由 const routingWorkflowId this.getRoutingWorkflowId(aiResponse.classification); await this.n8nClient.workflows.execute(routingWorkflowId, { data: { originalTicket: ticketData, aiAnalysis: aiResponse, }, }); return aiResponse; } private getRoutingWorkflowId(classification: string): string { const map: Recordstring, string { ‘退货’: ‘workflow_id_for_returns’, ‘投诉’: ‘workflow_id_for_complaints’, // … 其他分类映射 }; return map[classification] || ‘workflow_id_for_general’; } }修改n8n工作流中的Function节点现在n8n工作流中的“Function”节点代码可以变得非常简洁它只需调用我们这个服务。// n8n Function 节点中的代码 const { TicketClassifierService } require(‘/absolute/path/to/your/compiled/service.js’); const classifier new TicketClassifierService(process.env.OPENAI_API_KEY, n8nClient); // items是n8n传入的数据 for (const item of items) { const ticketData { id: item.json.ticketId, description: item.json.description, customerEmail: item.json.email, }; try { const result await classifier.classifyAndRoute(ticketData); item.json.aiClassification result; return [item]; // 将结果传递给下一个节点 } catch (error) { // 错误处理例如将工单路由到人工审核队列 item.json.error error.message; // 触发另一个处理错误的工作流 await n8nClient.workflows.execute(‘workflow_id_for_errors’, { data: item.json }); return []; } }5.3 第三步编写测试与部署编写单元测试在tests/services/ticket-classifier.test.ts中我们可以测试分类逻辑可以模拟OpenAI响应。import { TicketClassifierService } from ‘../../src/services/ticket-classifier’; import { mockN8nClient, mockOpenAI } from ‘../mocks’; // 假设的模拟模块 describe(‘TicketClassifierService’, () { it(‘should correctly classify a return request’, async () { const service new TicketClassifierService(‘fake-key’, mockN8nClient); // 模拟OpenAI返回一个“退货”分类的JSON mockOpenAI.chat.completions.create.mockResolvedValue(mockReturnResponse); const result await service.classifyAndRoute({ id: ‘123’, description: ‘我上周买的鞋子尺寸不对想退货。’, customerEmail: ‘testexample.com’, }); expect(result.classification).toBe(‘退货’); expect(mockN8nClient.workflows.execute).toHaveBeenCalledWith(‘workflow_id_for_returns’, expect.anything()); }); });配置部署将你的TypeScript项目构建后可以通过多种方式部署作为n8n的“自定义节点”更深入的集成方式需要按照n8n的规范打包节点。作为独立的微服务你的服务部署在单独的服务器上通过REST API与n8n的Webhook节点和HTTP Request节点通信。n8n工作流调用你的服务API你的服务处理LLM逻辑并回调n8n触发后续流程。这种方式解耦更彻底技术栈更灵活。使用n8n-llm-workflows的CLI进行批量部署如果你将工作流定义为代码可以使用CLI工具将工作流JSON同步到多个n8n实例开发、测试、生产。6. 进阶技巧与避坑指南来自实战的经验之谈在真实项目中大规模使用这类工具我积累了一些宝贵的经验和需要警惕的“坑”。6.1 成本控制与性能优化LLM API调用是按Token收费的不当的使用会导致成本失控。设置预算与告警在OpenAI等平台后台设置每月使用预算和告警阈值。缓存机制对于常见、重复性的查询例如“你们的营业时间是什么”可以将LLM的回复缓存起来使用Redis或内存缓存下次直接返回避免重复调用。可以在你的服务层或n8n的“Function”节点中实现简单的缓存逻辑。模型选型不是所有任务都需要GPT-4。分类、提取实体等任务gpt-3.5-turbo甚至更小的微调模型完全够用成本可能只有前者的十分之一。在n8n-llm-workflows的配置中将模型类型作为可配置参数。异步与批处理如果工单量巨大不要来一个处理一个。可以设计工作流将一段时间内如每分钟的工单收集起来批量发送给LLM如果API支持批处理或者使用队列如RabbitMQ、AWS SQS异步处理避免阻塞主流程和应对速率限制。6.2 错误处理与鲁棒性LLM服务是外部依赖网络、速率限制、内容政策都可能导致失败。实现重试逻辑在调用LLM API的代码中使用指数退避策略进行重试。许多HTTP客户端库如axios-retry直接支持。import axiosRetry from ‘axios-retry’; axiosRetry(openaiInstance, { retries: 3, retryDelay: (retryCount) retryCount * 1000, // 1秒2秒3秒后重试 retryCondition: (error) error.response?.status 429, // 仅在遇到429过多请求时重试 });设置超时与降级方案为LLM调用设置严格的超时如10秒。如果超时或连续失败工作流应能自动降级例如将工单路由到“待人工处理”队列并发送告警通知。输入验证与清理在将用户输入送入LLM前进行基本的清理和长度检查防止提示词注入攻击或过长的输入耗尽Token。6.3 版本管理与团队协作当你的智能工作流越来越多团队协作开发时版本管理至关重要。工作流即代码将n8n工作流的JSON定义文件也纳入Git版本控制。n8n支持导入/导出JSON。你可以建立流程在n8n图形界面设计好工作流 - 导出JSON - 提交到Git - 通过CI/CD管道自动部署到测试和生产环境。环境隔离为开发、测试、生产环境配置不同的n8n实例和不同的API密钥例如开发环境用免费的或低限额的API密钥。使用n8n-llm-workflows的CLI进行状态同步可以编写脚本使用CLI工具对比代码库中的工作流定义与线上n8n实例中的工作流实现差异化的同步更新避免手动操作出错。6.4 监控与可观测性你需要知道你的AI工作流运行得怎么样。在关键节点添加日志在你的TypeScript服务中和n8n的“Function”节点中详细记录输入、输出、耗时、Token使用量、成本估算等信息。将这些日志发送到集中式日志系统如ELK Stack、Datadog。在n8n中利用“Error Trigger”节点创建一个全局的错误处理工作流被其他工作流的错误连线触发用于收集所有失败执行的上下文并发送告警如到Slack或邮件。自定义指标使用Prometheus等工具暴露诸如llm_api_call_duration_seconds、llm_api_call_total、workflow_classification_counter等指标以便在Grafana中绘制仪表盘实时监控系统健康度和业务效果。7. 常见问题排查与解决方案速查表在实际操作中你肯定会遇到各种问题。这里我整理了一份快速排查清单覆盖了从配置到运行的常见坑点。问题现象可能原因排查步骤与解决方案n8n客户端连接失败1. n8n实例地址或端口错误。2. API密钥无效或权限不足。3. 网络防火墙或代理阻止。1. 检查.env文件中的N8N_API_BASE_URL确保末尾有/。2. 登录n8n后台在“设置”-“API”中确认密钥有效并检查其权限范围是否包含工作流操作。3. 使用curl命令测试连通性curl -H “X-N8N-API-KEY: your_key” http://localhost:5678/api/v1/workflows。工作流执行返回4041. 工作流ID不正确。2. 工作流已被删除或禁用。1. 通过n8n客户端或API先列出所有工作流确认目标工作流的准确ID。2. 登录n8n图形界面确认该工作流存在且处于“活动”状态。LLM API调用超时或无响应1. API密钥错误或余额不足。2. 网络问题或代理配置错误。3. 请求体过大或格式错误。1. 在OpenAI等平台后台检查密钥状态和余额。2. 尝试在服务器上直接使用curl或ping测试到API域名的连通性。3. 在代码中打印出即将发送的请求体检查提示词长度和JSON格式是否正确。确保未超过模型上下文长度限制。TypeScript编译错误1. Node.js或TypeScript版本不匹配。2. 依赖包未安装或版本冲突。1. 检查package.json中的engines字段使用nvm切换到指定Node版本。2. 删除node_modules和package-lock.json重新运行npm install。检查是否有类型定义包types/…缺失。工作流测试失败输出不匹配1. LLM输出的非确定性即使温度低。2. 测试断言过于严格精确字符串匹配。3. 测试环境与生产环境配置不同。1. 为测试设置更低的温度如0并使用response_format: { type: “json_object” }来稳定JSON输出。2. 将断言改为检查关键字段是否存在或符合正则表达式而不是完全相等。3. 确保测试中使用的API密钥、模型名称等配置与测试意图一致例如测试时使用模拟响应。提示词注入导致意外行为用户输入中包含了精心构造的文本试图覆盖系统指令。1.输入过滤对用户输入进行基本的清理移除或转义可能被误解为指令的字符序列。2.使用分隔符在系统指令和用户输入之间使用明确的、唯一的分隔符如### END SYSTEM ###并在指令中要求模型忽略分隔符之外的内容。3.后置验证对LLM的输出进行业务逻辑验证如果输出完全不符合预期格式或包含敏感词则触发人工审核。回顾整个探索过程n8n-llm-workflows这个项目给我的最大启发是它找到了一条将低代码的敏捷性与代码的严谨性相结合的实用路径。它没有试图用代码完全取代n8n的可视化编排而是用代码去增强和赋能那些在可视化编排中难以管理、测试和规模化的部分——尤其是涉及LLM的复杂逻辑。对于想要认真构建企业级AI自动化应用却又受限于传统开发流程的团队来说这套方法论和工具组合拳无疑提供了一个极具吸引力的新选择。我个人在后续的项目中会持续沿用这种“n8n负责流程编排与基础连接外部服务负责复杂AI逻辑与业务规则”的架构模式这让我既能享受快速原型开发的乐趣又能保证最终交付物的稳定性和可维护性。
