TorchEasyRec中INPUT_TILE 环境变量的三个模式

NPUT_TILE 是 tzrec 在模型导出和在线推理（Predict）阶段的优化策略，核心场景是：推荐系统中，1 个 user 对应 N 个 item（如召回后排序），可以避免 user 侧特征的重复计算。

INPUT_TILE=1（无 tile / 默认模式）

• 含义：标准模式，不做任何 user/item 拆分优化
• 行为：每条 (user, item) 对独立计算，user 特征会被重复处理 N 次
• 数据格式：所有特征 batchsize = B（正常 batch）
• 用于：训练阶段、不需要 tile 优化的预测场景

INPUT_TILE=2（DataParser 层 tile）

• 含义：在 DataParser（数据解析层） 对 user 侧稀疏特征做 tile 扩展
• 行为：

• user 侧稀疏特征：batch_size=1，在 data_parser.py 的 _to_sparse_features_user1tile_itemb 中 tile 到 B
• user 侧稠密特征：batch_size=1，在 embedding.py 的 _tile_and_combine_dense_kt 中 tile
• item 侧特征：batch_size=B，正常处理

• tile 位置：Embedding 查找之前，先把 user 数据复制 N 份，再一起做 Embedding
• 优点：实现简单，兼容性好
• 缺点：user 的 Embedding 查找仍然重复 N 次

INPUT_TILE=3（Embedding 层 tile）

• 含义：在 Embedding 查找之后 才做 tile 扩展，进一步减少计算
• 行为：

• user 侧稀疏特征：batch_size=1，单独用 ebc_user（独立的 EmbeddingBagCollection）做 Embedding 查找，查找结果再 .tile(tile_size, 1) 扩展到 B
• user 侧稠密特征：batch_size=1，同样在 Embedding 后 tile
• item 侧特征：batch_size=B，正常处理

• tile 位置：Embedding 查找之后
• 优点：user 的 Embedding 只查找 1 次，然后复制 N 份——计算量最优
• 缺点：需要将模型中的 ebc 拆分为 ebc + ebc_user 两个 Embedding 表，导出时需要做参数名映射（见 write_mapping_file_for_input_tile）

总结对比

三种模式的最终预测结果是完全一致的（集成测试中有严格验证），区别仅在于推理效率的优化程度。

INPUT_TILE=3 的限制条件

1. 必须明确区分 user/item 特征

这是最核心的前提。每个特征必须能被识别为 user 侧或 item 侧：

• FG 模式（FG_DAG / FG_NORMAL）：通过 pyfg.FgArrowHandler.user_features() 自动识别，特征的 expression 字段需要以 user: 或 item: 声明（如 expression="user:int_d"）
• 非 FG 模式：通过 feature.side_inputs 中的 side 判断，所有 side_inputs 均为 "user" 的特征才会被标记为 is_user_feat=True
• 如果特征的 user/item 归属不明确，tile 逻辑会出错

2. 仅用于导出（Export）和推理（Predict），不用于训练

INPUT_TILE 是一个环境变量，在 export 和 predict 阶段设置：

QUANT_EMB=1 INPUT_TILE=3 python -m tzrec.export ...

训练阶段不需要也不应该设置 INPUT_TILE。

3. 模型结构限制：会拆分 Embedding 表

INPUT_TILE=3 在导出时会将 Embedding 层拆分为两组独立模块：

• ebc → ebc (item 侧) + ebc_user (user 侧)
• mc_ebc → mc_ebc + mc_ebc_user
• ec_list → ec_list + ec_list_user

需要通过 write_mapping_file_for_input_tile 做参数名映射，将训练时的权重正确加载到拆分后的模型中。

4. 推理数据格式要求

• user 侧特征的 batch_size 必须为 1（即同一个 batch 内所有样本共享同一个 user）
• item 侧特征的 batch_size 为 N（N 个候选 item）
• 数据需要通过 create_predict_data 这样的工具预处理，确保 user 特征只取第一条然后 repeat

5. 需要 FG 模式（FG_DAG 或 FG_NORMAL）

从 data_parser.py 可以看到，is_input_tile() 时需要初始化 FgArrowHandler 来获取 user_inputs 和 user_feats。因此必须使用 FG 模式（FG_DAG 或 FG_NORMAL），FG_ENCODED 的纯预处理数据模式不支持。

6. INPUT_TILE_3ONLINE 子模式的额外限制

如果同时设置 INPUT_TILE_3_ONLINE=1：

• 序列特征直接使用 jt.values() 而非 jt.to_padded_dense(seq_len) — 参见 embedding.py L1341-1345
• 不支持离线 predict（仅支持在线推理） — 见 is_input_tile_3_online 注释

7. 依赖 torchrec（macOS 不可用）

整个 INPUT_TILE 机制依赖 KeyedJaggedTensor、EmbeddingBagCollection 等 torchrec 组件，因此在 macOS 上无法使用。

总结