GitHub - Hyp3R0d/TARDIS: TARDIS is a causal video-generation framework for temporal consistency that transports predictable content from previous frames via confidence-weighted motion transport, projects the residual into a transport-orbit tangent space (handled by a deterministic corrector) versus a normal quotient space (handled by diffusion)

TARDIS 连续视频生成框架

TARDIS（Transport-Aligned Residual Diffusion in Innovation Subspaces）是一个用于连续视频生成的完整框架。它解决的核心问题很直观：视频相邻画面大多没有变化，如果每一帧都从头生成，就会重复计算，也更容易出现人物、物体和背景抖动。

我们的做法是先把上一帧中可以继续沿用的内容“搬运”到当前帧，再只对真正发生变化的部分进行扩散生成。模型会结合运动信息和可见性判断完成跨帧对齐，把画面分成稳定的传输部分和需要更新的创新部分；风险路由器进一步挑出最值得计算的区域，稀疏残差扩散只处理这些局部变化。生成结果随后写回因果状态，供下一帧继续使用。这样既能减少无效计算，也能让连续镜头中的主体、场景和纹理更加稳定，同时保持清晰的细节和较好的感知质量。

本项目客户端采用 HarmonyOS ArkUI 声明式 UI 框架开发，配套 TARDIS 推理服务端提供连续视频生成能力。

项目的核心原则可以概括为一句话：

先传输可预测世界，再只扩散不可预测事件。

相邻视频帧中的背景、主体和纹理通常可以由历史状态和运动关系解释。TARDIS 先把上一帧的生成状态对齐到当前坐标系，再在传输轨道之外的创新空间中进行稀疏残差扩散，把计算预算留给真正需要更新的区域。

推理结果集中展示

若可视化结果加载不完全请等待3-5秒或刷新

这里集中展示 TARDIS 在城市夜景、科幻空间、人物肖像、自然环境与多种艺术风格中的生成效果。可以直接观察画面构图、主体清晰度、光影层次、环境细节和连续镜头的整体观感。

1. 十六组生成场景

十六组场景涵盖霓虹城市、科幻机甲、轨道空间、电影动作、自然生灵和幻想世界，集中呈现 TARDIS 面对不同题材时的画面表现。

场景展示	场景展示
Cyberpunk city	Rain alley
Sci-fi mecha	Lunar lab
Oil seaside	Fantasy forest
Action thriller	Pixel RPG
Arctic wolf	Xianxia cliff
Japan animation	Wildlife close-up
Cyberpunk operative	Hard-surface mecha
Orbital astronaut	Snow leopard

2. 画面对比

实验室、电影街景、太空舱、现实厨房、霓虹雨巷与黑白人像共同构成这组画面对比。重点可以放在人物轮廓、空间关系、材质质感、光照反射和背景细节上。

3D 写实场景：未来实验室、电影街景与太空舱

Future laboratory, cinematic street and astronaut capsule

写实厨房

霓虹雨巷

黑白电影人像

五类风格场景：美式卡通客厅、黏土夜市、未来实验室、太空舱与铅笔画咖啡馆。

这组画面覆盖室内生活、夜间街市、未来空间与手绘场景。不同材质和光照条件下，主体轮廓、环境层次和画面风格均可直接对照。

3. 更多场景效果

现实厨房、电影街景、美式卡通客厅、黏土夜市、未来实验室、霓虹雨巷、太空舱、铅笔画咖啡馆和黑白电影人像展示了 TARDIS 对不同画面语言的适应能力。

场景	完整画面	局部细节展示
写实厨房
电影街景
美式卡通客厅
黏土夜市
未来实验室
霓虹雨巷
太空舱
铅笔画咖啡馆
黑白电影人像

左侧呈现完整构图，右侧帮助聚焦人物、物体和环境中的关键细节。多种场景放在一起，可以更直观地观察主体表现、空间层次和风格完成度。

4. 相同主题下的效果对照

现实厨房、霓虹雨巷和黑白电影人像采用相同主题分别生成。每组汇集 TARDIS 与五种其他结果，便于直观比较构图、人物表现、局部细节和环境氛围。

写实厨房

TARDIS	ZeroScope	Pyramid Flow

Transformer-T2V	ModelScope T2V	Wan2.1 T2V

霓虹雨巷

TARDIS	ZeroScope	Pyramid Flow

Transformer-T2V	ModelScope T2V	Wan2.1 T2V

黑白电影人像

TARDIS	ZeroScope	Pyramid Flow

Transformer-T2V	ModelScope T2V	Wan2.1 T2V

实机演示

下面展示 TARDIS 从运行、连接到生成和桌面创作的完整过程。

训练过程	连接过程	生成过程

桌面端创作流程：选择参考画面、输入创意、等待生成并查看结果。

桌面端界面展示：

准备创作	生成中	查看与保存结果

