Skip to content

feat: add optional SeaCache probe for DBCache - #1370

Merged
DefTruth merged 2 commits into
mainfrom
dev
Nov 19, 2026
Merged

DefTruth merged 2 commits into
mainfrom
dev

Conversation

@DefTruth

Copy link
Copy Markdown
Member

Summary

Add SeaCache as an opt-in, model-agnostic probe metric inside DBCache. It applies the official separable SEA/Wiener filter before the existing relative-L1 decision; it does not introduce a new CacheType or calibrator.

Related to #1363.

What changed

  • Add cache_contexts/seacache_uitls.py with fp32 FFT/iFFT, mean-normalized gains, flow/VP/explicit AB schedules, and dense/packed image/video geometry validation.
  • Add DBCacheConfig(enable_seacache=False) plus seacache_mode, seacache_feature_shape, seacache_power_exp, and seacache_ab_schedule; expose matching YAML and CLI options.
  • Keep the default CacheType.DBCache, artifact names, buffers, cache guards, and execution path unchanged when disabled.
  • Preserve the original patchable CachedContextManager.similarity() body. Only can_cache() dispatches to the new seacache_similarity() when explicitly enabled, retaining the SGLang patch point.
  • Store raw Fn values and filtered SEA indicators separately, so third-party Fn-prefix apply_cache() never consumes a filtered tensor as a cache value.
  • Preserve each anchor's own AB coefficients, reuse the current indicator on a miss, and leave both anchors unchanged on a hit.
  • Support CP, uneven Ulysses-Anything shards, TP, CP+TP, and CP+CFG diff reuse. CP restores global geometry before FFT; TP filters channel shards independently; existing reductions keep rank decisions consistent.
  • Resolve parallel metadata lazily through weak transformer references because cache enablement precedes parallel dispatch; disable clears all SeaCache runtime references.
  • Add generic API/distributed tests, a YAML example, user documentation, and versioned research records.

This is a DBCache Fn-probe adaptation, not a reproduction of the official whole-step execution path. Missing scheduler coefficients or incompatible geometry fail loudly instead of silently using raw L1.

Tests and compatibility

  • 351 passed across SeaCache, all related calibrators, config/reset, and distributed regressions.
  • 23 SGLang cache-dit integration tests passed; downstream behavior probes 8/8; adapter registry unchanged.
  • All relevant pre-commit hooks pass.
  • Coverage includes an independent NumPy filter reference, dense/packed image and video equivalence, dtype restoration, flow/VP/AB schedules, per-anchor AB timing, invalid metadata, guards, hit/miss anchor semantics, raw-vs-filtered Fn values, repeated requests, reset/disable, calibrator composition, zero-cache bit-exact behavior, YAML/CLI, 2-rank equal/uneven CP, TP2, 4-rank CP+TP, and CP+CFG diff reuse.
  • Distributed tests compare real can_cache() diff and decisions against a single full-tensor reference on every rank.

FLUX.1-dev E2E

Environment: RTX PRO 5000, physical GPU 2, torch 2.15.0+cu132, 1024x1024, 28 steps, seed 0. Cached arms use compile, F1B0, warmup 8, and max continuous cached steps 3. SeaCache uses flow mode, global geometry 64x64, and power exponent 2.

Config Latency Peak memory Cache Steps PSNR / SSIM vs base PSNR / SSIM vs compile
Base eager 16.91s 33.82GiB 0 — —
Compile 14.89s 33.82GiB 0 — —
Compile + DBCache reuse, rdt=0.12 8.67s 33.87GiB 12 27.95 / 0.9620 28.09 / 0.9643
Compile + SeaCache, rdt=0.12 11.77s 33.89GiB 6 29.03 / 0.9700 29.52 / 0.9749
Compile + SeaCache, rdt=0.24 8.19s 33.89GiB 13 27.52 / 0.9534 27.80 / 0.9576
Compile + SeaCache, rdt=0.24 repeat 8.18s 33.89GiB 13 28.56 / 0.9537 28.89 / 0.9575

Same-config repeat for SeaCache rdt=0.24: 33.46dB / 0.9887 SSIM.

At the same rdt=0.12, SeaCache halves cache hits and is slower than reuse while improving precision. At rdt=0.24 it reaches a similar hit count, but does not show a stable precision advantage. FFT cost and compile/image noise prevent a universal speed or quality ranking. This is a single-prompt wiring probe, not a claim that SeaCache generally outperforms DBCache.

Ulysses CP2

Config Latency Peak memory Cache Steps
CP2 + DBCache, rdt=0.12 5.77s 33.84GiB 12
CP2 + SeaCache, rdt=0.12 7.81s 33.87GiB 6

PSNR/SSIM between the CP2 outputs: 31.37 / 0.9728. Single-card and CP2 SeaCache diff distributions match; both complete without hangs or rank-divergent decisions.

Visual comparison

All outputs preserve the cat, sign, and Hello world text; no black images or structural corruption were observed.

FLUX SeaCache comparison

@DefTruth
DefTruth merged commit 50539e9 into main Nov 19, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant