ComfyUI VLM Nodes

面向生产环境的视觉语言、结构化提示、音频及实用工具 节点，适用于 ComfyUI。版本 3.4 支持 ComfyUI 选定的 NVIDIA CUDA、AMD ROCm、Apple Metal、Intel XPU 和 CPU 设备，且无需替换其 PyTorch 构建。它移除了启动安装程序和全局加速器缓存刷新， 增加了真实的图像/视频批次处理和实时 token 流式传输，并使用 ComfyUI 模型 驻留和卸载功能。

现代模型覆盖

Modern VLM 节点提供了一个稳定的接口，并配备了一个刻意 精简的、包含 12 个选项的生产环境选择器：

• Qwen 3.5 0.8B 和 4B
• Qwen 3 VL 2B、4B 和 8B Instruct
• SmolVLM2 500M 和 2.2B Video
• Liquid LFM2.5-VL 450M
• InternVL 3.5 1B
• Granite Vision 4.1 4B
• Gemma 3 4B IT
• 兼容的自定义 Hugging Face 图像转文本仓库

独立的 [Legacy] Modern VLM Compatibility 节点包含冗余的、 已被取代的、实验性的以及非常大的层级：

• Qwen 3.5 2B、9B、27B 和 35B-A3B
• Qwen 3.6 27B
• Qwen 3 VL 30B-A3B Instruct
• 用于现有工作流的 Qwen 2.5 VL 3B 和 7B
• Gemma 3 12B 和 27B IT
• SmolVLM2 256M Video
• Liquid LFM2.5-VL 1.6B
• InternVL 3.5 2B
• Granite Vision 3.3 2B

先前保存的 ModernVLM 工作流即使其选定的模型已移至 Legacy 仍然有效。服务器为向后兼容接受所有已知的目录值；仅可见的新工作流选择器经过精选。 专用的 Molmo、PaLI-Gemma、Qwen2-VL、MiniCPM-V、Kosmos-2、MC-LLaVA、UForm 以及脚本风格的 MoonDream 节点也收集在 VLM Nodes/Legacy/Model Loaders 下。面向创作者维护的 Florence-2、 Moondream2、JoyTag、llama.cpp/GGUF、检测、分割、跟踪、API 和视频智能节点保留在其功能类别中。

十六个精选的 sub-4B/低显存选项在内部被标记为 small-and-fast 层级。默认是 Qwen 3 VL 2B：它比大型检查点加载快得多，同时保留了广泛的图像和视频理解能力。 目录有意使用官方模型仓库和维护的 Transformers 接口，而不是未经验证的社区量化版本。 精选模型使用原生 Transformers 实现；仅当显式的自定义模型选项需要时，才启用远程仓库代码。 Florence-2 使用 Transformers 原生转换的检查点，而不是 Microsoft 的遗留仓库代码。

实时文本输出

Modern VLM 默认通过 ComfyUI 的原生 progress_text WebSocket 通道解码文本。已连接的 ViewText 节点会在 token 到达时进行更新，在执行完成后显示最终响应，并在 ComfyUI 重新水合工作流输出历史时恢复最后的结果。对于 不需要增量 UI 更新的仅 API 或无头运行，请禁用 stream_output。流式传输是 尽力而为的，绝不会更改最终的 STRING 输出或导致推理失败。

文本工作流工具包

原始的 SimpleText、JsonToText 和 ViewText 节点 ID 及其 第一个 STRING 输出对于已保存的工作流保持稳定。它们现在位于 组织良好的 VLM Nodes/Text 子类别中，并暴露了描述性名称、搜索 别名、工具提示、附加指标和严格的错误消息：

JSON 实用工具从不评估代码、遵循引用、访问文件或 发起网络请求。模板字段是直接名称，而非 Python 属性/索引表达式。approx_tokens 被刻意标记为 粗略的 UTF-8 预算估算；当精确计费 或上下文核算至关重要时，请使用目标模型的 tokenizer。

在通用聊天节点会丢弃 有用的模型能力之处，专用节点仍然可用：

