AudioBookRequest源码解析:10级比较链背后的有声书源排序算法

原创2026-10-31 11:16:172,281 阅读

AudioBookRequest源码解析:10级比较链背后的有声书源排序算法

AudioBookRequest 是一个轻量级有声书请求管理工具,用于为 Plex / Audiobookshelf / Jellyfin 搭建有声书愿望单并自动下载。它最有意思的设计,藏在 app/internal/ranking/ 目录下的有声书源排序算法:系统拿到 Prowlarr 返回的一堆候选资源后,会用一条"10级比较链"逐级打分,把最匹配、质量最好的源排到第一位。

项目简介:有声书界的 Overseer

AudioBookRequest 的定位类似电影界的 Overseer / Ombi,但专门服务于有声书:

  • 通过 Audible 接口搜索并请求有声书,也支持手动添加任意书目
  • 接入 Prowlarr,复用你已有的 Indexer 和下载客户端
  • 自动下载、通知推送(Apprise / Gotify / Discord 等)、用户分组管理

AudioBookRequest 有声书源搜索页面

搜索结果页面(上图中来自项目文档 README.md),每本书的卡片右上角小图标就标记了它的协议来源(torrent / usenet / 手动)。

AudioBookRequest 项目横幅

排序流程总览:从搜索到排序只需三步

当用户点击某本书查看资源时,app/internal/query.py 中的 query_sources 会串联起整个流程:

  1. query_prowlarr 从 Prowlarr 拉取候选源(ProwlarrSource 列表)
  2. 对每个源调用 quality_extract.py 的 extract_qualities,并发地估算该源的码率和音频格式(asyncio.gather 同时发起)
  3. 调用 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 的排序算法没有使用任何机器学习或复杂评分公式,而是用了一个非常"古典"但极其清晰的方案:

  1. 并发提取每个源的码率与格式特征(quality_extract.py)
  2. 用 cmp_to_key 把 10 个单一职责的比较器串成责任链
  3. 逐级比较、打平即下移,保证排序结果确定、可解释、可配置

对想学习排序/打分系统设计的读者,这条比较链(download_ranking.py)是一个很好的小样本:规则显式化、仲裁权顺序传递、每一级独立可测——复杂系统的"可预测性"往往就来自这种克制的设计。

登录后查看全文
AudioBookRequest