是什么
RecsysAggregatedModel 是 Phoenix 排序模型的代码构件。它是一个 Haiku hk.Module，定义在 phoenix/xrex/models/recsys_model.py:2482。配置类是同一文件中的 RecsysAggregatedModelConfig（:959）。本页说明类结构与方法；排序的工作原理见 Phoenix 排序模型。
旧构件的去向。 旧页面描述的
PhoenixModel/PhoenixModelConfig（phoenix/recsys_model.py）已在 2026-08-13 随演示代码一起删除（git diff 0bfc279 HEAD显示D phoenix/recsys_model.py）。新文件同名，但位于phoenix/xrex/models/下，共 5764 行，是生产代码。HashKeys/HashTable（phoenix/xrex/models/recsys_embedding.py:176、:230）取代了旧版的HashConfig；字典形式的RecsysFeaturesBatch取代了旧版的RecsysBatch。
同一文件还提供召回模型复用的公共构件：block_user_reduce（:1673）、block_history_reduce（:1947）、embed_entity_sid（:1714）、right_anchored_rope_positions（:260）。RecsysTwoTowerModel（召回模型） 引用这些构件。
配置：RecsysAggregatedModelConfig
该类用 @configclass 声明，位于 recsys_model.py:959-1520。它的字段很多，包括广告、搜索、购买价值等其他产品的开关。与首页排序有关的主要字段如下：
| 字段 | 含义 | 类默认值 | 旗舰 home_direct_packed |
|---|---|---|---|
model_config |
TransformerConfig |
必填 | 8 层、2560 维 |
hash_table |
统一嵌入表的哈希配置 | 必填 | 见 哈希嵌入 |
emb_table_width |
嵌入表宽 | 必填 | 1024 |
history_seq_len / candidate_seq_len |
序列长度 | — | 1022 / 64 |
num_continuous_actions |
连续头槽位数 | 8 | 8 |
continuous_action_losses |
连续值损失清单 | 一条 MAE 停留损失 | 5 条停留相关 + 2 条首页续看/主页访问，见下 |
feature_prep_enabled / feature_prep |
是否使用“各自投影再相加”的特征准备路径 | False |
True |
use_post_sid / sid_* |
语义 ID 输入 | 关 | 开，6 层 × 256 |
use_seqpack / right_anchored_rope |
序列打包、右锚定 RoPE | — | 开 / 开 |
log_q_correction |
按负样本出现次数加权 | False（:1239） |
True |
view_loss_weight |
浏览类动作的损失权重 | 1.0（:1323） |
0.5 |
mask_neg_feedback_on_negatives |
在负样本上不计算负反馈头 | True（:1312） |
True |
act_l2_weight |
激活 L2 正则 | 0.0 | 5e-7 |
page_rl |
整页强化学习与解码器 | 关 | 关（仅 immersive_page_rl* 打开） |
出处：类定义在 recsys_model.py:959-1340；旗舰取值在 phoenix/xrex/configs/xrecsys.py:316-387、:532-577、:786-1062。
make()（recsys_model.py:1355-1442）先执行一组校验，再构造 RecsysAggregatedModel。校验项包括购买价值、辅助价值头、广告头掩码、侧输入，以及连续损失互不冲突（validate_continuous_action_losses）。
辅助配置
| 类 | 位置 | 作用 |
|---|---|---|
ContinuousActionLossConfig |
recsys_model.py:339-416 |
定义一条连续值损失：槽位、类型（mse/mae/huber/tweedie/binary/cread）、权重、产品面过滤、norm_scale、CREAD 阈值参数 |
NormConfig |
:332-337 |
norm_scale 与是否取 log |
ContextFeaturesConfig / CategoricalFeatureConfig |
:578-609 |
旧式上下文特征（产品面、帖龄、时区、本地小时、星期、互动计数分桶等） |
FeaturePrepConfig |
phoenix/xrex/models/recsys_feature_prep.py:156-278 |
特征准备路径的全部开关 |
UserFeaturesConfig |
phoenix/xrex/models/recsys_user_features.py |
用户画像 token 的维度设置 |
输入与输出类型
- 输入批次
RecsysFeaturesBatch：一个字典，包含user_hashes、user_ip_hashes、history_seq、candidate_seq（每个序列包含post_hashes、auth_hashes、actions、continuous_actions、product_surface、impr_ts、post_creation_ts_sec、categorical_features、bool_features、int64_features、SID 等）。训练时还包含packing_layout（phoenix/xrex/data/recsys/recsys_batch.py）。 - 嵌入
RecsysEmbeddings：模型从统一表查出的用户、历史帖、候选帖、历史作者、候选作者、IP 嵌入（recsys_embedding.py:35-42）。 - 前向输出（
__call__的返回值）：logits [B, C, 64]、continuous_predictions [B, C, 8]、按槽位的原始 logit、辅助价值头 logit。需要时，输出还包含候选嵌入与用户嵌入（recsys_model.py:4417-4463）。
模块级函数
| 函数 | 位置 | 作用 |
|---|---|---|
compute_post_age_bucket |
recsys_model.py:198-238 |
帖龄分桶（线性或 log1p） |
right_anchored_rope_positions |
:260-281 |
计算右锚定位置；所有候选的位置都等于历史末尾 |
get_candidate_tweet_counts |
:1523-1538 |
计算 log-Q 所用的批内出现次数 |
block_user_reduce |
:1673-1711 |
旧式用户 token：哈希嵌入拼接后投影 |
embed_entity_sid |
:1714-1835 |
语义 ID 查表，可选交叉注意力与前缀嵌入 |
block_history_reduce |
:1947-2060 |
旧式历史 token：帖子、SID、作者、动作、产品面拼接后投影 |
block_candidate_reduce |
:2062-2150 |
旧式候选 token |
attention_segment_ids |
:2277-2288 |
生成段 ID：前缀与历史 = 1，候选 = -1，padding = 0 |
RecsysAggregatedModel 方法
| 方法 | 位置 | 作用 |
|---|---|---|
build_inputs |
recsys_model.py:3804-4310 |
构造“前缀、历史、候选”三段序列。feature_prep_enabled=True 时直接调用 build_feature_prep_inputs；否则使用旧式 block_*_reduce |
__call__ |
:4312-4463 |
transformer 前向 → 末层 RMSNorm → 取候选位置 → 离散头 + 连续头 |
decode |
:3321-3324 |
离散头：乘以 [D, 64] 反嵌入矩阵 |
decode_continuous |
:3480-3567 |
连续头：按槽位与产品面选择激活方式；CREAD 槽位改用 _decode_cread 的还原值 |
_decode_cread |
:3452-3477 |
CREAD 头：输出 [D, 30] 阈值 logit，经 sigmoid 后按区间宽度加权求和 |
loss_inputs_and_normalizers |
:4464-4728 |
准备标签、负样本掩码、log-Q 权重和各项归一化分母 |
loss |
:4730-5302 |
离散多标签 BCE + 各连续损失 + 价值头等 |
page_rl_loss |
:5304-5360 |
整页强化学习损失（仅在 page_rl 打开时使用） |
metrics |
:5362-5624 |
AUC、RCE、NDCG、校准等指标 |
forward |
:5626 |
服务时的前向入口，可选整页解码 |
设计决策
| 决策 | 理由 |
|---|---|
| 新旧两条输入路径并存 | 旗舰配置使用特征准备路径；旧预设与召回旗舰仍用 block_*_reduce，以保持可复现 |
| 连续损失用清单配置，按权重启停 | 无需修改模型代码即可整体替换停留损失（如 10-08 由 MAE/Tweedie 换成 CREAD）；validate_continuous_action_losses 防止同一槽位重复生效 |
| 一个类覆盖首页、广告、搜索、沉浸页 | 各产品共用主干与训练器，通过配置开关区分。源码未写理由，此为推测 |
源码锚点
phoenix/xrex/models/recsys_model.py:959-1442——RecsysAggregatedModelConfig与make()phoenix/xrex/models/recsys_model.py:2482-5764——RecsysAggregatedModelphoenix/xrex/models/recsys_model.py:1673-2150——block_*_reduce与embed_entity_sidphoenix/xrex/configs/xrecsys.py:489-662—— 预设：xrecsys_seqpack、home_direct_packed、home_direct_packed_gb300、immersive_page_rl、immersive_page_rl_cread、home_direct_packed_nano、xrecsys_search
相关页面
- Phoenix 排序模型 —— 排序原理与预测字段
- RecsysTwoTowerModel（召回模型） —— 复用本文件公共构件的召回模型
- 候选隔离注意力掩码 —— 段 ID 与候选专用层
- Transformer 骨架 —— 由
model_config构造的 transformer - 哈希嵌入 ——
hash_table与统一嵌入表 - Phoenix 训练 —— 训练器与服务运行器