# PhysVidBench (/zh/docs/evaluation/benchmark-hub/physvidbench)



## 官方参考 [#官方参考]

| 资源        | 链接                                                                                                 |
| --------- | -------------------------------------------------------------------------------------------------- |
| 项目页       | [cyberiada.github.io/PhysVidBench](https://cyberiada.github.io/PhysVidBench/)                      |
| 论文        | [arXiv:2507.15824](https://arxiv.org/abs/2507.15824)                                               |
| GitHub    | [github.com/ensanli/PhysVidBenchCode](https://github.com/ensanli/PhysVidBenchCode)                 |
| HF 数据集    | [Anonymousny/PhysVidBench](https://huggingface.co/datasets/Anonymousny/PhysVidBench)               |
| 仓内 runner | `worldfoundry/evaluation/tasks/execution/runners/physvidbench/run_physvidbench_official_runner.py` |

## 简介 [#简介]

PhysVidBench 评估日常 text-to-video 场景中的物理常识。本地源 README 描述了三步流程：根据 prompt 生成视频、为每个视频提取八条 AuroraCap caption track、再用 Gemini 基于这些 caption 回答物理常识问题。

WorldFoundry 已经在 `worldfoundry/evaluation/tasks/execution/runners/physvidbench` 中包含可运行的 PhysVidBench runner。运行 WorldFoundry 时不要克隆上游代码仓库。完整 prompt/question 数据可以下载 Hugging Face dataset `Anonymousny/PhysVidBench`；代码执行仍应走仓内 runner。

## 准备资产 [#准备资产]

* Prompt/question CSV：仓内 fixture 位于 `worldfoundry/data/benchmarks/assets/physvidbench/prompts_questions.csv`；可用 `WORLDFOUNDRY_PHYSVIDBENCH_PROMPT_MANIFEST` 或 `--prompt-manifest` 覆盖。
* Caption tracks：八个文本文件，base name 为 `cogvideo2b`，suffix 分别为 `_FP`、`_OP`、`_SR`、`_TD`、`_AU`、`_MT`、`_FM` 和无 suffix。可用 `WORLDFOUNDRY_PHYSVIDBENCH_CAPTIONS_DIR`、`WORLDFOUNDRY_PHYSVIDBENCH_CAPTION_BASE`、`--captions-dir` 或 `--caption-base` 覆盖。
* 完整数据：超出仓内 fixture 时，使用 HF dataset `Anonymousny/PhysVidBench` 或你自己物化的 prompt/question CSV。
* 候选视频：将 `WORLDFOUNDRY_GENERATED_ARTIFACT_DIR` 指向生成视频。
* Gemini judge：设置 `GEMINI_API_KEY`、`GOOGLE_API_KEY` 或 `WORLDFOUNDRY_PHYSVIDBENCH_GEMINI_API_KEY`，并安装 `google-genai`。本地 fixture 检查可设置 `WORLDFOUNDRY_PHYSVIDBENCH_JUDGE_BACKEND=mock`。

## 生成产物布局 [#生成产物布局]

PhysVidBench prompt ID 是数字。生成视频应为 zero-padded 扁平文件：

```text
generated_videos/
  0000.mp4
  0001.mp4
  ...
```

覆盖率检查会去掉数字文件名开头的零，因此 `0.mp4` 和 `0000.mp4` 都映射到 prompt ID `0`。Caption 文件按 `PromptID` 行号索引，所以每条 caption track 都必须包含足够行数。

## 用 WorldFoundry 运行 [#用-worldfoundry-运行]

通过公开 CLI 导入已有 PhysVidBench QA 结果 CSV：

```bash
worldfoundry-eval zoo benchmark-run \
  --benchmark-id physvidbench \
  --mode official-validation \
  --official-results-path /path/to/output.csv \
  --generated-artifact-dir /path/to/generated_videos \
  --output-dir tmp/physvidbench/validation \
  --json
```

通过公开 CLI 运行仓内 Gemini QA 路径：

```bash
export WORLDFOUNDRY_GENERATED_ARTIFACT_DIR=/path/to/generated_videos
export GEMINI_API_KEY=...

worldfoundry-eval zoo benchmark-run \
  --benchmark-id physvidbench \
  --mode official-run \
  --generated-artifact-dir "${WORLDFOUNDRY_GENERATED_ARTIFACT_DIR}" \
  --output-dir tmp/physvidbench/run \
  --json
```

直接调用仓内 runner：

```bash
export WORLDFOUNDRY_GENERATED_ARTIFACT_DIR=/path/to/generated_videos
export WORLDFOUNDRY_BENCHMARK_OUTPUT_DIR=tmp/physvidbench/direct
export GEMINI_API_KEY=...

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/physvidbench/run_physvidbench_official_runner.py \
  --run-official \
  --generated-artifact-dir "${WORLDFOUNDRY_GENERATED_ARTIFACT_DIR}" \
  --output-dir "${WORLDFOUNDRY_BENCHMARK_OUTPUT_DIR}" \
  --json
```

直接导入结果：

```bash
PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/physvidbench/run_physvidbench_official_runner.py \
  --official-results-path /path/to/output.csv \
  --generated-artifact-dir /path/to/generated_videos \
  --output-dir tmp/physvidbench/direct-validation \
  --json
```

无 Gemini 的本地小规模 fixture 路径：

```bash
WORLDFOUNDRY_PHYSVIDBENCH_JUDGE_BACKEND=mock \
PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/physvidbench/run_physvidbench_official_runner.py \
  --run-official \
  --generated-artifact-dir /path/to/generated_videos \
  --output-dir tmp/physvidbench/mock \
  --json
```

## 指标 [#指标]

| Metric ID                       | 含义                                                  |
| ------------------------------- | --------------------------------------------------- |
| `physical_commonsense_accuracy` | 所有 yes/no QA 的总体准确率。                                |
| `affordance_understanding`      | `Object Properties & Affordances` 问题准确率。            |
| `tool_use_consistency`          | `Action & Procedural Understanding` 问题准确率。          |
| `material_property_consistency` | `Material Interaction & Transformation` 问题准确率。      |
| `temporal_dynamics_consistency` | `Temporal Dynamics` 问题准确率。                          |
| `physvidbench_average`          | WorldFoundry 主指标。优先取可用类别准确率均值；没有类别 bucket 时使用总体准确率。 |

所有指标都是越高越好，并以 `0..1` accuracy 输出。

## 输出 [#输出]

输出目录包含：

* `scorecard.json`：运行状态、指标、prompt/video 覆盖率、QA backend 与 leaderboard 有效性标记。
* `output.csv`：仓内 QA 路径写出，字段包括 `PromptID`、`Question`、`Types`、`Model_Answer` 和 `Match`。
* `raw_metric_table.jsonl`：每个声明指标一行。
* `per_sample_scores.jsonl`：从 QA 结果复制出的 question-level 行。
* 通过 `worldfoundry-eval zoo benchmark-run` 调用时，还会写出 `specialized_normalizer_stdout.log` 与 `specialized_normalizer_stderr.log`。

## 限制 [#限制]

* 当前 checkout 中打包的 prompt/caption 资产不是完整 383-prompt benchmark 包；它足够说明和验证接线。完整评测请使用 HF dataset 或显式覆盖文件。
* 仓内 QA runner 消费 captions；它不会对视频运行 AuroraCap。你需要自行准备八条 caption track。
* 默认非 mock backend 需要 Gemini API 权限和 `google-genai`。
* 完整 leaderboard parity 需要完整 prompt 覆盖、完整 caption tracks、生成视频与归一化 QA 输出。

[返回 Benchmark Hub](/zh/docs/evaluation/benchmark-hub)