Image Quality Evaluator

ComfyUI-ImageEval-FID-IS-CLIP-LPIPS

ComfyUI 图像生成质量评估自定义节点 — 一键计算 FID / IS / CLIP-Score / LPIPS 四大核心指标，输出专业评估报告。

---

功能简介

在 ComfyUI 工作流中直接对生成图像进行量化质量评估，无需离开 ComfyUI 环境，无需手动跑脚本。

| 指标 | 说明 | 越低/高越好 | |------|------|-------------| | FID (Fréchet Inception Distance) | 生成图像与真实图像的分布距离 | 越低越好 | | IS (Inception Score) | 生成图像的清晰度和多样性 | 越高越好 | | CLIP-Score | 生成图像与输入 prompt 的语义匹配度 | 越高越好 | | LPIPS (Learned Perceptual Image Patch Similarity) | 两批图像间的感知相似度 | 越低越相似 |

---

安装

方法一：ComfyUI Manager（推荐）

1. 打开 ComfyUI Manager
2. 搜索 ComfyUI-ImageEval
3. 点击 Install

方法二：手动安装

1. 进入 ComfyUI 的 custom_nodes 目录：

   cd ComfyUI/custom_nodes/
   

2. 克隆本仓库：

   git clone https://github.com/zx725tt/ComfyUI-ImageQualityEvaluator.git
   

3. 安装依赖（重要：如果使用的是 ComfyUI-aki 等打包版本，请使用自带 Python 安装，见下方说明）：

   pip install scipy clip-score lpips
   

4. 重启 ComfyUI

⚠️ ComfyUI-aki / 便携版用户特别注意

ComfyUI-aki 等打包版本使用独立的嵌入式 Python，系统 Python 的 pip install 不会生效！

请使用 ComfyUI 自带的 Python 来安装依赖，例如：

# ComfyUI-aki v1.3 示例路径，请按实际安装路径调整
G:\软件\ComfyUI-aki\ComfyUI-aki-v1.3\python\python.exe -m pip install scipy
G:\软件\ComfyUI-aki\ComfyUI-aki-v1.3\python\python.exe -m pip install clip-score
G:\软件\ComfyUI-aki\ComfyUI-aki-v1.3\python\python.exe -m pip install lpips

安装完成后，必须重启 ComfyUI 才能生效。

---

使用方法

基本流程

1. 在 ComfyUI 右侧节点面板搜索 图像质量评估器 或 ImageQualityEvaluator
2. 将节点拖入工作区
3. 填写真实图像文件夹路径和生成图像文件夹路径
4. （可选）填写 save_path 将报告保存到文件
5. 点击 Queue Prompt

参数说明

| 参数 | 类型 | 说明 | |------|------|------| | real_images_dir | STRING (必填) | 真实参考图像文件夹路径（FID 计算必需） | | generated_images_dir | STRING (必填) | 待评估的生成图像文件夹路径 | | device | 下拉选择 | cuda（GPU，推荐）/ cpu | | batch_size | INT | 批处理大小（1~128，默认32） | | compare_images_dir | STRING (可选) | 用于 LPIPS 计算的对比图像文件夹 | | prompts | STRING (多行) | 每行一个 prompt，与生成图像按顺序对应（CLIP-Score 必需） | | save_path | STRING (可选) | 评估报告保存路径，如 D:/eval_report.txt，留空不保存 | | enable_fid | BOOLEAN | 是否计算 FID（默认开） | | enable_is | BOOLEAN | 是否计算 IS（默认开） | | enable_clip | BOOLEAN | 是否计算 CLIP-Score（默认开） | | enable_lpips | BOOLEAN | 是否计算 LPIPS（默认开） |

输出示例

╔══════════════════════════════════════════════════════════════════╗
║            AI 图像生成质量评估报告                        ║
╚══════════════════════════════════════════════════════════════════╝

