qapyq（CapPic）：AI 辅助的图像/视频数据集标注工具

开篇：训练 LoRA 模型时，最头疼的环节是什么？

当你准备用 1000 张精挑细选的图片微调一个 Stable Diffusion LoRA 模型时，最耗时的往往不是等待训练跑完——而是前期的数据清洗与标注。你需要给每张图打上准确的标签（caption），裁剪掉无关的背景区域，绘制出用于训练的 mask 蒙版，把 caption 批量导出成模型能识别的格式……这些机械性的工作占用了大量时间，而且极易出错。

qapyq（项目名读作类似 "copy-pic"，别名为 CapPic）正是为解决这个痛点而生的。这是一款由独立开发者 FennelFetish 打造的桌面应用，专门面向需要处理大量图像/视频数据集的 AI 训练爱好者。它用 AI 模型自动完成标注，再用精心设计的 Qt 图形界面让你高效地批量编辑、校对和导出结果——一条龙服务，把最繁琐的数据准备工作变得可控且高效。

图1：qapyq 五个窗口同时展开的完整界面。

背景：为什么这个工具值得被关注？

qapyq 的诞生背景与 LoRA / Stable Diffusion 微调社区的爆发式增长密切相关。2023—2024 年，LoRA 模型微调技术迅速普及，无数 AI 爱好者开始尝试用自己的数据集训练个性化模型。然而，高质量训练数据的准备长期缺乏好用的工具：要么用脚本批量处理但无法预览校对，要么用通用图像标注工具但缺乏对 diffusion 训练流程的专门支持。

FennelFetish 从这个空白中看到了机会，开发了 qapyq。项目的 GitHub 页面显示仓库创建于 2024 年 10 月，不到一年时间就积累了 163 个 GitHub stars 和 10 个 fork，issue 仅 4 个（说明维护状态健康）。项目采用 AGPL-3.0 开源协议，并配有详细的 Wiki 用户指南。

类比：qapyq 是什么工具的合体？

如果一定要用生活中的例子来类比，qapyq 像是一个配备了 AI 助理的专业图片工作室。它的Gallery（画廊）是你的图片库管理器，支持百万级文件秒开；Captioning（标注）窗口是你的文字编辑台，可以用 AI 自动生成描述；Masking（蒙版）工具是你的裁剪台，负责把主体从背景中精准分离；Batch（批处理）则是你的流水线主管，把重复劳动自动化。四个工位可以分布在多台显示器上，各自独立运行。

核心功能：每个模块能做什么？

🖼️ 媒体浏览与管理

qapyq 的 Gallery 窗口基于 Qt 构建，启动迅速，在测试中能流畅处理包含上百万个文件的数据集目录。界面支持多标签页、分屏浏览、全屏幻灯片播放、缩放平移等操作，还可以按语义相似度对图库排序——输入一句文字描述，qapyq 会调用 CLIP/SigLIP 模型计算每张图的语义向量，按相关性排列结果。

此外还有专门的图片对比工具（Compare）、尺寸/面积测量工具，以及视频逐帧预览与导出功能。ffmpeg 集成在后台，对视频文件的处理与图片几乎一样顺手。

✏️ 标注（Captioning）

这是 qapyq 最核心的模块。标注窗口支持：

• 手动编辑：拖拽调整标签顺序、批量添加/删除标签、着色高亮、分组管理。
• AI 自动生成：调用视觉语言模型（VLM）自动为图片生成描述或关键词标签。
• Focus Mode（聚焦模式）：用一个统一的标签快速"涂抹"到多个文件上，适合给系列图片打相同的风格标签。
• Multi-Edit（多文件编辑）：同时在多个文件的 caption 上进行查找替换、条件过滤、排序等操作。
• CLIP Token 计数器：实时显示当前 caption 的 token 数量，帮助你控制 prompt 长度不超过模型限制。
• 级联更新：caption 存储在每张图对应的 JSON 文件中，可以级联导出为 TXT 文件，支持模板变量。

支持的模型非常全面，涵盖了 JoyTag、WD Tagger、Florence-2、InternVL 系列、Qwen2-VL/Qwen3-VL、JoyCaption、MiniCPM-V、Moondream2、Ovis 系列等主流 tagging 和 captioning 模型。大部分支持 GGUF 量化格式，降低显存占用。

🎨 蒙版（Masking）

蒙版模块支持：

• 手动绘制：多层蒙版编辑，画笔大小、羽化等参数可调。
• 自动生成：调用 YOLO、Florence-2、Qwen3-VL、InSPyReNet、RMBG-2.0 等模型自动检测主体并生成蒙版。
• 宏录制：把一系列蒙版操作录制为宏（macro），然后在批处理中批量应用——这个设计非常适合 LoRA 训练中反复使用的标准化蒙版模板。
• VAE 重建预览：将图像编码到 latent 空间再解码还原，检验蒙版效果对 diffusion 训练的影响。

📐 裁剪与缩放

