x-algorithm：X「为你推荐」信息流的完整架构拆解

核心判断

这是目前公开可读的、最完整的一套生产级推荐信息流代码。它的价值不在某个单一算法，而在整条链路的工程切分：候选从哪来、分数怎么算、帖子能不能被看到、非内容位怎么插入——每一层都有独立的子系统、独立的规则和独立的代码目录。对做推荐系统或内容分发的工程师而言，这个仓库几乎是一份可审计的参考架构。

值得先给出它最容易读错的一点：这个仓库不是"排序算法 demo"，而是一个运行中的社交平台信息流的真实切片。2026 年 8 月的两次更新把可见性过滤（visibility filtering）、打分权重参数和 Phoenix 模型的训练代码都补齐了——你能看到生产默认值，也能看到巴西 2026 选举过滤这种合规性改动是如何以一个 Rust filter 的形式落进代码的。

截至本文写作时，仓库 32.6k stars，主语言 Rust，Apache 2.0 许可，2026 年 1 月创建、持续更新。

系统地图

For You 信息流每次请求经过两条相对独立的路径：决定"排什么、怎么排"的请求路径（Request Path），和持续运行、产出帖子和账号标签的标注路径（Labeling Path）。两条路径在最后的可见性过滤处汇合。

请求路径（每次刷新触发）
  1. Query Hydration     载入用户行为序列、关注列表、屏蔽/静音、已看记录
  2. Candidate Sources   并行查询三个候选源（站内 + 站外）
  3. Candidate Hydration 补全帖子文本、作者信息、互动计数
  4. Pre-Scoring Filters 去重、48 小时时效、屏蔽账号、已看已推……
  5. Scoring             PhoenixScorer 预测动作概率 → RankingScorer 加权求和 → VMRanker 重排
  6. Selection           TopKScoreSelector 按分数取前 K
  7. Post-Selection Filters  可见性过滤（读标注路径的标签）+ 会话收敛
  → Blending Pipeline    广告、Who to Follow、提示位与帖子混排

标注路径不在请求路径上，它持续运行：内容理解模型（grox、媒体模型、CLIP 嵌入）与账号评分模型（agatha、bdsm、user-cred-v2）产出分数，规则引擎（scarecrow 内嵌 botmaker）把分数变成标签写入存储；请求路径末端，可见性过滤服务读取这些标签，对每个"帖子 × 观看者"组合给出三选一的答复：ALLOW（正常展示）/ INTERSTITIAL（折叠在警告之后）/ DROP（不展示）。

两条路径的分野是整个系统最重要的边界：排序决定顺序，可见性决定能不能出现——不同服务、不同输入、不同规则。

关键机制拆解

候选源：一进两出

• Thunder（站内）：把关注账号的最新帖子保持在内存里，请求时直接返回。它还会接收"已看帖子清单"并在源头上排除。
• Phoenix retrieval（站外）：把观看者和帖子都表示为向量，返回离观看者最近的帖子。
• SimClusters（站外）：按"谁在跟什么互动"给账号和帖子聚类，用簇找候选。附带一条专门的成人内容过滤（作者被打成人标签且观看者未关注时剔除）。

站内站外候选汇入同一管道，由同一个模型统一打分。

打分：多动作预测，而不是单一相关性

Phoenix 模型对每个"帖子 × 观看者"对预测一大批动作的概率：互动类（点赞、回复、转发、引用、分享）、点击类（点帖子、点头像、点链接、展开图片）、注意力类（视频质量观看、停留时长、活跃秒数）、关注作者，以及负向动作（不感兴趣、静音作者、拉黑作者、举报、未停留）。

RankingScorer 把它们压成一个数：

Final Score = Σ (weight_i × P(action_i))

正动作正权重，负动作负权重，权重全部硬编码在 home-mixer/params/param.rs，算术在 home-mixer/scorers/ranking_scorer.rs。

README 专门用一段纠正一个普遍误读：权重乘的是预测概率，不是原始互动计数。看到举报的权重是点赞的 468 倍，不能得出"1 次举报抵消 468 个赞"——那 468 倍作用在你自己举报的概率上，而这个概率很大程度上由你自己的历史行为决定。8 月 14 日的更新甚至在代码里补了注释，专门防止人和 LLM 读错这一处。

加权求和之后还有三个修正：

最后 VMRanker 调用独立的 vm-ranker 服务，在帖子的嵌入向量上跑行列式点过程（DPP），牺牲一点总分换取相邻帖子的多样性。

过滤：十七道预过滤 + 三道后置

