Danbooru模糊查找
Danbooru 模糊查找技术报告
——基于多视图语义匹配的标签检索与推荐系统
[toc]
- 立即使用：https://huggingface.co/spaces/SAkizuki/DanbooruSearch
- Github链接（含使用指南）：https://github.com/SuzumiyaAkizuki/DanbooruSearchOnline
项目概述与需求来源
DanbooruSearcher 是一个专为 AI 图像生成器设计的语义检索系统
。在当前的提示词（Prompt）工程中，底层系统依赖高度结构化、特定格式的英文标签（例如采用下划线连接的
white_sailor_collar），这与人类日常的自然语言表达习惯存在巨大的语义鸿沟
。
现有的常规检索方案通常依赖简单的字符串匹配或单一视角的向量检索，存在以下不足：
跨语言障碍： 用户通常使用母语（如中文）描述复杂场景，而目标标签多为特定英文甚至日文罗马音词汇，传统翻译往往会丢失特定领域的语境，或无法与真正精准的标签对应。例如：汉语「水手服」可能会被翻译软件翻译为「sailor suit」，但是用户想找的标签大概率应该是「serafuku」。
逆向检索需求: 现有的检索方案往往是用户根据标签检索其对应的含义。但是在T2I实践时，用户脑中有关于概念的模糊认知，希望写出对应的精准标签才是更加迫切的需求。例如：用户可能想画出「紧身衣勒入皮肤后的凹陷」的效果，但不知道这有一个专用标签「skindentation」。
头脑风暴与相关推荐: 现有的检索方案往往只有粗略分类。用户可能想要搜索关于「中国风古装」或者「天空」的大量标签，以进行头脑风暴辅助绘图。或者，用户想要在绘图时根据标签的相关性提升绘图质量。
大语言模型打标辅助: 用户会使用大语言模型辅助写标签。但是大语言模型对danbooru数据集的知识很可能不足，导致其不知道使用什么精准标签，转而使用自然语言描述或产生幻觉采用错误的标签。如果每次对话都将全部标签传给大模型，不仅效果不好，token用量也不可接受。用户需要先进行粗略检索，将可能出现的标签发给大模型，作为大模型的前置知识。
本项目通过引入多语言嵌入模型、构建四路多视图语义向量索引，并结合点互信息（PMI）机制的共现推荐算法，系统性地解决了上述问题 。
模型选型与多视图检索
系统采用解耦设计，核心引擎层（core/engine.py）负责承载所有复杂的计算与检索逻辑
。
数据预处理和清洗
在Github和Hugging Face上，可以拿到关于danbooru标签的数据，包括标签、汉语翻译、释义(wiki)、类别、频数。
在数据预处理阶段，首先截取了频数≥100的标签。因为本工具是服务于T2I任务的，而频数过少的标签，很可能在T2I任务上表现不佳。其次，删除了所有类别为artist和meta的标签。因为其难以检索或对出图帮助不大。
最后，我使用grok-4.1-fast大模型，将wiki翻译为汉语，根据wiki复查标签汉语释义的正确性，为每个汉语释义生成扩展词，并判断其是否为NSFW标签。
最终，形成的标签数据库具有如下格式：
| name | cn_name | wiki | post_count | category | nsfw |
|---|---|---|---|---|---|
| 1girl | 1个女孩,单人,女孩,人物 | 画面中只出现一个女性角色 | 7419839 | 0 | 0 |
标签共现原始数据具有以下格式：
| tag_a | tag_b | count |
|---|---|---|
| 1girl | solo | 3816210 |
在预处理阶段，删除了tag_a或tag_b不在标签数据库中的条目。进一步的筛选，将在下文详述。
语义编码模型选型
系统选用了智源研究院开源的多功能多语言嵌入模型
BAAI/bge-m3 。该模型在本项目中的核心优势包括：
统一多语言语义空间： 原生支持中英文双语，使得中文查询向量与英文标签向量能够直接在同一高维空间中计算余弦相似度，彻底免去了易错的机器翻译前置步骤 。
超长上下文支持： 具备高达 8192 token 的上下文处理窗口，能够无损编码复杂的长文本百科释义（Wiki）数据 。
灵活的部署降级： 优先加载本地离线模型，若缺失则自动回退至拉取 HuggingFace Hub，保障了不同环境下的高可用性 。
四路多视图向量化架构
本项目创新性地使用了思路多视图向量化架构，以适应用户的多种检索需求。
单一向量空间无法完美映射极其复杂的查询意图 。为此，系统为数据库中的每个标签独立提取并构建了四路平行的向量矩阵（视图）：
英文视图： 适配正向查询需求，直接编码原始的下划线格式英文标签名，处理纯正的专业术语检索 。
中文扩展词视图： 适配概念相关推荐与头脑风暴需求，编码包含所有同义词和多义项的中文译名集合，极大提升了模糊查询的召回广度 。
中文核心词视图： 适配精确查词需求，仅提取并编码多义项列表中的首个核心释义，用以剥离冗余修饰，保证匹配的绝对精度 。
释义（Wiki）视图： 适配模糊反向查询需求，对长篇百科描述进行编码，专门应对用户输入的复杂长句和场景化描述 。
混合检索与综合打分机制
当用户输入长句描述时，系统执行智能混合检索逻辑：
动态词典与过滤： 引擎在启动时根据标签数据动态构建
jieba分词词典，同时使用包含约 90 个高频词的停用词表进行噪音清洗 。多粒度并发查询： 将拆分后的词语与未切割的原始长句同时并行输入模型进行 Encode，兼顾局部概念捕获与全局语义贴合 。
热度非线性加权打分： 检索结果命中后，系统会将语义相似度得分（
semantic_score）与该标签在全网的对数归一化热度（pop_score）进行加权融合 。融合公式如下。其中，\(Score_{semantic}\)是向量余弦相似度。\(Score_{popularity}\)是归一化后的热度分数，即 (\(\dfrac{\ln(1+count)}{max\_log\_count}\))。\(w\):是用户可调节的热度权重参数。对数处理（\(log1p\)）有效防止了绝对高频标签在排序中产生统治性偏差，使得低频高质量特征得以显现 。
\[ FinalScore = Score_{semantic} \times (1-w) + Score_{popularity} \times w \]
关联共现与推荐引擎
除了语义检索，系统还实现了一套强大的“相关特征挖掘”推荐引擎，核心在于清洗和利用标签的共现数据。
基于 PMI 的离线噪音过滤
原始的共现矩阵（约 316 万行关联数据）太大，如果直接读取整个共现矩阵，其耗时不可接受。而且其面临严重的高频数据干扰问题，极高频的基础通用标签会与几乎所有特征产生伪关联 。两个热门标签之间出现一万条共现，可能只是巧合。而两个低频标签之间出现一百条共现，可能却暗示着强相关性。系统在离线阶段使用点互信息（PMI）进行数学评估：
\[ PMI(a, b) = \log_2 \frac{cooc(a, b) \times N}{count(a) \times count(b)} \]
通过对比实际共现概率与随机独立共现期望，过滤掉无信息量的弱关联 。在完成点互信息评估后，共现矩阵呈现出一张无向稠密图,需要进行图稀疏化和网络结构优化。数据精简策略设定为 \(PMI \ge 5\) 且每个标签最多保留 50 个优质邻居。这样可以最大地保持整个共现图的连通性、不破坏其核心结构，且保证了节点的度分布均匀，使核心推荐词表体积从 96MB 大幅压缩至 10~15MB ，加载时间从20s压缩到5s。
多种子在线交叉惩罚推荐
用户选定多个标签（种子集合）后，触发多维聚合推荐算法：
特征叠加： 系统提取所有种子的优质邻居，若某标签被多个种子同时指向，其原始共现得分将被线性累加（强化交叉属性） 。
TF-IDF 思想平滑： 为彻底剥夺高频词的绝对优势，系统使用TF-IDF思想，对累加总分执行惩罚性归一化：
\[ \text{normalized\_score}(tag) = \frac{\text{raw\_score}(tag)}{\sqrt{\text{post\_count}(tag)}} \]
该机制确保了类似具有 100 次冷门共现特征的排名，能够通过分母缩放反超拥有 10000 次泛化共现的高频特征，实现精准的“细节提示词”补全 。
工程优化与系统架构简述
数据结构与性能控制
增量更新（\(O(\Delta)\) 复杂度）： 针对十万级别的词库，引擎摈弃了每次耗时极长（1~3分钟）的全量重建，而是采用智能差异对比机制 。对比更新前后的数据集，仅针对变动集执行重编码切片操作，实现热更新 。
降维与序列化： 四路检索向量使用 FP16 精度压缩存储为
.safetensors，搭配.parquet格式管理元数据，使内存开销减半，I/O 加载耗时从约 25 秒缩减至 1 秒内 。底层向量运算： 推荐模块的共现表构建舍弃了 Pandas 循环，全部重写为 NumPy 向量化操作（如
np.lexsort与np.unique），极大突破了大规模字典构建的性能瓶颈 。
前后端解耦与预热
前端 GUI 严格收敛于渲染逻辑与输入过滤 。为防止冷启动时阻塞心跳包导致
WebSocket 崩溃，系统在 @app.on_startup
阶段注入异步钩子触发引擎后台静默加载，并通过双向数据绑定向用户展示过渡状态，保障了稳定的工程可用性
。与此同时，系统提供API接口和CLI控制台命令版本。