指标              | 结果                  | 说明
---------------------------------------------------------------------------
  FID            | 12.34                 | 越低越好 (好:<30, 一般:30~100, 差:>100)
  IS             | 145.67 ± 2.34         | 越高越好 (好:>100, 一般:30~100, 差:<20)
  CLIP-Score     | 0.3124                | 越高越好 (好:>0.30, 一般:0.25~0.30, 差:<0.20)
  LPIPS          | 0.0823                | 越低越相似 (好:<0.10, 一般:0.10~0.30, 差:>0.50)

---------------------------------------------------------------------------
📋 运行日志:
┌────────────────────────────────────────────────────────────────────┐
│ ⏳ 正在计算 FID...                                                 │
│   ✅ FID: 12.34                                                  │
│ ⏳ 正在计算 IS...                                                  │
│   ✅ IS: 145.67 ± 2.34                                           │
│ ⏳ 正在计算 CLIP-Score...                                         │
│   ✅ CLIP-Score: 0.3124                                          │
└────────────────────────────────────────────────────────────────────┘

📊 综合判断:
  ✅ FID=12.34 优秀 (分布接近真实图)
  ✅ CLIP-Score=0.3124 优秀 (图文匹配度高)

---

指标解读指南

FID（Fréchet Inception Distance）

• 原理：计算真实图像与生成图像在 Inception V3 特征空间中的 Wasserstein-2 距离
• 参考标准：
  • < 10：优秀，生成分布与真实分布几乎一致
  • 10 ~ 30：良好
  • 30 ~ 100：一般，有明显差距
  • > 100：较差
• 要求：需要 real_images_dir（真实图像）和 generated_images_dir（生成图像）中的图像数量均 ≥ 2

IS（Inception Score）

• 原理：结合清晰度和多样性，基于 Inception V3 分类概率分布计算
• 参考标准：
  • > 100：优秀（如 ImageNet 预训练 GAN 的水平）
  • 30 ~ 100：一般
  • < 20：较差
• 注意：IS 只能评估生成图像本身，不需要真实图像

CLIP-Score

• 原理：使用 CLIP 模型计算生成图像与输入 prompt 的余弦相似度
• 参考标准：
  • > 0.30：优秀，图文高度匹配
  • 0.25 ~ 0.30：良好
  • 0.20 ~ 0.25：一般
  • < 0.20：较差，图文不匹配
• 要求：需要在 prompts 参数中按顺序填写每张生成图像对应的 prompt

LPIPS（Learned Perceptual Image Patch Similarity）

• 原理：使用深度学习感知损失计算两幅图像的相似度，符合人类视觉感知
• 参考标准：
  • < 0.10：非常高相似度
  • 0.10 ~ 0.30：中等相似度
  • 0.30 ~ 0.50：低相似度
  • > 0.50：差异很大
• 要求：需要 generated_images_dir 和 compare_images_dir 中图像数量一致且按顺序对应

---

工作流示例

节点可以作为工作流的最终输出节点使用（OUTPUT_NODE = True，无需连接到其他节点）。

最小工作流（只计算 FID + IS）

[图像质量评估器]
  real_images_dir    = D:/datasets/real/
  generated_images_dir = D:/outputs/sd_generated/
  device             = cuda
  batch_size         = 32

完整工作流（四项全开）

[图像质量评估器]
  real_images_dir      = D:/datasets/real/
  generated_images_dir  = D:/outputs/sd_generated/
  compare_images_dir    = D:/outputs/reference/
  prompts              = a beautiful landscape\nportrait of a woman\n...
  save_path            = D:/eval_report.txt
  device               = cuda
  batch_size           = 32
  enable_fid           = True
  enable_is            = True
  enable_clip          = True
  enable_lpips         = True

工作流 JSON 文件已包含在 workflows/ 目录中，可直接导入 ComfyUI。

---

故障排除

节点执行后没有任何输出

原因：依赖包没有安装到 ComfyUI 使用的 Python 环境中。

解决：确认你使用的是 ComfyUI 自带的 Python 安装依赖（见上方「安装 - 方法二」），安装完成后重启 ComfyUI。

Prompt has no outputs 报错

原因：ComfyUI 要求工作流至少有一个输出节点。

