快速开始¶

这页只做一件事：让你从干净环境跑通一次 Baseline 训练、评估和推理，并说明这些命令实际会读写哪些文件。

准备环境¶

需要：

• Linux
• Python 3.12 - 3.14
• uv
• Git
• NVIDIA GPU 与支持当前 cuda132 profile 的驱动，本地 GPU 训练时需要

安装依赖：

git clone https://github.com/Puiching-Memory/TAAC_2026.git
cd TAAC_2026

uv sync --locked --extra cuda132

如果你还要跑测试、lint 或文档站：

uv sync --locked --extra dev --extra cuda132

说明：

• cuda132 是当前仓库支持的本地 CUDA profile。
• uv sync 按 .python-version 选择 Python，缺少对应版本时自动安装。
• dev 包含 Ruff、Vulture、Pytest、Coverage 和 Zensical。
• 线上 bundle 不依赖 uv，见 线上 Bundle 上传。

本地 Docker 镜像使用相同的 uv sync 流程，固定启用 cuda132；基础镜像默认值只在 docker/Dockerfile 声明。 入口脚本默认同步依赖，以适配开发容器挂载的仓库，然后执行传入命令；设置 AUTO_SYNC=0 可跳过同步。 编译 CUDA 扩展需要与该 profile 匹配的 Toolkit，本地 Docker 镜像已包含它。

数据从哪里来¶

本地 PCVR smoke 使用 Hugging Face 上的 TAAC2026/data_sample_1000 demo parquet。仓库不提交 parquet 数据；公开样例数据的唯一来源是 Hugging Face。

普通 PCVR 本地命令不传 --dataset-path 时，运行时会通过 Hugging Face 缓存 demo_1000.parquet。如果你想把样例文件留在本地，或要做调试、bundle 模拟和 benchmark，可以这样下载：

mkdir -p data/sample_1000_raw
uv run huggingface-cli download TAAC2026/data_sample_1000 \
  demo_1000.parquet \
  --repo-type dataset \
  --local-dir data/sample_1000_raw

样例 schema 归档在 docs/archive/files/schema/sample_1000_raw.schema.json。这是基于线上格式和线下 parquet 读取反推得到的参考快照；本地 smoke 命令建议显式传 --schema-path 使用它。

本地 PCVR 训练、评估和推理可以显式传 --dataset-path 读取本地 parquet 文件或目录；调试自定义数据时也建议显式传 --schema-path，或把 schema.json 放在数据文件同目录。真实线上数据仍由 bundle 模式下的平台环境变量注入。

训练 Baseline¶

bash run.sh train \
  --experiment experiments/baseline \
  --run-dir outputs/quickstart_baseline \
  --optimizer.device cpu \
  --data.num_workers 0 \
  --data.batch_size 8 \
  --optimizer.max_steps 1 \
  --schema-path docs/archive/files/schema/sample_1000_raw.schema.json

训练完成后，输出目录里会有 checkpoint 和 sidecar。当前 checkpoint 通常位于：

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

如果你有可用 GPU，可以把 --optimizer.device cpu 改成 --optimizer.device cuda，并适当调大 batch size / max steps。

评估训练结果¶

bash run.sh val \
  --experiment experiments/baseline \
  --run-dir outputs/quickstart_baseline \
  --device cpu \
  --num-workers 0 \
  --schema-path docs/archive/files/schema/sample_1000_raw.schema.json

传 --run-dir 时，运行时会在目录下自动寻找最新的 global_step*/model.safetensors。

评估会写出：

outputs/quickstart_baseline/
├── evaluation.json
├── validation_predictions.jsonl
└── evaluation_observed_schema.json

evaluation.json 里包含 metrics、checkpoint 路径、schema 路径和数据诊断；validation_predictions.jsonl 保留逐样本验证预测，便于排查分数异常。

生成推理结果¶

bash run.sh infer \
  --experiment experiments/baseline \
  --checkpoint outputs/quickstart_baseline \
  --result-dir outputs/quickstart_infer \
  --device cpu \
  --num-workers 0 \
  --schema-path docs/archive/files/schema/sample_1000_raw.schema.json

输出文件：

outputs/quickstart_infer/
└── predictions.json

predictions.json 的顶层 key 是 predictions，内部是 user_id -> probability：

{
  "predictions": {
    "user_001": 0.8732
  }
}

换一个实验包¶

只改 --experiment：

bash run.sh train \
  --experiment experiments/interformer \
  --run-dir outputs/quickstart_interformer \
  --optimizer.device cpu \
  --data.num_workers 0 \
  --data.batch_size 8 \
  --optimizer.max_steps 1 \
  --schema-path docs/archive/files/schema/sample_1000_raw.schema.json

实验选择见 实验包总览。

生成线上 Bundle¶

训练 bundle：

uv run taac-package-train \
  --experiment experiments/baseline \
  --output-dir outputs/bundles/baseline_training

推理 bundle：

uv run taac-package-infer \
  --experiment experiments/baseline \
  --output-dir outputs/bundles/baseline_inference

训练 bundle 输出 run.sh + code_package.zip，推理 bundle 输出 infer.py + code_package.zip。上传和本地模拟方式见 线上 Bundle 上传。

命令边界¶

run.sh 只支持：

打包、测试和文档站分别使用独立命令：taac-package-*、pytest 和 zensical。

run.sh 的分发逻辑在 src/taac2026/application/bootstrap/run_sh.py：

• 不写子命令时默认等价于 train。
• train 最终调用 taac-train。
• val / eval / infer 最终调用 taac-evaluate。
• 本地默认 runner 是 uv；bundle 模式或 TAAC_RUNNER=python 会改用当前 Python。
• --cuda-profile 目前只接受 cuda132，也可以用 TAAC_CUDA_PROFILE=cuda132。

训练 CLI 使用嵌套配置：参数按 PCVRTrainConfig 的分组加前缀，例如 --data.batch_size、--data.num_workers、--optimizer.max_steps、--optimizer.device。评估和推理 CLI 仍是扁平参数，使用连字符形式：--num-workers、--batch-size、--device。

常见失败¶

评论