Registry 与参考

MetricRegistry

默认 registry 从 registry.py 的 BUILTIN_METRIC_REGISTRY_ENTRIES 加载全部内置条目。

发现与查询

worldfoundry-eval metric list
worldfoundry-eval metric list --json

worldfoundry-eval metric show fid
worldfoundry-eval metric show clip-score --json

worldfoundry-eval metric validate fid clip_score has_artifact:generated_artifact

Registry key 大小写不敏感，下划线会归一化为连字符（clip_score、clip-score、clipscore 等价）。参数化 id 使用前缀：

• has_artifact:<name> — 示例：has_artifact:generated_artifact。指定 artifact 存在时返回 1。
• numeric:<name> — 示例：numeric:reward。从 result metadata/scores 读取名为 <name> 的数值字段。

Python API

from worldfoundry.evaluation.tasks.metrics.registry import (
    default_metric_registry,
    list_metric_registry_entries,
    validate_metric_ids,
    create_existing_results_metric,
)

for entry in list_metric_registry_entries():
    print(entry.id, entry.family, entry.aliases)

registry = default_metric_registry()
entry = registry.get("clip-score")
canonical = registry.canonical_metric_id("numeric:reward")

payload = validate_metric_ids(["fid", "unknown_metric"])
assert payload["ok"] is False

metric = create_existing_results_metric(
    metrics=["artifact_count", "has_artifact:video"],
    required_artifacts=["generated_artifact"],
)

已注册指标

方向：↑ 越高越好，↓ 越低越好。

图像分布（family=distribution）

比较 reference 与 generated 图像集合的 set-level 指标。Torch-fidelity 系列（fid/、kid/、inception_score/ 等）共用 _shared/vendor/torch_fidelity/；独立实现包括 Clean-FID、CMMD、IPR、Vendi、Rarity 以及 fwd/vendor/pytorchfwd。

from worldfoundry.evaluation.tasks.metrics import (
    compute_distribution_metrics,
    compute_fid,
    compute_inception_score,
    compute_clip_fid,
    compute_cmmd,
    compute_clean_fid,
    compute_fwd,
    compute_improved_precision_recall,
    compute_vendi_score,
    compute_mean_rarity_score,
)

scores = compute_distribution_metrics(
    "/path/to/reference",
    "/path/to/generated",
    metrics=("fid", "kid", "prc"),
)

fid = compute_fid("/path/to/reference", "/path/to/generated")
clip_fid = compute_fid("/path/to/reference", "/path/to/generated", feature_extractor="clip-vit-b-32")
is_scores = compute_inception_score("/path/to/generated")
cmmd = compute_cmmd("/path/to/reference", "/path/to/generated")
clean_fid = compute_clean_fid("/path/to/reference", "/path/to/generated")
fwd = compute_fwd("/path/to/reference", "/path/to/generated")
ipr = compute_improved_precision_recall("/path/to/reference", "/path/to/generated")
vendi = compute_vendi_score(feature_matrix)

FID、KID、Inception Score、precision/recall、MIND 和 compute_distribution_metrics(...) 接受图片目录或明确的图片文件列表。列表保留传入顺序，与目录使用相同的 RGB 转换和 samples_resize_and_crop 预处理。SwAV FID 也接受文件列表，并沿用自身的预处理及 max_size 上限。

内置后端通过 worldfoundry.evaluation.tasks.metrics._shared.vendor.torch_fidelity 加载，与已安装的 torch_fidelity 包及 TorchMetrics 的导入顺序相互独立。自定义特征提取器和噪声源需注册到该内置包。PPL 也接受外部包的生成器 wrapper，保留其潜变量和类别信息。

compute_realism_score(...) 接受生成图片目录、单个图片文件、数组，以及文件与数组组成的序列。目录批次中的每张图片分别产生一个 realism 分数；mean_realism 是逐图分数的均值，不受 batch size 影响。

Precision 表示生成样本被参考流形覆盖的比例，recall 表示参考样本被生成流形覆盖的比例。在 compute_precision_recall(...) 和 compute_distribution_metrics(...) 中，后端 input1_* 参数对应生成输入，input2_* 参数对应参考输入。批量接口也在生成集上计算 Inception Score。

compute_ppl(...) 返回后端的均值与标准差。设置 ppl_reduction="none" 时，还会保留 perceptual_path_length_raw NumPy 数组，包含经过百分位过滤后的逐样本距离。summarize_distribution_metrics(...) 将该键改名为 ppl_raw，同时保留数组。

