AIRI 接入 ComfyUI 本地图像生成工作流配置、验证与源码级原理【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiAIRI本地自托管 AI 伴侣通过 Artistry 模块支持将图像生成任务交给 ComfyUI 执行让你复用自己安装的模型、节点与工作流把图像生成完整保留在本地环境。本文以官方 ComfyUI 接入指南为主体结合仓库中 ComfyUI Provider 页面 与 主进程 Provider 实现 的源码细节完整讲解从服务准备、工作流导入、连接测试到端到端验证的每一步并揭示 AIRI 调用 ComfyUI 的底层 API 调用链与参数注入机制。读完本文你将能独立完成 ComfyUI 的接入、暴露字段的安全配置、故障排查并理解exposedFields、占位符替换、轮询取图等内部实现原理。为什么选择 ComfyUIAIRI 的 Artistry 模块支持多种图像生成提供者ComfyUI 是其中的本地选项。选择 ComfyUI 的意义在于复用已有资产使用你自己安装的模型Checkpoint、LoRA、VAE、自定义节点与已调试好的工作流无需在云端重复配置本地环境闭环图像生成发生在你的本地机器或可信局域网内提示词与生成结果不离开你的网络边界灵活可控任何能在 ComfyUI 中直接运行的 API 工作流都能被 AIRI 调用。从源码结构看这一能力由三部分协同实现packages/stage-shared/src/artistry.ts定义了跨进程调用契约连接测试、配置同步、无头生成等事件Artistry 模块 Store 保存comfyuiServerUrl、comfyuiSavedWorkflows、comfyuiActiveWorkflow等状态而 ComfyUI Provider 在主进程侧真正执行 HTTP 调用。准备工作ComfyUI 服务与工作流接入前需要准备三件事启动 ComfyUI 服务。AIRI 默认连接http://localhost:8188请确认 ComfyUI 已在默认端口运行。准备一个可直接执行的图像工作流并从 ComfyUI 导出其API 格式的工作流 JSONAPI format workflow。这是关键步骤AIRI 消费的是扁平化的 API 格式nodeId - { class_type, inputs, _meta }而非用于界面展示的 UI 格式。确认网络可达。如果 AIRI 与 ComfyUI 不在同一台设备需要保证该地址能从 AIRI 所在设备正常访问同一可信局域网通常即可必要时需配置 ComfyUI 的监听地址与防火墙。原文在导入工作流时的安全提示同样适用于此导入前请务必检查工作流中的节点、模型路径与参数不要从不可信来源导入工作流 JSON。在 AIRI 中配置 ComfyUI1. 填写 Server URL 并测试连接打开Settings → Providers → Artistry → ComfyUI填写 ComfyUI 的Server URL默认http://localhost:8188然后点击Test验证 AIRI 能否读取到 ComfyUI 的服务状态。连接测试在不同运行环境下走了两条不同路径见 comfyui.vue桌面端Electron通过 IPC 将测试请求代理到主进程由主进程发起请求以绕过浏览器 CORS 限制。渲染进程先通过artistryTestComfyUIConnection事件定义于 artistry.ts返回{ ok, info, isCors }调用主进程再由主进程侧实现完成实际的连通性探测浏览器端直接以 CORS 模式fetchComfyUI 的/system_stats接口成功后会把检测到的 GPU 设备名展示在界面上data.devices[].name。测试成功时会显示绿色状态信息失败则显示红色错误信息若错误信息中包含fetch或CORS界面会额外渲染一个 CORS 排障提示框并给出重启 ComfyUI 时应使用的 CORS 启动选项。2. 上传 API 工作流 JSON 并选择暴露字段在Workflow区域点击上传按钮选择之前导出的 API 格式.json文件。上传后 AIRI 会解析工作流并列出所有节点见 comfyui.vue节点按 API 格式的扁平对象解析每个nodeId对应一个节点标题取自node._meta?.title无标题时回退到class_type每个节点的输入字段会逐一列出连接线数组link 数组会被自动跳过只保留可直接赋值的标量输入文本、数值、布尔值等你需要为每个节点勾选 AIRI 允许控制的输入字段这些被勾选的字段组成该工作流的exposedFields暴露字段。随后填写工作流名称并保存。保存时会生成ComfyUIWorkflowTemplate结构为{ id, name, workflow, exposedFields }其中id由名称自动规整小写、非字母数字转为-。第一个保存的工作流会自动被设为活动工作流保存多个后可在列表中通过单选按钮切换活动工作流。3. 理解暴露字段与配置片段在已保存工作流的展开详情中AIRI 会展示两个重要信息Exposed Parameters按节点标题分组展示已暴露的字段直观呈现 AIRI 对该工作流可控制的参数面Config Snippet一个可直接复制的 JSON 片段模板形如{ template: 工作流id, 节点标题: { 字段: ... } }。它展示了在调用 Artistry 时如何按节点标题传参覆盖字段值——这正是暴露字段是安全边界这一设计的体现。验证配置是否生效按以下顺序完成端到端验证在Settings → Modules → Consciousness中选择一个支持工具调用tool calling的聊天模型。AIRI 需要模型先调用 Artistry 工具ComfyUI 才会收到生成任务打开Settings → Modules → Artistry选择ComfyUI (Local)回到聊天窗口让 AIRI 生成一张合规非敏感图片观察 ComfyUI 的Queue或History中是否出现任务。若有图片返回即证明连接、活动工作流、暴露字段与聊天模型的工具调用全链路均正常。源码视角AIRI 如何驱动 ComfyUI 生成主流程队列 → 轮询 → 取图主进程的ComfyUIProvidercomfyui.ts在收到生成请求后执行如下调用链解析模板按request.extra?.template || request.model || activeWorkflowId的优先级确定工作流模板若未配置任何模板任务直接以失败状态返回并提示先在工作流区上传工作流应用覆盖参数深拷贝工作流后将请求中的提示词与额外参数注入到暴露字段详见下文提交任务POST {serverUrl}/prompt请求体为{ prompt: resolvedPrompt }成功响应中携带prompt_id轮询结果每 5 秒POLL_INTERVAL_MS轮询GET /history/{prompt_id}总超时 5 分钟POLL_TIMEOUT_MS。若任务结束但输出为空会等待 1 秒重试一次以防竞态条件拼装图片 URL从任意节点的输出中取第一张图片拼出{serverUrl}/view?filename...subfolder...typeoutput形式的结果地址返回给界面。参数注入的安全边界机制applyOverridescomfyui.ts实现了参数注入的核心逻辑提示词自动注入若请求携带 prompt 且未使用{{PROMPT}}占位符AIRI 会找到第一个暴露了text字段的节点并注入提示词按节点标题匹配request.extra中非保留键template、internalJobId、remixId、options的对象值被当作节点标题 - 字段值的覆盖映射仅当该字段在exposedFields中才会被写入节点输入——未暴露的字段即使传入也会被忽略这就是参数注入的安全边界seed 自动随机化若seed被暴露且未显式指定每次生成会自动填入Math.floor(Math.random() * 1e15)保证每次生成结果不同。双向流程图片上传与占位符当工作流或请求中包含{{IMAGE}}/{{PROMPT}}占位符时AIRI 会进入双向流程comfyui.ts若请求携带图片且检测到{{IMAGE}}先通过POST /upload/imagemultipart 表单文件名vhack_时间戳.png把图片上传到 ComfyUI 的 input 目录拿到返回的文件名随后在整棵工作流对象上递归替换{{PROMPT}}与{{IMAGE}}占位符再提交队列。这为换装/改材质等图生图场景提供了支持。跨进程契约整个 Artistry 能力通过 artistry.ts 中定义的 Eventa 事件在渲染进程与主进程间通信包括ARTISTRY_SYNC_CONFIG_ADDRESS同步提供者配置、ARTISTRY_TEST_COMFYUI_CONNECTION_ADDRESS测试连接以及artistryGenerateHeadless无头生成返回imageUrl或base64。桌面端的 artistry-bridge.ts 与 artistry 配置 负责在两侧桥接这些调用。故障排查Test 失败确认 ComfyUI 正在运行并检查Server URL、端口与网络路由是否正确。浏览器端测试还会受到 CORS 限制可改用桌面端IPC 代理进行测试。浏览器报跨域错误使用 AIRI 的 ComfyUI Provider 页面上提示的 CORS 选项重启 ComfyUI即带上对应的--enable-cors-header类启动参数具体以页面展示为准。工作流在 ComfyUI 中失败将 API 格式的工作流 JSON 重新导入 ComfyUI 本体逐一确认其中引用的每个自定义节点与模型均已安装且路径正确。Queue / History 中始终没有任务交互式 Artistry 流程要求所选聊天模型支持工具调用并确认Settings → Modules → Artistry已设为ComfyUI (Local)。纯文本、无法调用工具的模型无法启动交互式 Artistry 任务。小结ComfyUI 接入为 AIRI 提供了完全本地化的图像生成能力一次导入 API 工作流、勾选暴露字段、激活模板即可让聊天模型通过工具调用把生成任务送入本地 ComfyUI 队列并通过轮询 History 取回结果。理解exposedFields安全边界、{{PROMPT}}/{{IMAGE}}占位符与双向上传流程能帮助你构建更复杂的本地图像工作流同时保持对参数面的完全掌控。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考