Skip to content

BiliTube(五):关键词、权重、提示词怎么拆成外置配方 ​

决定开源这个项目时,卡在一个很实际的问题上:代码可以给,榜单的标准不能给。

真实的 20 个关键词、标题党词表、五项互动权重、时长分桶、以及那段决定「什么算水」的 prompt,是这套东西真正值钱的部分。公开它,等于公开一套可以被反向优化的规则:谁想让自己的视频上榜,照着词表和权重反推就行。

但只给一个「去掉配方」的版本也不行。两份代码必然漂移,今天改个 bug,明天就忘了同步另一份。

ADR-018 的解法是:把标准外置成一个目录,代码只认目录结构,不认内容。

一、先看拆分前有多乱 ​

v0.1.0 里,「按什么标准跑」散在三处:

  • config/ 里放关键词和部分规则;
  • scoring.py 里焊着权重 WEIGHTS、分桶 BUCKETS、小样本阈值 MIN_GROUP_SIZE;
  • llm.py 里焊着完整的 SYSTEM_PROMPT。

结果是:改一个权重,要改 Python、跑测试、重新发版;想公开引擎,就得手工做一个「公开版」;两版之间的差异没人能说清。

更麻烦的是,权重和 prompt 是产品决策,不是工程实现。它们应该像文案一样被版本化、被 review、被回滚,而不是藏在代码常量里。

二、一个配方就是一个目录 ​

现在的结构是固定的五个文件:

text
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:

python
@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: str

bilitube/preset.py#L28-L40

frozen=True 是有意的:配方加载后不应该被运行时修改。要改,改文件、重新加载。

三、加载时校验什么 ​

配方是人工维护的,一定会写错。错得越早发现越好,最好在跑采集之前就报出来。

load_preset() 做了五类检查:

python
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 为空")

bilitube/preset.py#L91-L103

五类检查分别是:

  1. 五个文件都存在,JSON 能解析;
  2. keywords.txt 去掉空行和注释后不能为空;
  3. prompt.md 不能是空文件;
  4. 权重不能为空,且之和必须是 1.0(容差 0.01);
  5. 时长分桶不能为空。

第二条容易被忽略:一个只有注释的 keywords.txt,跑起来会「成功采集 0 条」,然后导出空榜单。与其让它安静地跑完,不如在加载时直接报错。

第四条也救过一次:手工调权重时把 0.20 写成了 0.02,五项加起来是 0.52。如果不校验,机器分会整体缩水,但排序看起来「还正常」,很难发现。

四、引擎默认值:保留,但只做占位 ​

配方化不等于「没配方就不能跑」。代码里保留了一组默认值,只在未传 --preset 时生效:

python
# 以下是引擎默认值: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,
}

bilitube/scoring.py#L24-L38

等权是故意选的占位值,不是真实配方。它的作用是让测试、示例和最小演示能跑起来,同时明确告诉读代码的人:这不是线上标准。

系统提示词也一样。代码里只保留输出契约(字段、类型、长度),不写判定标准:

python
# 引擎默认提示词:只保留「输出契约」,不含任何领域判定标准。
# 真正的判定标准放在 presets/<name>/prompt.md,由 preset 传进来。
SYSTEM_PROMPT = """你是内容策展编辑,负责判断一条视频是否值得观看。
只输出一个 JSON 对象……
"""

bilitube/llm.py#L32-L47

这条边界很重要:格式属于引擎,标准属于配方。 格式错了是 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 页、没有后端的静态站。

本文阅读--次|全站访问--次|访客--人