舞萌的曲库是个重灾区：
ハッピーシンセサイザ千本樱（原曲是 千本桜）senbonzakura、happy synthesizerqianbenying前几种用字符串技巧还能救。最后一种是字符串搜索天生无解的 —— 你没法穷举所有「玩家会怎么形容一首歌」。这才是我们引入 embedding 的真正动机：不是「向量检索很酷」，而是有一类查询字符串永远接不住。
命中 ~0.2ms
空
命中 ~30ms
空
命中 ~200ms+
空 / 失败
用户输入 query
① 字符串精确层
精确 / 前缀 / 子串 / 罗马音 / 拼音
返回结果
② 字符串模糊层
trigram + 编辑距离
③ 向量兜底层
embedding API + 余弦相似度
返回「没找到」
命中 ~0.2ms
空
命中 ~30ms
空
命中 ~200ms+
空 / 失败
用户输入 query
① 字符串精确层
精确 / 前缀 / 子串 / 罗马音 / 拼音
返回结果
② 字符串模糊层
trigram + 编辑距离
③ 向量兜底层
embedding API + 余弦相似度
返回「没找到」
关键决策是顺序，不是技术选型。
①② 覆盖了约 96% 的真实查询（拿生产环境 1394 首曲库验证过），③ 只服务「意译 / 语义描述」这类字符串救不回来的剩下 4%。
如果把向量层放前面，每次查询都要吃一次网络往返（embedding API 是远端服务），等于把 200ms 的成本摊到 100% 的查询上，只为解决 4% 的问题。
贵的层放最后，是检索系统设计的通用原则。
在碰向量之前，把便宜的招数打满。核心是一条归一化管线：
原串
NFKC
全角→半角
小写
丢装饰符号
简体→日文异体
压空白
归一化形
原串
NFKC
全角→半角
小写
丢装饰符号
简体→日文异体
压空白
归一化形
几个值得说的点：
1. 简体 → 日文异体字映射表。 樱→桜、泽→沢、铁→鉄……只收「形近但字不同」的映射。同形字（花→花）是噪声，不收。这张表只能手工维护，因为中日汉字对应没有简单算法，也不存在权威的自动化映射。
2. 假名 → 罗马音静态表。 舞萌曲库里出现过的假名只有 152 种，全在标准五十音范围内。一个 dict 就够了，不需要引入任何分词库或罗马音转换依赖。用户打 senbonzakura，我们把曲名里的假名转成罗马音去比。
3. 装饰符号全丢。 ★☆♪、全角括号、长音符 ー……这些在曲名里大量出现，但玩家永远不会输入。让它们参与匹配只会添乱。
归一化之后，① 层做精确 / 前缀 / 子串匹配，② 层用 trigram + 编辑距离兜住错别字。
曲名是短文本，且高度非自然语言（假名、符号、英文混排）。jieba 这类分词器对曲名的切分结果不稳定，反而会引入噪声；曲库规模也不值得上 SQLite FTS 之类的索引。归一化 + trigram 在这个量级已经够用。
成本控制的核心就这一句话：
scripts/build_music_vectors.py，把全部曲名批量交给 embedding API 算好，存进本地数据库。换模型或改文本时用 --rebuild-stale 增量重算。一次 embedding 调用（一句话、1024 维）按量计费基本可以忽略；如果你在本地跑模型（比如 bge-m3），成本是零，代价只是内存和启动时间。
存库里有个 text_blob 字段，是真正喂给 embedding 模型的文本。它不是简单塞曲名，而是把归一化形、罗马音、拼音全拼进去 —— 让向量天然带上跨书写系统的语义。
这样 happy synthesizer 和 ハッピーシンセサイザ 即使字符串层没命中，向量距离也会很近。
这也是给某首歌补别名的地方：发现某首歌搜不到，就往 text_blob 里加别名，重算那一条向量。
text_blob 是人写的，embedding / model_name 是机器写的。
手动去编辑 embedding 里的浮点数没有任何意义 —— 向量是模型学出来的语义坐标，不是可以手调的参数。要改语义，改文本，然后重算。
这是整个设计里最反直觉的部分：我们做了向量检索，但没有用任何向量数据库。
先算一笔账：
| 项 | 数值 |
|---|---|
| 曲库规模 | 1394 首 |
| 向量维度 | 1024 |
| 数据类型 | float32 |
| 总占用 | ≈ 5.7 MB |
| 暴力算余弦（Top-K） | ~1ms 量级 |
5.7MB 全部装进一个 numpy 矩阵，暴力算余弦相似度只要 1ms 量级 —— 比任何 ANN（近似最近邻）索引都快，而且是精确结果，零精度损失。
那引入 faiss 的成本呢？C++ 编译依赖（生产环境是 Python 3.14，wheel 覆盖不全）、安装体积、维护成本，而收益为零。就算曲库涨到 10 万首也才 400MB，暴力算仍是几毫秒。
真到百万级再换不迟。
「用向量检索」和「用向量数据库」是两回事。小数据集上，numpy 就是最好的向量数据库。
np.frombuffer 零拷贝解析，启动加载 1400 条只要几毫秒。向量检索配置 模型 bge-m3 就能改，不用重启。换模型名后需要跑一次重算（不同模型的向量空间不通用）。向量检索是锦上添花。 它的任何失败都不应该影响查歌这个主功能。
生产环境里，一个「可选增强」把自己失败成主流程故障，是最常见的翻车方式。
最后一层工程约束：检索的同步路径里包含 DB 读和 numpy 计算，不能直接跑在事件循环里，否则会卡住整个 bot。
1# search_sync 是同步实现，调用方必须用线程池包裹2result = await asyncio.to_thread(search_sync, query)3
4# search_async 是现成的异步入口，内部就是 to_thread(search_sync)5result = await search_async(query)6
7# embedding 客户端提供同步 embed_batch（批量、带二分重试），异步包装同样走线程池这延续了项目一贯的规矩：NoneBot 事件循环里禁止 PyMySQL、慢 SQLite、Pillow、numpy 大计算 —— 该进线程的进线程。
| 层 | 耗时 | 覆盖 |
|---|---|---|
| ① 字符串精确 / 前缀 / 子串 / 罗马音 / 拼音 | ~0.2ms | 绝大多数查询 |
| ② trigram + 编辑距离模糊 | ~30ms | 错别字、书写变体 |
| ③ 向量兜底（仅 ①② 都空时） | ~200ms+ | 意译、语义描述 |
总结：
text_blob 设计成「人可改」，别名补在那里，向量自然懂。这里会记录我的技术笔记、项目复盘和一些日常碎碎念。
]]>