FlashVSR API 镜像使用说明

基座：FlashVSR v1.1（单步扩散流式视频超分，Wan2.1-1.3B DiT + TCDecoder） 适配：RTX 5090 双卡（DiT+KV 于卡 A，TCDecoder 于卡 B） 用途：生成 768p 视频的高质量 2K 超分（质量优于 RTX VSR，速度较慢）

一、镜像信息

镜像地址	harbor.suanleme.cn/public-hub/flashvsr:1.1-5090-fat
暴露端口	8000（FastAPI + uvicorn 单 worker，GPU 任务队列串行）
GPU 需求	2× RTX 5090 (32GB×2)：GPU0 峰值 27.8 GiB / GPU1 峰值 10.5 GiB
推荐规格	5090×2
并发模型	单实例串行（GPU 互斥），扩容靠加节点

二、部署

2.1 创建任务

• 资源：5090×2
• 镜像：harbor.suanleme.cn/public-hub/flashvsr:1.1-5090-fat
• 必须环境变量：

PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
NVIDIA_DRIVER_CAPABILITIES=compute,utility

expandable_segments 是硬性要求——不开时 PyTorch 分配器碎片额外吃 ~5.9 GiB，GPU0 必 OOM（fix 系列实证）。

2.2 启动特性

• 容器入口先跑 imports 自检（快速失败，不带病服务），再起 API
• 模型懒加载：首次任务触发权重加载（~26s），此后常驻
• 首任务含模型加载 ~60-90s，属正常

2.3 健康检查（建议配）

探针	配置
startup_probe	httpGet /healthz:8000，initial_delay 90s，period 20s，failure_threshold 10
liveness_probe	httpGet /healthz:8000，period 30s，failure_threshold 3

三、API

3.1 端点总览

方法	路径	说明
GET	/healthz	健康检查（model_ready / busy / queue_len）
POST	/api/v1/upscale	JSON 提交（video_b64 或 video_url，scale 可选）
POST	/api/v1/upscale/file	multipart 文件上传（推荐）
GET	/api/v1/tasks/{task_id}	轮询进度（progress 0~1）
GET	/api/v1/tasks/{task_id}/result	下载成品 MP4

3.2 提交任务

curl -F "file=@input.mp4" -F "scale=2.0" \
     http://<服务地址>/api/v1/upscale/file

3.3 参数

参数	类型	默认	说明
scale	float	2.0	放大倍率（官方按 4× 训练，2× 属 OOD，实测质量未崩）
video_url / video_b64	str		JSON 提交二选一

3.4 尺寸处理链

输入 → scale 缩放 → 128 对齐 → 中心裁剪。输出分辨率可能与理论值差 ±128 内（例：768×1408 → 1536×2816）。

3.5 轮询与下载

curl http://<服务地址>/api/v1/tasks/6c88f3fa796a





curl -o out.mp4 http://<服务地址>/api/v1/tasks/6c88f3fa796a/result

四、性能实测（2×RTX 5090）

输入	输出	推理	端到端
768×1408 竖屏，33 帧	1536×2816	12.9s（0.44 s/帧）	38.5s
1376×768 横屏，362 帧（15s@24fps）	2688×1536	115~140s（0.32-0.39 s/帧）	241~271s

• 音轨自动 mux（有音轨时）
• 显存恒定不随视频长度增长（流式管线，KV 有界）
• 质量参考（vs bicubic）：锐度提升 8-14×，PSNR 23-32dB