• Moondream 3.1 9B-A2B: 官方 2B 激活参数的 Photon 运行时，支持查询、 字幕生成以及高吞吐量的图像/视频检测与指向。
• Moondream 3 Preview 分段: 通过相同的隔离 Photon 加载器实现原生 SVG 分割。SVG 被保留， 并转换为抗锯齿 MASK、黑白预览、前景抠图、叠加层、多边形、 标准 VLM_DETECTIONS 以及核心边界框。检测/指向 并发提交帧，以便 Photon 可以动态进行批处理；每次运行 都会报告实测的 worker FPS、端到端 FPS 以及实时因子。
• Florence-2: 字幕生成、OCR、检测、区域字幕生成和指代表达分割， 支持结构化 JSON、掩码和叠加层输出。
• PaLI-Gemma: 字幕/VQA 以及官方 16-token VQ-VAE 分割 解码器；分割 token 不再被错误解释为多边形点。
• Moondream2: 固定查询 API，具有显式的解码控制。官方 检查点通过其原生 safetensors 状态字典加载，避免了 Transformers 5 中静默空输出的回归问题，同时保留了 ComfyUI 管理的加载和卸载。
• Qwen2-VL: 图像批次和实时视频帧批次。
• Legacy Molmo, Kosmos-2, UForm, MCLLaVA, and MiniCPM-V 2.6 GGUF，以及 维护中的 JoyTag。
• llama.cpp LLaVA/GGUF，结构化提示建议，OpenAI 兼容的 提示，以及 AudioLDM2。

结构化检测、分割和跟踪

视觉节点使用稳定的、带类型的套接字，而不是在节点之间传递特定于模型的 列表：

所有空间坐标均为源图像像素。边界框为 [x1, y1, x2, y2]，右/下边缘为开区间；多边形至少包含三个点，四边形恰好包含四个点。JSON 根包含 schema、 version、媒体尺寸/帧数/FPS 及其有序记录。密集 掩码张量保留在进程内，并有意从 JSON 中省略，以免 API 结果意外增长数百兆字节。

工具层无需特定于模型的胶水代码即可进行转换：

• VLMStructuredSpatialParser 严格解析来自任意 VLM 的像素、归一化 0–1 或 归一化 0–1000 JSON，并转换为 VLM_DETECTIONS 和 VLM_POINTS。 VLMSpatialPromptBuilder 创建匹配的约束提示词。
• VLMDetectionsToBoundingBoxes、VLMDetectionsToPoints 和 VLMDetectionsToMasks 输出 Comfy 核心框、中心点、合并及 单独的二值掩码、反向掩码、可直接预览的黑白 图像以及稳定颜色的实例图。如果存在多边形/四边形掩码，则进行光栅化， 否则使用边界框。现有输出索引 保持稳定；面向创建者的掩码图像和实例图将被追加。
• VLMFilterDetections、VLMSelectDetection、VLMCropDetections 和 VLMRenderDetections 提供标签/分数/面积/框选择、填充裁剪 以及确定性叠加。
• VLMMaskProcessor 接受任何 Comfy MASK，包括 SAM2/SAM3 掩码，并 返回羽化蒙版、严格二值掩码、反向掩码以及 黑白图像。其膨胀/收缩和高斯羽化在 Torch 中运行，无需 OpenCV 或 SciPy。
• VLMMaskComposite 将静态图像或视频掩码批次应用于源图像，并 返回替换合成图、隔离的前景、仅原始 背景板以及黑白掩码图像。单个掩码或 背景可安全地广播到视频批次中。
• VLMDetectionsFromJSON 和 VLMDetectionsToJSON 是版本化检测架构的显式 API 和 持久化边界。

通用 VLM 性能工具

性能节点位于任何本地或托管 VLM 之前，因此其节省效果不 依赖于 CUDA、ROCm、MPS、XPU、CPU、Transformers、llama.cpp 或 Photon：

• VLM Performance Profile 输出相干的 max_frames、像素预算、 最长边、批处理大小以及 unload_after 值。Live / robotics、 Fast video、Balanced、High detail 和 Low VRAM handoff 是显式的 起始点，而非隐藏的全局标志。
• VLM Adaptive Frame Sampler 是现有的轨迹感知时间门控。它 结合了均匀覆盖、场景变化、运动以及可选的轨迹变化， 同时保留源帧索引和时间戳。
• VLM Image Pixel Budget 对选定的分析副本进行一次降采样，保持 宽高比，从不放大，并且可以将尺寸对齐到 14/28 像素的 VLM 补丁或 32 像素的检测器骨干网络。提供快速面积和抗锯齿双三次 模式。

