%20(1).png)
ComfyUI Joy Caption 插件完全教程
1. 插件简介
插件地址： https://github.com/TTPlanetPig/Comfyui_JC2
ComfyUI Joy Caption 插件是一个超级强大的图片描述生成工具，就像给你的电脑配了一个专业的"看图说话"助手。这个插件能够：
主要功能：
- 自动分析图片内容并生成详细的文字描述
- 支持多种描述风格（正式描述、随意描述、训练提示词等）
- 支持两个版本：Alpha Two 和最新的 Beta One
- 可以生成不同长度的描述文字
- 支持多种专业用途（艺术评论、产品列表、社交媒体等）
- 自动下载和管理所需的AI模型
- 支持显存优化，适配不同配置的电脑
能给我们带来什么效果：
- 快速为大量图片生成准确的描述文字
- 为AI绘画提供高质量的训练数据
- 自动化图片标注工作
- 生成各种风格的图片说明文字
2. 如何安装
方法一：通过 ComfyUI Manager 安装（推荐）
- 打开 ComfyUI Manager
- 搜索 "JC2" 或 "Joy Caption"
- 点击安装
方法二：手动安装
- 进入 ComfyUI 的
custom_nodes文件夹 - 运行命令：
git clone https://github.com/TTPlanetPig/Comfyui_JC2.git - 安装依赖包：
pip install -r requirements.txt - 重启 ComfyUI
安装后设置
- 插件会自动创建所需的文件夹
- 首次使用时会自动下载所需的AI模型
- 如需加速，可以运行插件目录下的
安装liger-kernel.bat
3. 节点详细解析
3.1 JoyCaption2 节点（完整版）
这个节点就像一个"全能图片描述师"，它能看懂图片并用各种风格写出描述文字。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| image | image | IMAGE类型 | - | 要分析的图片 | 输入的图像张量 | 连接图片加载节点的输出 |
| llm_model | llm_model | 选择列表 | unsloth/Meta-Llama-3.1-8B-Instruct | 选择用哪个大脑来理解图片 | 语言模型选择 | 推荐使用默认模型 |
| dtype | dtype | 选择列表 | nf4 | 模型运行模式，像画质设置 | 数据类型和量化模式 | nf4省显存，bf16效果更好 |
| caption_type | caption_type | 选择列表 | Descriptive | 描述风格类型 | 生成文本的类型和风格 | 选择"Descriptive"生成详细描述 |
| caption_length | caption_length | 选择列表 | medium-length | 描述文字的长度 | 生成文本的长度控制 | "short"简短，"long"详细 |
| user_prompt | user_prompt | 文本框 | - | 自定义描述要求 | 用户自定义提示词 | 输入"描述这张图的颜色" |
| max_new_tokens | max_new_tokens | 整数 | 260 | 最多生成多少个词 | 生成文本的最大长度 | 260够用，太大会很慢 |
| top_p | top_p | 浮点数 | 0.8 | 创意程度，像想象力开关 | 核采样参数 | 0.8平衡，0.9更有创意 |
| temperature | temperature | 浮点数 | 0.6 | 随机程度，像思维活跃度 | 温度参数控制随机性 | 0.6稳定，0.8更多样 |
| cache_model | cache_model | 布尔值 | False | 是否把模型留在内存里 | 是否缓存模型以加速后续使用 | True加速但占内存 |
| device | device | 选择列表 | cuda:0 | 选择用哪个显卡运行 | GPU设备选择 | 有多张显卡时选择 |
| enable_extra_options | enable_extra_options | 布尔值 | True | 是否启用额外选项 | 是否启用扩展功能选项 | True开启更多功能 |
| character_name | character_name | 文本框 | - | 图片中人物的名字 | 角色名称用于替换模板 | 输入"小明"会在描述中使用 |
额外选项参数（17个）：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| replace_character_names | replace_character_names | 布尔值 | False | 用指定名字称呼图中人物 | 替换角色名称选项 | 开启后会用character_name替换 |
| exclude_unchangeable_attributes | exclude_unchangeable_attributes | 布尔值 | False | 不描述不能改变的特征 | 排除固有属性描述 | 不描述性别、种族等 |
| include_lighting_details | include_lighting_details | 布尔值 | False | 描述光线情况 | 包含光照信息 | 描述"柔和的自然光" |
| include_camera_angle | include_camera_angle | 布尔值 | False | 描述拍摄角度 | 包含相机角度信息 | 描述"俯视角度拍摄" |
| mention_watermark_presence | mention_watermark_presence | 布尔值 | False | 说明是否有水印 | 提及水印存在与否 | "图片右下角有水印" |
| note_jpeg_artifacts | note_jpeg_artifacts | 布尔值 | False | 说明图片压缩情况 | 注明JPEG压缩痕迹 | "图片有轻微压缩痕迹" |
| include_exif_data | include_exif_data | 布尔值 | False | 推测拍摄参数 | 包含相机设置信息 | "可能使用f/2.8光圈拍摄" |
| exclude_sexual_content | exclude_sexual_content | 布尔值 | False | 保持内容健康 | 排除成人内容描述 | 生成适合所有人的描述 |
| exclude_image_resolution | exclude_image_resolution | 布尔值 | False | 不提及图片分辨率 | 不包含分辨率信息 | 不会说"高清图片" |
| describe_aesthetic_quality | describe_aesthetic_quality | 布尔值 | False | 评价图片美观程度 | 包含美学质量评估 | "图片质量很高" |
| include_composition_style | include_composition_style | 布尔值 | False | 描述构图方式 | 包含构图风格信息 | "使用三分法构图" |
| exclude_text_elements | exclude_text_elements | 布尔值 | False | 不提及图中文字 | 不描述图像中的文本 | 忽略图片中的标语 |
| specify_depth_of_field | specify_depth_of_field | 布尔值 | False | 描述景深效果 | 指定景深和焦点信息 | "背景虚化效果" |
| specify_lighting_sources | specify_lighting_sources | 布尔值 | False | 说明光源类型 | 指定光照来源 | "使用人工照明" |
| avoid_ambiguous_language | avoid_ambiguous_language | 布尔值 | False | 使用明确的词汇 | 避免模糊表达 | 不用"可能"、"似乎" |
| classify_image_as_sfw_nsfw | classify_image_as_sfw_nsfw | 布尔值 | False | 标注内容分级 | 分类图像内容等级 | 标注"安全内容" |
| describe_key_elements_only | describe_key_elements_only | 布尔值 | False | 只描述重要元素 | 仅描述关键要素 | 突出主要内容 |
3.2 ExtraOptionsNode 节点（额外选项节点）
这个节点就像一个"选项打包器"，把各种描述要求打包成一个整体。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| enable_extra_options | enable_extra_options | 布尔值 | True | 总开关，控制是否使用额外选项 | 启用扩展选项的主开关 | True开启所有额外功能 |
| character_name | character_name | 文本框 | - | 图片中人物的名字 | 角色名称用于模板替换 | 输入人物名字如"张三" |
其他17个额外选项参数与JoyCaption2节点相同
3.3 JoyCaption2_simple 节点（简化版）
这个节点就像一个"简化版图片描述师"，功能精简但更容易使用。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| image | image | IMAGE类型 | - | 要分析的图片 | 输入的图像张量 | 连接图片加载节点 |
| llm_model | llm_model | 选择列表 | unsloth/Meta-Llama-3.1-8B-Instruct | 选择AI大脑 | 语言模型选择 | 使用默认即可 |
| dtype | dtype | 选择列表 | nf4 | 运行模式 | 数据类型选择 | nf4节省显存 |
| caption_type | caption_type | 选择列表 | Descriptive | 描述风格 | 文本生成类型 | 选择合适的风格 |
| caption_length | caption_length | 选择列表 | medium-length | 描述长度 | 文本长度控制 | 根据需要选择 |
| user_prompt | user_prompt | 文本框 | - | 自定义要求 | 用户自定义提示 | 输入特殊要求 |
| max_new_tokens | max_new_tokens | 整数 | 260 | 最大词数 | 生成文本最大长度 | 260通常够用 |
| top_p | top_p | 浮点数 | 0.8 | 创意程度 | 核采样参数 | 0.8平衡效果 |
| temperature | temperature | 浮点数 | 0.6 | 随机程度 | 温度参数 | 0.6稳定输出 |
| cache_model | cache_model | 布尔值 | False | 是否缓存模型 | 模型缓存选项 | True加速但占内存 |
| device | device | 选择列表 | cuda:0 | 显卡选择 | GPU设备选择 | 选择可用显卡 |
| extra_options_node | extra_options_node | 文本 | - | 外部额外选项 | 来自ExtraOptionsNode的输入 | 连接ExtraOptionsNode输出 |
3.4 JoyCaptionBetaOne_Full 节点（Beta版完整版）
这个节点是最新版本的"超级图片描述师"，功能更强大，效果更好。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| image | image | IMAGE类型 | - | 要分析的图片 | 输入图像张量 | 连接图片加载节点 |
| caption_type | caption_type | 选择列表 | Descriptive | 描述类型 | 文本生成类型选择 | 有更多专业选项 |
| caption_length | caption_length | 选择列表 | medium-length | 描述长度 | 文本长度控制 | 支持数字精确控制 |
| quantization_mode | quantization_mode | 选择列表 | bf16 | 模型精度模式 | 量化模式选择 | bf16质量好，nf4省显存 |
| custom_prompt | custom_prompt | 文本框 | - | 自定义提示词 | 覆盖默认提示的自定义输入 | 完全自定义描述要求 |
| character_name | character_name | 文本框 | - | 人物角色名称 | 用于名称替换的角色名 | 输入图中人物名字 |
| temperature | temperature | 浮点数 | 0.6 | 创意随机度 | 生成随机性控制 | 0.6稳定，更高更有创意 |
| top_p | top_p | 浮点数 | 0.9 | 词汇选择范围 | 核采样概率阈值 | 0.9平衡多样性 |
| max_new_tokens | max_new_tokens | 整数 | 512 | 最大生成词数 | 生成文本的最大长度 | 512支持更长描述 |
| device | device | 选择列表 | cuda:0 | 运行设备 | GPU设备选择 | 选择合适的显卡 |
| cache_model | cache_model | 布尔值 | True | 模型缓存 | 是否在内存中缓存模型 | True提高后续速度 |
| enable_liger_kernel | enable_liger_kernel | 布尔值 | True | 加速内核 | 启用LIGER加速内核 | True提升运行速度 |
Beta版额外选项（25个）：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| extra_option_0_if_there_is_a | extra_option_0_if_there_is_a | 布尔值 | False | 使用指定名字称呼人物 | 角色名称替换选项 | 开启后用character_name替换 |
| extra_option_1_do_not_include | extra_option_1_do_not_include | 布尔值 | False | 不描述固有特征 | 排除不可变属性 | 不描述种族、性别等 |
| extra_option_2_include_informa | extra_option_2_include_informa | 布尔值 | False | 包含光照信息 | 描述光线情况 | 说明光线类型和方向 |
| extra_option_3_include_informa | extra_option_3_include_informa | 布尔值 | False | 包含拍摄角度 | 描述相机角度 | 说明俯视、仰视等 |
| extra_option_4_include_informa | extra_option_4_include_informa | 布尔值 | False | 提及水印情况 | 说明水印存在 | 指出是否有水印 |
| extra_option_5_include_informa | extra_option_5_include_informa | 布尔值 | False | 说明压缩痕迹 | 描述JPEG压缩效果 | 指出图片压缩情况 |
| extra_option_6_if_it_is_a_phot | extra_option_6_if_it_is_a_phot | 布尔值 | False | 推测相机参数 | 包含拍摄技术信息 | 推测光圈、快门等 |
| extra_option_7_do_not_include | extra_option_7_do_not_include | 布尔值 | False | 保持内容健康 | 排除成人内容 | 生成适合所有人的内容 |
| extra_option_8_do_not_mention | extra_option_8_do_not_mention | 布尔值 | False | 不提及分辨率 | 排除分辨率信息 | 不说"高清"、"低分辨率" |
| extra_option_9_you_must_includ | extra_option_9_you_must_includ | 布尔值 | False | 评价美学质量 | 包含审美评价 | 说明图片美观程度 |
| extra_option_10_include_inform | extra_option_10_include_inform | 布尔值 | False | 描述构图风格 | 包含构图技巧信息 | 说明三分法、对称等 |
| extra_option_11_do_not_mention | extra_option_11_do_not_mention | 布尔值 | False | 忽略图中文字 | 不描述文本内容 | 不提及图片中的文字 |
| extra_option_12_specify_the_de | extra_option_12_specify_the_de | 布尔值 | False | 说明景深效果 | 描述焦点和虚化 | 说明前景清晰背景模糊 |
| extra_option_13_if_applicable_ | extra_option_13_if_applicable_ | 布尔值 | False | 区分光源类型 | 说明光照来源 | 区分自然光和人工光 |
| extra_option_14_do_not_use_any | extra_option_14_do_not_use_any | 布尔值 | False | 使用明确语言 | 避免模糊表达 | 不用"可能"、"似乎" |
| extra_option_15_include_whethe | extra_option_15_include_whethe | 布尔值 | False | 标注内容等级 | 分类图像内容 | 标注安全级别 |
| extra_option_16_only_describe_ | extra_option_16_only_describe_ | 布尔值 | False | 只描述重点 | 突出关键元素 | 专注主要内容 |
| extra_option_17_if_it_is_a_wor | extra_option_17_if_it_is_a_wor | 布尔值 | False | 不提及艺术家 | 排除作者信息 | 不说明作者和作品名 |
| extra_option_18_identify_the_i | extra_option_18_identify_the_i | 布尔值 | False | 说明图片方向 | 描述横竖比例 | 说明横版、竖版、方形 |
| extra_option_19_use_vulgar_sla | extra_option_19_use_vulgar_sla | 布尔值 | False | 使用粗俗语言 | 包含不雅词汇 | 使用直白粗俗的表达 |
| extra_option_20_do_not_use_pol | extra_option_20_do_not_use_pol | 布尔值 | False | 避免委婉表达 | 使用直接语言 | 不用礼貌的委婉说法 |
| extra_option_21_include_inform | extra_option_21_include_inform | 布尔值 | False | 说明人物年龄 | 包含年龄信息 | 推测并说明年龄段 |
| extra_option_22_mention_whethe | extra_option_22_mention_whethe | 布尔值 | False | 说明拍摄距离 | 描述镜头距离 | 说明特写、远景等 |
| extra_option_23_do_not_mention | extra_option_23_do_not_mention | 布尔值 | False | 不描述情绪氛围 | 排除主观感受 | 不说"温馨"、"忧郁" |
| extra_option_24_explicitly_spe | extra_option_24_explicitly_spe | 布尔值 | False | 明确拍摄高度 | 说明视角高度 | 说明平视、俯视、仰视 |
| extra_option_25_if_there_is_a_ | extra_option_25_if_there_is_a_ | 布尔值 | False | 必须提及水印 | 强制说明水印 | 有水印时必须指出 |
3.5 ExtraOptionsNode_Beta 节点（Beta版额外选项）
这个节点是Beta版的"选项打包器"，功能更丰富。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| enable_extra_options | enable_extra_options | 布尔值 | True | 额外选项总开关 | 启用扩展功能的主控制 | True开启所有额外功能 |
| character_name | character_name | 文本框 | - | 人物角色名称 | 用于名称替换的角色名 | 输入图中人物的名字 |
其他25个额外选项参数与JoyCaptionBetaOne_Full节点相同
3.6 JoyCaptionBetaOne_Simple 节点（Beta版简化版）
这个节点是Beta版的"简化图片描述师"，保持强大功能但操作简单。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| image | image | IMAGE类型 | - | 要分析的图片 | 输入图像张量 | 连接图片加载节点 |
| caption_type | caption_type | 选择列表 | Descriptive | 描述类型 | 文本生成类型 | 选择合适的描述风格 |
| caption_length | caption_length | 选择列表 | medium-length | 描述长度 | 文本长度控制 | 根据需要选择长度 |
| quantization_mode | quantization_mode | 选择列表 | bf16 | 模型精度 | 量化模式选择 | bf16质量好 |
| custom_prompt | custom_prompt | 文本框 | - | 自定义提示 | 覆盖默认的自定义提示 | 输入特殊要求 |
| temperature | temperature | 浮点数 | 0.6 | 创意程度 | 生成随机性控制 | 0.6稳定输出 |
| top_p | top_p | 浮点数 | 0.9 | 词汇范围 | 核采样参数 | 0.9平衡效果 |
| max_new_tokens | max_new_tokens | 整数 | 512 | 最大词数 | 生成文本最大长度 | 512支持长描述 |
| device | device | 选择列表 | cuda:0 | 运行设备 | GPU设备选择 | 选择合适显卡 |
| cache_model | cache_model | 布尔值 | True | 模型缓存 | 是否缓存模型 | True提升速度 |
| extra_options_str | extra_options_str | 文本 | - | 外部额外选项 | 来自ExtraOptionsNode_Beta的输入 | 连接额外选项节点 |
| enable_liger_kernel_opt | enable_liger_kernel_opt | 布尔值 | True | 加速内核选项 | 启用LIGER加速 | True提升性能 |
4. 使用技巧和建议
4.1 选择合适的版本
- Alpha Two版本：稳定可靠，适合日常使用
- Beta One版本：功能更强，效果更好，推荐新用户使用
- Full版本：功能完整，适合专业用户
- Simple版本：操作简单，适合快速使用
4.2 显存优化建议
- 显存不足19GB：使用nf4模式
- 显存充足：使用bf16模式获得最佳效果
- 多张显卡：选择合适的device参数
- 显存紧张：关闭cache_model选项
4.3 描述类型选择技巧
- Descriptive：适合一般图片描述
- Training Prompt：适合AI绘画训练数据
- Booru tag list：适合动漫图片标注
- Art Critic：适合艺术作品分析
- Product Listing：适合商品图片描述
4.4 参数调优建议
- temperature：0.6稳定，0.8有创意，1.0很随机
- top_p：0.8-0.9平衡，0.95更多样
- max_new_tokens：260够用，512支持长文本
- caption_length：根据实际需要选择
5. 常见问题解答
Q1：显存不够怎么办？
A：
- 使用nf4模式而不是bf16
- 关闭cache_model选项
- 减少max_new_tokens数值
- 使用Simple版本节点
Q2：生成的描述不准确怎么办？
A：
- 尝试使用Beta One版本
- 调整temperature参数（降低获得更稳定结果）
- 使用custom_prompt自定义要求
- 选择合适的caption_type
Q3：如何加速生成过程？
A：
- 开启cache_model选项
- 安装liger-kernel加速包
- 使用bf16模式（如果显存够用）
- 启用enable_liger_kernel选项
Q4：额外选项怎么使用？
A：
- Full版本：直接在节点上勾选需要的选项
- Simple版本：需要配合ExtraOptionsNode使用
- 根据需要选择合适的额外选项
- character_name用于替换描述中的人物名称
Q5：不同描述类型有什么区别？
A：
- Descriptive：正式详细的描述
- Straightforward：直接简洁的描述
- Stable Diffusion Prompt：适合AI绘画的提示词
- Danbooru tag list：动漫风格的标签列表
- Art Critic：艺术评论风格的分析
6. 实用工作流示例
6.1 基础图片描述工作流
- 加载图片 → JoyCaptionBetaOne_Simple
- 设置caption_type为"Descriptive"
- 选择合适的caption_length
- 运行获得描述文字
6.2 专业标注工作流
- 加载图片 → JoyCaptionBetaOne_Full
- 开启多个额外选项
- 设置character_name（如有人物）
- 使用"Training Prompt"类型
- 获得专业训练数据
6.3 批量处理工作流
- 使用图片批处理节点
- 连接JoyCaption2节点
- 开启cache_model加速
- 设置合适的参数批量处理
7. 总结
ComfyUI Joy Caption插件是一个功能强大的图片描述生成工具，通过6个不同功能的节点，你可以：
- 自动生成高质量的图片描述文字
- 支持多种专业用途和描述风格
- 灵活控制描述的长度和详细程度
- 优化显存使用适配不同配置
- 批量处理大量图片
掌握这个插件，你就能在ComfyUI中实现专业级的图片自动标注和描述生成，大大提高工作效率！