除 Electron 桌面客户端外，本项目还采用华为 UI Engine（HarmonyOS ArkUI 声明式 UI 框架）开发了移动端创作客户端，源码位于 UI/ 目录。该客户端复刻桌面端完整创作链路：提示词输入（512 字符上限）、参考图选择与预览、画质/画幅/帧率/时长/音效设置、异步任务提交与状态轮询、生成完成后在应用内播放视频，并保留本地创作记录；接口契约与 tardis-client 一致（POST /api/generations 创建任务、GET /api/generations/{id} 轮询状态）。使用 DevEco Studio 打开 UI/ 目录构建 HAP，即可在 HarmonyOS 手机、平板或 2in1 设备上实机运行。

部署与接口速查

本节是 README 级别的可复制入口；字段级约束、错误包络和安全边界以仓库外的 API.md（TARDIS 推理服务端 v1 契约）为准。训练与推理使用不同节点：训练节点为 NVIDIA RTX 4090（24 GB），推理节点为 NVIDIA RTX 5060（8 GB）。正式配置固定为 Python 3.12、PyTorch 2.8、bf16 AMP、16 帧训练 clip、两步 endpoint update、batch 1、 active ratio 0.35、VAE slicing 和因果状态缓存；训练使用 micro batch 1、梯度累计 4、 EMA 0.999、gradient checkpointing，验证集 TC/LPIPS 加权分数选择 best.pt。

cd /path/to/project
python3.12 -m venv .venv && source .venv/bin/activate
python -m pip install -e .
export TARDIS_STORAGE_ROOT=/root/autodl-tmp/TARDIS
export TARDIS_DATASETS_FILE=/path/to/project/datasets.txt
TARDIS_DATASET=dataverse bash scripts/train.sh
TARDIS_DATASET=dataverse TARDIS_CHECKPOINT=$TARDIS_STORAGE_ROOT/checkpoints/dataverse/<run>/best.pt bash scripts/infer.sh
TARDIS_DATASET=dataverse TARDIS_CHECKPOINT=$TARDIS_STORAGE_ROOT/checkpoints/dataverse/<run>/best.pt \
  TARDIS_PROMPT='A cinematic robot walks through a rainy neon street' bash scripts/apply.sh

预训练衔接、后训练与微调

像素生成先验（VAE、文本编码器和首帧先验）以冻结权重加载；本仓库训练的是时域增量参数，包括 motion、transport、state、router、lite_corrector、keyframe_residual_dit、residual teacher/student 和 metric_adapter。三个数据集分别建立运行目录、优化器状态和 EMA，禁止在同一训练进程中混合数据源。正式数据契约为 512x512、16 帧窗口、30 FPS metadata、split seed 3407。

阶段	可训练模块	输入窗口	作用
预训练衔接	`keyframe_residual_dit`、`lite_corrector`	1 帧	从 identity-preserving 初值启动增量分支
时序适配	motion、transport、state、lite	16 帧	学习运动传播、可见性和状态更新
后训练	router、residual teacher/student、metric adapter 逐阶段解冻	16 帧	闭环、因果蒸馏以及 TC/LPIPS 对齐
部署推理	EMA shadow（无梯度）	16 帧或按时长展开	两步 endpoint 轨迹生成 MP4

后训练由 scripts/train.sh 统一承载，不需要另一个训练服务。TARDIS_TRAIN_MODE 选择参数所有权：keyframe_only 只训练关键帧残差 DiT 和轻量校正器，full_temporal 训练完整时域模块；TARDIS_CURRICULUM_PROFILE 可选 full、transport、closed_loop_motion 或 metric_alignment，用于完整课程或针对性诊断。后训练以 optimizer step 计数，默认 20 x 64 / 4 = 320 步，课程比例固定为 5%/5%/10%/20%/20%/40%：

课程阶段	预算	teacher forcing	residual steps	新增目标
`transport_warmup`	5%	1.00	0	diffusion、transport、flow、visibility、lite
`router_calibration`	5%	1.00	0	risk field、survival 和 active-token budget
`residual_teacher`	10%	1.00	4	法向创新残差教师
`closed_loop`	20%	1.00 → 0.25	4	自身历史状态、warp consistency、long-term drift
`crcd`	20%	0.25 → 0	1	teacher/student 因果残差蒸馏
`metric_alignment`	40%	0	1	TC、LPIPS、文本对齐和 `metric_adapter`；选择 `best.pt`

P0：关键帧衔接