PPL 默认保留第 1 至第 99 百分位范围。将 ppl_discard_percentile_lower 或 ppl_discard_percentile_higher 设为 None，可独立关闭对应边界。对于生成器实例和 module wrapper，条件采样读取模型的 num_classes，成对的潜变量样本使用相同标签。

SceneFID manifest 的 key 可以是相对于图片根目录的路径或绝对路径。省略 generated_bboxes_json 时，参考 key 会按相对路径复用于生成目录，保留子目录层级；绝对参考路径必须位于参考根目录下。缺少图片时会报错，不会回退到其他同名文件。生成图片的文件名或 bbox 不同时，应提供独立的生成 manifest。

SceneFID、LQS 和 object-wise consistency 共用 bbox 约定：四值表示 (x1, y1, x2, y2)，五值表示 (x, y, width, height, extra)，第五项不参与几何计算。像素坐标与归一化坐标使用相同格式；四值 xywh 输入需在调用前转换。

LQS 在同类别内按最小总中心距离匹配对象，支持两侧数量不同。召回率为匹配数量除以真实对象数量，精确率为匹配数量除以预测对象数量；位置和面积一致性使用已匹配的对象对。匹配目标和对象计数分母依据 LQS 定义，使用 SciPy 的矩形指派求解器替代全排列枚举。

视频分布（family=distribution，video tags）

import numpy as np
from worldfoundry.evaluation.tasks.metrics import (
    compute_fvd_from_numpy,
    compute_fvd_from_frame_dirs,
    compute_fid_vid,
    compute_fvmd,
    compute_jedi_from_features,
)

# uint8 数组形状：(N, T, H, W, C)
fvd = compute_fvd_from_numpy(real_videos, gen_videos, device="cuda")

fvd = compute_fvd_from_frame_dirs(
    reference_frame_dirs=["/path/to/ref_frames/video_0"],
    generated_frame_dirs=["/path/to/gen_frames/video_0"],
)

fid_vid = compute_fid("/path/to/ref_frames", "/path/to/gen_frames")  # 别名 fid_vid
fvmd = compute_fvmd("/path/to/reference_videos", "/path/to/generated_videos")

jedi = compute_jedi_from_features(train_features, test_features)

JEDiMetric.load_features(num_samples=...) 对缓存数组与新提取的特征使用相同的单侧样本上限；读取缓存不会截短磁盘上的文件。特征提取在本地运行，不创建或销毁分布式进程组，加载两侧特征后释放提取器。

JEDi 视频批次使用 (B, T, C, H, W)，像素范围为 [0, 1]；提取器先转换为通道在首维的视频片段，再执行归一化。Encoder 和 probe checkpoint 必须与模型匹配；缺少权重或形状不匹配时直接报错，不会保留初始化权重继续计算。

使用预计算特征时，run_jedi_scorer(...) 报告实际的 reference_num_samples、generated_num_samples 和 feature_dim。原有 num_samples 字段在两侧数量相等时记录共同数量，不相等时为 null。

Mock JEDi 后端直接用 UTF-8 seed 字节构造 NumPy 种子。相同 seed 和维度在独立进程中产生相同的特征与分数。

感知成对（family=perceptual）

reference 与 generated 图像之间的成对相似度（条件一致性、重建质量）。

import numpy as np
from worldfoundry.evaluation.tasks.metrics import (
    compute_lpips,
    compute_ssim,
    compute_ms_ssim,
    compute_psnr,
    compute_perceptual_bundle,
    compute_dino_similarity,
    compute_dreamsim,
)

ref = np.load("reference.npy")
gen = np.load("generated.npy")

bundle = compute_perceptual_bundle(ref, gen)
dino_sim = compute_dino_similarity(ref, gen)
dreamsim_dist = compute_dreamsim(ref, gen)

PSNR、SSIM、MS-SSIM 和 FSIM 保留输入像素尺度，两张图必须使用相同单位。任一输入是 uint8 或任一最大值超过 1 时，data_range 默认为 255，否则为 1。浮点像素值不足以判断预期值域时，应显式传入 data_range；该参数按原始单位传给后端。

LPIPS 接受 uint8 像素或 [0, 1] 归一化浮点数，使用 TorchMetrics 的 normalize=True。为兼容已有调用，任一浮点图像最大值超过 1 时，也按 [0, 255] 处理。两张图始终共用一个归一化尺度。