推荐顺序为 Video Slice → VLM Adaptive Frame Sampler → VLM Image Pixel Budget → 任意 VLM。模型自身的官方处理器仍然 执行其所需的归一化/裁剪；像素预算节点只是防止 每个下游模型反复接收不必要的源像素。 本地 torch 模型仍注册在 ComfyUI 的智能模型管理器中，而 外部分配器在加载前预留空间，并且仅关闭其 拥有的句柄。

在本仓库 D 盘测试环境的真实 vlm_api_people_birds.mp4 输入上， 这些实用工具从 60 个 1280×720 帧中选择了 10 个，并在冷启动 WSL 运行中 将其调整为 938×518，耗时约 0.44 秒。这将在模型推理前 将帧×像素分析工作量减少了 11.38 倍。这是一项 输入工作量减少的测量，并非声称每个模型都运行快 11.38 倍； 令牌生成和特定于模型的视觉编码器仍然决定 端到端速度。

自适应视频智能

视频智能层将生成式 VLM 推理排除在逐帧循环之外：

• VLMAdaptiveFrameSampler 结合场景变化、运动、轨迹变化和均匀覆盖信号。它始终保留真实的源帧索引和时间戳，强制执行帧预算，并返回选择/诊断 JSON。Uniform coverage、运动、场景和轨迹优先级模式仍可用于确定性实验。
• VLMVideoTemporalReasoner 是单节点路径。它自适应地采样输入，仅缩小 VLM 分析副本（默认最长边为 448 像素），运行推荐的视频处理模型，将结果解析为经过验证的 VLM_EVENTS，并返回摘要、事件、选择、采样预览、原始响应、诊断、事件 JSON 和选择 JSON。
• VLMVideoReasoningPrompt 和 VLMEventsFromVideoJSON 为自定义的本地或托管 VLM 工作流暴露相同的严格时间戳/证据契约。
• VLMTrackAwareCrops 为每个持久轨迹选择代表性观测，添加可配置的上下文，并将裁剪图像填充至一个批次大小。这使得 VLM 能够标记身份，而无需重新读取每一帧完整图像。
• VLMBuildSceneState 将轨迹加上可选事件转换为紧凑的持久世界状态摘要，包含首次/末次观测、当前边界框、置信度、状态和像素速度。

小型 VLM 通常将证据返回为所提供图像批次中的位置，即使被要求提供源索引也是如此。解析器仅在所有值都是无歧义的有效所提供图像位置时才接受该形式，将其映射回不可变的源选择，并记录归一化模式。任意或未提供的证据帧、超出范围的时间戳、无效的置信度、重复的证据、格式错误的 JSON 以及非有限值将导致验证失败。

在仓库的真实数据冒烟测试（RTX 3090，Qwen3-VL 2B，157 帧 896x448 H.264 片段）中，混合采样在 0.30 秒内选择了 12 帧，将时间输入减少了 92.36%，将分析像素减少了 75%，在独立运行器中使用了 4.24 GiB 峰值分配 VRAM，并在 35.17 秒内生成了有效的时间戳结果。等效的实时 ComfyUI /prompt 图在 37.45 秒内完成。这些是单机器测量值，而非可移植的性能保证。

开放词汇图像和视频检测

VLMOpenVocabularyDetection 为一个接口暴露了以下功能：

• Grounding DINO Tiny 和 Base
• OWLv2 Base Ensemble
• OmDet Turbo Swin Tiny

它接受静态图像或 IMAGE 视频帧批次，并逐帧处理该批次。输出按套接字顺序为 detections、json、 preview、box_mask 和 Comfy 核心 bounding_boxes。当输入为视频时，请连接 GetVideoComponents 的 FPS 输出，以确保每个时间戳都正确。 对于基于检测的跟踪，请在完整的有界批次上运行检测，并将其连接到 VLMTrackDetections。

VLMTrackDetections 采用 ByteTrack 风格的两阶段高/低置信度关联、运动预测、标签感知匹配以及基于时间的过期机制。 在提供的序列内，ID 是持久的，并且在启用 emit_predictions 时，能够存活于短暂的检测丢失期间。独立的 Comfy 队列运行或 独立切分的片段是独立的跟踪会话；它们不会 静默地重用 ID。

