添加模型

介绍

第一份模型 PR 应该保持窄：一个模型族、一个 operator、一个 pipeline、必要时一个 runtime profile、一条已解析 runner path，以及一份聚焦 run-evidence report。

好的第一份 PR 只需要证明 route 能端到端跑通，不必在第一天覆盖所有 task variant、所有 checkpoint 或所有 benchmark cell。

实现区域

模型集成会落在几个固定 surface 上。用下面列表判断 diff 应该改哪里：

• Pipeline 与 operator — 公开模型入口，以及 prompt、图片、视频、camera control、action 和 interaction state 的输入整理。
• Runtime implementation — 放在合适的 synthesis、representation 或 base-model package 下的推理代码。
• Evaluation binding — 统一 route resolution，让 CLI 和 benchmark runner 能找到该方法。
• Catalog metadata — Source、license、checkpoint refs、task coverage、runtime profile、blockers 和支持状态。
• 聚焦检查 — 小型确定性测试或 helper 命令，用来证明本次修改的 runner surface。

可运行路由契约

WorldFoundry 通过同一套公开 contract 解析每个 runnable method。加捷径前先确认这些规则：

• Pipeline — 每个 runnable method 都必须通过 catalog pipeline_target 或 evaluation/models/pipelines/bindings.py 解析到具体 pipeline class。
• Operator — 每个 runnable pipeline 都必须有 operator，即使第一版只是薄实现。Input validation、media loading、camera/action parsing 和 interaction shaping 都放在这里。
• Runtime profile — Runtime profile 描述环境、checkpoint、命令和 execution metadata。它不能替代 pipeline/operator route，也不能单独作为支持声明。
• Binding source — Route normalization 只放在 evaluation/models/pipelines/bindings.py；不要在 catalog、loading、resolver 或 check code 里新增平行 parser。
• Base-model code — base_models/perception_core 和 base_models/three_dimensions 只放 inference/runtime primitives。不要在这里添加 training loops、dataset builders、dataloaders、augmentation pipelines 或 callbacks。

实现清单

状态规则

Catalog 字段描述意图；staged evidence 决定 support matrix 是否认可。

• source.status=open_source — 官方 public source 可用，并记录 license metadata。
• source.status=api — 模型通过 hosted provider 或 private service boundary 调用。
• source.status=closed — 没有公开 runnable source/checkpoint。
• integration_status=planned — Source 或 code 存在，但必需的 runnable checks 未完成。
• integration_status=blocked — Source、license、checkpoint、dependency、API 或 hardware 条件阻止可运行集成。
• integration_status=integrated — 必需 runnable checks 通过，且 report 对当前 manifest 是 fresh。

Manifest claims 本身不可信。Support matrix 会从 staged evidence 重新计算 readiness。

常用命令

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo models --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-show --model-id <model-id-or-alias> --include-manifest --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-specs --model-id <model-id> --json

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-download --check-local \
  --model-id <model-id> \
  --json

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-download \
  --model-id <model-id> \
  --repo-id <org/name> \
  --cache-dir /path/to/checkpoints \
  --check-local \
  --report-path tmp/model_zoo/download/<model-id>.json \
  --json

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo model-download --check-local \
  --model-id <model-id> \
  --execute \
  --json

conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval evaluate \
  --mode model \
  --model-id <model-id> \
  --model-manifest-dir worldfoundry/data/models/catalog \
  --requests-path tmp/demo/requests.jsonl \
  --output-dir tmp/model_eval/<model-id> \
  --metric artifact_count \
  --json

只有在机器被允许拉取 checkpoint 时，才添加 --execute、--disable-xet、--disable-hf-transfer、--timeout 或 --retries。

Run-evidence report

模型检查命令会把报告写到 tmp/model_zoo/validation/<model-id>。Report 应包含 manifest entry hash、check script hash、git commit、stage results、blockers 和 next action。任一项漂移时，support matrix 会把 report 视为 stale。

PR 证据

Reviewer 应能根据 PR 内容复现你的路径，而不必猜测机器状态：

• Manifest diff — 相关 worldfoundry/data/models/catalog/<category>/<model-id>.yaml 条目。
• Source checks — tmp/model_zoo/validation/<model-id>/report.json。
• Checkpoint state — Cache location 和 repo id，不提交 checkpoint。
• Demo parity — 官方命令、raw logs、generated artifact path。
• Runner parity — WorldFoundry runner 命令和 output artifact path。
• Tests — test/ 或 test_stream/ 下的聚焦文件。
• Support matrix — 提升状态时刷新 tmp/preflight_report.md。

不要提交 checkpoints、generated videos、local caches、API keys 或 private assets。

Cache 边界

Cache path 只能放临时下载、checkpoint copies、dataset mirrors、official-runtime clone caches、generated previews 和 logs。不要把模型架构代码放进 cache/，也不要让 in-tree runner 从 cache path import Python modules。如果 runner 需要模型架构代码，把这些代码放在 worldfoundry/ 下，并随模型集成一起 review。

Runtime 卫生边界

推理时必须使用的 transforms 可以留在对应 runtime package 中，例如 GroundingDINO util.transforms、DUST3R cropping/transforms、DROID-SLAM RGB-D geometry helpers。Training datasets、dataloaders、losses、callbacks、augmentation-only modules 和 experiment scripts 不应进入 runtime package，除非这个框架未来开始支持该模型族的仓内训练。

pixelsplat 是当前 3D base models 下的例外，因为它仍使用官方 Lightning test runner 和 dataset-shaped loader。把它视为需要移植成纯推理 runner 的技术债，不要把它作为新增集成的模式。