Heym LLM 节点完全指南：一次搞定文本生成、视觉理解、结构化输出与 Batch API 批量调用

在 Heym 工作流中，LLM 节点是与大语言模型交互的核心组件：它可以生成文本、理解图片（视觉输入）、生成图片、返回符合 JSON Schema 的结构化结果，还能通过 Batch API 一次性提交成百上千条请求。本文将带你快速上手 Heym LLM 节点的 5 大核心能力，并给出批量模式与故障回退等实用技巧，让每一条 LLM 调用都可控、可观测。

什么是 Heym LLM 节点？

LLM 节点通过已配置的LLM Credential（API 密钥凭据）调用语言模型，是 Heym 中实现 AI 能力的入口。它支持的能力包括：

节点的参数面板定义在 LlmNodeProperties.vue，运行逻辑则位于 llm_node.py，完整的官方文档见 llm-node.md。

快速开始：LLM 节点核心配置清单

新建一个 LLM 节点后，按下表完成最基础配置即可运行：

配置完成后点击Run Workflow，画布上即可看到节点逐步执行、结果流入下游节点：

四大输出模式详解

文本生成：最基础也最常用的模式

保持 Output Type 为text，把提示词写在userMessage中即可。例如用$input.text接收上游文本，配合 systemInstruction 让模型扮演"客服助手"或"数据摘要器"。

视觉理解：让模型"看图说话"

勾选Include image input后，imageInput表达式可填写：

• 图片 URL（如$input.imageUrl）
• base64 data URL（data:image/png;base64,...）

模型会把图片与文字消息一起处理，适合发票识别、截图分析、图片问答等场景。图片加载与安全检查逻辑位于 llm_service.py 中。

图片生成：从文字到图像

将 Output Type 切换为image，选择支持图像生成的模型（如nanobanana、gemini-2.0-flash-exp），userMessage即变为图像描述提示词，可再指定imageSize（默认 1024x1024）与imageQuality。输出通过$nodeLabel.image获取 base64 图片数据。

结构化 JSON 输出：让结果直接进入下游流程

开启JSON Output并填写jsonOutputSchema，Heym 会自动把 Schema 约束注入系统提示词，并对模型返回做解析——解析成功后，下游节点可以直接用$nodeLabel.fieldName访问字段，无需再做脆弱的字符串提取。解析逻辑见 llm_node.py。

Batch API 批量模式：一次提交，整批处理

当你要对一批数据逐条调用 LLM（如批量摘要、批量分类）时，开启Batch mode可以走服务商原生 Batch API（基于/v1/files与/v1/batches接口），相比逐条请求成本更低、更稳定。

Batch 模式的 4 条硬性规则

1. outputType必须保持text（不支持图片输出）
2. 不能同时启用图片输入
3. userMessage表达式必须解析为数组，例如：
   • $input.items.map("item.text")
   • $vars.promptList
4. 数组中每一项必须是字符串或原始值

输入校验与归一化由 llm_batch_input.py 完成：如果表达式只解析出单个字符串而非数组，节点会在调用服务商之前就报出清晰的验证错误，而不是白白消耗配额。

用 batchStatus 分支实时跟踪进度

开启 Batch 模式后，节点会多出一个batchStatus输出手柄。把需要"边跑边通知"的节点（消息推送、日志记录）连到这个分支，就能在pending→processing→completed/failed的状态变化时收到回调，payload 包含：

• $input.batchId、$input.batchStatus、$input.status
• $input.total、$input.completed、$input.failed
• $input.requestCounts.total/completed/failed、$input.provider、$input.model

批量结果的读取方式

主输出中提供：

• $nodeLabel.results：按原始顺序的逐项结果（含index、customId、status、text、error、usage）
• $nodeLabel.text：所有成功文本的拼接
• $nodeLabel.completed/$nodeLabel.failed：成功与失败计数

若 Batch 模式同时开启了 JSON 输出，Heym 会逐条解析成功项，把解析后的对象收集到$nodeLabel.parsedResults，失败的项标记为error，不会拖垮整批任务。相关行为可在 test_llm_batch_mode.py 中找到对应的测试用例。

💡 注意：Batch 模式仅 LLM 节点支持，Agent 节点不可用；Google 凭据不支持 Batch，面板会直接提示并禁用开关（见 llm_provider.py）。

实用进阶技巧

• 故障回退（Fallback）：配置fallbackCredentialId+fallbackModel，主凭据或模型报错时自动切换重试，避免整条工作流因单次 API 故障而失败。
• Extra Body 透传：勾选Send extra request body，把一段 JSON 对象合并进每次 API 请求，例如关闭某些模型的思考模式。内容为$表达式，解析前会先做变量替换。
• 推理模型：对 o1/o3 等推理模型可设置reasoningEffort（low/medium/high）控制推理深度。
• Guardrails 护栏：在调用 LLM 之前拦截不安全用户消息，可按类别与严重级别过滤。
• Responses API：OpenAI 凭据可勾选Use Responses API走新接口，与 Chat Completions 的提示词、JSON Schema、结果形状保持一致，但不能与 Batch 模式同时使用。

观察每一次 LLM 调用

LLM 节点天然接入 Heym 的 Traces 与 Analytics：每一次请求、响应、token 用量、延迟与成本都有完整记录。批量模式跑完上百条请求后，你可以在 Traces 页面按模型、凭据、来源筛选，快速定位是哪一条失败、花了多少钱：

相关资源

• 官方 LLM 节点文档：llm-node.md
• 节点执行入口：llm_node.py
• 批量输入校验：llm_batch_input.py
• 执行器中的 LLM 执行逻辑：workflow_executor.py
• 属性面板：LlmNodeProperties.vue