SAM2.1 和 Comfy 核心 SAM3.1

VLMSAM2VideoSegmentation 通过 SAM2.1 Hiera Tiny、 Small、Base+ 或 Large，使用一个 IMAGE 批次传播首帧检测、一个核心 BOUNDING_BOX 或种子掩码。它返回 VLM_TRACKS、报告 JSON、逐帧并集 掩码、帧优先的单个对象掩码以及一个叠加批次。在种子帧分配的对象 ID 在该视频会话中保持稳定。

VLMSAM3TrackAdapter 有意设计为一个适配器，而非第二个 SAM3 加载器。它 验证 ComfyUI 核心 SAM3_TRACK_DATA，保持核心位打包掩码 负载不变，并暴露带有掩码 引用的轻量级 VLM_TRACKS 元数据。将其直通输出连接到核心 SAM3_TrackPreview 或 SAM3_TrackToMask，并将 tracks 连接到 VLMTrackReport。这避免了 在内存或 JSON 中重复密集掩码。

SAM3 权重使用 Meta 的 SAM 许可证。上游 facebook/sam3 仓库 要求接受访问条款并共享所需的账户信息； ComfyUI 检查点也被标记为 sam-license。在下载前请审查并 接受许可证。示例中命名了 ComfyUI 的 sam3.1_multiplex_fp16.safetensors；如果不可用，请使用 SAM2.1 工作流，而不是替换为无关的检查点。

Florence-2 任务覆盖

Florence2 公开了所有 15 种受支持的任务契约：

每个任务都返回 text、structured_json、mask 和 visualization。 不产生空间结果的任务返回空掩码和源 图像可视化。区域任务拒绝模糊的多边界框输入；请使用 VLMSelectDetection 来隔离记录，然后提供恰好一个核心 BOUNDING_BOX，具有相同的像素坐标。

视频记忆策略

• 使用 core Video Slice 修剪长媒体，然后使用 GetVideoComponents。 在检测或分割之前对完整帧批次进行降采样，并保持 每帧具有相同的尺寸。
• Grounding detection 支持可配置的微批次；在最低 VRAM 情况下保持 batch_size=1 或在内存允许时增加它。它同时返回嵌套的 每帧 core BOUNDING_BOX 值和扁平的元数据丰富的 BOUNDING_BOXES。
• SAM2.1 将源视频帧存储在 CPU 上，默认将其推理状态保持在 CPU 上， 并将视觉特征缓存限制为一帧。Union masks 和 预览在 CPU 上返回。完整的每对象 mask 体积是可选的，使用 mask_output=union_and_objects；禁用 render_preview 以避免在长片段上 产生另一个全分辨率叠加副本。
• 从 Grounding DINO Tiny 加上 SAM2.1 Hiera Tiny 开始。只有在管道正确后才增加检测器或 分割器的大小。unload_after=false 每个节点实例缓存一个模型；当另一个大型模型必须 立即随后运行时，使用 true。
• Video Slice 是一个独立的传播会话。对于非常长的媒体， 使用有界切片，为每个切片重新播种，并在 调用者中保持重叠/输出映射。该包不假装 ID 在单独的 队列之间是全局稳定的。
• SAM3 适配器从不为其报告解包完整的 mask 体积。仅当确实需要密集的选定 mask 时，才使用 core SAM3_TrackToMask。

API 格式示例位于 examples/vision:

• grounding_dino_image_api.json
• moondream3_preview_svg_segment_api.json
• moondream31_video_detect_api.json
• sam2_video_tracking_api.json
• sam3_core_adapter_blueprint_api.json
• video_temporal_reasoning_api.json
• vlm_performance_preflight_api.json

无依赖的 text-toolkit 示例位于 examples/text_toolkit_api.json。 机器人策略、安全及 sidecar 示例位于 examples/robotics，其中包括一个完整的通用 HTTP 策略图。

将指定的媒体上传到 ComfyUI 的输入目录，调整文件名和 标签，然后将 JSON 对象作为 prompt 值提交给 /prompt。这些 是 API 图，而非前端工作流导出 JSON。

