Back to Details

torch-recsys-model-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Torch RecSys Model Dev

Torch RecSys模型开发

Use this skill to turn existing RecSys model ideas into stable PyTorch code by keeping context small, carrying the most important data facts, making contracts explicit, and tying each change to a focused verification.
使用该技能可将现有的RecSys模型想法转化为稳定的PyTorch代码，方法是保持上下文精简，聚焦最重要的数据事实，明确契约，并将每一处变更与针对性验证绑定。

When to use

适用场景

  • Building or debugging 
    torch.nn.Module
    recommender models.
  • Working with Transformer, HSTU, attention, FiLM, RAB, MTP, dual-mask, dense/list/sparse feature fusion, pCVR/CTR heads, or ablation axes.
  • A repo already has many model designs and bugs come from interface drift, shape mismatch, masking, config flags, or train/eval mismatch.
Do NOT use for:
  • Full official competition rule interpretation or submission policy review; use the domain skill such as 
    taac-unirec-dl
    when those facts are uncertain.
  • Broad literature review or historical plan synthesis.
  • 构建或调试
    torch.nn.Module
    推荐系统模型。
  • 涉及Transformer、HSTU、注意力机制、FiLM、RAB、MTP、双掩码、密集/列表/稀疏特征融合、pCVR/CTR头或消融轴的开发工作。
  • 代码仓库中已有多种模型设计，但Bug源于接口漂移、形状不匹配、掩码问题、配置标志错误或训练/评估逻辑不一致。

Context Budget

不适用场景

  1. Start from the current task, error, or module name; do not read broad archives first.
  2. Keep a compact Data Facts Snapshot in context before model work: target label, train/test field differences, sequence/static feature groups, padding/null rules, metric/loss alignment, and leakage constraints.
  3. Prefer 
    configs/base.yaml
    , the directly touched 
    src/model/*.py
    , the relevant 
    src/data/*
    contract file, and the current train/eval entrypoint.
  4. Read tests narrowly: one focused test file for the touched module plus one smoke/integration test only when the boundary crosses data -> model -> loss -> eval.
  5. Do not load large historical planning or synthesis documents unless the user explicitly asks for design archaeology.
  • 完整的官方竞赛规则解读或提交政策审核；若相关信息不确定，请使用
    taac-unirec-dl
    等领域技能。
  • 宽泛的文献综述或历史方案整合。

Workflow

上下文预算

  1. Identify the active boundary.
    • Choose exactly one primary boundary: data/collate, embedding/fusion, sequence block, head/loss, train loop, evaluator, or config wiring.
    • If the task spans multiple boundaries, write the handoff contract first and change one side at a time.
  2. Establish the Data Facts Snapshot.
    • Pull only the facts needed for model design from local official docs, schema code, dataset sample readers, or the domain skill.
    • Include facts in the working context; do not keep model work blind to labels, test shape, missing fields, metric, or leakage constraints.
    • See references/model-contracts.md.
  3. Establish contracts before editing.
    • Batch contract: input keys, shape, dtype, padding/null convention, device, and expected missing fields.
    • Model contract: 
      forward()
      inputs, output keys, score/logit shape, optional auxiliary outputs only if the current architecture already uses them, and train/eval behavior.
    • Config contract: each optional component has a flag, default, and test-visible behavior.
    • See references/model-contracts.md.
  4. Debug systematically.
    • Reproduce the smallest failure command first.
    • Classify the failure as schema, collate, shape, mask, feature fusion, loss, training instability, metric, or config wiring.
    • Fix the first broken contract, then rerun only the smallest relevant verification.
    • See references/debugging-protocol.md.
  5. Keep experiments disciplined.
    • One architecture idea per patch.
    • New modules must be ablation-friendly and not silently change baseline behavior.
    • Do not add another model idea while baseline smoke or focused tests are red.
    • See references/experiment-discipline.md.
  1. 从当前任务、错误或模块名称入手；不要先查阅大量归档资料。
  2. 在开展模型工作前，在上下文中保留精简的数据事实快照：目标标签、训练/测试字段差异、序列/静态特征组、填充/空值规则、指标/损失对齐及防泄漏约束。
  3. 优先参考
    configs/base.yaml
    、直接涉及的
    src/model/*.py
    文件、相关的
    src/data/*
    契约文件，以及当前的训练/评估入口文件。
  4. 针对性阅读测试文件：仅阅读与修改模块相关的单个聚焦测试文件；仅当边界涉及数据→模型→损失→评估时，才额外阅读一个冒烟/集成测试文件。
  5. 除非用户明确要求追溯设计历史，否则不要加载大型历史规划或整合文档。

Inline Example

工作流程

Before changing a model module:
bash
rg -n "class .*Model|def forward|PcvrConfig|use_|loss|logit" src/model src/train_eval.py configs
Then read only the files named by the result that are directly involved in the current failure or feature.
  1. 确定活跃边界。
    • 精准选择一个主边界：数据/整理（collate）、嵌入/融合、序列模块、头部/损失、训练循环、评估器或配置关联。
    • 若任务跨越多个边界，先编写交接契约，再逐一修改各部分。
  2. 建立数据事实快照。
    • 仅从本地官方文档、schema代码、数据集样本读取器或领域技能中提取模型设计所需的事实。
    • 将这些事实纳入工作上下文；模型开发过程中不能忽视标签、测试形状、缺失字段、指标或防泄漏约束。
    • 参考references/model-contracts.md。
  3. 修改前先确立契约。
    • 批量契约：输入键、形状、数据类型（dtype）、填充/空值约定、设备及预期缺失字段。
    • 模型契约：
      forward()
      输入、输出键、得分/对数几率（logit）形状，仅当当前架构已使用时才包含可选辅助输出，以及训练/评估行为。
    • 配置契约：每个可选组件都有标志、默认值及测试可见行为。
    • 参考references/model-contracts.md。
  4. 系统化调试。
    • 先复现最小化的失败命令。
    • 将失败分类为schema问题、整理（collate）问题、形状问题、掩码问题、特征融合问题、损失问题、训练不稳定、指标问题或配置关联问题。
    • 修复第一个失效的契约，然后仅重新运行最相关的最小化验证。
    • 参考references/debugging-protocol.md。
  5. 规范实验流程。
    • 每个补丁仅实现一个架构想法。
    • 新模块需支持消融实验，且不得静默改变基线行为。
    • 在基线冒烟测试或聚焦测试未通过前，不要添加新的模型想法。
    • 参考references/experiment-discipline.md。
—

内联示例

—
修改模型模块前：
bash
rg -n "class .*Model|def forward|PcvrConfig|use_|loss|logit" src/model src/train_eval.py configs
然后仅阅读结果中与当前失败或功能直接相关的文件。