第 3 篇 · 核心引擎:LangGraph 编排与多路召回重排
《从零造一个影片推荐智能体》系列 · 第 3 篇 / 共 10 篇 上篇收尾说「第 3–8 篇各自认领其中一层,不会回来重画这张图」。这篇先挑最上面那颗心脏开刀——它怎么听懂人话、怎么派活、怎么把一堆参差不齐的候选排成一份像样的片单。
前言
上一篇我们把地图摊开了,六层、agent/、快慢车道。有朋友看完问了个特别实在的问题:「架构我都懂,可你说半天 Agent,它到底干了啥?」
这个问题问得我挺高兴,因为它戳到了我最想聊的部分。
想象一下你瘫在沙发上打开对话框,敲了一句「推荐一部太空科幻片,要那种孤独感的」。回车下去,屏幕上先是跳一个「正在识别意图」的小步骤,接着是「正在检索影片」,然后答案一个字一个字往外蹦,最后给你三到五部片子,每部还附一段「为什么推它」。
这一整串动作从头到尾不到十秒。可中间发生的事,比「调了一下大模型」多得多——它得先弄明白你这句到底是「找片」还是「记偏好」还是「找某个导演的作品」,再决定派哪几路人马去查库,查回来几十条候选还得合并、去重、避重口味,最后才轮到写文案。
这篇文章要讲的,就是这十秒里发生的所有事。而串起这十秒的,正是本文的主角 -- 一条五个节点的流水线,外加四把「把混乱理顺」的梳子(融合、去重、多样性、心态.jpg)。
照例先说清楚:下面每一行代码、每一个数字我都是从当前仓库里现翻的,不是拍脑袋——你看到的就是代码真实的样子。
一条线五个工种:状态图到底长啥样
先把这五个节点贴出来,agent/graph.py 里就这点东西:
parse_intent → plan → execute → reflect → generate
build_agent() 里是这么接的:
g.add_edge(START, "parse_intent")
g.add_edge("parse_intent", "plan")
g.add_edge("plan", "execute")
g.add_edge("execute", "reflect")
g.add_edge("reflect", "generate")
g.add_edge("generate", END)
return g.compile()
看到这儿你可能会「咦」一声——一篇说「带条件路由、还挂了 MemorySaver」的文章,怎么图上是一条直线?别急,这个我自己打自己脸的事我放到「疑点」里专门交代,先往下看。
我喜欢把这五个节点想成一个小车间里的五个工种接力:
- parse_intent(接单员):把「推荐一部太空科幻片,要那种孤独感的」这句人话,榨成结构化槽位
{intent, query, genres, country, min_year};- plan(排产员):看接单员给的意图,决定今天派哪几路人出去干活,产出一张工单
plan = ["search_by_text"];- execute(干活的人):按工单跑召回,拿到几十条候选,再合并去重、排好序;
- reflect(质检老师傅):清点一下「货够不够」,不够就去库房再拉一趟;
- generate(文案):最后把结果写成一段人能读的话。
上图(照
agent/graph.py画的):五个工种一条直线接力,没有条件路由、没有 checkpointer;只有首尾两个节点触 LLM,中间三段全是确定性逻辑。
整套流水线的状态就是 AgentState(一个 TypedDict),每个节点只往回灌自己关心的那几个字段。里面有俩字段挺巧,值得单拎出来说,因为它们是后面 SSE 流式时间轴的原料:
steps: Annotated[list, operator.add] # 各节点步骤,reducer 自动累加
thinking: Annotated[dict, _merge_thinking] # LLM 深度思考,跨节点深合并 {route, generate}
通俗的理解:steps 是「车间门口那块看板」——谁做完了就在上面划一笔;operator.add 这个 reducer 的意思是每个节点只管往 steps 里 append 自己那一笔,LangGraph 自动帮你拼起来,节点之间不用互相认识。
每一步长这样(_new_step):
{"order": 1, "node": "parse_intent", "kind": "llm",
"summary": "意图识别:recommend", "detail": {...},
"elapsed_ms": 412, "thinking": "..."}
elapsed_ms 是真实耗时,detail 里塞的是这一节点的关键结构化信息。第 6 篇讲 SSE、第 7 篇讲前端时间轴的时候,消费的就是这份 steps——这话我在第 2 篇说过一遍,这里再说一次是因为它真的贯穿三层。
(事件实时推出去靠 _step_sink / _token_sink / _thinking_sink 三个钩子,只有 /recommend/stream 会注入;非流式接口它们是 None,节点读到就跳过。这仨咱们第 6 篇见,这里先欠着。)
意图识别:把人话榨成 slots
接单员是整个链路里第一个碰 LLM 的人,但只用一个轻量模型(chat_light(),第 4 篇细讲为啥要分强弱)。
流程就三步:拿 INTENT_PROMPT 问模型 → 用正则抠出第一个 {...} JSON → 抠不出来或者压根调挂了,走 _heuristic() 纯规则兜底。
系统里一共六种意图:recommend(找片)、similar(找类似的)、board(高分榜)、explain(解说某部)、preference(记偏好)、by_person(找某人的作品)。
解析器出来以后还有三重兜底矫正,这一段是我改得最多的地方,每个分支背后都是一次翻车:
# 1) 白名单:模型吐出词表里没有的意图一律按 recommend 处理
if intent not in ("recommend", "similar", "board", "explain", "preference", "by_person"):
intent = "recommend"
# 2) 人名兜底:模型把「诺兰的电影」误判成 recommend 时矫正回来
if intent == "recommend" and _looks_like_person_query(query):
intent = "by_person"
# 3) 关键词兜底:命中「记一下/记住/我喜欢/我的偏好」一律归 preference
if intent not in ("preference", "by_person") and (...):
intent = "preference"
那个 _looks_like_person_query() 长得很有生活气息,是一排实打实的中文正则:
bool(re.search(r"(导演|演过|演的|执导|拍[过的]?|的作品|拍的电影|导的|编剧)", query)) or \
bool(re.search(r"[\u4e00-\u9fa5]{2,4}(的电影|的作品|演的|拍的|导的)", query))
为啥非要这串兜底?因为在小模型上,「意图分类」是个性价比极低的活——它今天给你分对,明天飘一下就错了,而一旦分错,后面整条链路全是错的。我把能规则覆盖的部分全用规则锁死,只把「理解这句人话到底啥意思」留给模型。
顺带交代一句「我记得最清楚的一个教训」。以前在这里用正则从用户原话里切 2–3 字汉语片段当「偏好类型」,结果「我喜欢周星驰的电影」被切成 ["我喜欢", "周星驰", "的电"] 落进偏好库。你猜后果是啥?这哥们此后每次内容召回都带着这三个垃圾类型去过滤,召回几乎必空,推荐质量静默劣化,而且这些数据删都删不掉(当时的补救全靠人肉清库)。现在所有写入路径都得过一道词表闸门(retrieval/candidates.py 的 normalize_genres),不在 34 个标准类型里的条目一律丢弃。这段后来在第 8 篇讲护栏时还会再见面。
规划:先派工单,再开工
有了意图,_plan 就开工了。这里要说清楚一件事,因为它跟很多人对「Agent」的想象不一样:
本项目的规划是规则式的,不是让 LLM 自己挑工具。
get_tools() 里躺着八个 @tool 装饰的 LangChain 工具,但它的文档字符串自己写得明明白白:「当前生产链路是规则式规划器,没有 tool-calling 循环消费本函数」——它面向的是未来切到 LLM 自主选路的场景,现在只有测试在用。
为什么不让它自己选?第 2 篇我撂过一句:「本地小模型做工具调用会抖,今天选 A 明天选 B」。规划这件事一旦抖起来,结果不可复现,排查地时候你会想撞墙。所以我写死了一张映射表:
| 意图 | 派出去的路(plan) |
|---|---|
recommend / explain | search_by_text(MCP_ENABLED=true 时追加 search_prod) |
similar | search_similar(展开为 content / relation / graph 三路) |
board | high_quality_board |
by_person | search_by_person |
preference | [](不召回,直接进 Generate 写记忆) |
similar 这条最绕也最有意思:它得先 _resolve_item_id() 把片名定位到 douban:{PK} 这种 id,定位成功才走三路,定位失败就退化成普通文本召回。注意这里——它是唯一一条「一个意图跑多路召回」的路径,后面讲 RRF 的时候你就知道为什么这事重要了。
还有个藏在注释里的坑:_plan 里写 slots["name"] = slots.get("name") or slots.get("query") or state.get("query", ""),后面专门注释「必须取 state 内的 query——本作用域无局部 query 变量」。这是个真实的低级错误留下的疤:早期版本这里手滑写了局部 query,人名全空,by_person 这整条链路静默失效。所以我现在写这种兜底语句,宁可啰嗦三遍。
召回:六条路,各管一段
到 _execute 干活了。它先把最终要几条(top_k)和召回要几条(recall_k)分开:
top_k = int(state.get("top_k") or 20)
# 召回池不小于 20:融合/MMR/精排都需要足够候选才有挑选空间(与最终条数解耦)
recall_k = max(20, top_k)
这行看着平淡,它修的是一个真实 bug:以前 rerank 里硬编码 top_k=20,接口收到 top_k=50 会被静默截断成 20 条——用户明明要 50,你给 20,还一声不吭。现在召回池永远不小于 20,融合、MMR、精排都有挑选空间。
六条召回路(RUNNERS 字典)各自地盘如下,最关键的其实是最后一列「分数怎么算」,因为它是下一篇(融合)矛盾的源头:
| 路 | 干啥的 | 分数(score)怎么来的 | 量级 |
|---|---|---|---|
search_by_text | 自然语言描述找片(主力) | 向量相似度 1 - dist | ≈ [0, 1] |
search_similar | 找相似影片(展开三路) | 见下 | 混合 |
search_by_person | 找某导演/演员的作品 | 0.6 + 0.4 × rating/10 | ≈ [0.6, 1.0] |
search_prod | 生产库补充通道(默认关) | 远端返回,双源各查一轮 | 不定 |
high_quality_board | 高分榜兜底 | rating × log10(1 + rating_count) | 大数(评分×人数) |
search_graph | 图谱多跳扩展 | 路径强度 × 质量偏置 | 中等 |
search_similar 展开出的三路里,relation 路是用 SQL 直接把「同剧组」权重累加出来的:
SUM(CASE n.credits_type WHEN 'director' THEN 2.5 WHEN 'writer' THEN 1.5 ELSE 1.0 END) AS shared
注意这个数是无上界的——一部片跟.seed 片共享三个导演两编剧四卡司,shared 能累加到两位数。而 content 路是余弦相似度,永远在 [0,1] 里打转。
看到这儿,敏感的同学应该已经闻到火药味了:一个 [0,1] 的小数、一个能跑到几十的大数、还有一个几十分的质量乘积,怎么放一起相加? 这事儿留给下一节。
再说两个细节,都是「看起来不重要、线上能救命」的那种:
- 单路召回降级(
_safe_recall):任一路抛异常就降级成空列表、打一条 warning 日志,然后其他人照跑。以前只有 person / prod 两路有这层保护,similar的三路和主路by_text都是裸调——向量库抖一下,整个请求 500。现在降级后由reflect补候选,主链路不中断。by_person不依赖图谱开关:它走KnowledgeGraphStore.person_filmography(),只用最底层的 fetcher,即便GRAPH_ENABLED=false图谱遍历整体关掉,该路径也能返回人物作品集。
融合:别再拿分数硬加了
回来主题,上面埋的那个量级问题,就是本节的存在理由。
最早的实现叫 fuse()(ranker/scorer.py),做法是先把每路的分数 min-max 归一化到 [0,1],再乘权重相加。听起来很合理,实际有三个致命脆点:
- 一路里只要出一个离群值,整路的动态范围就被压缩 —— 一帮认真打分的人被一个 outlier 拖累;
- 单路只有一条候选时(分母为 0),代码只能返回 0.5 这个「随缘值」;
- 最要命的:所有分数被拉到同一个 [0,1] 区间后,「相似度 0.9」和「shared 累计 12 分」到底谁更强,全靠权重的玄学。
于是就有了现在的主角二号 -- RRF(Reciprocal Rank Fusion,倒数排名融合)。它的脾气特别简单:不看你考了多少分,只看你在自己班里排第几。
rrf[wk] += w_src / (k + rank) # k 默认 60,rank 是该路内部的 1-based 名次
然后归一化、再叠加原有的质量分/偏好分/反馈分:
base = raw / max_rrf # 归一化到 [0,1]
d["score"] = base + quality + pref + feedback_term # 最终综合分
通俗的理解:几个评委各交一份自己排好的名次表,主席不看具体评分,只按「第 1 名折算多少票 / 第 5 名折算多少票」加权汇总。你考 2 分没关系,你在三张表上都排前三,你就该靠前。这样一来,量级、离群值、分布在体现什么都没意义了——因为它压根不看分数。
我这个项目里,RRF_K=60,各路权重现在是:
content:1.0, relation:0.8, coldstart:0.6, graph:0.7, person:0.9, prod:0.5
要不要拿证据说话?当然。内部离线评估(2026-09-14,本机真实数据,5 个查询平均)记了:
| 指标 | RRF | 原 score 融合 |
|---|---|---|
| NDCG@10 | 0.9969 | 0.8904 |
| NDCG@20 | 0.9958 | 0.9312 |
| MRR | 0.60 | 0.23 |
MRR 那个 0.23 → 0.60 的差距最说明问题:MRR 看的是「第一个真正相关的结果排在几位」,它涨了近两倍,意味着最该被看见的那部片,确实被顶到第一屏了。
还有个我特别喜欢的鲁棒性探针:往某一路注入一部「无关高分」的离群片,结果 ——
多路印证的种子片:RRF 中
#1 → #1,稳如老狗; 那部无关的离群片:在 RRF 里被压到#8,在原来 min-max 那套里被抬到了#2。
这不就是「噪点多的时候,看名次比看分数靠谱」嘛。一句话总结:RRF 不是万能的,但在「多路召回来源各异、分数不可比」这个特定场景下,它比 min-max 硬归一化稳太多了。
顺手修的一个小 FAA:fuse 和 rrf_fuse 都得先把「规划名」翻译成「规范来源名」,靠的是 _PLAN_TO_CANON 这张表(search_by_text → content、high_quality_board → coldstart)。以前只有 rrf_fuse 翻译了,fuse 拿规划名直接查权重表——查不着,全部落 1.0。也就是说「向后兼容回退」的那条路上,所有权重配置都被静默丢了。 这种坑,看代码三个字都看不出毛病,只有真去看一次才能真正长记性。
最后是 sort_by_score,一行醍醐灌顶的代码:
return sorted(cands, key=lambda c: (-float(c.score), str(c.id)))
加了 str(c.id) 这个次级排序键。以前只用 -score,同分时顺序取决于 Python 字典遍历序 —— 换个会话、换批数据,同分影片的先后就会飘。用户感知是「怎么每次排序不一样」,我们这边则是缓存和对比测试没法复现。加个稳定的 tie-break,比调半天模型有用多了。
重排:别让货架上全是红烧肉
候选融合完了,现在是一堆排好序的片子。可这里有个典型问题:分数最高的十条里,可能有七条都是「科幻」,你还都推给用户,用户就觉得你这系统「脑子一根筋」。
于是二级 pipeline 的第二道:MMR(最大边际相关性)多样性重排。目标函数就一行:
mmr = (1 - lambda_div) * cands[i].score - lambda_div * sim
前半截是你自己牛不牛,后半截是你跟已选重的部分有多像。MMR_LAMBDA = 0.3,意思是「相关性还是老大,但相似度要扣 30% 的分」。
这里的关键是那个 sim —— 也就是「两部片有多像」这件事怎么算。最早只用了类型的 Jaccard 距离,后来我把它升级成了类型 / 年代 / 地区三维加权:
_DIV_WEIGHTS = {"genre": 0.6, "year": 0.2, "country": 0.2}
# 年代相似度:差 30 年归零,差 0 年为满分
s += _DIV_WEIGHTS["year"] * max(0.0, 1.0 - abs(ya - yb) / 30.0)
这样就能把「同类型但同十年同产地」的一批片给推开。还有个细节我很欣赏:缺信息维度不惩罚(缺字段返回 0,不假设不同),避免元数据稀疏的源被无谓推远 —— 拿不到信息不等于有差异,别乱给人加戏。
MMR 之后才是可选精排。这里有个非常妙的协同设计(_with_position_prior):
MMR 好不容易把多样性编进了名次,结果精排一上来纯按相关性重排,多样性全白干。所以给融合分叠一个随名次指数衰减的小先验:
_POSITION_PRIOR_W = 0.1
def _position_prior(pos, total): # 第 1 名 1.0,最后一名 0.5
return 0.5 ** ((pos - 1) / (total - 1))
权重只有 0.1,手段是「微调不重排」:相关性差距大于先验差时按相关性排(尊重精排),两者接近时保持 MMR 的次序(尊重多样性)。这也是那种「不写下来第二年就看不懂当时为啥要这 0.1」的代码。
精排本身有两套实现,靠 RERANK_PROVIDER 切(默认现在是 cloud):
local:本地 LIGHT 模型逐条打 0–1 相关性分,最终0.7 × 融合分 + 0.3 × LLM 分;8 路线程池并发打分(以前是串行 30 次调用,慢到怀疑人生),单条失败回退该候选融合分,绝不拖垮整批;cloud:阿里百炼qwen3.7-text-rerank专用重排序模型。云端失败自动回退 local —— 这条降级链保证请求不中断。
默认 RERANK_LLM_TOPN = 0,也就是精排默认关着。不是跑不起,是开发期没必要烧这个钱,而且按顺序 annotation 的广告位永远排给融合了 MMR 的那版就够了。等你真上线想再抠一点精度,把它打开即可,业务代码一行不用改(嗯,这就是第 2 篇那三个开关的又一次兑现)。
跨源对齐:一部片子,两本户口
这片 Apart 有点意思。同一部电影,在豆瓣和 IMDb 各有一条记录。 中文名《星际穿越》在这儿,英文名 Interstellar 在那儿,评分两边也不一样。
那召回的时候怎么办?内容召回可能捞到中文那条,图谱召回可能捞到英文那条 —— 融合完一看,列表里出现两部《星际穿越》,用户当场就懵了。
解决办法是给每部片子生成一把跨源归并键(work_key),优先级非常明确:
def work_key(c):
if c.imdb_id: return f"imdb:{c.imdb_id}" # ① 双源唯一键,最优先
if c.douban_id: return f"douban:{c.douban_id}" # ② 次之
return c.id # ③ 都没有才回退自身 id
只要两条记录都带着 imdb_id,就合并成一个 work。合并不是简单地丢掉一条,而是 merge_candidate() 做三件事:
- 把两边的跨源外链 id 都补齐(
douban_id+imdb_id双双齐全),前端就能同时跳豆瓣和 IMDb;- 异名保留:把另一侧的不同标题记进
title_alt,中文 UI 显示中文名,英文名也不丢;- 展示字段择优:由
_richer()决定 id/标题/评分用谁的 —— 优先级是「双源外链齐全 > 评分样本量大 > 中文源优先 > 标题更长」。
通俗的理解:这俩不是两份档案,是同一部片在两个国家各上了一次户口;我们要做的是合并户口,把两边的信息都并到一张身份证上,而不是毙掉其中一张。
上图:
work_key把同片两条记录归并成一张身份证,再由merge_candidate()补齐外链、保留异名、择优展示。
这条路我踩过一个很疼的坑:早期 relation / person 路召回出来的豆瓣候选没有带上 imdb_id,于是它跟 content 路捞到的同一带 merged,work_key 落到了第 3 档(回退自身 id),结果列表里出现两部《xxx》,而且曝光/反馈还按两个 id 双计 —— 用户看到重复条目,我们还以为是推荐有问题。 现在 relation_recall 和 graph 的 movie_meta 都强制把 imdb_id 带上,注释就写在那一行的正上方,谁删谁负责。
图谱:用「人脉」找电影
最后说说我最喜欢的一路:知识图谱多跳召回(graph/)。
内容召回回答的是「像不像」,关系召回回答的是「是不是同剧组」,而图谱召回回答的是 —— 「跟这部片隔着几个人的那部,是什么?」
它的核心是 KnowledgeGraphStore.traverse(),一个带跳数衰减的非负权重最短路(类 Dijkstra):
cand = dist[u] + rel.weight / hop # hop 越深,贡献越低
if cand > dist.get(v, -1e9):
dist[v] = cand
parent[v] = (u, rel) # 记 parent,用于回溯路径
边的权重(graph/schema.py 的 REL_WEIGHT)很有讲究:
directed_by: 2.5 # 导演,最强
written_by: 1.5 # 编剧次之
acted_by: 1.0 # 卡司最弱
has_genre: 0.8 # 同类型
from_country: 0.5 # 同地区
导演权重最高是符合直觉的 —— 同一个导演的作品,比同一个龙套演过的作品可预期得多。
算完 dist 还要乘一个质量偏置,让高分影片优先:
if quality_bias:
rb = 0.6 + 0.4 * min(max(m["rating"], 0), 10) / 10.0
score *= rb # 满分片 ×1.0,0 分片 ×0.6,不至于沉底但也不会往上窜
然后是这整段活最有意思的部分:路径回溯(_build_paths)。因为刚才存了 parent,沿着链条往回走就能拼出一句话:
《星际穿越》 → 导演 诺兰 → 《盗梦空间》 → 主演 玛丽昂·歌迪亚 → 《玫瑰人生》
上图(照
graph/traverse()画的):从种子片出发,沿关系权重多跳扩散,再沿parent回溯出一条白盒解释路径。
这条链路直接存进 Candidate 的 graph_paths 字段,意味着每一部从图谱路捞出来的片子,都能自己解释「我为什么会出现在这儿」。这东西对用户体验的提升是巨大的 —— 不是黑盒的「猜你喜欢」,而是白盒的「因为它同导演,所以推荐它」。
工程上也有两个值得一提的改动:
- 类型扩展改走维度表 JOIN:以前查「某个类型有哪些片」用的是
genres LIKE '%动画%'—— 全表扫描不说,还会把「动画电影」给误匹配进来。现在改走{src}_genre_relate+{src}_genre的等值 JOIN,成本恒定;维度表万一缺失,自动回退旧的 LIKE 路径,图谱不塌。- 邻接缓存 FIFO 淘汰:每个实体的出边按需查一次就缓存起来。以前容量满了是整体
.clear(),导致缓存突然全失效、引发一轮打库抖动;现在是 OrderedDict 按入库序逐出最早的那一项,名副其实的 FIFO。
至于「生产上换成 Neo4j」—— 遍历逻辑只依赖 GraphFetcher 接口(relations_from / movie_meta / person_label / search_person),现在的实现是 MysqlGraphFetcher,真要上 Neo4j 就换一个 fetcher,算法一行不动。这也是第 2 篇说的「面向接口编程」的又一次兑现。
疑点
这篇文章写到这里,我自己回头看都有几个地方想追问。老规矩,替你也问出来。
问:第 2 篇你说「带条件路由」「挂了 MemorySaver」,怎么这篇的图上是一条直线,连 checkpointer 都没有?说话不算话啊。
答:……这是得我自己认的一处。第 2 篇那个说法是照着早期方案文档写的,没对着代码核。 今天贴出来的 build_agent() 就是全部事实:add_edge 一条直线,g.compile() 裸编译,没有 checkpointer。两件事分别怎么说:①「条件」其实在节点内部实现 —— _reflect 里 if len(ranked) >= 5: return {}(够了就什么都不做,直接往下走),_plan 给 preference 产出空气 plan 跳过召回,效果上等价于分支,但边的关系本身是全线性的;② checkpointer 的确没接 —— 不是忘了,是压根用不上:会话历史和偏好各自落在 MySQL 的业务表里(第 5 篇讲),LangGraph 这张图只在单次请求内活着,没必要再套一层持久化。这是第 2 篇初版「文档 / 架构图与代码口径不一致」那毛病的又一次发作。本篇按代码补齐,第 2 篇那句也已经在上一轮照 agent/graph.py 的真实代码订正对齐了 —— 现在三处口径(第 2 篇 / 这篇 / 代码)一致,你无论从哪篇看都不会被带偏。
问:既然后面有 RRF 融合,similar 那条路为什么还要单独套一层内层融合?直接交上去不就行了?
答:问到点子上了,以前就是这么干的,而且是个 bug。_run_search_similar 老版本会先在内部做一层 score 预融合,再把整包当一路返回给外层 RRF。后果有两个:relation 0.8 / graph 0.7 的权重只在内层有效,外层拿到整包时 _PLAN_TO_CANON 把它映射成 content(1.0) —— 配的权重等于没有;而且 min-max 的量级脆弱性在这条路上原地复活。现在改成直接返回三路原始列表,由外层统一融合。一句话:权重只认一层入口,别搞两套。
问:既然 MMR 已经保证了多样性,还要 LLM 精排干嘛?精排不会把多样性又抹掉吗?
答:会,所以才有 _with_position_prior 那个 0.1 的位置先验。精排说到底是「给前 llm_topn 名做微调」,不是「推翻 MMR 重来」;先验只解 collisions,赢不了真正的差距。另外这事儿的默认答案是:精排现在默认关着(RERANK_LLM_TOPN=0)——开发期这个钱没必要烧,等真要抠那几个百分点再打开。能用规则解决的事,就别急着上模型。
问:preference 这种「纯记偏好」的意图,为啥也要走一遍完整的五节点?看着有点浪费。
答:这条是我至今没修的一个 inefficiency,实话说。 preference 意图在 _plan 里产出空 plan,_execute 自然召回空,ranked 是空列表;然后进 _reflect,它不看意图、只看 len(ranked) >= 5 —— 空的,于是判定「候选不足」,再去跑一遍 high_quality_board 冷启动兜底补 20 条,Winners 重排一遍;最后到 _generate,走 preference 分支直接写记忆返回,这 20 条榜单一份都没用上。一整趟 SQL 加一轮重排,白跑了。修起来倒不难(_reflect 里加一句 if intent == "preference": return {}),属于「知道在那儿、但优先级没排上」的那类欠账 —— 跟下面 One More Thing 是同一类处境。
One More Thing:闭环还差最后一公里
整套排序到这里看着挺圆满,但还差一件事 —— 以上都是「系统的判断」,还没有「用户的反馈」。
具体说:_quality_pref() 里的偏好分,读的是 user_preferences 里用户自己说过的话(「我喜欢科幻」)—— 这叫自述偏好;而用户看了推荐之后点没点、踩没踩、是不是早就看过腻了 —— 这些行为偏好一个都没进来。
所以我在反馈调权闭环的设计里规划了一条闭环:曝光埋点 → /feedback 收集赞踩点击 → 聚合成带时间衰减的用户画像 → 回灌 rerank。
这条路现在走到哪儿了?一半。埋点、get_feedback_profile、_feedback_term 都已经实现并且默认开着(FEEDBACK_REWEIGHT_ENABLED=true,半衰期 30 天)。量化口径是这样的:
if aid in black: return float(black[aid]) # 踩过:直接返回,沉底,不给后续加分机会
t += float(boost.get(aid, 0.0)) # 赞过/点过:加分
# 类型亲和度:叠加后必须封顶 ±0.3
t += max(-_GENRE_AFFINITY_MAX, min(_GENRE_AFFINITY_MAX, raw))
那个封顶也是血泪:以前没上限,一部片命中五个高亲和类型时这一项能累计到 1.5,足以把质量分和融合信号全压下去 —— 反馈信号不该有资格盖过用户自己说的话。现在正负对称封顶 0.3,跟自述偏好的封顶口径一致。
但要诚实地说:方案里的「探索护栏」(最后保留 ≥1 个冷启动槽位,防止越推越窄的过滤气泡),我翻了一遍 rerank.py,没找到 —— 这块确实还没实现。 有兴趣的同学可以把它当成练手的小作业,改动量很小:在 top_k 收口前,强制留一个槽位给 recall_source == "coldstart" 的候选。
So,这个闭环现在是「半合上」的状态:采集有、聚合有、回灌有,防气泡的护栏没有——具体补没补上,留到第 9 篇审计时再清点。
小结
这篇信息量偏大,收个尾方便你回忆:
整条链是五个节点接力(意图 → 规划 → 执行 → 反思 → 生成),中间只有两头用了 LLM,靠确定性逻辑稳住了基本盘;召回是六条路并行,每条路各管一段、各自独立降级;融合用 RRF 按名次投票代替按分数相加,换来了 NDCG@10 0.8904 → 0.9969、MRR 0.23 → 0.60;MMR + 位置先验保证了结果不重口味;work_key 把跨源重复抹掉、_richer 挑出更好的那条展示;图谱那一路用多跳 BFS + 关系权重 + 路径回溯,让每个推荐结果自带解释。
而贯穿这一切的一条暗线其实是:能用确定性逻辑解决的,就别交给模型;非交给模型不可的,也得给它在 outputs 上加一层锁。 这话在第 4 篇讲 LLM 降级、第 8 篇讲护栏时还会再听到。
下一篇我们往下钻一层 —— 这次出场的不是某个节点,而是躲在所有节点背后、谁都要喊一嗓子的那个东西:模型怎么调度、挂了怎么降级、怎么兜底到本地。也就是第 2 篇里只亮了个名字、一直没展开的「强弱分档」。
这一篇就到这。如果多路召回那套让你有点启发,点个赞、收个藏,原创不易,谢了。 编排和召回的代码我都开源了,fuse/RRF 那段注释比文章还啰嗦,踩过的坑全留着当路标——想翻源码照着改的,来这儿:MovieAgent。像 similar 这种「一个意图跑三路召回」的玩法,你项目里有没有类似场景?还是你更信奉「一路召回 + 一个强力重排模型」一把梭?评论区聊聊你的路数。