节点参考

所有 89 个已注册节点，按其菜单类别分组。Node ID 是 写入工作流和 API JSON 中的 class_type — 当您需要查找在画布上看到的节点时， 请搜索该字符串。

Modern VLM

当前视觉语言模型的主要入口点。

Moondream 3

在隔离的 Photon 运行时中的 Moondream 3 / 3.1。加载一次，然后在 任务节点之间复用 MOONDREAM31_MODEL 输出。

Florence-2

视觉：检测、分割、跟踪

开放词汇检测和视频分割。这些节点输出结构化的 VLM_DETECTIONS / VLM_POINTS / VLM_TRACKS 类型，而非松散字符串。

视觉：空间推理

视觉：检测工具

结构化检测结果与普通 Comfy 类型之间的转换器和过滤器。

视觉：遮罩工具

视频智能

针对长视频的自适应帧选择和时序推理。

LLM（本地 GGUF）

llama.cpp 文本模型。LLM Loader (GGUF) 生成采样器所使用的 CUSTOM 模型句柄；Managed Cache 变体拥有自己的句柄，并可在每次运行后释放它。

LLaVA (local GGUF multimodal)

通过 llama.cpp 实现的视觉模型。这些模型需要 GGUF 及其视觉投影器 (mmproj)。

Hosted APIs

Robotics / VLA policies

这些节点用于构建和检查策略观测/动作。它们从不向机器人硬件发送命令。重型策略运行时保留在隔离的 LeRobot、openpi、GR00T、OpenVLA/OFT 或 JAX 环境中。

文本工具包

无依赖的字符串处理，因此无需额外的节点包即可对 VLM 响应进行整形。

性能与诊断

在报告 bug 之前，请先运行 VLM Runtime Diagnostics —— 它会报告你的 设备、后端以及已安装的可选包。

Audio

MiniMax Music 仅从 ComfyUI 服务器 环境中读取 MINIMAX_API_KEY。它使用固定的 global_en 和 cn_zh 端点，支持音乐 生成和翻唱模型，解码 URL 或十六进制响应，并通过现有的波形和 AUDIO 套接字输出 MP3、WAV 或 PCM 结果。 aigc_watermark 字段仅针对 cn_zh 请求发送。请参阅官方 全球 或 中国 音乐 API 参考，了解账户和内容要求。

Legacy model loaders

保留用于现有工作流。新图应优先使用 Modern VLM，它 通过一个接口涵盖了这些架构中的大部分。

安装

通过 ComfyUI Manager 安装，或克隆到 ComfyUI/custom_nodes 并运行：

python -m pip install -r ComfyUI/custom_nodes/ComfyUI_VLM_nodes/requirements.txt

使用 ComfyUI 的 Python 运行该命令。不要从 此仓库安装或替换 torch：ComfyUI 自带的安装程序会选择 CUDA、ROCm、XPU、Metal 或 CPU。 当前官方的 bitsandbytes 轮子仅在其 支持的操作系统/架构组合上自动安装。不支持的机器将保留所有 非量化节点。

机器人 / VLA 隔离运行时

机器人节点将策略依赖项置于 ComfyUI 之外。通用 HTTP 客户端无需其他包即可工作。原生 openpi WebSocket 和 GR00T ZeroMQ 客户端使用轻量级可选附加组件：

python -m pip install \
  -r ComfyUI/custom_nodes/ComfyUI_VLM_nodes/requirements-robotics-client.txt

VLA Model Catalog 涵盖当前的 SmolVLA、X-VLA、π0/π0-FAST/π0.5、 GR00T N1.7、WALL-OSS、MolmoAct2、VLA-JEPA、LingBot-VA、FastWAM、EO-1、 EVO-1、OpenVLA-OFT 以及 Octo 路线。“可用”意味着受支持的独立 运行时/检查点路径；基础模型和仅架构条目仍需 特定具身训练和转换。

从小型消费级硬件开始使用 SmolVLA。包含的经过身份验证的 LeRobot 边车加载一个选定的策略，使用其序列化的处理器， 通过有界的 JSON/JPEG 返回动作块，保持其驻留以加快速度， 并可在空闲超时后将其卸载到 CPU。远程策略 URL 需要 加密传输和显式选择加入。令牌是固定的环境变量 （VLA_POLICY_TOKEN、OPENPI_API_KEY 或 GROOT_API_TOKEN），并且 绝不是工作流输入。

