AudioBookRequest源码解析:10级比较链背后的有声书源排序算法
AudioBookRequest源码解析:10级比较链背后的有声书源排序算法
AudioBookRequest 是一个轻量级有声书请求管理工具,用于为 Plex / Audiobookshelf / Jellyfin 搭建有声书愿望单并自动下载。它最有意思的设计,藏在 app/internal/ranking/ 目录下的有声书源排序算法:系统拿到 Prowlarr 返回的一堆候选资源后,会用一条"10级比较链"逐级打分,把最匹配、质量最好的源排到第一位。
项目简介:有声书界的 Overseer
AudioBookRequest 的定位类似电影界的 Overseer / Ombi,但专门服务于有声书:
- 通过 Audible 接口搜索并请求有声书,也支持手动添加任意书目
- 接入 Prowlarr,复用你已有的 Indexer 和下载客户端
- 自动下载、通知推送(Apprise / Gotify / Discord 等)、用户分组管理
搜索结果页面(上图中来自项目文档 README.md),每本书的卡片右上角小图标就标记了它的协议来源(torrent / usenet / 手动)。
排序流程总览:从搜索到排序只需三步
当用户点击某本书查看资源时,app/internal/query.py 中的 query_sources 会串联起整个流程:
query_prowlarr从 Prowlarr 拉取候选源(ProwlarrSource列表)- 对每个源调用 quality_extract.py 的
extract_qualities,并发地估算该源的码率和音频格式(asyncio.gather同时发起) - 调用 download_ranking.py 的
rank_sources,用 Python 标准库的cmp_to_key把自定义比较器交给sort,得到有序列表;若开启了自动下载,就直接取排名第一的源开始下载
也就是说,排序不是简单的"按热度",而是多维权重逐级仲裁——这正是下面要拆解的核心。
核心解析:10级比较链是如何工作的?
比较器数组:排序的"裁判团"
排序的全部规则集中在 CompareSource 类的一个数组里:
self.compare_order = [
self._compare_valid, # 1. 硬性有效性
self._compare_title, # 2. 书名相似度
self._compare_authors, # 3. 作者相似度
self._compare_narrators, # 4. 讲述人相似度
self._compare_format, # 5. 音频格式优先级
self._compare_flags, # 6. Indexer 标签加分
self._compare_indexer, # 7. Indexer 优先级
self._compare_subtitle, # 8. 副标题/卷名相似度
self._compare_seeders, # 9. 做种人数
self._compare_age, # 10. 资源新旧
]
每一级比较器的返回值遵循同一个约定:
- 能分出胜负 → 返回正数/负数,排序立即定下
- 打平 → 调用
self._get_next_compare(next_compare + 1),把裁决权移交给下一级 - 十级全部打平 → 落入 default_compare,返回 0(视为相等)
这种"逐级淘汰"设计让规则可预测:任何两个源,你都能精确说出是谁在哪一级赢的。
10级规则逐条拆解
| 级别 | 比较器 | 规则 | 优胜者 |
|---|---|---|---|
| 1 | _compare_valid | 码率是否落在用户设定区间内(默认 20~400 kbit/s);torrent 还要求做种数 ≥ Min Seeders(默认 2);且必须满足最低匹配:书名命中,或作者/讲述人至少一方命中 | 合法源 > 不合法源 |
| 2 | _compare_title | 用 rapidfuzz.partial_ratio 计算书名在资源标题中的模糊匹配度,超过阈值(默认 90)才算命中 |
命中的源 |
| 3 | _compare_authors | 作者名与资源标题、资源元数据双向模糊匹配(token_set_ratio,默认阈值 75),取匹配人数 |
匹配人数多 |
| 4 | _compare_narrators | 同作者,但针对讲述人(Narrator) | 匹配人数多 |
| 5 | _compare_format | 按用户自定义的格式顺序(默认 flac → m4b → mp3 → unknown-audio → unknown) | 格式优先级高 |
| 6 | _compare_flags | 资源携带的 Indexer 标签(如 internal、private)按用户配置的分数累加 |
标签分高 |
| 7 | _compare_indexer | 按用户在设置页拖拽出的 Indexer 顺序 | 排在前面的 Indexer |
| 8 | _compare_subtitle | 副标题(如 "Book 1"、卷名)的模糊匹配 | 命中的源 |
| 9 | _compare_seeders | usenet 直接跳过(无意义) | 做种人多 |
| 10 | _compare_age | 协议不同则跳过;torrent 越老越稳,usenet 越新越好 | 更"新鲜/更稳" |
两个值得注意的工程细节:
- 第 1 级是"守门员"。它不只是过滤码率,还调用了 _has_minimum_match:书名命中,或者至少一位作者/讲述人命中,否则该源直接判负。这避免了标题蹭名但内容不符的资源混进前列。
- **第 10 级的"方向反转"**很体现领域知识:torrent 做种人数会随时间衰减,所以老资源更可靠;而 usenet 条目有保留期,新资源才下得动。同一个"年龄"字段,协议不同结论相反。
质量提取:码率是怎么估算出来的?
排序依赖的 Quality(码率 + 格式)来自 extract_qualities。它并没有真的下载文件检查(源码中该功能因限流问题被关闭,见 quality_extract.py 的注释),而是走了一条轻量路线:
- 格式识别:扫描资源标题关键词 —— 含
mp3/flac/m4b对应判型,含audiobook则归为unknown-audio - 码率估算:
kbits = 8 × 文件大小 ÷ 书籍总秒数 ÷ 1000,用"体积 ÷ 时长"反推出平均码率 - 估算出的码率随后与 QualityProfile 中各格式的合法区间(
quality_flac、quality_m4b…)比对,区间外(比如 300 kbit/s 的"flac"大概率是假的)会在第 1 级被判为无效
这一招简单粗暴但非常有效:绝大多数假 flac、假 m4b 资源在估算码率后会现出原形。
用户侧配置:排序规则几乎全部可调
上面所有阈值和顺序都不是硬编码,而是存在数据库里(QualityProfile 以 StringConfigCache 形式缓存),并暴露给了设置页 Settings/Download/Sliders.jinja:
- Auto Download 开关 + 各格式码率区间滑块(flac / m4b / mp3 / unknown-audio / unknown)
- Min Seeders:做种数下限
- Title / Name Similarity Ratio:书名、人名模糊匹配阈值(默认 90 / 75)
- 另外的格式顺序(
quality_format_order)、Indexer 顺序(quality_indexer_order)和标签加分(quality_indexer_flags)在 Settings/Download/IndexerFlags.jinja 中配置
这解释了为什么同一台 Prowlarr 在 ABR 中的排序结果可以完全符合个人口味:10 级比较链里,第 5~7 级和大部分阈值全部来自用户配置。
总结
AudioBookRequest 的排序算法没有使用任何机器学习或复杂评分公式,而是用了一个非常"古典"但极其清晰的方案:
- 并发提取每个源的码率与格式特征(quality_extract.py)
- 用 cmp_to_key 把 10 个单一职责的比较器串成责任链
- 逐级比较、打平即下移,保证排序结果确定、可解释、可配置
对想学习排序/打分系统设计的读者,这条比较链(download_ranking.py)是一个很好的小样本:规则显式化、仲裁权顺序传递、每一级独立可测——复杂系统的"可预测性"往往就来自这种克制的设计。
