%20(1).png)
ComfyUI-Miaoshouai-Tagger 插件保姆级教程
1. 插件简介
插件原地址： https://github.com/miaoshouai/ComfyUI-Miaoshouai-Tagger
这个插件就像是一个超级聪明的"看图说话"小助手！它能够自动看懂你的图片，然后用文字描述出图片里有什么内容。比如你给它一张美女照片，它能告诉你"这是一个长发飘飘的女孩，穿着红色连衣裙，在花园里微笑"这样的描述。
主要用途：
- 自动给图片写描述文字（就像给图片配字幕）
- 批量处理大量图片，一次性给所有图片都写好描述
- 帮助训练AI模型时准备图片标签
- 把图片内容转换成文字提示词，用于生成新图片
能带来什么效果：
- 节省大量手工写图片描述的时间
- 让图片描述更准确、更专业
- 支持多种描述风格（简单描述、详细描述、标签式描述等）
- 可以和其他ComfyUI节点配合使用，实现自动化工作流
2. 如何安装
方法一：通过ComfyUI管理器安装（推荐）
- 打开ComfyUI
- 点击"Manager"按钮
- 搜索"Miaoshouai-Tagger"
- 点击安装
方法二：手动安装
- 打开终端或命令提示符
- 进入ComfyUI的custom_nodes文件夹
- 运行命令：
git clone https://github.com/miaoshouai/ComfyUI-Miaoshouai-Tagger.git - 安装依赖包：
pip install -r ComfyUI-Miaoshouai-Tagger/requirements.txt
方法三：便携版安装
如果你用的是ComfyUI便携版，在ComfyUI_windows_portable文件夹中运行：
python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Miaoshouai-Tagger\requirements.txt
3. 节点详细解析
3.1 🐾MiaoshouAI Tagger 节点
这是插件的核心节点，就像一个专业的"图片解说员"，能够看懂图片并用文字描述出来。
3.2 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| model | model | promptgen_base_v1.5, promptgen_large_v1.5, promptgen_base_v2.0, promptgen_large_v2.0 | promptgen_base_v2.0 | 选择不同的"大脑"来看图片，就像选择不同水平的解说员 | 选择不同版本的Florence-2模型，影响描述质量和速度 | 新手用base版本就够了，追求质量用large版本 |
| folder_path | folder_path | 字符串路径 | 你的图片文件夹路径 | 告诉程序去哪个文件夹找图片，就像告诉快递员地址 | 指定要处理的图片文件夹路径 | 输入：/Users/你的用户名/Pictures/待处理图片 |
| caption_method | caption_method | tags, simple, detailed, extra, mixed, extra_mixed, analyze | extra_mixed | 选择描述风格，就像选择说话方式（简单说还是详细说） | 不同的图像描述生成模式 | tags=标签式，simple=简单描述，detailed=详细描述 |
| max_new_tokens | max_new_tokens | 1-4096的整数 | 1024 | 控制描述文字的长度上限，就像限制作文字数 | 生成文本的最大token数量 | 1024够用，想要更长描述可以调到2048 |
| num_beams | num_beams | 1-64的整数 | 4 | 控制描述质量，数字越大质量越好但速度越慢 | beam search的束宽，影响生成质量 | 4是平衡点，追求质量可以调到8 |
| random_prompt | random_prompt | never, always | never | 控制每次是否生成不同的描述，就像掷骰子 | 是否启用随机采样生成不同结果 | never=固定结果，always=每次都不同 |
| images | images | IMAGE类型 | 可选 | 直接输入图片，就像直接给解说员看照片 | 输入的图像张量数据 | 连接其他节点的图片输出 |
| filenames | filenames | STRING类型 | 可选 | 指定保存文件的名字，就像给文件起名字 | 输出文件的文件名 | 连接文件名生成节点 |
| captions | captions | STRING类型 | 可选 | 已有的描述文字，新描述会接在后面 | 已存在的标题文本，用于拼接 | 连接其他描述节点的输出 |
| prefix_caption | prefix_caption | 多行字符串 | 空 | 在描述前面加的固定文字，就像开场白 | 添加到生成描述前的前缀文本 | 输入："这是一张关于" |
| suffix_caption | suffix_caption | 多行字符串 | 空 | 在描述后面加的固定文字，就像结束语 | 添加到生成描述后的后缀文本 | 输入："的精美图片" |
| replace_tags | replace_tags | 字符串 | 替换规则示例 | 替换描述中的特定词汇，就像查找替换功能 | 文本替换规则，格式为search:replace | 输入："girl:woman;man:person" |
3.3 🐾MiaoshouAI Save Tags 节点
这个节点就像一个"文件管理员"，负责把生成的描述文字保存到文件里。
3.4 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| filenames | filenames | STRING类型 | 必需输入 | 要保存的文件名，就像给文档起名字 | 输入的文件名字符串 | 连接Tagger节点的filenames输出 |
| captions | captions | STRING类型 | 必需输入 | 要保存的描述内容，就像要写入文档的内容 | 要保存的标题文本内容 | 连接Tagger节点的captions输出 |
| save_folder | save_folder | 字符串路径 | 你的保存目录 | 指定保存文件的文件夹，就像选择存放位置 | 文件保存的目标文件夹路径 | 输入：/Users/你的用户名/Documents/标签文件 |
| filename_prefix | filename_prefix | 字符串 | 空 | 给文件名加前缀，就像给所有文件统一编号 | 文件名的前缀字符串 | 输入："tag_"会生成tag_001.txt这样的文件 |
| mode | mode | overwrite, append | overwrite | 选择写入方式：覆盖原文件还是追加到末尾 | 文件写入模式 | overwrite=替换原内容，append=追加到末尾 |
3.5 🐾MiaoshouAI Flux Clip Text Encode 节点
这个节点专门为Flux模型设计，就像一个"翻译官"，把描述文字转换成Flux模型能理解的格式。
3.6 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| clip | clip | CLIP类型 | 必需输入 | 连接CLIP模型，就像连接翻译工具 | CLIP模型对象，用于文本编码 | 连接Load CLIP节点的输出 |
| caption | caption | STRING类型 | 必需输入 | 输入要编码的描述文字，就像要翻译的原文 | 输入的标题文本，支持动态提示 | 连接Tagger节点的captions输出 |
| guidance | guidance | 0.0-100.0的浮点数 | 3.5 | 控制生成图片时对描述的遵循程度，就像调节"听话程度" | CFG引导强度，影响生成结果与提示的匹配度 | 3.5是默认值，想要更严格遵循可以调到7.0 |
3.7 🐾MiaoshouAI Caption Analyzer 节点（测试版）
这个节点就像一个"信息提取器"，能从详细描述中提取出特定的信息，比如人物的年龄、发色、服装等。
3.8 参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| analyze | analyze | STRING类型 | 必需输入 | 输入要分析的详细描述文字，就像给分析师看报告 | 输入的分析文本，包含各种属性信息 | 连接Tagger节点analyze模式的输出 |
| subject_index | subject_index | 0-2的整数 | 0 | 选择分析第几个人物，0表示第一个人 | 指定要分析的主体对象索引 | 0=第一个人，1=第二个人，2=第三个人 |
| camera_angle | camera_angle | True/False | False | 是否提取拍摄角度信息，就像问"从什么角度拍的" | 是否提取相机角度属性 | 勾选后会输出"camera angle is low angle"这样的信息 |
| art_style | art_style | True/False | False | 是否提取艺术风格信息，就像问"什么画风" | 是否提取艺术风格属性 | 勾选后会输出"art style is anime"这样的信息 |
| location | location | True/False | False | 是否提取地点信息，就像问"在哪里拍的" | 是否提取位置场景属性 | 勾选后会输出"location is beach"这样的信息 |
| text | text | True/False | False | 是否提取图片中的文字信息 | 是否提取图像中的文本内容 | 勾选后会输出图片中出现的文字 |
| distance_to_camera | distance_to_camera | True/False | False | 是否提取与镜头的距离，就像问"离得近还是远" | 是否提取主体与相机的距离信息 | 勾选后会输出"distance to camera is close up"这样的信息 |
| background | background | True/False | False | 是否提取背景信息，就像问"背景是什么" | 是否提取背景描述属性 | 勾选后会输出"background is forest"这样的信息 |
| position_in_image | position_in_image | True/False | False | 是否提取在图片中的位置，就像问"在图片的哪个位置" | 是否提取主体在图像中的位置信息 | 勾选后会输出"position in image is center"这样的信息 |
| gender | gender | True/False | False | 是否提取性别信息，就像问"男的女的" | 是否提取性别属性 | 勾选后会输出"gender is female"这样的信息 |
| age | age | True/False | False | 是否提取年龄信息，就像问"多大年纪" | 是否提取年龄属性 | 勾选后会输出"age is young adult"这样的信息 |
| hair_style | hair_style | True/False | False | 是否提取发型信息，就像问"什么发型" | 是否提取发型属性 | 勾选后会输出"hair style is long hair"这样的信息 |
| hair_color | hair_color | True/False | False | 是否提取发色信息，就像问"什么颜色头发" | 是否提取头发颜色属性 | 勾选后会输出"hair color is blonde"这样的信息 |
| facial_expression | facial_expression | True/False | False | 是否提取面部表情信息，就像问"什么表情" | 是否提取面部表情属性 | 勾选后会输出"facial expression is smiling"这样的信息 |
| eye_direction | eye_direction | True/False | False | 是否提取眼神方向信息，就像问"眼睛看哪里" | 是否提取眼部朝向属性 | 勾选后会输出"eye direction is looking at viewer"这样的信息 |
| facing_direction | facing_direction | True/False | False | 是否提取面部朝向信息，就像问"脸朝哪个方向" | 是否提取面部朝向属性 | 勾选后会输出"facing direction is front"这样的信息 |
| race | race | True/False | False | 是否提取种族信息，就像问"什么人种" | 是否提取种族属性 | 勾选后会输出"race is asian"这样的信息 |
| ear | ear | True/False | False | 是否提取耳朵信息，就像问"耳朵什么样" | 是否提取耳部特征属性 | 勾选后会输出"ear is pointed"这样的信息 |
| expression | expression | True/False | False | 是否提取整体表情信息，就像问"整体什么表情" | 是否提取整体表情属性 | 勾选后会输出"expression is happy"这样的信息 |
| body | body | True/False | False | 是否提取身体信息，就像问"身材怎么样" | 是否提取身体特征属性 | 勾选后会输出"body is slim"这样的信息 |
| accessory | accessory | True/False | False | 是否提取配饰信息，就像问"戴了什么装饰品" | 是否提取配饰属性 | 勾选后会输出"accessory is necklace"这样的信息 |
| pants | pants | True/False | False | 是否提取裤子信息，就像问"穿什么裤子" | 是否提取下装属性 | 勾选后会输出"pants is jeans"这样的信息 |
| clothing | clothing | True/False | False | 是否提取服装信息，就像问"穿什么衣服" | 是否提取服装属性 | 勾选后会输出"clothing is dress"这样的信息 |
| shoes | shoes | True/False | False | 是否提取鞋子信息，就像问"穿什么鞋" | 是否提取鞋类属性 | 勾选后会输出"shoes is sneakers"这样的信息 |
| action | action | True/False | False | 是否提取动作信息，就像问"在做什么" | 是否提取动作行为属性 | 勾选后会输出"action is sitting"这样的信息 |
4. 使用技巧和建议
4.1 选择合适的模型版本
- 新手推荐： promptgen_base_v2.0 - 速度快，质量够用
- 追求质量： promptgen_large_v2.0 - 质量更高，但速度较慢
- 老版本： v1.5版本相对稳定，如果v2.0有问题可以回退
4.2 描述模式选择建议
- tags： 适合训练模型时使用，输出标签式关键词
- simple： 适合快速了解图片内容，输出简单描述
- detailed： 适合需要详细信息的场景
- extra_mixed： 推荐选择，综合效果最好
- analyze： 配合Caption Analyzer节点使用，提取结构化信息
4.3 批量处理技巧
- 把所有要处理的图片放在同一个文件夹
- 确保图片格式为png、jpg或jpeg
- 设置合适的保存路径
- 使用filename_prefix给生成的文件统一命名
4.4 性能优化建议
- 如果显存不足，选择base版本而不是large版本
- num_beams设置为4-8之间，太高会很慢
- max_new_tokens根据需要调整，不要设置过大
5. 常见问题解答
Q1: 插件安装后找不到节点怎么办？
A:
- 确认插件已正确安装到custom_nodes文件夹
- 重启ComfyUI
- 检查是否安装了所需的依赖包
- 查看ComfyUI控制台是否有错误信息
Q2: 模型下载失败怎么办？
A:
- 检查网络连接是否正常
- 确认有足够的磁盘空间（模型约2-4GB）
- 可以手动从Hugging Face下载模型到ComfyUI/models/LLM文件夹
- 使用国内镜像站点下载
Q3: 生成的描述不准确怎么办？
A:
- 尝试不同的caption_method模式
- 调整num_beams参数（增加到6-8）
- 使用large版本模型
- 确保输入图片质量清晰
Q4: 处理速度太慢怎么办？
A:
- 使用base版本而不是large版本
- 降低num_beams参数（设为2-4）
- 减少max_new_tokens数值
- 确保有足够的显存
Q5: 如何批量处理大量图片？
A:
- 将所有图片放在同一文件夹
- 在folder_path参数中指定文件夹路径
- 不连接images输入，让节点自动读取文件夹
- 连接SaveTags节点保存结果
Q6: 生成的文本包含不想要的内容怎么办？
A:
- 使用replace_tags参数替换特定词汇
- 格式：
不想要的词:替换词;另一个词:另一个替换词 - 使用prefix_caption和suffix_caption添加固定前后缀
- 选择更合适的caption_method模式
6. 高级使用技巧
6.1 工作流组合建议
- 基础流程： Load Image → Tagger → Save Tags
- Flux流程： Load Image → Tagger → Flux CLIP Text Encode → Flux模型
- 分析流程： Load Image → Tagger(analyze模式) → Caption Analyzer
- 批量流程： Tagger(folder模式) → Save Tags
6.2 参数调优经验
- 追求速度： base模型 + num_beams=2 + max_tokens=512
- 追求质量： large模型 + num_beams=8 + max_tokens=2048
- 平衡设置： base模型 + num_beams=4 + max_tokens=1024
6.3 与其他节点配合
- 可以与图片预处理节点配合，先调整图片再描述
- 可以与文本处理节点配合，进一步处理生成的描述
- 可以与条件节点配合，根据不同条件选择不同处理方式
7. 总结
ComfyUI-Miaoshouai-Tagger是一个功能强大的图像描述生成插件，特别适合：
- AI图片训练数据准备
- 批量图片内容分析
- 自动化工作流构建
- Flux模型提示词生成
通过合理配置参数和选择合适的模式，可以获得高质量的图片描述结果。建议新手从基础设置开始，逐步探索更高级的功能。
希望这个教程能帮助你更好地使用这个强大的插件！如果遇到问题，可以参考常见问题解答部分，或者到插件的GitHub页面寻求帮助。