cd /path/to/project
source .venv/bin/activate
export TARDIS_STORAGE_ROOT=/root/autodl-tmp/TARDIS
export TARDIS_DATASETS_FILE=/path/to/project/datasets.txt
export TARDIS_CHECKPOINT_ROOT="$TARDIS_STORAGE_ROOT/checkpoints"
export TARDIS_OUTPUT_ROOT="$TARDIS_STORAGE_ROOT/outputs"
TARDIS_DATASET=dataverse \
TARDIS_TRAIN_MODE=keyframe_only \
TARDIS_CURRICULUM_PROFILE=transport \
TARDIS_EPOCHS=4 TARDIS_STEPS_PER_EPOCH=64 \
TARDIS_MICRO_BATCH_SIZE=1 TARDIS_GRADIENT_ACCUMULATION_STEPS=4 \
TARDIS_VALIDATION_BATCH_SIZE=2 TARDIS_PRECISION=bf16 \
bash scripts/train.sh

P1：完整时序后训练

TARDIS_DATASET=dataverse \
TARDIS_WARM_START="$TARDIS_CHECKPOINT_ROOT/dataverse/<p0-run>/best.pt" \
TARDIS_WARM_START_USE_EMA=1 \
TARDIS_TRAIN_MODE=full_temporal TARDIS_CURRICULUM_PROFILE=full \
TARDIS_EPOCHS=20 TARDIS_STEPS_PER_EPOCH=64 \
TARDIS_MICRO_BATCH_SIZE=1 TARDIS_GRADIENT_ACCUMULATION_STEPS=4 \
TARDIS_VALIDATION_BATCH_SIZE=2 TARDIS_NUM_FRAMES=16 \
TARDIS_DIFFUSION_STEPS=2 TARDIS_ACTIVE_RATIO=0.35 \
TARDIS_EMA_DECAY=0.999 bash scripts/train.sh

将 TARDIS_DATASET 替换为 openvid 或 seedance 即可分别训练另外两个数据集。TARDIS_WARM_START 只加载权重，不恢复优化器；精确续训则使用 TARDIS_RESUME，并要求数据集、world size、结构签名和精度完全一致：

TARDIS_DATASET=openvid \
TARDIS_RESUME="$TARDIS_CHECKPOINT_ROOT/openvid/<run>/latest.pt" \
TARDIS_PRECISION=bf16 bash scripts/train.sh

跨数据集 warm-start 是显式的 CLI 接口，而不是脚本环境变量。需要时直接调用训练模块并传入 --allow-cross-dataset-warm-start；同数据集 warm-start 不需要该开关：

torchrun --standalone --nproc_per_node=1 -m tardis.cli.train \
  --dataset openvid --datasets-file "$TARDIS_DATASETS_FILE" \
  --warm-start "$TARDIS_CHECKPOINT_ROOT/dataverse/<run>/best.pt" \
  --allow-cross-dataset-warm-start \
  --curriculum-profile metric_alignment --train-mode full_temporal \
  --precision bf16 --epochs 6 --steps-per-epoch 64 \
  --micro-batch-size 1 --gradient-accumulation-steps 4 \
  --validation-batch-size 2

后训练的主要可调接口如下；其余模型结构参数仍沿用本节上方的统一训练参数，并且必须与 checkpoint 签名一致：

参数	默认值	接口语义
`TARDIS_TRAIN_MODE`	`full_temporal`	`keyframe_only` 或 `full_temporal`
`TARDIS_CURRICULUM_PROFILE`	`full`	完整、transport、闭环或指标对齐课程
`TARDIS_WARM_START`	空	只加载指定 checkpoint 权重
`TARDIS_WARM_START_USE_EMA`	`1`	warm-start 使用 EMA shadow
`TARDIS_RESUME`	空	恢复 optimizer、scheduler、AMP scaler、EMA、课程游标和 RNG
`TARDIS_EPOCHS` / `TARDIS_STEPS_PER_EPOCH`	`20 / 64`	总课程预算来源
`TARDIS_MICRO_BATCH_SIZE`	`2`	每卡 micro-batch；正式后训练常设为 `1`
`TARDIS_GRADIENT_ACCUMULATION_STEPS`	`2`	梯度累计；正式后训练常设为 `4`
`TARDIS_VALIDATION_BATCH_SIZE`	`8`	完整 validation 的批大小
`TARDIS_EMA_DECAY`	`0.999`	时域参数 EMA 衰减，冻结先验不进入 shadow
`TARDIS_TC_LOSS_WEIGHT` / `TARDIS_LPIPS_LOSS_WEIGHT`	`5.0 / 3.0`	`metric_alignment` 的双目标权重
`TARDIS_CRCD_LOSS_WEIGHT`	`1.0`	因果残差蒸馏权重
`TARDIS_PRECISION`	`bf16`	`bf16`、`fp16` 或 `fp32`；`fp16` 才启用 GradScaler

