# 添加模型 (/zh/docs/guides/add-model)



## 介绍 [#介绍]

第一份模型 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。

## 实现清单 [#实现清单]

<Steps>
  <Step>
    在 `worldfoundry/pipelines/<family>/` 添加或更新 pipeline；它必须暴露 `from_pretrained()` 和确定性的 `process()` / `__call__()` 契约。
  </Step>

  <Step>
    在 `worldfoundry/operators/` 添加或更新 operator；每个 runnable method 都需要，不只复杂输入路径需要。
  </Step>

  <Step>
    按现有布局，把 backend-specific inference code 放在 `base_models/`、`synthesis/` 或 `representations/`。不要把 training/data-processing helper trees 提交到 perception 或 3D base-model packages。
  </Step>

  <Step>
    通过 catalog YAML 的 `pipeline_target` 或 `evaluation/models/pipelines/bindings.py` 里的 canonical binding helpers 注册 route。
  </Step>

  <Step>
    只有模型能参与 generic benchmark runner 时，才在 `worldfoundry/evaluation/models/pipelines/handlers.py` 添加 inference handler。
  </Step>

  <Step>
    添加或更新相关 `worldfoundry/data/models/catalog/<category>/<model-id>.yaml` 条目，记录 source、license、checkpoint refs、tasks、runtime profile 和 integration status。
  </Step>

  <Step>
    当官方 demo settings 可对比时，添加小型 model-zoo check helper。
  </Step>

  <Step>
    为确定性 runner behavior 添加聚焦回归测试。
  </Step>
</Steps>

## 状态规则 [#状态规则]

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。

## 常用命令 [#常用命令]

<Tabs items="['inspect', 'check', 'download', 'clone', 'evaluate']">
  <Tab>
    ```bash
    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
    ```
  </Tab>

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

  <Tab>
    ```bash
    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
    ```
  </Tab>

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

  <Tab>
    ```bash
    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
    ```
  </Tab>
</Tabs>

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

## Run-evidence report [#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 证据 [#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-边界]

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 卫生边界 [#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 的技术债，不要把它作为新增集成的模式。