裁剪工具支持自定义尺寸预设（如 512×512、768×1152 等常见训练分辨率），还可以调用 AI 超分辨率模型（基于 spandrel 后端，支持 Real-ESRGAN 等架构）进行智能放大。动态保存路径模板变量（如 {{path}}_{{w}}x{{h}}.png）让批量导出文件的命名井井有条。

📊 统计与筛选

Stats 窗口可以列出数据集中所有标签、分辨率分布、蒙版区域统计、概念文件夹大小，并支持导出 CSV。结合筛选器，可以快速从大数据集中提取子集用于针对性训练。

🚀 批处理

Batch 模块把上述所有能力封装为命令行可调用的脚本（batch_caption.py、batch_apply.py、batch_file.py 等），适合在远程服务器上无人值守运行。

技术架构

技术栈

qapyq 的技术选型非常务实：

• GUI 框架：PyQt6（Qt for Python）。Qt 是久经考验的跨平台桌面框架，性能和稳定性兼优。用 Python 绑定而非原生 C++ 开发，大幅降低了入门门槛，同时保留了 Qt 的全部 UI 能力。
• AI 推理：PyTorch（支持 CUDA/ROCm 多平台）+ Hugging Face Transformers + llama-cpp-python（GGUF 量化支持）+ ONNX Runtime（WD Tagger 等 ONNX 模型）。subprocess 隔离推理进程，VRAM 可完全释放。
• 图像处理：Pillow（PIL）、OpenCV，视频处理依赖 ffmpeg。
• 后端架构：主进程（main_host.py）运行 GUI 和调度逻辑，推理作为独立子进程运行，通过进程间通信解耦——GUI 崩溃不会影响推理进程，反之亦然。
• 代码组织：模块化清晰，caption/ 处理标注逻辑、batch/ 处理批处理、infer/ 处理 AI 推理、tools/ 处理各类工具窗口、lib/ 是底层库。

AI 模型生态

qapyq 支持的模型几乎覆盖了图像标注生态的主流架构：

类别	代表模型	用途
Tagging	JoyTag、WD Tagger、PixAI Tagger	关键词标签
Captioning	Florence-2、InternVL、Qwen2-VL、JoyCaption、MiniCPM	完整句子描述
Masking 检测	YOLO、Florence-2、Qwen3-VL	目标检测定位主体
Masking 分割	InSPyReNet、RMBG-2.0	主体与背景分离
Embedding	CLIP、SigLIP	语义排序
超分辨率	spandrel 后端所有架构	AI 放大
VAE	Flux、SDXL、SD1.5、Qwen VAE	latent 空间预览

配置文件

config.py 集中管理所有默认参数，导出的用户配置写入 qapyq_config.json，与程序分离便于迁移。caption 规则可导出为 default-caption-rules.json 复用，蒙版宏保存在 user/mask-macros/ 目录。

上手门槛

普通用户（无需 AI 模型）：安装 Python 3.10+、克隆仓库、运行 setup.sh 选择基础组件即可。依赖通过脚本自动装入虚拟环境，简单易行。

AI 爱好者：需要额外下载 AI 模型权重（从 Hugging Face 下载）。setup 脚本支持 CUDA 12.6/12.8/13.0 和 ROCm 6.4/7.2 多平台，显存需求因模型而异，JoyTag 等轻量模型 2-4GB 显存即可运行，InternVL3 等大型 VLM 建议 6GB+。

服务器用户：项目支持 headless 模式安装（仅后台推理服务），可远程通过 SSH 运行推理，适合有多台机器的玩家。

坑点提醒：Python 3.14 在 setup 和推理时可能出现兼容性问题，项目文档建议使用 Python 3.12 获得最广泛的兼容性。

局限与争议

1. 没有 Docker 部署选项：项目无 Dockerfile 或 docker-compose，对于希望容器化运行的用户不友好。但考虑到这是一个 Qt 图形应用，强行容器化反而会增加 GUI 走 X11 Forwarding 的复杂度，这个设计取舍可以理解。
2. Windows 体验可能弱于 Linux：run.sh 包含 glibc malloc 参数调优（MMAP_THRESHOLD_），这是 Linux 特有的内存管理优化，Windows 用户无法受益。
3. 模型下载依赖外部：AI 模型权重需要用户自行从 Hugging Face 下载，国内用户可能需要代理或镜像。
4. GUI 定制能力有限：界面使用 Qt Fusion 风格，不支持主题切换，对追求颜值的用户吸引力一般。

行业意义

qapyq 的出现填补了 LoRA/Diffusion 训练数据准备工具链的一个关键空白。它不是第一个图像标注工具，但它是第一个将完整的 caption → mask → crop → batch 流程与多模型 AI 推理深度整合的桌面应用。随着 AI 图像生成工具的持续普及，这类工具的需求只会增长。项目的活跃维护（2026年7月23日仍有推送）、详细的 Wiki 文档、模块化的代码架构，都显示出这是一个认真维护的社区项目，而非一时兴起的实验性作品。

对于每一个想要训练自己的 LoRA 或 diffusion 模型的人，qapyq 值得花 10 分钟安装试用——它很可能是你工作流中缺失的那一块拼图。