AdamW 使用 learning rate 1e-4、weight decay 1e-2、warmup 64 steps、global-norm clipping 1.0；验证时临时交换 EMA 参数，完整 validation 上 TC/LPIPS 组合分数改善才更新 best.pt。test split 不参与后训练、early stopping、调参或权重选择。训练完成后沿用本 README 的 infer.sh 和 apply.sh 接口，默认加载 EMA checkpoint；运行记录应保存 run manifest、数据 manifest hash、结构签名、checkpoint SHA-256、TC/LPIPS 以及资源统计。

桌面客户端只访问本机代理 http://127.0.0.1:8787；代理再向 TARDIS 推理服务端发起 HTTPS 请求，密钥只放在服务端环境变量或桌面端安全存储中。上行创建任务的最小字段为 prompt（必填，最长 512 字符）、可选 imageData（PNG/JPEG Data URL，解码后不超过 5 MB）和 settings（quality、size、fps、duration、withAudio）。本地接口为：

POST http://127.0.0.1:8787/api/generations
Content-Type: application/json

{"prompt":"A cinematic robot walks through a rainy neon street",
 "imageData":"data:image/png;base64,...",
 "settings":{"quality":"speed","size":"1280x720","fps":30,"duration":5,"withAudio":false}}

返回 id、requestId、taskStatus 和 model；客户端随后轮询：

GET http://127.0.0.1:8787/api/generations/{task-id}

下行状态统一为 PROCESSING、SUCCESS 或 FAIL。成功时返回临时 videoUrl、 coverUrl 和元数据，客户端立即下载为 video.mp4、cover.jpg、manifest.json。服务端规范接口对应 POST /tardis/v1/videos、GET /tardis/v1/videos/{id}、 GET /tardis/v1/videos/{id}/content；请求使用 Authorization: Bearer <token>、 Content-Type: application/json、X-Request-ID 和建议的 Idempotency-Key。创建成功返回 202，状态接口返回 queued/running/succeeded/failed/cancelled，建议每 2--5 秒轮询并遵循 Retry-After；常见故障为 401/403/404/409/422/429/503/504。

公网节点的 web-server 只负责 JDK HTTP 运维接口和 Nginx 前置，不承载 GPU 推理。默认应用端口为 8080、Nginx 端口为 80（生产环境改为 TLS 443），核心配置为：

upstream tardis_app { server 127.0.0.1:8080; keepalive 16; }
server {
  listen 80;
  location / { proxy_pass http://tardis_app; proxy_http_version 1.1;
    proxy_set_header Host $host; proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }
  location /tardis/ { proxy_pass http://127.0.0.1:18080/;
    proxy_buffering off; proxy_read_timeout 120s; }
}

GPU 主机通过 SSH 反向隧道主动出站，网关只监听回环端口：

ssh -NT -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
  -o ServerAliveCountMax=3 -R 127.0.0.1:18080:127.0.0.1:8000 \
  tunnel@gateway.example.com

启动运维前置：cd web-server && mvn package && java -jar target/tardis-webserver.jar；容器方式为 docker compose up --build。SSH 账号应仅允许受限 remote forwarding，公网不暴露 GPU 端口、管理端点或本地绝对路径。

系统总览

仓库包含两条彼此独立的运行链路。桌面创作链路面向在线视频生成，使用客户端内置的 Express 代理访问 TARDIS 推理服务端；GPU 研究链路面向 TARDIS 的训练、评测和 prompt-only 推理，直接运行根目录下的 Python CLI。web-server 是可选的 HTTP/运维前置，不是当前客户端的生成 API，也不包含 GPU 推理代码。

桌面创作链路（在线视频 API）
┌──────────────────────────┐   loopback :8787   ┌────────────────────────────┐
│ tardis-client (Electron) │ ─────────────────> │ tardis-client/server        │
│ prompt / reference /     │                    │ Express proxy              │
│ polling / player /       │ <───────────────── │ API key kept server-side   │
│ local archive            │   video + status   └──────────────┬─────────────┘
└──────────────────────────┘                                  │ HTTPS
                                                               ▼
                                                    TARDIS 推理服务端 API

GPU 研究链路（本地或远端 GPU）
┌───────────────────────┐   ┌──────────────────────────┐   ┌─────────────────────┐
│ scripts/train.sh      │──>│ tardis.cli.train         │──>│ checkpoints + logs  │
│ scripts/infer.sh      │──>│ tardis.cli.infer         │──>│ metrics + showcases │
│ scripts/apply.sh      │──>│ tardis.cli.apply         │──>│ MP4 + JSON          │
└───────────────────────┘   │ frozen prior + TARDIS    │   └─────────────────────┘
                            │ TAR / TOQ / IRF-DIS / CIOD│
                            └──────────────────────────┘

可选 SSH 反向代理服务/运维层
┌──────────────────────┐       ┌──────────────┐
│ web-server :8080     │ <──── │ nginx :80    │
│ static / health /    │       │ proxy_pass   │
│ info / metrics /     │       └──────────────┘
│ admin (Basic Auth)   │
└──────────────────────┘

