1. 项目概述当本地大模型遇上自动化工作流最近在折腾一个挺有意思的东西用 n8n 和 llama.cpp 在本地搭建一个“路由器”式的 AI 智能体。听起来有点玄乎其实核心想法很简单把本地运行的大语言模型LLM变成一个能理解复杂指令、并自动调用各种工具和 API 来完成任务的“智能中枢”。就像家里的路由器负责分配网络流量一样这个 AI-Agent 负责解析你的自然语言指令然后智能地调度、组合 n8n 中预先编排好的自动化工作流最终给你一个完整的结果。为什么是 n8n 和 llama.cpp 这个组合n8n 是一个强大的开源工作流自动化平台它通过可视化的节点连接能轻松集成数百种服务从数据库、API 到本地脚本。而 llama.cpp 则是一个高效的在消费级硬件上本地运行开源大模型的推理框架。两者的结合完美解决了“大模型有脑子但没手无法执行具体操作”和“自动化工具有手但没脑子缺乏智能决策”的问题。你不用再把 API Key 交给云端服务所有数据、模型推理、业务流程都在你自己的机器上闭环在追求数据隐私和可控性的今天这无疑是个极具吸引力的方案。这个项目适合那些已经对本地部署 AI 有些经验并且希望将 AI 能力与具体业务自动化深度结合的开发者、运维或技术爱好者。2. 核心架构与设计思路拆解2.1 为什么是“路由器”模式的 AI-Agent传统的 AI 应用无论是聊天机器人还是文本生成大多是一次性的问答或内容创作。而“路由器”模式的核心在于决策与调度。想象一下你给这个 Agent 下达一个指令“帮我分析上个月的网站访问日志找出异常流量并生成一份报告发到我的邮箱。” 这个指令包含了多个子任务1) 获取日志文件2) 分析数据3) 识别异常4) 生成报告5) 发送邮件。一个简单的聊天模型可能会回复你“我可以帮你写分析报告的模板”但它不会去执行。而我们的 Router AI-Agent 需要做的是理解与规划利用 llama.cpp 运行的本地大模型将你的自然语言指令分解成一系列可执行的、有序的步骤。匹配与路由将分解后的步骤与 n8n 中已经创建好的、对应特定功能的工作流进行匹配。比如“获取日志”对应一个从服务器拉取文件的流程“分析数据”对应一个调用 Python 脚本或 SQL 查询的流程。执行与编排按顺序或根据条件触发这些 n8n 工作流并将上一个工作流的输出作为下一个工作流的输入进行传递。汇总与回复将所有工作流的执行结果汇总最终通过模型生成一个自然语言的总结回复给你。这个过程中llama.cpp 模型扮演“大脑”负责理解和规划n8n 扮演“四肢”和“工具箱”负责具体执行而连接两者的“神经中枢”就是我们用代码编写的 Agent 核心逻辑也就是“路由器”本身。2.2 技术选型深度解析n8n 与 llama.cpp 的黄金组合n8n 的优势与考量n8n 选择它不仅仅因为它是开源的。它的节点化、低代码特性使得创建和修改工作流异常快速。更重要的是它的HTTP Request 节点和Webhook 节点为我们提供了完美的交互接口。我们可以让 Agent 核心程序通过 HTTP 请求来触发特定的工作流。此外n8n 支持本地执行 JavaScript/Python 代码节点这意味着我们可以在工作流中嵌入复杂的数据处理逻辑而无需依赖外部服务。不过n8n 本身并不是为高并发、低延迟的 AI 交互设计的所以在架构上我们需要将其定位为“任务执行器”而非“实时响应器”。llama.cpp 的定位与模型选择llama.cpp 以其极高的推理效率和低内存占用著称特别适合在本地部署 7B、13B 参数的模型。对于 Agent 任务模型的选择至关重要。它不需要特别强的创意写作能力但需要优秀的任务分解Task Decomposition、工具调用Tool Calling和结构化输出Structured Output能力。因此像DeepSeek-Coder、Qwen2.5-Coder或专门微调过的Mistral系列模型往往是比原始 Llama 更好的选择。它们能更好地理解“接下来需要调用哪个工具”、“需要的参数是什么”这类指令。你需要根据自己机器的硬件主要是 GPU 显存或 CPU 内存来权衡模型的大小和精度FP16, GPTQ, GGUF 等格式。架构设计图概念层面[用户指令] - [Agent 核心 (Python/Node.js)] - [调用本地 llama.cpp API (思考与规划)] - [解析出任务列表与参数] - [按序调用对应 n8n Webhook] - [n8n 执行工作流1, 工作流2...] - [结果返回 Agent 核心] - [汇总结果发送给 llama.cpp 生成总结] - [最终回复给用户]这个架构的关键在于 Agent 核心程序的编写它需要实现与大模型 API 的对话、对模型输出的解析、以及对 n8n 工作流的调度。注意这不是一个“开箱即用”的集成llama.cpp 主要提供模型推理 API如通过llama-servern8n 提供自动化执行能力中间的“路由器”逻辑需要你自己用脚本桥接。这是本项目最大的价值创造点。3. 环境准备与核心组件部署3.1 llama.cpp 模型服务部署首先我们需要一个能提供 API 服务的本地大模型。这里以 llama.cpp 的server为例。获取 llama.cpp 并编译git clone https://github.com/ggerganov/llama.cpp cd llama.cpp make -j4 # 根据你的 CPU 核心数调整Linux/macOS # 或者使用 CMake 进行更灵活的编译支持 CUDA 等加速 mkdir build cd build cmake .. -DLLAMA_CUBLASON # 启用 CUDA 加速 cmake --build . --config Release下载合适的 GGUF 格式模型 前往 Hugging Face 或 ModelScope寻找适合你硬件和任务需求的模型。例如Qwen2.5-Coder-7B-Instruct-GGUF。下载对应的.gguf文件到llama.cpp目录下的models/文件夹。启动模型 API 服务器# 在 build 目录或编译产出目录下 ./bin/server -m ../models/qwen2.5-coder-7b-instruct.Q4_K_M.gguf -c 4096 --host 0.0.0.0 --port 8080-m: 指定模型路径。-c: 上下文长度根据模型能力设置。--host 0.0.0.0: 允许其他本地服务如你的 Agent 程序访问。--port 8080: 指定服务端口。启动成功后你会看到类似HTTP server listening on http://0.0.0.0:8080的日志。此时一个兼容 OpenAI API 格式的本地模型服务就运行在http://localhost:8080了。你可以用curl简单测试curl http://localhost:8080/v1/chat/completions -H Content-Type: application/json -d { model: gpt-3.5-turbo, messages: [{role: user, content: Hello}], max_tokens: 100 }3.2 n8n 的安装与基础工作流创建n8n 的安装方式非常灵活这里推荐使用 Docker最为方便。使用 Docker 运行 n8ndocker run -d --name n8n -p 5678:5678 -v ~/.n8n:/home/node/.n8n n8nio/n8n这条命令会在后台运行 n8n将本地端口 5678 映射到容器内端口并将工作流等数据持久化在本地~/.n8n目录。访问与初始化 打开浏览器访问http://localhost:5678。按照引导完成初始用户注册。之后你就进入了 n8n 的可视化编辑器。创建一个示例“工具”工作流 我们的 Agent 需要调用 n8n 中的工作流作为“工具”。首先我们创建一个最简单的工具——一个查询当前时间的工作流。在 n8n 编辑器中新建一个工作流。从节点面板拖入一个“Webhook”节点。配置它为POST方法并设置一个路径例如/get-current-time。保存后n8n 会生成一个唯一的 Webhook URL如http://localhost:5678/webhook/your-workflow-id/get-current-time。这个 URL 就是 Agent 调用这个“工具”的入口。连接一个“Function”节点或“Set”节点。在代码或字段中设置一个返回当前时间的逻辑。例如在 Function 节点中使用return [{json: {currentTime: new Date().toISOString()}}];。再连接一个“Respond to Webhook”节点确保工作流能正确返回响应。保存并激活这个工作流。现在当你向那个 Webhook URL 发送 POST 请求时就会得到当前时间的 JSON 响应。实操心得在 n8n 中为每个独立功能创建单独的工作流并通过 Webhook 触发这是构建“工具库”最清晰的方式。记得为每个工作流起一个语义化的名字如“获取系统时间”、“查询数据库用户”并在描述中写明其功能和输入输出格式这后续会帮助大模型理解该工具的用途。4. Agent 核心路由器的实现这是项目的核心代码部分。我们将用 Python 来实现这个“路由器”逻辑因为它有丰富的库支持 HTTP 请求和 JSON 处理。4.1 定义工具清单与模型系统提示词首先Agent 需要知道它有哪些“工具”可用。我们需要维护一个工具清单并生成引导模型的系统提示词。# tools.py import json # 定义 n8n 工作流工具清单 N8N_TOOLS [ { name: get_current_time, description: 获取当前的系统时间ISO 8601 格式。, parameters: { type: object, properties: {}, # 此工具无需参数 required: [] }, n8n_webhook_url: http://localhost:5678/webhook/your-workflow-id-1/get-current-time }, { name: search_local_files, description: 在指定目录下搜索包含特定关键词的文件。, parameters: { type: object, properties: { directory: {type: string, description: 要搜索的目录路径。}, keyword: {type: string, description: 搜索关键词。} }, required: [directory, keyword] }, n8n_webhook_url: http://localhost:5678/webhook/your-workflow-id-2/search-files }, # ... 可以继续添加更多工具 ] def get_system_prompt(): 生成系统提示词告诉模型可用的工具及其用法。 tools_json json.dumps(N8N_TOOLS, indent2, ensure_asciiFalse) prompt f你是一个智能助手可以调用以下工具来帮助用户完成任务。工具列表如下 {tools_json} 请遵循以下规则 1. 理解用户请求判断是否需要调用工具以及调用哪个工具。 2. 如果需要调用工具你必须严格按照以下 JSON 格式回复且只回复这个 JSON 对象 json {{ thought: 你的思考过程解释为什么选择这个工具。, tool_to_call: 工具名称必须与上述列表中的 name 字段完全一致。, tool_parameters: {{}} // 工具所需的参数字典即使为空也必须保留此字段。 }}如果不需要调用工具或任务已完成请用自然语言直接回复用户。一次只调用一个工具。 return prompt这个系统提示词至关重要它用结构化输出JSON的要求来“约束”模型的行为使其输出易于被程序解析。 ### 4.2 实现与大模型和 n8n 的交互循环 接下来我们编写主循环处理用户输入、调用模型、解析输出、执行工具、并整合结果。 python # agent_router.py import requests import json import re from tools import N8N_TOOLS, get_system_prompt class RouterAIAgent: def __init__(self, llm_api_urlhttp://localhost:8080/v1/chat/completions): self.llm_api_url llm_api_url self.system_prompt get_system_prompt() self.conversation_history [{role: system, content: self.system_prompt}] def _call_llm(self, messages): 调用本地 llama.cpp API payload { model: gpt-3.5-turbo, # 模型名可任意填写llama.cpp server 会忽略 messages: messages, max_tokens: 1024, temperature: 0.1, # 低温度保证输出更稳定、更结构化 } try: response requests.post(self.llm_api_url, jsonpayload, timeout60) response.raise_for_status() return response.json()[choices][0][message][content] except Exception as e: return f调用模型失败: {e} def _parse_tool_call(self, model_response): 尝试从模型回复中解析出工具调用指令 # 使用正则表达式提取 JSON 块 json_match re.search(rjson\s*(.*?)\s*, model_response, re.DOTALL) if not json_match: # 如果没有代码块尝试直接解析整个回复如果它是纯JSON json_str model_response.strip() else: json_str json_match.group(1).strip() try: tool_call json.loads(json_str) # 验证必要字段 if all(k in tool_call for k in (thought, tool_to_call, tool_parameters)): return tool_call except json.JSONDecodeError: pass return None # 不是有效的工具调用 def _execute_n8n_tool(self, tool_name, parameters): 调用对应的 n8n Webhook 执行工具 tool next((t for t in N8N_TOOLS if t[name] tool_name), None) if not tool: return {error: f未知工具: {tool_name}} webhook_url tool[n8n_webhook_url] try: # 向 n8n 的 Webhook 发送 POST 请求参数放在 JSON body 中 resp requests.post(webhook_url, jsonparameters, timeout30) resp.raise_for_status() return resp.json() # 假设 n8n 工作流返回 JSON except Exception as e: return {error: f调用工具 {tool_name} 失败: {e}} def chat_round(self, user_input): 处理一轮用户对话 # 1. 将用户输入加入历史 self.conversation_history.append({role: user, content: user_input}) # 2. 调用大模型获取回复 llm_response self._call_llm(self.conversation_history) print(f[模型原始回复]\n{llm_response}\n) # 3. 尝试解析是否为工具调用 tool_call self._parse_tool_call(llm_response) if tool_call: print(f[工具调用解析] 思考: {tool_call[thought]}) print(f[工具调用解析] 工具: {tool_call[tool_to_call]}, 参数: {tool_call[tool_parameters]}) # 4. 执行工具 tool_result self._execute_n8n_tool(tool_call[tool_to_call], tool_call[tool_parameters]) print(f[工具执行结果]\n{tool_result}\n) # 5. 将工具执行结果作为新的上下文再次调用模型进行总结或下一步决策 result_message f工具 {tool_call[tool_to_call]} 的执行结果是: {json.dumps(tool_result, ensure_asciiFalse)} self.conversation_history.append({role: user, content: result_message}) # 再次调用模型让它基于工具结果生成给用户的回复或决定下一步 final_response self._call_llm(self.conversation_history) # 将模型的最终回复加入历史 self.conversation_history.append({role: assistant, content: final_response}) return final_response else: # 如果不是工具调用直接作为最终回复 self.conversation_history.append({role: assistant, content: llm_response}) return llm_response # 简单的主循环 if __name__ __main__: agent RouterAIAgent() print(本地 Router AI-Agent 已启动。输入 quit 退出。) while True: try: user_input input(\n用户: ) if user_input.lower() quit: break response agent.chat_round(user_input) print(f\n助手: {response}) except KeyboardInterrupt: break except Exception as e: print(f发生错误: {e})这个RouterAIAgent类实现了一个简单的循环用户输入 - 模型思考可能输出工具调用 JSON- 解析并执行工具 - 将结果反馈给模型 - 模型生成最终回复。这是一个单轮工具调用的基础框架复杂的任务需要扩展为支持多轮规划和调用的状态机。5. 高级功能与优化实践5.1 实现多步骤任务规划与执行上面的基础版只能处理单次工具调用。对于“查日志并发邮件”这样的多步骤任务我们需要增强 Agent 的规划能力。这可以通过以下两种方式实现在系统提示词中要求模型输出步骤列表修改系统提示词要求模型在接到复杂任务时先输出一个完整的步骤规划Step-by-Step Plan然后 Agent 程序按顺序执行每个步骤。这要求模型有较强的规划能力。实现递归或循环调用这是更灵活的方式。当模型完成一个工具调用并得到结果后Agent 不急于生成最终回复而是再次将“当前状态包含所有历史结果”和“原始任务”一起提交给模型询问“基于当前结果和原始任务下一步应该做什么”。如此循环直到模型认为任务完成并输出最终总结。第二种方式的提示词片段示例...工具定义部分不变... 当前任务状态 - 原始用户目标{original_goal} - 已执行步骤 1. 步骤1描述结果{result1} 2. 步骤2描述结果{result2} - 当前最新情况{latest_context} 请分析基于当前状态和原始目标下一步应该调用工具吗如果需要请按之前的 JSON 格式指定工具如果任务已完成请直接给出给用户的最终答复。这相当于让模型在每一轮都重新评估局势动态决定下一步容错性和灵活性更高。5.2 n8n 工作流的设计模式与最佳实践为了让 Agent 更好地调用n8n 工作流的设计需要遵循一些规范统一的接口所有作为“工具”的工作流其 Webhook 应接受 JSON 格式的 POST 请求并返回结构化的 JSON 响应。响应中最好包含success布尔值、data主要数据和message可选信息字段。错误处理在工作流内部使用“Catch”节点来捕获任何节点可能抛出的错误并将错误信息格式化为统一的错误响应 JSON 返回给 Agent而不是让工作流执行失败。参数验证在 Webhook 节点后可以接一个“Function”节点来验证输入参数是否齐全、格式是否正确避免无效调用进入核心逻辑。敏感信息处理涉及密码、API密钥等务必使用 n8n 的“Credentials”功能存储不要在工作流中硬编码。Agent 调用时也无需传递这些敏感信息。工作流模块化将常用功能如数据格式转换、调用特定 API封装成子工作流Subworkflow可以提高复用性和可维护性。5.3 性能优化与稳定性保障llama.cpp 推理优化量化使用 Q4_K_M 或 Q5_K_M 等量化等级的 GGUF 模型能在精度损失极小的情况下大幅降低内存占用和提升推理速度。批处理与缓存如果并发请求多可以考虑使用llama.cpp的-b批处理大小参数或者部署像llama-cpp-python这样的 Python 绑定库并启用 KV 缓存。硬件加速确保编译时启用了正确的后端如 CUDA for NVIDIA GPU, Metal for Apple Silicon能获得数倍至数十倍的性能提升。n8n 执行优化异步调用Agent 在调用 n8n Webhook 时如果任务耗时较长应采用异步方式例如n8n 工作流快速返回一个“任务已接收”的响应然后通过回调或让 Agent 轮询另一个“获取结果”的 Webhook 来取得最终结果避免 HTTP 请求长时间阻塞。资源隔离对于可能消耗大量资源CPU/内存的工作流可以考虑使用 n8n 的“队列”模式或将其部署到单独的进程中避免影响其他轻量级工作流或 n8n 主服务。Agent 自身的健壮性重试机制对 n8n 或 llama.cpp 的 HTTP 调用添加指数退避的重试逻辑。超时设置为所有网络请求设置合理的超时时间避免线程被无限挂起。日志记录详细记录每一轮对话、模型回复、工具调用和结果便于问题排查和效果分析。6. 常见问题与排查技巧实录在实际搭建和运行过程中你几乎一定会遇到下面这些问题。这里记录了我的踩坑实录和解决方案。6.1 模型不输出结构化 JSON问题模型经常无视系统提示词中的 JSON 格式要求回复自然语言。排查与解决检查系统提示词确保提示词清晰、强硬地要求了 JSON 格式并提供了无可挑剔的示例。可以尝试用“你必须”、“只能”等强约束性词语。调整温度Temperature将 API 调用时的temperature参数调低如 0.1降低模型输出的随机性使其更“听话”。使用“Grammar”约束llama.cpp 的 server 支持GBNF 语法来强制约束模型输出格式。这是终极解决方案。你需要编写一个.gbnf文件来定义你期望的 JSON 结构然后在启动 server 时通过--grammar参数加载。这能近乎 100% 保证输出格式正确。模型能力尝试换用指令遵循能力更强、更擅长结构化输出的模型如Mistral-7B-Instruct-v0.3或Qwen2.5-Coder系列。6.2 n8n Webhook 调用失败或超时问题Agent 调用 n8n Webhook 时返回错误或长时间无响应。排查步骤手动测试首先用curl或 Postman 手动向 Webhook URL 发送一个 POST 请求检查 n8n 工作流是否能正常触发和返回。curl -X POST http://localhost:5678/webhook/your-id/your-path -H Content-Type: application/json -d {}检查工作流状态在 n8n 的“执行列表”中查看该工作流的执行记录。如果执行失败可以点进去查看具体是哪个节点报错。检查网络与防火墙确保运行 Agent 的机器能访问到运行 n8n 的localhost:5678。如果是 Docker 部署注意容器网络模式bridge下从宿主机外部访问需要用宿主机的 IP 和映射端口。工作流逻辑错误常见于 Function 节点代码错误、HTTP Request 节点连接超时等。利用 n8n 的“调试模式”可以逐步执行并查看每个节点的输入输出是定位问题的利器。6.3 多轮对话中上下文混乱或遗忘问题在连续对话中模型忘记了之前用户说过的话或工具执行的结果。解决管理对话历史在RouterAIAgent类中我们维护了conversation_history列表。关键在于在每次调用模型时需要将完整的、精简的历史记录传递过去。llama.cpp server 的上下文长度有限如 4096历史记录太长会被截断。历史摘要对于非常长的对话可以实现一个摘要功能。当历史 token 数接近上限时调用模型对之前的对话内容进行总结然后用一段摘要替换掉旧的历史消息从而节省上下文窗口。只传递关键信息在工具调用循环中不必每次都传递全部原始对话。可以只传递“原始目标”、“最新工具结果”和“上一步的模型思考”这能有效节省上下文。6.4 工具匹配不准或参数提取错误问题模型选择了错误的工作流或提取的参数格式不对。解决优化工具描述tools.py中每个工具的description和parameters的description字段要尽可能精确、无歧义。用模型能理解的语言描述清楚工具的用途、输入和输出。提供示例在系统提示词中除了工具列表还可以提供一两个用户查询和正确工具调用 JSON 的示例Few-shot Learning能显著提升模型的表现。后置参数校验与修正在 Agent 解析出工具名和参数后执行调用前可以加入一层简单的校验逻辑。例如检查必填参数是否存在参数类型是否大致符合预期如路径是否为字符串。甚至可以准备一个轻量级的“参数修正”提示词让模型对不明确的参数进行二次确认。这个本地 Router AI-Agent 项目就像在拼装一个数字时代的“瑞士军刀”llama.cpp 提供了智能的刀柄n8n 则是各种各样锋利的刀片而你的代码则是将它们牢固结合在一起的卡榫和弹簧。整个过程最耗时的部分往往不是写代码而是反复调试提示词、设计合理的工作流接口、以及处理各种边界情况。当看到一句简单的自然语言指令被自动拆解、并驱动多个复杂的后台流程逐一执行完成时那种成就感是巨大的。它让自动化不再是死板的“如果-那么”而是变成了能理解你意图的、活的智能流程。你可以从本文提供的最简框架开始先实现一两个工具感受整个链路跑通的快感然后再逐步扩展你的工具库并加入错误处理、状态管理等更复杂的逻辑。