---
title: "RecsysAggregatedModel（排序模型）"
description: "生产版排序模型构件：RecsysAggregatedModelConfig，以及 RecsysAggregatedModel 的输入构造、前向、输出头与损失方法；旧 PhoenixModel 已删除"
---

> Documentation Index
> Fetch the complete documentation index at: https://x-algorithm.vergego.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RecsysAggregatedModel（排序模型）

## 是什么

`RecsysAggregatedModel` 是 Phoenix 排序模型的代码构件。它是一个 Haiku `hk.Module`，定义在 `phoenix/xrex/models/recsys_model.py:2482`。配置类是同一文件中的 `RecsysAggregatedModelConfig`（`:959`）。本页说明类结构与方法；排序的工作原理见 [Phoenix 排序模型](https://x-algorithm.vergego.ai/concepts/phoenix-ranking/)。

> **旧构件的去向。** 旧页面描述的 `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（召回模型）](https://x-algorithm.vergego.ai/entities/recsys-retrieval-model/) 引用这些构件。

## 配置：RecsysAggregatedModelConfig

该类用 `@configclass` 声明，位于 `recsys_model.py:959-1520`。它的字段很多，包括广告、搜索、购买价值等其他产品的开关。与首页排序有关的主要字段如下：

| 字段 | 含义 | 类默认值 | 旗舰 `home_direct_packed` |
|------|------|------|------|
| `model_config` | `TransformerConfig` | 必填 | 8 层、2560 维 |
| `hash_table` | 统一嵌入表的哈希配置 | 必填 | 见 [哈希嵌入](https://x-algorithm.vergego.ai/concepts/hash-based-embeddings/) |
| `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` —— `RecsysAggregatedModel`
- `phoenix/xrex/models/recsys_model.py:1673-2150` —— `block_*_reduce` 与 `embed_entity_sid`
- `phoenix/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 排序模型](https://x-algorithm.vergego.ai/concepts/phoenix-ranking/) —— 排序原理与预测字段
- [RecsysTwoTowerModel（召回模型）](https://x-algorithm.vergego.ai/entities/recsys-retrieval-model/) —— 复用本文件公共构件的召回模型
- [候选隔离注意力掩码](https://x-algorithm.vergego.ai/concepts/candidate-isolation-masking/) —— 段 ID 与候选专用层
- [Transformer 骨架](https://x-algorithm.vergego.ai/concepts/grok-transformer/) —— 由 `model_config` 构造的 transformer
- [哈希嵌入](https://x-algorithm.vergego.ai/concepts/hash-based-embeddings/) —— `hash_table` 与统一嵌入表
- [Phoenix 训练](https://x-algorithm.vergego.ai/concepts/phoenix-training/) —— 训练器与服务运行器

Source: https://x-algorithm.vergego.ai/entities/recsys-model/index.mdx