三个工程边界

组件	目录	作用	默认入口
TARDIS GPU 引擎	根目录 `tardis/`、`scripts/`	训练、验证、全量评测、prompt-only 生成	`bash scripts/train.sh`、`infer.sh`、`apply.sh`
SSH 反向代理服务与前置服务	`web-server/`	JDK 17 HTTP 服务、静态资源、健康检查、指标、限流、Basic Auth、nginx 反代；不提供 `/api/generations`	`scripts/start.ps1` 或 Docker Compose
桌面客户端	`tardis-client/`	prompt、参考图、进度轮询、播放、创作记录和本地归档	`npm run desktop:dev` 或打包 EXE

服务端本体是 GPU 上的 Python CLI/推理引擎，不是 FastAPI/Flask 常驻 HTTP API。客户端的生成请求由 tardis-client/server 直接转发到 TARDIS 推理服务端的异步接口；web-server 只承担静态资源和运维接口。若云端部署需要长期 HTTP 入口或反向 SSH 通道，应在部署环境中额外配置受限隧道，并明确映射到实际 API 服务。

方法怎么工作

TARDIS 把连续视频中的每一步生成拆成两个互补动作，读者可以把它理解成“先复用，再补变化”：

TAR（Transport-Aligned Residualization）：从文本和因果状态预测运动，传输上一帧 latent、短期状态和 anchor，并构造当前帧相对于 transport prior 的残差。
DIS（Diffusion in Innovation Subspaces）：通过可见性校准的创新风险路由器选择 active patch，将残差投影到 transport orbit 的法向子空间，仅对风险区域的创新 token 运行稀疏 residual DiT。

一次完整的推理过程大致如下：

prompt
  -> frozen text encoder / TARDIS first-frame prior
  -> frame 0
  -> prompt-conditioned motion scaffold
  -> motion/state transport
  -> transport-orbit quotient projector
  -> innovation risk field + proper time
  -> lite tangent corrector + sparse normal residual diffusion
  -> causal state update
  -> next frame

主要模块位于 tardis/models/：

模块	责任
`priors.py`	冻结 VAE、文本编码器和首帧图像先验
`motion.py`	source-motion teacher 与 prompt-conditioned motion scaffold
`transport.py`	latent warp、visibility 加权、历史状态传输
`quotient.py`	transport Jacobian 轨道、tangent/normal 残差分解
`router.py`、`clock.py`	创新风险、active patch 和事件时间预算
`residual.py`	lite tangent corrector 与 sparse residual DiT
`state.py`	causal state、anchor、scene-cut reset 和长期记忆
`tardis.py`、`factory.py`	主模型编排与 checkpoint-compatible 装配

训练目标同时包含官方 TC、LPIPS、残差扩散、transport、flow/visibility、router、drift、文本和因果创新算子蒸馏项。完整默认值见 scripts/train.sh 和 docs/train.md。

项目结构

project/
├── tardis/                  # TARDIS Python package
│   ├── cli/                  # train / infer / apply / runtime
│   ├── data/                 # dataset contracts, manifest, archive, split
│   ├── models/               # TAR, TOQ, IRF/DIS, state updater
│   ├── training/             # objective, losses, curriculum, EMA, distill
│   ├── metrics/              # TC, LPIPS, FVD, FID, CLIPScore, SSIM
│   ├── experiments/          # benchmarks, ablations, diagnostics, reports
│   └── utils/                # checkpoint, video I/O, resources, randomness
├── scripts/                  # deployment-oriented shell entry points
├── docs/                     # train/infer/apply/dataset documentation
│   └── demo/                 # README GIFs and selected visual evidence
├── appendix/                 # archival competition and development documents
│   ├── competition_requirements.md/.pdf
│   └── (historical records only)
├── tests/                    # unit and integration tests
├── data/                     # .gitkeep only; large datasets stay on data disk
├── checkpoints/              # .gitkeep only; large weights stay on data disk
├── outputs/                  # .gitkeep only; generated outputs stay on data disk
├── web-server/               # JDK HTTP service and nginx configuration
├── tardis-client/            # Electron + React desktop application
├── 实验方案.md                 # benchmark selection and experiment protocol
├── 技术文档.md                 # deployment, protocol, and operations reference
├── datasets.txt              # canonical dataset roots (edit per machine)
├── pyproject.toml            # Python package and dependency contract
├── CITATION.cff              # citation metadata
└── LICENSE                   # Apache License 2.0 for project code

数据集与 benchmark

项目内部固定使用三个 canonical dataset 名称：

canonical name	上游数据源与引用	默认 manifest root
`dataverse`	Vchitect T2V DataVerse	`Vchitect_T2V_DataVerse`
`openvid`	OpenVid-1M	`OpenVid-1M`
`seedance`	seedance-2-prompts-datasets	`seedance-2-prompts-datasets`

