跳转至

新增实验包

新增实验包时，先让它像现有实验一样被发现、能训练、能评估，再考虑模型创新。共享训练、评估、推理和打包能力都在 src/taac2026/，实验包应该保持薄。

最小目录

experiments/my_experiment/
├── __init__.py
└── model.py

需要私有层时可以加 layers.py，但不要把共享 runtime 复制进实验包。

从哪里复制

你要做什么 建议起点
HyFormer 小改 experiments/baseline
HyFormer 小改或训练增强 experiments/baseline（用类型化配置隔离训练变量）
用户-物品交互结构 experiments/interformer
统一 Transformer 结构 experiments/onetrans
多组件消融 experiments/symbiosis（V2/V3 配置扩展和消融默认值）

__init__.py 负责什么

普通 PCVR 实验通过 create_pcvr_experiment() 声明自己：

from pathlib import Path

from taac2026.api import PCVRModelConfig, PCVRNSConfig, PCVRTrainConfig, create_pcvr_experiment


TRAIN_DEFAULTS = PCVRTrainConfig(
    model=PCVRModelConfig(num_blocks=2, num_heads=4, dropout_rate=0.02),
    ns=PCVRNSConfig(
        grouping_strategy="explicit",
        user_groups={"U1": [1, 15]},
        item_groups={"I1": [11, 13]},
        tokenizer_type="rankmixer",
        user_tokens=5,
        item_tokens=2,
    ),
)

EXPERIMENT = create_pcvr_experiment(
    name="pcvr_my_experiment",
    package_dir=Path(__file__).resolve().parent,
    model_type=MyModel,
    train_defaults=TRAIN_DEFAULTS,
)

关键点：

  • name 要唯一，通常用 pcvr_ 前缀。
  • model_type 必须和 model.py 里的模型类一致。
  • NS 分组写在 PCVRNSConfig 里，不需要独立 ns_groups.json。
  • 训练、预测和 runtime 流程由框架统一编排，实验包不需要实现或覆盖 hooks。

实验发现机制

加载逻辑在 src/taac2026/application/experiments/registry.py：

  • --experiment experiments/my_experiment 会按文件系统路径加载。
  • --experiment experiments.my_experiment 会按 Python module 加载。
  • 被加载模块必须导出 EXPERIMENT。
  • EXPERIMENT 必须满足 Experiment 协议；PCVR 模型使用 create_pcvr_experiment()，函数式维护工具使用 FunctionExperiment。

create_pcvr_experiment() 位于 src/taac2026/application/experiments/experiment.py。它用统一的训练、评估、推理流程构造 PCVRExperiment，普通实验不需要自己实现 train()、evaluate() 或 infer()。

PCVRExperiment 的运行逻辑在 src/taac2026/application/experiments/experiment.py：

  • train() 解析本地 demo 数据或线上数据路径，调用训练 workflow。
  • evaluate() 根据 checkpoint sidecar 重建模型和 schema，写 evaluation.json。
  • infer() 读取 checkpoint 和 schema，写 predictions.json。
  • 进入实验包模型代码前，会临时把实验目录放到 sys.path，并隔离 model / utils 这类插件模块名。

model.py 负责什么

模型类需要能被共享 PCVR runtime 构造，并满足训练 / 评估 / 推理契约：

  • forward(inputs) 返回 (B,) logits。
  • predict(inputs) 返回 (logits, embeddings)。
  • 稀疏和稠密参数能被正确分组。
  • checkpoint 侧车里的 train_config.json 和 schema.json 能在评估 / 推理阶段复用。

优先复用共享建模组件：

from taac2026.api import (
    EmbeddingParameterMixin,
    FeatureEmbeddingBank,
    NonSequentialTokenizer,
    SequenceTokenizer,
)

论文特有组件可以留在实验包内；通用能力应该沉到 src/taac2026/infrastructure/modeling/。

Checkpoint Sidecar

训练成功后，runtime 期望 checkpoint 目录至少包含：

global_step*/
├── model.safetensors
├── schema.json
└── train_config.json

model.safetensors 只保存权重；schema.json 和 train_config.json 才能让评估 / 推理重新构造输入契约、NS 分组、runtime execution 和模型默认参数。只复制权重文件会导致评估或推理失败。

改这些内容时要特别小心：

  • PCVRTrainConfig / PCVRModelConfig 字段名
  • PCVRNSConfig 的 grouping strategy 和 fid 分组
  • PCVRBatch / PCVRModelInput 结构
  • train_config.json 的 typed 序列化（build_pcvr_train_config_sidecar / load_pcvr_train_config_sidecar）
  • resolve_schema_path 的 schema 来源语义（显式路径必须存在，否则使用唯一 fallback）
  • checkpoint 目录命名和最新 checkpoint 解析规则

本地验证

先看能否发现并加载：

uv run python -c "from taac2026.application.experiments.registry import load_experiment_package; print(load_experiment_package('experiments/my_experiment').name)"

然后按 测试指南 选择实验契约、CPU smoke 和训练到推理的 roundtrip 检查。新增模型要确认它进入现有契约测试覆盖范围；修改共享契约还需要完整 CPU 门禁。

涉及 bundle 时，按 Bundle 指南 生成并检查受影响的上传物，验证选中实验和共享框架都已打包。平台入口应在脱离仓库 import 上下文的条件下验证。

提交前检查

  • 实验名、目录名和模型类名能对应上。
  • PCVRNSConfig 里的 fid 来自当前 schema。
  • 本地 PCVR smoke 默认不需要 --dataset-path；调试自定义 parquet 时可以显式传本地路径和 schema。
  • forward() 和 predict() 输出形状符合契约。
  • 训练后能生成 global_step*/model.safetensors、schema.json 和 train_config.json。
  • 测试范围符合 测试指南，包含受影响的共享契约。

评论