134 lines
5.6 KiB
Markdown
134 lines
5.6 KiB
Markdown
# ComfyUI-Smart-Metadata-Reader
|
|
|
|
语言 / Language: 中文 | [English](README_EN.md)
|
|
|
|
`ComfyUI-Smart-Metadata-Reader` 是一个 Python-only 的 ComfyUI 自定义节点。它的主节点 `Smart Metadata Reader` 是图片加载器型节点，可以选择或上传图片，读取图片里已经保存的 AI 生成 metadata，并输出图片、遮罩、真实正负提示词和常用生成参数。
|
|
|
|
## 项目简介
|
|
|
|
这个节点不是“看图反推提示词”。它不会分析图片内容来猜 prompt，而是读取图片文件里已有的 metadata，尤其是 ComfyUI 生成 PNG 中保存的 `prompt` 和 `workflow` JSON。
|
|
|
|
它的核心目标是处理复杂 ComfyUI workflow：从最终 selected sampler 的 `positive` / `negative` conditioning 链路反向追踪，提取真正进入最终生图步骤的正面提示词、负面提示词、模型、VAE、LoRA、seed、steps、CFG、sampler、scheduler 和尺寸等信息。
|
|
|
|
## 解决什么问题
|
|
|
|
普通 prompt reader 往往只能读取简单的 A1111 参数，或者在 ComfyUI workflow 里直接查找 `CLIPTextEncode.inputs.text`。但复杂 workflow 里，`CLIPTextEncode.inputs.text` 可能是上游链接，例如字符串拼接节点、ShowText 缓存、翻译节点、ControlNet conditioning、detailer 或其他 custom node。
|
|
|
|
本项目把 ComfyUI metadata 当成 graph 解析，而不是把 workflow 里所有文本字段扫一遍。
|
|
|
|
## 与普通 Prompt Reader 的区别
|
|
|
|
- 从最终输出图片链路选择 sampler，而不是随便取最后一个节点。
|
|
- positive / negative 只从 selected sampler 的 conditioning 链路解析。
|
|
- 不扫描整个 workflow 的所有 `text` 字段。
|
|
- 不会把 ControlNet 的 image、strength、control_net、model_name 等参数混进 prompt。
|
|
- 不会把 Gemini / OpenAI / ChatGPT / Claude / LLM 节点的 `system_instruction`、`system_prompt`、`prompt`、`instruction`、`messages` 这类模板当成最终提示词。
|
|
- `ShowText|pysssss` 有 `text_0` 缓存结果时，会优先使用缓存结果。
|
|
- 不过滤 LoRA trigger words、角色词、风格词、NSFW 词、质量词、翻译文本或用户手写标签。
|
|
|
|
## 安装方式
|
|
|
|
进入你的 ComfyUI 安装目录：
|
|
|
|
```bash
|
|
cd ComfyUI/custom_nodes
|
|
git clone https://github.com/CyberShadowX/ComfyUI-Smart-Metadata-Reader.git
|
|
cd ComfyUI-Smart-Metadata-Reader
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
安装后重启 ComfyUI。
|
|
|
|
## 使用方式
|
|
|
|
1. 在 ComfyUI 中添加节点 `Smart Metadata Reader`。
|
|
2. 从 ComfyUI `input` 目录选择图片，或通过图片控件上传图片。
|
|
3. 使用节点输出连接后续节点，或直接查看输出文本。
|
|
|
|
## 输出端口
|
|
|
|
主节点输出：
|
|
|
|
- `image`
|
|
- `mask`
|
|
- `positive`
|
|
- `negative`
|
|
- `seed`
|
|
- `steps`
|
|
- `cfg`
|
|
- `width`
|
|
- `height`
|
|
- `model_name`
|
|
- `filename`
|
|
- `setting`
|
|
|
|
`setting` 是给人看的整合参数文本，包含文件名、来源、模型、VAE、LoRA 列表、seed、steps、CFG、sampler、scheduler、尺寸、状态、置信度和 unresolved 信息。
|
|
|
|
## 支持的 Metadata 格式
|
|
|
|
- ComfyUI `prompt` metadata 优先，因为它更接近实际执行 graph。
|
|
- ComfyUI `workflow` metadata 用于补充 UI 缓存和 fallback，例如 `ShowText|pysssss` 的显示缓存。
|
|
- A1111 / Forge `parameters` 会在 ComfyUI graph 无法启动解析时作为 fallback。
|
|
- 通过 Pillow 读取 PNG、JPEG、WEBP 中的 metadata。
|
|
|
|
如果图片被平台压缩、聊天软件转发或图床处理后丢失 metadata，本节点无法恢复原始提示词。这种情况只能依赖其他图像反推工具。
|
|
|
|
## 支持的主要节点类型
|
|
|
|
Phase 1 初始支持包括：
|
|
|
|
- `KSampler`
|
|
- `KSamplerAdvanced`
|
|
- `SamplerCustom`
|
|
- `SamplerCustomAdvanced`
|
|
- `CLIPTextEncode`
|
|
- `CLIPTextEncodeSDXL`
|
|
- `StringFunction|pysssss`
|
|
- `ShowText|pysssss`
|
|
- `DeepTranslatorTextNode`
|
|
- `ControlNetApply`
|
|
- `ControlNetApplyAdvanced`
|
|
- `ConditioningCombine`
|
|
- `ConditioningConcat`
|
|
- `InpaintModelConditioning`
|
|
- `FaceDetailer` 和常见 detailer passthrough 模式
|
|
- `CheckpointLoaderSimple`
|
|
- `CheckpointLoader`
|
|
- `VAELoader`
|
|
- `LoraLoader`
|
|
- `LoraLoaderModelOnly`
|
|
|
|
## 重要解析原则
|
|
|
|
- positive 必须来自 selected sampler 的 `positive` conditioning 链路。
|
|
- negative 必须来自 selected sampler 的 `negative` conditioning 链路。
|
|
- 不扫描整个 workflow 的所有文本节点。
|
|
- 未连接到最终 sampler 的 Gemini、ShowText、StringFunction、PrimitiveString、备注文本或旧 CLIPTextEncode 不会污染结果。
|
|
- ControlNet、Detailer、Inpaint、ConditioningCombine、ConditioningConcat 只在最终 conditioning 链路上作为 passthrough 或 branch 解析。
|
|
- LoRA loader 的文件名和强度会单独进入 setting；但 LoRA trigger words 如果通过文本节点进入 prompt，就会保留在 positive / negative 中。
|
|
- 不做内容审查，不做提示词优化，不删 token。
|
|
|
|
## 当前限制
|
|
|
|
- Phase 1 是 Python-only。节点内部三个大文本框和更像 SD Prompt Reader 的图片预览 UI 留到 Phase 2 JS 前端增强。
|
|
- 部分未知 custom conditioning 节点会返回 `PARTIAL` / unresolved，而不是猜测 prompt。
|
|
- 某些 custom node 的运行结果如果没有写入 metadata 缓存，可能无法还原。
|
|
- 被压缩或重新保存后丢失 metadata 的图片无法读取原始生成参数。
|
|
|
|
## 本地验证
|
|
|
|
在插件目录运行：
|
|
|
|
```bash
|
|
python -m pytest -q
|
|
python -m compileall .
|
|
```
|
|
|
|
## 手动 ComfyUI 验证
|
|
|
|
1. 重启 ComfyUI。
|
|
2. 搜索并添加 `Smart Metadata Reader`。
|
|
3. 选择或上传一张带有 metadata 的图片。
|
|
4. 确认节点输出 `image`、`mask`、`positive`、`negative` 和 `setting`。
|
|
5. 如果解析状态是 `PARTIAL`，查看 `setting` 中的 unresolved 信息，定位不支持的 custom node。
|