默认 datasets.txt 中记录的是：

/home/TARDIS/data/Vchitect_T2V_DataVerse
/home/TARDIS/data/OpenVid-1M
/home/TARDIS/data/seedance-2-prompts-datasets

部署到其他机器时，推荐复制路径文件并设置 TARDIS_DATASETS_FILE，不要把大规模视频复制进 Git。标准 split 使用 train/validation/test 三段，默认 split seed 为 3407；记录数和 manifest 版本应以目标数据盘上的 tardis_manifest.jsonl 与 curation_report.json 为准。

正式 benchmark 设置是 3 个数据集、TARDIS 与 9 个外部对比基线：

#	方法标识	SOTA 对比模型与引用
1	`animatediff_lightning`	AnimateDiff-Lightning
2	`sd_turbo_independent`	SD-Turbo 独立逐帧基线
3	`text2video_zero`	Text2Video-Zero
4	`streamdiffusion_img2img`	StreamDiffusion image-to-video path
5	`rerender_flow`	ReRender-A-Video
6	`tokenflow_core`	TokenFlow
7	`vid2vid_zero_core`	vid2vid-zero
8	`controlvideo_canny`	ControlVideo Canny condition
9	`stablevideo_propagation`	StableVideo propagation

后六类通常属于 source-conditioned 对比，不能与 prompt-only apply 结果混写。实现和分组位于 tardis/experiments/benchmark.py。

用于画面展示的五个外部模型及来源：

模型	来源
ZeroScope	模型页面
Pyramid Flow	项目页面
Transformer-T2V	论文与模型说明
ModelScope T2V	模型页面
Wan2.1 T2V	项目页面

完整来源说明见 docs/demo/model_sources.txt。

GPU 服务端部署

环境

Linux + NVIDIA CUDA GPU；训练和推理默认使用 bf16。
Python >=3.12。
PyTorch >=2.8,<2.9，以及 diffusers、transformers、accelerate、torchvision、av、opencv-python-headless、lpips、open-clip-torch、torchmetrics 等。
可访问模型缓存和数据盘；默认基础先验由 TARDIS 推理服务端提供。

安装：

cd /path/to/project
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

研究/代码质量依赖：

python -m pip install -e '.[dev]'

数据盘和缓存

export TARDIS_STORAGE_ROOT=/root/autodl-tmp/TARDIS
export TARDIS_DATASETS_FILE=/path/to/project/datasets.txt
export TARDIS_CHECKPOINT_ROOT="$TARDIS_STORAGE_ROOT/checkpoints"
export TARDIS_OUTPUT_ROOT="$TARDIS_STORAGE_ROOT/outputs"
export HF_HOME="$TARDIS_STORAGE_ROOT/cache/huggingface"
export TORCH_HOME="$TARDIS_STORAGE_ROOT/cache/torch"

默认脚本会设置 HF_ENDPOINT=https://hf-mirror.com 和 HF_HUB_DISABLE_XET=1；正式实验应记录 manifest、checkpoint SHA-256、模型签名、分辨率、帧数、采样步数、精度和 GPU 型号。

训练

标准入口通过脚本位置推导根目录，提升服务端内容后不需要额外改路径：

cd /path/to/project
source .venv/bin/activate
TARDIS_DATASET=dataverse bash scripts/train.sh

切换数据集：

TARDIS_DATASET=openvid bash scripts/train.sh
TARDIS_DATASET=seedance bash scripts/train.sh

快速 smoke 覆盖项（只用于检查路径和张量形状，不用于正式性能或质量结论）：

TARDIS_EPOCHS=20 \
TARDIS_STEPS_PER_EPOCH=64 \
TARDIS_MICRO_BATCH_SIZE=2 \
TARDIS_GRADIENT_ACCUMULATION_STEPS=2 \
TARDIS_NUM_FRAMES=16 \
TARDIS_DIFFUSION_STEPS=2 \
TARDIS_ACTIVE_RATIO=0.35 \
bash scripts/train.sh

训练在 validation 上使用 TC/LPIPS 选择 best.pt，并保存 latest.pt、日志和统计；test 指标不参与 checkpoint 选择。

全量推理评测

TARDIS_DATASET=dataverse \
TARDIS_CHECKPOINT=/root/autodl-tmp/TARDIS/checkpoints/dataverse/<run>/best.pt \
bash scripts/infer.sh

infer 针对一个数据集完整 test split 生成指标和固定数量 showcase：

