fix(eval): address #1380 review (cache filename, registry, deps, warn)

- README: correct the documented cache filename to
  ``${FASTVIDEO_EVAL_CACHE}/fvd/real_features_{extractor}.pt`` — the file
  is per-extractor partitioned since CLIP and VideoMAE landed; the old
  ``real_features.pt`` form is never used.
- test_registry: include ``common.fvd`` in ``_CORE_METRICS`` so a
  decorator/import-time breakage on this top-level metric surfaces in CI
  rather than at runtime, alongside the other structurally-similar
  top-level common metrics already in the tuple.
- metric.dependencies: declare ``transformers`` (used by the CLIP and
  VideoMAE extractors). Already in base deps so the registry pre-import
  check passes today; futureproofs if transformers ever moves to an extra.
- accumulate: ``warnings.warn`` when ``sample["reference"]`` is silently
  ignored because reference features are already loaded (from cache or an
  earlier accumulate call). Surfaces the foot-gun rather than producing a
  plausible-but-wrong score.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: shaoxiongduan

fastvideo/eval/README.md

@@ -273,7 +273,7 @@ ev.evaluate(samples=[
 # corpus result is in the returned EvalResults.corpus["common.fvd"]
 ```
 
-Reference features are cached to ``${FASTVIDEO_EVAL_CACHE}/fvd/real_features.pt``
+Reference features are cached to ``${FASTVIDEO_EVAL_CACHE}/fvd/real_features_{extractor}.pt``
 the first time ``sample["reference"]`` is passed; subsequent runs load
 the cache automatically. Override with ``$FASTVIDEO_FVD_REF_FEATURES``
 or the ``cache_path=`` constructor kwarg.

fastvideo/eval/metrics/common/fvd/metric.py

@@ -157,7 +157,7 @@ class FVDMetric(BaseMetric):
     requires_reference = False  # uses cached real features, not per-sample ref
     higher_is_better = False  # lower FVD = better
     needs_gpu = True
-    dependencies = ["huggingface_hub", "scipy"]
+    dependencies = ["huggingface_hub", "scipy", "transformers"]
 
     def __init__(
         self,
@@ -234,6 +234,18 @@ def accumulate(self, sample: dict) -> None:
                     ref = ref.unsqueeze(0)
                 self._real_features = _extract_chunked(self._extractor, ref, self._chunk)
                 self._save_cache(self._real_features)
+        elif sample.get("reference") is not None:
+            # Reference features already exist (from cache or an earlier
+            # accumulate call). Silently dropping ``sample["reference"]``
+            # would be a foot-gun for callers expecting per-sample-reference
+            # semantics — warn so the mismatch surfaces.
+            warnings.warn(
+                "common.fvd: sample['reference'] ignored because reference features "
+                "are already loaded (from cache or a prior accumulate call). Pass the "
+                "entire reference set on a single accumulate() call, or pre-build the "
+                f"cache at {self.cache_path}.",
+                stacklevel=2,
+            )
 
     def finalize(self) -> MetricResult:
         """Compute FVD from all accumulated generated features vs. real features."""

fastvideo/tests/eval/test_registry.py

@@ -18,6 +18,7 @@
     "common.psnr",
     "common.ssim",
     "common.lpips",
+    "common.fvd",
     "optical_flow.gt_optical_flow",
     "optical_flow.synthetic_optical_flow",
     "physics_iq",