预过滤发生在打分之前，按顺序执行，条目读起来像一份产品需求清单：跨源去重、48 小时时效、观看者自己的帖子、已看/已推记录（两条独立记录兜底）、静音关键词、被拉黑账号、无权查看的订阅帖……其中 InventoryHoldoutFilter 按帖子-观看者对确定性抽样保留一小部分流量做实验对照，是实验体系的一环。

后置过滤发生在排序定局之后：VFFilter 按可见性服务的答复删帖；AncillaryVFFilter 连带删除父帖/被引帖/被转帖已被 DROP 的内容；DedupConversationFilter 收敛同一会话的多条分支。可见性规则有两个要点：第一条答 DROP 的规则即终止评估；另有一组规则只在"帖子来自观看者未关注账号的推荐位"时生效，且只能 DROP 不能放行——同一帖子对粉丝可见、对推荐受众不可见，垃圾内容的高召回拦截就是这么做的。

混排：模型不管的部分

排序完成后的帖子只是 Blending Pipeline 的一个输入源。BlenderSelector 把广告、Who to Follow、提示等非内容位与帖子交错插入；默认广告混排器还会为广告邻位重排帖子。这也是读代码时容易忽略的一点：你在信息流里看到的"非帖子"内容，模型完全不参与排序。

一个请求的完整旅程

以一次下拉刷新为例：home-mixer 先把观看者最近的互动序列、关注列表、屏蔽静音、已看记录装配进查询上下文；Thunder 返回关注账号的新帖，Phoenix retrieval 与 SimClusters 并行返回站外候选；补水后的候选过十七道预过滤，剩下的每条帖子交给 PhoenixScorer 预测全部动作概率，RankingScorer 加权求和、做三项修正，VMRanker 重排，TopK 取前 K；随后 VFFilter 逐条询问可见性服务——它读的正是标注路径里 scarecrow/agatha/bdsm 这些系统写下的标签——通过的帖子进入混排，与广告、推荐关注位交错后成为最终时间线。响应发出后还有副作用阶段：记录曝光、刷新缓存、上报广告事件。

开源边界与透明度设计

仓库刻意留了几个缺口：Grox 的 LLM 提示词、部分 botmaker 规则未公开，理由是防刷。作为补偿，X 上线了 Under the Hood 工具（x.com/i/under_the_hood），用户可以看到自己账号和帖子上的可见性标签的聚合统计，并把标签与仓库里的规则代码对照——官方将其定位为"代码 + 可见输出"的组合式透明度。此外，占显著流量比例（如 10% 以上）的实验会被同步进仓库，生产默认值由 cron 脚本写回 param.rs，docs/BIDIRECTIONAL_BOOST_CHANGE.md 展示了一个参数值随一次时间线改动演变的过程。

关键设计决策

README 明确列出了五条，值得逐条对照源码理解：

1. 多动作预测：不预测单一"相关性"，而是预测几十种动作的概率，合并成单一分数是独立、显式的一步。
2. 候选隔离：transformer 推理时候选之间互不可见、只看观看者上下文——帖子分数不依赖同批其他帖子，因此一致且可缓存。
3. 哈希嵌入：检索与排序都用多哈希函数做嵌入查表，无需维护词表，新帖子即刻可表示。
4. 排序与可见性分离：两个独立服务、不同输入、不同规则。
5. 可组合管道：candidate-pipeline crate 把管道执行、监控与业务逻辑解耦，独立阶段并行执行、错误优雅降级，新源/过滤器/打分器即插即用。

适用边界与阅读建议

这个仓库不是拿來直接部署的推荐系统：部署相关的基础设施引用（如 xai_kafka）未包含，Grox 提示词等关键文件缺席；例外是 Phoenix——它带完整 Cargo workspace、pyproject.toml、quickstart 和合成数据生成，可以在本机跑通一个概念验证级的训练与服务闭环。

阅读顺序建议：先读 README 的两张架构图建立地图，再进 home-mixer/params/param.rs 看真实权重，然后按请求路径顺序读 candidate_pipeline/phoenix_candidate_pipeline.rs 与 filters、scorers 目录；对内容治理感兴趣的读者，visibility-filtering/rules/registry.rs 的规则求值顺序和 botmaker 规则引擎是更有价值的一侧。

结语

x-algorithm 的意义超出了 X 自己：它把一个亿级社交平台信息流的"检索—打分—过滤—混排"全链路以可审计的代码形式公开，连合规改动和实验参数的演变过程都留在仓库里。对推荐系统工程师，它是难得的参考架构；对普通用户，配合 Under the Hood 工具，它第一次让"我的帖子为什么没被展示"有了可对照代码的答案。

仓库地址：xai-org/x-algorithm