CLI 接口

• worldfoundry-eval metric list — 列出或 JSON 导出全部 registry 条目。
• worldfoundry-eval metric show <id> — 查看单条 entry、别名、参数化前缀。
• worldfoundry-eval metric validate <id>... — 批量解析 id；未知 id 时 exit 1。
• worldfoundry-eval evaluate --metric ... — 仅内置 existing-results 指标（artifact_count、required_artifacts_present、has_artifact:<name>、numeric、numeric:<name>）。
• worldfoundry-eval plan create --metric ... — 构造 run plan JSON 时使用相同内置 metric ID。

分布与感知类指标目前通过 Python 调用。Benchmark runner 在计算官方 metric stack 时可能复用相同底层实现（EvalCrafter IS/FID、MiraBench FVD 等）。多模态 scorer（CLIPScore、VQAScore、ITMScore）通过 worldfoundry.evaluation.tasks.metrics.get_score_model(...) 暴露，实现位于 execution/runners/_scorers/。

依赖

安装 distribution-metrics extra 以使用 torch-fidelity、Clean-FID、CMMD、感知 torchmetrics 等：

pip install -e ".[distribution_metrics]"

distribution_metrics extra 核心依赖包括 torch、torchvision、torchmetrics、scikit-learn、scipy、transformers、pillow，以及 pyproject.toml 中声明的可选 metric 包。

重依赖保持 lazy import：导入 worldfoundry.evaluation.tasks.metrics 不应要求所有 checkpoint 已就绪，直到具体 compute_* 被调用。

修改指标时，请用有代表性的输入与上游实现比对分数，并记录后端版本和结果。私有指标回归测试未包含在公开仓库中。

Checkpoint 与环境变量

FVD 解析顺序见 fvd/fvd_core.py：显式 i3d_checkpoint → WORLDFOUNDRY_FVD_I3D_CKPT → WORLDFOUNDRY_MIRABENCH_FVD_I3D_CKPT → WORLDFOUNDRY_CKPT_DIR 下路径。

架构

worldfoundry/evaluation/tasks/metrics/
├── _base.py             # MetricModuleSpec 协议 + registry entry 工厂
├── _discover.py         # 从各 metric 文件夹自动发现 METRIC_MODULE
├── _shared/             # 跨 metric 基础设施（distribution helper、torch-fidelity loader）
│   └── vendor/torch_fidelity/  # Vendored torch-fidelity（Apache-2.0）
├── registry.py          # MetricRegistryEntry、MetricRegistry、legacy + discovered entries
├── fid/ kid/ …          # 每个分布 metric 一个文件夹（METRIC_ID、compute、METRIC_MODULE）
├── lpips/ ssim/ …       # 每个成对感知 metric 一个文件夹
├── fvd/ fvmd/ opens2v/ sadpad/  # 视频分布 + OpenS2V + SadPaD
├── cmmd/ clean_fid/ vendi_score/ …      # 独立分布 helper
└── jedi/                # Video JEPA distance（wrapper.py + vendored JEDi）

统一 metric 模块布局

每个已迁移的 metric 文件夹导出统一接口：

• METRIC_ID、ALIASES、HIGHER_IS_BETTER、FAMILY、TAGS — Registry 元数据
• METRIC_MODULE — 供 auto-discovery 的 :class:MetricModuleSpec
• compute(...) / compute_<name>(...) — 按 metric family 的稳定 compute API
• 论文 / 仓库链接 — 见 指标配方子页面 各 metric 小节内联说明

已迁移 metric 的 registry entry 通过 _discover.discover_metric_registry_entries() 注册，而非在 registry.py 中硬编码重复项。

Import 入口

顶层 metrics/__init__.py 从各 per-metric 模块 re-export compute_* 函数，保持 from worldfoundry.evaluation.tasks.metrics import compute_fid 等现有 import 可用。

Benchmark catalog metric 与官方结果归一化在 execution/runners/ 完成；benchmark-specific 配置应写在对应的 Benchmark Hub 子页面。

相关页面

• Evaluation — run 契约、evaluate 与 scorecard 输出。
• Benchmark Hub — 每个 benchmark 的指标、资产与运行命令。
• Local asset preparation — checkpoint 准备，含 FVD I3D 权重。