# MiraBench (/zh/docs/evaluation/benchmark-hub/mirabench)



## 简介 [#简介]

MiraBench 是 MiraData 引入的长视频生成评测组件。MiraData 是一个带结构化 captions 的 large-scale long-video dataset。MiraBench 从六个角度评估长视频生成：temporal consistency、temporal motion strength、3D consistency、visual quality、text-video alignment 和 distribution consistency。官方 scorer 暴露 17 个指标，包括 DINO/CLIP temporal consistency、RAFT-style motion strength、3D reconstruction errors、aesthetic/imaging quality、ViCLIP alignment、FVD、FID 和 KID。

WorldFoundry 已经把 MiraBench runtime 集成在 `worldfoundry/evaluation/tasks/execution/runners/mirabench/runtime/mirabench`，公开 runner 是 `worldfoundry/evaluation/tasks/execution/runners/mirabench/run_mirabench_official_runner.py`。

官方参考：

* Project page: [mira-space.github.io](https://mira-space.github.io/)
* Paper: [arXiv:2407.06358](https://arxiv.org/abs/2407.06358)
* Dataset: [TencentARC/MiraData](https://huggingface.co/datasets/TencentARC/MiraData)
* Official source reference: [mira-space/MiraData](https://github.com/mira-space/MiraData)

## 评测协议 [#评测协议]

MiraBench 使用带结构化 captions 的 metadata CSV。WorldFoundry 内置了官方 example files：

```text
worldfoundry/data/benchmarks/assets/mirabench/data/evaluation_example/meta_generated.csv
worldfoundry/data/benchmarks/assets/mirabench/data/evaluation_example/meta_gt.csv
```

完整运行时准备一个包含以下列的 `meta_generated.csv`：

```text
video_idx,video_path,short_caption,dense_caption,main_object_caption,background_caption,style_caption,camera_caption
```

runner 会根据 `video_idx` materialize generated-video paths，因此生成视频按下面方式放置：

```text
/path/to/mirabench/generated_videos/
  1.mp4
  2.mp4
  ...
  150.mp4
```

canonical benchmark prompt set 包含 150 条 prompts。需要缺失视频直接失败时使用 `--strict`。

主指标是 `mirabench_average`。

| Metric                                                                                                      | 含义                          |
| ----------------------------------------------------------------------------------------------------------- | --------------------------- |
| `dynamic_degree`, `tracking_strength`                                                                       | 运动强度和长程 tracking strength。  |
| `dino_temporal_consistency`, `clip_temporal_consistency`, `temporal_motion_smoothness`                      | 时序结构、语义连续性和运动平滑度。           |
| `mean_absolute_error`, `root_mean_square_error`                                                             | 3D consistency errors；越低越好。 |
| `aesthetic_quality`, `imaging_quality`                                                                      | 视觉质量指标。                     |
| `camera_alignment`, `main_object_alignment`, `background_alignment`, `style_alignment`, `overall_alignment` | 结构化 caption alignment 指标。   |
| `fvd`, `fid`, `kid`                                                                                         | 分布指标；越低越好。                  |
| `mirabench_average`                                                                                         | 官方 aggregate，或可用指标的均值。      |

## 数据与权重准备 [#数据与权重准备]

从 WorldFoundry 仓库根目录开始：

```bash
cd /path/to/WorldFoundry
export WORLDFOUNDRY_MIRABENCH_META_CSV=/path/to/mirabench/meta_generated.csv
export WORLDFOUNDRY_MIRABENCH_GT_META_CSV=/path/to/mirabench/meta_gt.csv
export WORLDFOUNDRY_GENERATED_ARTIFACT_DIR=/path/to/mirabench/generated_videos
```

如果需要官方 released metadata，可以从 Hugging Face 下载 MiraData metadata：

```bash
hf download TencentARC/MiraData \
  --repo-type dataset \
  --local-dir /path/to/datasets/MiraData
```

准备 `calculate_score.py` 使用的 scorer checkpoints：

```bash
export WORLDFOUNDRY_MIRABENCH_CKPT_PATH=/path/to/mirabench/data/ckpt
export WORLDFOUNDRY_MIRABENCH_SCORER_BACKEND=official
export WORLDFOUNDRY_MIRABENCH_DEVICE=cuda
```

快速本地 wiring run 可以设置 `WORLDFOUNDRY_MIRABENCH_SCORER_BACKEND=mock` 写出 deterministic placeholder metrics。这个 backend 不能用于报告 benchmark 数字。

## 生成候选视频 [#生成候选视频]

使用 `meta_generated.csv` 里的 `dense_caption` 或 `short_caption` 字段作为生成 prompts。对于 WorldFoundry 已集成模型，使用对应 synthesis workflow 跑这些 prompts，然后按 `video_idx` 导出一个视频：

```text
/path/to/mirabench/generated_videos/
  1.mp4
  2.mp4
  ...
```

## 运行 Official Scoring [#运行-official-scoring]

运行仓内 MiraBench official scorer：

```bash
cd /path/to/WorldFoundry

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/mirabench/run_mirabench_official_runner.py \
  --run-official \
  --meta-csv "${WORLDFOUNDRY_MIRABENCH_META_CSV}" \
  --generated-artifact-dir "${WORLDFOUNDRY_GENERATED_ARTIFACT_DIR}" \
  --output-dir tmp/mirabench/official-run \
  --strict \
  --json
```

official backend 会 dispatch 仓内 `calculate_score.py`，materialize 一个带绝对视频路径的 generated meta CSV，并把产出的 `average_score.csv` 转成 WorldFoundry scorecard。

## 导入已有结果 [#导入已有结果]

如果你已经有 MiraBench `average_score.csv` 或等价 JSON/CSV result export，可以直接导入：

```bash
cd /path/to/WorldFoundry

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/mirabench/run_mirabench_official_runner.py \
  --official-results-path /path/to/mirabench/average_score.csv \
  --meta-csv "${WORLDFOUNDRY_MIRABENCH_META_CSV}" \
  --generated-artifact-dir "${WORLDFOUNDRY_GENERATED_ARTIFACT_DIR}" \
  --output-dir tmp/mirabench/imported \
  --json
```

也可以通过统一 benchmark 入口导入同一个结果：

```bash
worldfoundry-eval zoo benchmark-run \
  --benchmark-id mirabench \
  --mode official-validation \
  --official-results-path /path/to/mirabench/average_score.csv \
  --generated-artifact-dir "${WORLDFOUNDRY_GENERATED_ARTIFACT_DIR}" \
  --output-dir tmp/mirabench/official-validation \
  --json
```

## 输出文件 [#输出文件]

运行会写出：

* `scorecard.json`: WorldFoundry 统一 scorecard，包含可用 MiraBench metrics。
* `mirabench_average_score.json`: official average score output 的 normalized copy。
* `raw_metric_table.jsonl`: scorecard 使用的 metric rows。
* `per_sample_scores.jsonl`: 当结果文件暴露 sample-level values 时写出逐视频结果。
* `upstream_scorer/`: 使用 `--run-official` 时 materialized meta CSV、extracted frames 和 official scorer outputs。

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