outputs/infer/<dataset>/<timestamp>/
├── metrics.xlsx / metrics.csv
├── per_video_details.csv / per_video_details.jsonl
├── failures.jsonl
├── latency.json / resources.json
└── showcases/*.mp4

主指标为官方 TC 和 LPIPS；FVD、FID、CLIPScore、SSIM、warp error、长序列 drift 与延时统计用于诊断。只有在同一协议、同一数据划分和同一硬件上比较时，才应把数字写成性能结论。

Prompt-only 生成

apply 不读取 source video，仅由 prompt 和首帧 prior 启动因果 rollout：

TARDIS_DATASET=dataverse \
TARDIS_CHECKPOINT=/root/autodl-tmp/TARDIS/checkpoints/dataverse/<run>/best.pt \
TARDIS_PROMPT='A small robot walks through a misty bamboo forest at sunrise' \
TARDIS_STYLE=cinematic \
TARDIS_DURATION=2 \
bash scripts/apply.sh

输出：

outputs/apply/<dataset>/<timestamp>/video.mp4
outputs/apply/<dataset>/<timestamp>/video.json

不要把 apply 的 prompt-only 输出写成 source-conditioned video editing。

Web-server 与 SSH 反向代理服务

web-server/ 是 JDK 17 HTTP 服务，提供静态文件、健康检查、服务器信息、运行时指标、CORS、按 IP 限流和 Basic Auth 管理接口。nginx 配置将公网 80 端口反代到应用 8080 端口。

要求 JDK 17+、Maven 3.8+：

cd web-server
.\scripts\start.ps1

脚本默认执行 mvn package 后启动 target/tardis-webserver.jar；需要跳过测试构建时：

.\scripts\start.ps1 -SkipTests

Linux/macOS 等价命令：

cd web-server
mvn package
java -jar target/tardis-webserver.jar

默认监听 0.0.0.0:8080。Docker + nginx：

cd web-server
docker compose up --build

HTTP 接口：

接口	作用
`GET /`	静态首页
`GET /api/health`	健康状态
`GET /api/info`	服务信息
`GET /api/metrics`	请求计数、活跃请求和按路径统计
`GET /admin/info`	Basic Auth 管理信息
`GET /admin/metrics`	受保护的运行时指标

仓库中的 JDK 服务本身不包含 GPU 推理逻辑。若部署环境将它作为 SSH 反向代理服务的 HTTP 前置，运维层可以建立受限隧道：

ssh -N -T \
  -o ExitOnForwardFailure=yes \
  -R <gateway-port>:127.0.0.1:8080 \
  <user>@<gateway-host>

端口、用户、密钥和绑定地址必须按安全组和 SSH 策略配置；不要把管理接口或 SSH 私钥暴露到公网。nginx.conf 中的 proxy_pass 目标也应按实际隧道端口修改。

TARDIS Studio 桌面客户端

客户端界面采用 HarmonyOS ArkUI 声明式 UI 框架的设计理念与交互规范，围绕连续视频创作流程组织操作，并与 TARDIS 推理服务端协同完成生成、进度查看和结果管理。

客户端是 Electron + React + Vite 应用，支持：

prompt 必填，最多 512 个字符；
PNG/JPG/JPEG 参考图上传，并在对话框上方即时预览；
画幅、时长、FPS、质量和音效选项；
异步任务提交与 /api/generations/:id 轮询进度；
完成后在桌面窗口内播放视频；
侧边栏创作记录；
下载视频、封面和 manifest.json 到本地归档；
Electron safeStorage 保存 API Key，渲染层不接触明文密钥。

开发运行：

cd tardis-client
npm install
npm run desktop:dev

只调试网页界面时可使用 npm run dev；完整桌面链路使用 desktop:dev。

服务端 API 密钥只应放在本机环境变量或客户端设置面板中：

$env:TARDIS_INFERENCE_API_KEY = '<your-service-key>'
npm run desktop:dev

客户端本地 Express 代理默认监听 127.0.0.1:8787，代理将异步请求发送到 TARDIS 推理服务端的视频接口。渲染层只访问本地代理，不直接持有服务端密钥。

构建桌面包：

npm run build
npm run desktop:dist

Windows 产物位于 tardis-client/release/win-unpacked/，可直接启动 TARDIS Studio.exe。本地归档默认位于 %APPDATA%\\tardis-video-studio\\archives，可用 TARDIS_ARCHIVE_DIR 覆盖。

客户端 API 契约：

POST http://127.0.0.1:8787/api/generations
Content-Type: application/json

{
  "prompt": "A cinematic robot walks through a rainy neon street",
  "imageData": "data:image/png;base64,...",
  "settings": {
    "quality": "speed",
    "size": "1280x720",
    "fps": 30,
    "duration": 5,
    "withAudio": false
  }
}

创建任务后轮询：

GET http://127.0.0.1:8787/api/generations/<task-id>

终态为 PROCESSING、SUCCESS 或 FAIL。云端 videoUrl/coverUrl 是临时地址，客户端成功后会立即下载到本地归档。完整字段约束见 tardis-client/server/API_CONTRACT.md。

输出、日志与可复现性

标准脚本将大型文件写入 TARDIS_STORAGE_ROOT：

$TARDIS_STORAGE_ROOT/
├── cache/{huggingface,torch,xdg}/
├── checkpoints/<dataset>/<run>/{latest.pt,best.pt}/
└── outputs/
    ├── train/<dataset>/<run>/
    ├── infer/<dataset>/<run>/
    └── apply/<dataset>/<run>/{video.mp4,video.json}

复现实验至少保存：数据集 revision、manifest hash、split seed；checkpoint SHA-256 和模型结构签名；分辨率、帧数、FPS、采样步数、precision、GPU；TC/LPIPS 实现版本、每视频明细和失败样例；首帧、steady-state、full-refresh 的 latency、p50/p95、峰值显存和 active ratio。

当前仓库不会把“平均 FPS”自动解释为逐帧实时保证。是否满足 FPS 目标必须在目标硬件上包含 motion、transport、quotient、VAE 和 I/O 的端到端实测。

研究实验脚本边界

scripts/train.sh、infer.sh、apply.sh 是迁移后可直接使用的标准入口；它们通过 SCRIPT_DIR 推导根目录。scripts/run_* 和 tardis/experiments/ 下部分 benchmark、队列和审计脚本仍保留 /home/TARDIS 或 /root/autodl-tmp/TARDIS 的研究环境假设，运行前应检查并覆盖绝对路径。

正式结果、抽帧图和代理指标来自独立证据包；README 中的 GIF 与缩略图是可视化演示，不应被当作全测试集统计。

故障排查

找不到数据或 manifest

cat "$TARDIS_DATASETS_FILE"
ls -lah /path/to/data-root/tardis_manifest.jsonl

确认 TARDIS_DATASETS_FILE 中的三个路径存在，并且每个源有 manifest、curation report 和媒体归档。

找不到 checkpoint

find "$TARDIS_CHECKPOINT_ROOT" -name best.pt -print

确保 TARDIS_DATASET、checkpoint 模型签名、分辨率、帧数、hidden size、层数和采样配置一致。

CUDA out of memory

降低 TARDIS_MICRO_BATCH_SIZE、TARDIS_VALIDATION_BATCH_SIZE，提高梯度累计，保持 TARDIS_GRADIENT_CHECKPOINTING=1，并确认 VAE decode chunk 没有超过显存容量。改变网络结构后不能直接复用不匹配 checkpoint。

Web-server 端口冲突

检查 src/main/resources/application.properties 的 server.port、nginx upstream 和 Docker 映射是否一致。不要同时启动 systemd、Docker 和手工 Java 进程，否则会争用 8080。

客户端无法轮询或下载

先检查本地 127.0.0.1:8787 代理，再确认服务端密钥有效、云端任务 ID 有效、临时视频 URL 尚未失效。客户端成功后应检查归档目录中的 video.mp4、cover.jpg 和 manifest.json。

安全与许可证

不要把 API Key、SSH 私钥、云端 token 或 .env.local 提交到仓库。
之前在聊天或日志中出现过的服务端密钥应立即轮换；README、截图和 GIF 不包含密钥。
Web-server 默认 Basic Auth 凭据仅用于本地开发，生产环境必须改为强密码并限制管理接口来源。
项目代码采用 Apache License 2.0，见 LICENSE。数据集、基础模型、模型权重和第三方依赖遵循各自的许可证、访问政策和再分发限制。

引用与相关文档

若使用 TARDIS 代码或方法，请参考 CITATION.cff。视觉来源和对照链接见 docs/demo/model_sources.txt。

docs/train.md：训练、验证和 checkpoint 选择
docs/infer.md：全量 test split、指标和 showcase
docs/apply.md：prompt-only causal rollout
docs/datasets.md：manifest、归档和数据划分
appendix/competition_requirements.md：赛题要求的可检索 Markdown 归档
appendix/competition_requirements.pdf：赛题要求原始 PDF 归档
实验方案.md：benchmark 选型、数据划分与实验方案
技术文档.md：训练、推理、协议和 SSH 反向代理服务部署说明
本 README 已汇总桌面客户端、JDK HTTP 服务、nginx、Docker 和 SSH 反向代理服务说明
docs/demo/：客户端演示结果、实机录屏 GIF、批量推理缩略图和视觉对比帧

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
UI		UI
appendix		appendix
docs		docs
scripts		scripts
tardis-client		tardis-client
tardis		tardis
tests		tests
web-server		web-server
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CITATION.cff		CITATION.cff
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
datasets.txt		datasets.txt
docker-compose.yml		docker-compose.yml
docker_build.sh		docker_build.sh
docker_run.sh		docker_run.sh
pyproject.toml		pyproject.toml
实验方案.pdf		实验方案.pdf
技术文档.pdf		技术文档.pdf

Latest commit

History

Folders and files

Repository files navigation