BiliTube(五):关键词、权重、提示词怎么拆成外置配方
决定开源这个项目时,卡在一个很实际的问题上:代码可以给,榜单的标准不能给。
真实的 20 个关键词、标题党词表、五项互动权重、时长分桶、以及那段决定「什么算水」的 prompt,是这套东西真正值钱的部分。公开它,等于公开一套可以被反向优化的规则:谁想让自己的视频上榜,照着词表和权重反推就行。
但只给一个「去掉配方」的版本也不行。两份代码必然漂移,今天改个 bug,明天就忘了同步另一份。
ADR-018 的解法是:把标准外置成一个目录,代码只认目录结构,不认内容。
一、先看拆分前有多乱
v0.1.0 里,「按什么标准跑」散在三处:
config/里放关键词和部分规则;scoring.py里焊着权重WEIGHTS、分桶BUCKETS、小样本阈值MIN_GROUP_SIZE;llm.py里焊着完整的SYSTEM_PROMPT。
结果是:改一个权重,要改 Python、跑测试、重新发版;想公开引擎,就得手工做一个「公开版」;两版之间的差异没人能说清。
更麻烦的是,权重和 prompt 是产品决策,不是工程实现。它们应该像文案一样被版本化、被 review、被回滚,而不是藏在代码常量里。
二、一个配方就是一个目录
现在的结构是固定的五个文件:
presets/<name>/
├── preset.json 元信息与文件索引:name / version / description
├── keywords.txt 采集关键词,一行一个,# 开头为注释
├── rules.json 过滤规则:词表、分区白名单、时长门槛、单 UP 配额
├── scoring.json 打分权重、时长分桶、小样本阈值
└── prompt.md 生成卡片的 system prompt仓库里公开的是 presets/example/,一个最小可用示例。线上的 ai-video 配方不在仓库里。
目录名就是配方名,preset.json 可以给文件起别名,但结构不能变。换一个领域——播客、论文、课程——复制一份目录,改这五个文件,Python 一行不用动。
加载逻辑集中在 preset.py:
@dataclass(frozen=True)
class Preset:
name: str
version: str
description: str
path: Path
keywords: tuple[str, ...]
rules: dict[str, Any]
rules_path: Path
weights: dict[str, float]
buckets: tuple[Bucket, ...]
min_group_size: int
prompt: strfrozen=True 是有意的:配方加载后不应该被运行时修改。要改,改文件、重新加载。
三、加载时校验什么
配方是人工维护的,一定会写错。错得越早发现越好,最好在跑采集之前就报出来。
load_preset() 做了五类检查:
weights = {str(k): float(v) for k, v in (scoring.get("weights") or {}).items()}
if not weights:
raise PresetError(f"{root}: scoring.weights 为空")
total = sum(weights.values())
if abs(total - 1.0) > 0.01:
raise PresetError(f"{root}: 权重之和应为 1.0,当前 {total:.3f}")
buckets = tuple(
(int(item[0]), None if item[1] is None else int(item[1]), str(item[2]))
for item in (scoring.get("buckets") or [])
)
if not buckets:
raise PresetError(f"{root}: scoring.buckets 为空")五类检查分别是:
- 五个文件都存在,JSON 能解析;
keywords.txt去掉空行和注释后不能为空;prompt.md不能是空文件;- 权重不能为空,且之和必须是 1.0(容差 0.01);
- 时长分桶不能为空。
第二条容易被忽略:一个只有注释的 keywords.txt,跑起来会「成功采集 0 条」,然后导出空榜单。与其让它安静地跑完,不如在加载时直接报错。
第四条也救过一次:手工调权重时把 0.20 写成了 0.02,五项加起来是 0.52。如果不校验,机器分会整体缩水,但排序看起来「还正常」,很难发现。
四、引擎默认值:保留,但只做占位
配方化不等于「没配方就不能跑」。代码里保留了一组默认值,只在未传 --preset 时生效:
# 以下是引擎默认值:preset 没提供时才用,权重故意取等权占位——
# 真实权重属于配方(presets/<name>/scoring.json),不随代码发布。
WEIGHTS = {
"fav_rate": 0.2,
"coin_rate": 0.2,
"like_rate": 0.2,
"talk_rate": 0.2,
"log_view": 0.2,
}等权是故意选的占位值,不是真实配方。它的作用是让测试、示例和最小演示能跑起来,同时明确告诉读代码的人:这不是线上标准。
系统提示词也一样。代码里只保留输出契约(字段、类型、长度),不写判定标准:
# 引擎默认提示词:只保留「输出契约」,不含任何领域判定标准。
# 真正的判定标准放在 presets/<name>/prompt.md,由 preset 传进来。
SYSTEM_PROMPT = """你是内容策展编辑,负责判断一条视频是否值得观看。
只输出一个 JSON 对象……
"""这条边界很重要:格式属于引擎,标准属于配方。 格式错了是 bug,标准变了是产品决策,两者的修改流程不该一样。
五、配方化之后,什么变了
| 动作 | 配方化之前 | 配方化之后 |
|---|---|---|
| 调权重 | 改 scoring.py,跑测试,发版 | 改 scoring.json,重跑 score |
| 换关键词 | 改 config/,可能还要改代码 | 改 keywords.txt |
| 调判定标准 | 改 SYSTEM_PROMPT | 改 prompt.md |
| 换领域 | 复制项目、改代码 | 复制 presets/example/,改五个文件 |
| 公开引擎 | 手工做公开分支 | 只发布代码,忽略配方目录 |
最后一行是这次改造的直接动机。仓库的 .gitignore 排除真实配方,公开的是示例;引擎和标准从此可以走两条发布线。
代价也有:
- 多了一层间接,读代码时要先看配方才能理解一次运行的行为;
prompt.md是纯文本,改它不触发类型检查,写错了只能靠运行时暴露;- 配方是人工维护的,校验只能覆盖结构,覆盖不了「这个权重合不合理」。
我觉得这个代价值得。它把「工程实现」和「产品判断」分开了,而这两件事本来就应该由不同的节奏来改。
六、实测与边界
| 项目 | 结果 |
|---|---|
| 配方文件数 | 5 个,结构固定 |
| 权重校验 | 和必须为 1.0,容差 0.01 |
| 关键词校验 | 去掉注释后不能为空 |
| prompt 校验 | 不能是空文件 |
| 公开配方 | 仅 presets/example/ |
| 线上配方 | 20 个关键词,不公开 |
踩坑:prompt.md 的改动不会进类型检查
scoring.json 写错类型会在加载时报错,prompt.md 不会。它是一段自由文本,少一个字段说明、多一句矛盾的指令,代码都看不出来。
实际发生过一次:prompt 里加了「优先考虑长视频」,但输出契约里没有对应字段,模型开始在 why 里解释时长,挤掉了真正的推荐理由。后来把「时长只作为背景,不作为主要判断依据」写回 prompt,才恢复稳定。
结论:配方也是代码,改完要跑一小批样本看输出,不能只靠「文件能加载」。
配方和配置文件有什么区别
配置文件通常是「一堆键值,代码决定怎么用」;配方是「一个完整的世界观,代码只负责执行」。
具体差别有三点:配方可以整目录替换,换一个领域不用改代码;配方有版本号和描述,能追溯「这一版榜单是用哪套标准跑的」;配方加载时会做语义校验,不只是语法校验。
所以它不叫 config.json,叫 preset。
七、小结
这一篇讲的是解耦:
- 引擎管流程:采集、过滤、分位、调用模型、导出;
- 配方管标准:关键词、规则、权重、分桶、prompt;
- 边界由目录结构固定,由加载校验保护;
- 默认值只做占位,不冒充线上标准。
标准拆出去之后,最后一公里是把结果交给人看。下一篇讲那个 1,774 页、没有后端的静态站。