参见 examples/robotics/README.md 了解 D 盘 WSL 设置、平台边界、当前模型就绪状态、观察模式、 动作安全语义以及可运行的 API 示例。

Moondream 3 / 3.1 独立运行时

Moondream 的官方 Photon 包将 Pillow 固定在 11 版本以下，而 当前 ComfyUI 使用较新的 Pillow。因此，它在专用的边车 环境中运行，并且从不更改 ComfyUI 的 Python 包。阅读并接受 Moondream 模型许可证 1.0，然后 在已注册的 LLavacheckpoints 模型文件夹下创建环境。

Linux/WSL/macOS：

runtime="ComfyUI/models/LLavacheckpoints/moondream31-runtime"
uv venv "$runtime/.venv" --python 3.12
uv pip install --python "$runtime/.venv/bin/python" \
  -r ComfyUI/custom_nodes/ComfyUI_VLM_nodes/requirements-moondream31.txt

Windows PowerShell：

$runtime = "ComfyUI\models\LLavacheckpoints\moondream31-runtime"
uv venv "$runtime\.venv" --python 3.12
uv pip install --python "$runtime\.venv\Scripts\python.exe" `
  -r "ComfyUI\custom_nodes\ComfyUI_VLM_nodes\requirements-moondream31.txt"

首次 Loader 执行会下载所选的官方模型至该 运行时 cache 目录。使用 moondream3.1-9B-A2B 进行查询、字幕、 检测和指向。仅使用 moondream3-preview 用于 SVG 分割 技能；最终的 3.1 模型卡未列出分割。当使用不同的隔离环境时，设置服务器端 MOONDREAM_PYTHON 环境变量 。不要将此路径或任何 凭据放入工作流中。

官方 Photon 本地推理目前支持 Linux/Windows 上的 NVIDIA Ampere 或更新版本以及 macOS 13 或更新版本上的 Apple Silicon。它目前 不提供本地 ROCm、Intel GPU 或 CPU 执行。这些平台保留此包中所有 可移植的 Transformers、GGUF、API 和视觉实用节点。

在 CUDA 12 x86-64 系统上，隔离依赖项有意安装 nvidia-cuda-runtime-cu12==12.9.79。Kestrel 0.4.6 的 AOT 内核需要 cudaLibraryLoadData 入口点，而 cu126 PyTorch 捆绑的 CUDA 12.6 运行时 中不存在该入口点。此固定版本仅更新 Photon 的私有运行时；它 不会替换 ComfyUI 的 PyTorch 构建或主机 NVIDIA 驱动程序。

GGUF 节点使用可选的 llama-cpp-python。安装为所需的 CUDA、ROCm/HIP、Metal、Vulkan、SYCL 或 CPU 后端构建的 wheel：

python -m pip install -r ComfyUI/custom_nodes/ComfyUI_VLM_nodes/requirements-llama-cpp.txt

参见 COMPATIBILITY.md 以获取已测试矩阵和官方 特定后端的 GGUF 命令。

GGUF 加载器现在会查询已安装的 llama.cpp 构建版本，而不是从 PyTorch 推断其能力。当安装了仅支持 CPU 的 wheel 时，加速器卸载会自动回退到 CPU。高级可选输入暴露了逻辑和物理提示批处理（n_batch/n_ubatch）、flash-attention 策略、 mmap，以及在不更改遗留 工作流套接字的情况下进行 CUDA/ROCm 多 GPU 层/行分割。Auto flash attention 在后端/模型 对拒绝时会重试可移植路径。

LLaVA Vision Projector Loader 支持基于元数据的 MTMD 以及 针对 LLaVA 1.5/1.6、MiniCPM-V 2.6、Moondream2、NanoLLaVA、 Qwen2.5-VL、Gemma 4、Llama 3 Vision Alpha 和 Obsidian 的显式处理程序。对于当前的 GGUF + mmproj 对，请使用默认的 基于元数据的处理程序；当模型卡片要求时，选择指定的 遗留处理程序。

模型仅在其节点首次执行时下载，并存储在 ComfyUI/models/LLavacheckpoints 之下。Hugging Face 下载遵循 HF_TOKEN。 Gemma 3 和 PaLI-Gemma 需要在 Hugging Face 上接受其模型许可证。

GPU 生命周期

• ComfyUI managed (BF16) 是默认且推荐的路径。仅当活动设备报告支持时才使用 BF16；否则，节点会安全地回退到 CUDA/ROCm/Metal/XPU 上的 FP16 或 CPU 上的 FP32。
• 4-bit/8-bit 模型和 llama.cpp 拥有外部分配器。在加载之前，节点会请求 ComfyUI 释放所需空间；卸载时会关闭确切拥有的模型，然后请求软缓存清理。小型量化模型保留在 ComfyUI 的活动设备上，而不是假设 GPU 为零。大型模型的 Accelerate 放置在 CUDA/ROCm/XPU 上启用；任何磁盘卸载都保留在模型的 ComfyUI 目录内。
• llama.cpp 模型和投影器字节包含在预加载预留中。运行时在 VLM Runtime Diagnostics 中报告 llama.cpp 自身编译的后端、GPU 卸载、mmap 和 mlock 功能。
• unload_after=false 为每个节点实例缓存一个模型，以实现快速重复队列。缓存创建是序列化的，因此并发的 API 工作不会使同一节点分配重复的模型句柄。在提示之间启用它以实现最大回收。
• Moondream Photon 在启动前请求 ComfyUI 腾出空间，然后拥有一个确切的隔离进程。unload_after=true 会优雅地关闭它，并在必要时终止该进程，从而释放 Photon 模型、KV 缓存和 CUDA 图分配，而不会刷新无关的 ComfyUI 模型。该 sidecar 有意不继承 ComfyUI 的 PyTorch 分配器覆盖； Photon 的 CUDA 图捕获在其自身进程中使用原生分配器。 工作进程不会继承无关的提供程序密钥或代理凭据；只有 HF_TOKEN，以及为显式选择的适配器指定的 MOONDREAM_API_KEY， 才能进入其服务器端环境。基础模型边车在本地遵守 DO_NOT_TRACK，并且不会启动 Kestrel 的匿名遥测任务。 其随机 IPC 密钥不会放置在进程命令行上。
• 已连接的 video_frames 批次成为主要视觉输入。 可选的静态图像套接字在视频推理中被忽略，以防止较小的模型 静默地从错误的媒体中生成回答。
• Qwen 3.5/3.6 的思考功能默认关闭，以降低延迟并保证 输出长度可预测；对于受益于视觉 推理的任务，请显式启用该功能。
• Auto (SDPA) 具有可移植性且为首选。Flash Attention 2 仅在 受支持的 CUDA/ROCm 构建中被接受，否则会在模型加载前失败。
• VLM 运行时诊断 生成一份零下载的 JSON 报告，包含 操作系统、Python、PyTorch、后端、数据类型能力以及可选的软件包版本。
• 仅用于可视化的配套仓库不会分配加速器内存。

除非 GPU 能够容纳它们，否则避免在一个工作流中放置多个独立量化的 VLM。在 24 GB 显卡上，Qwen 3 VL 2B 是快速的默认选择，Qwen 3 VL 8B 适合 BF16，而更大的模型应使用 NF4。当已安装的 PyTorch/后端组合没有其可选的优化线性注意力内核时，Qwen 3.5/3.6 可能会明显变慢。

API 节点

Hosted LLM API (Secure) 和 Hosted VLM API (Secure) 共享一个围绕当前 OpenAI Responses 和 Chat Completions 请求格式构建的提供商层，其中 Anthropic 使用其原生的 Messages/vision 契约，而 Gemini 在接地或结构化调用时切换到其原生的多模态契约。 VLM 节点 接受静态图像或视频帧批次，均匀采样 帧，调整大小并进行 JPEG 压缩，并在上传前强制执行每图像和总请求限制。两个节点都可以将文本流式传输到连接的 ViewText 节点。

两个 API 节点还暴露：

• 原生网络搜索，适用于通过 OpenRouter 路由的 OpenAI、Gemini、Anthropic、xAI 以及任何兼容模型。不支持的预设会在模型请求之前明确失败，而不是假装进行搜索。搜索可能会增加提供商成本，并且具有提供商特定的数据条款，因此默认关闭。
• JSON 对象和 JSON Schema 输出。已完成的 JSON 始终在本地解析，JSON Schema 结果在本地验证，无效结果会导致节点失败，而不是流入下游自动化流程。
• 通过自定义/本地端点实现开源结构化 VLM 输出。 OpenAI 标准模式支持 vLLM、Ollama 和兼容服务器； llama.cpp JSON Schema 发出 llama.cpp 的直接模式方言；并且 JSON object + local validation 是仅实现 JSON 模式的服务器可移植回退方案。

用户提供的模式限制为 64,000 个字符，受深度/节点数限制，根据其声明的 JSON Schema 草稿进行检查，并且只能使用本地片段 $ref 值。拒绝远程/文件引用，因此验证永远不会变成意外的网络或文件系统查找。

精选的生产配置文件包括：

预设 ID 已于 2026-07-29 对照官方 OpenAI, Gemini, Claude, xAI, DeepSeek, Groq, Mistral, 以及 Together, 加上 OpenRouter 的多模态兼容性 目录进行了审查。当提供商在下一个节点包发布之前暴露出更新的兼容模型时，请使用 model_override。

能力路由遵循当前的官方 OpenAI 网络搜索 和 结构化输出 契约， Gemini 接地 和 结构化输出, Claude 网络搜索 和 结构化输出 契约，xAI 网络搜索 和 结构化输出, 以及 OpenRouter 服务器端搜索。 本地方言基于 llama.cpp 服务器 API。

API 密钥不是节点输入。工作流仅包含提供商选择， 服务器在执行时解析该提供商的固定环境变量。内置凭据固定指向提供商的官方 HTTPS 主机； 仅自定义配置文件接受 URL，且只能读取 CUSTOM_API_KEY。 远程自定义 URL 要求使用 HTTPS，而无密钥 HTTP 仅限于 localhost/回环地址。默认禁用重定向跟随和环境代理，API 调用是无状态的，OpenAI Responses 明确使用 store=false，并且提供商异常在 ComfyUI 接收之前会被脱敏。

网络搜索将提示词（以及在支持的情况下，相同的多模态请求） 发送到所选提供商的服务器端搜索系统。对于不得在该提供商的搜索条款下处理的内容，请勿启用此功能。

打开较旧的 PromptGenerateAPI 工作流时，会在配置图之前自动清除其先前的 明文密钥小部件。保存迁移后的工作流以覆盖旧文件，并轮换任何先前已保存或 共享的密钥。有关设置和确切的威胁模型，请参阅 SECURITY.md。

可靠性保证

• 导入该包不会执行任何网络访问、编译或软件包安装。
• 缺失的可选后端仅导致需要它们的节点失败，并给出可操作的错误信息。
• 图像输入使用 ComfyUI BHWC 批次；文本响应保留每个批次项。Florence/PaLI 掩码使用 BHW。
• 已移除 forceInput 字符串 hack，防止前端小部件索引漂移。
• 下载内容保留在已配置的 ComfyUI 模型目录内。
• CI 在 Linux Python 3.10/3.13、Windows Python 3.12 和 macOS Python 3.12 上安装并导入完整包。CUDA、ROCm、Metal、XPU 和 CPU 的后端契约均得到验证，且不会假装托管的 CPU 运行器是 GPU。

使用以下命令运行本地检查：

PYTHONPATH=/path/to:/path/to/ComfyUI python -m pytest -q

实际权重检查是可选的，因为它们会下载数 GB 的检查点：

python tests/manual_model_smoke.py --model "Qwen 3 VL 4B Instruct"
python tests/manual_specialized_smoke.py --backend florence-large
python tests/manual_llama_cpp_smoke.py --download

参见 MODEL_VALIDATION.md 以获取确切的真实权重和 仅目录证据矩阵。

请在 issue tracker 报告可复现的 bug。

@software{Aydogan_ComfyUI_VLM_Nodes_2026,
  author  = {Aydoğan, Gökay},
  title   = {ComfyUI VLM Nodes},
  version = {3.5.0},
  year    = {2026},
  url     = {https://github.com/gokayfem/ComfyUI_VLM_nodes}
}