解决：本节点已设置 OUTPUT_NODE = True，如果仍然报错，请确认节点代码是最新版本，并重启 ComfyUI。

batch_size 只能输入固定数值（如 25、33、41...）

原因：ComfyUI INT 组件的 step 参数控制是否允许自由输入。

解决：本节点 step 已设置为 1，允许自由输入任意整数。如果仍然只能步进输入，请更新到最新版本。

CUDA out of memory

解决：降低 batch_size 参数（如从 32 改为 8 或 4），或切换 device 为 cpu。

CLIP-Score 显示 ⚠️ 未提供 prompts

原因：prompts 参数为空，或未正确填写。

解决：在 prompts 多行文本框中，按图像生成顺序每行填写一个 prompt。

调试日志

节点会在其安装目录下生成 eval_debug.log 文件，包含详细的执行日志，可用于排查问题。同时也可以查看 ComfyUI 终端输出。

---

技术细节

依赖项

| 包名 | 用途 | |------|------| | scipy | FID 计算中的矩阵平方根（sqrtm） | | clip-score | CLIP-Score 计算 | | lpips | LPIPS 计算 | | torch / torchvision | Inception V3 特征提取、图像处理与 GPU 加速 | | Pillow | 图像读取 | | numpy | 数值计算 |

图像处理规范

• 所有图像在计算前统一 Resize 到 299×299（Inception V3 输入尺寸）
• LPIPS 计算前图像归一化到 [-1, 1] 范围
• 支持格式：.png / .jpg / .jpeg / .webp / .bmp

FID / IS 计算实现

本节点不依赖 clean-fid 和 torch-fidelity，而是直接使用 torchvision.models.inception_v3 提取特征后手动计算：

• FID: Inception V3 提取 2048 维特征 → 计算两组特征的均值 μ 和协方差 Σ → FID = ‖μ₁−μ₂‖² + Tr(Σ₁+Σ₂−2√(Σ₁Σ₂))
• IS: Inception V3 提取 1000 分类概率 → 计算 KL(p(y|x) || p(y)) 的均值并取指数

这样做的优势是完全控制图像预处理流程（统一 299×299），避免了第三方库内部数据加载导致的 size mismatch 和 Imaginary component 等边缘错误。

节点架构

INPUT_TYPES:
  required:  real_images_dir, generated_images_dir, device, batch_size
  optional:  compare_images_dir, prompts, save_path,
             enable_fid, enable_is, enable_clip, enable_lpips

OUTPUT_TYPES:
  RETURN_TYPES:  (STRING,)
  RETURN_NAMES:   ("evaluation_result",)
  OUTPUT_NODE:    True   ← 可作为终端节点独立使用

---

更新日志

v1.2.0 (2026-06)

• ✅ 新增推荐图片数量提示（学术研究标准：FID≥500, IS≥100, CLIP-Score≥100, LPIPS≥50）
• ✅ FID/LPIPS 路径无效改为软跳过（不影响其他指标计算）
• ✅ 修复 LPIPS device 参数兼容性问题
• ✅ 修复 results/logs 初始化顺序 bug

v1.1.0 (2026-06)

• ✅ FID / IS 改为使用 torchvision Inception V3 手动实现，不再依赖 clean-fid 和 torch-fidelity
• ✅ 彻底修复 Imaginary component 和 stack expects each tensor to be equal size 错误
• ✅ 新增图像数量自动检查，不足时给出明确提示

v1.0.0 (2026-06)

• ✅ 初始版本，支持 FID / IS / CLIP-Score / LPIPS 四项指标
• ✅ 内置 save_path 参数，无需依赖 SaveText 节点
• ✅ OUTPUT_NODE = True，可直接作为工作流输出节点
• ✅ batch_size 支持自由输入（step=1）
• ✅ 内置调试日志（eval_debug.log）

---

许可证

MIT License — 可自由使用、修改和分发。

---

致谢

• clean-fid
• torch-fidelity
• clip-score
• LPIPS
• ComfyUI

---

问题反馈

如有 Bug 报告或功能建议，欢迎提交 Issue。