预制服务
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
# → {"task_id":"6c88f3fa796a","status":"queued","poll":"/api/v1/tasks/6c88f3fa796a"}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
# → {"status":"done","meta":{"in":"768x1408","out":"1536x2816",
# "frames_in":33,"frames_out":29,"fps":12,"infer_s":12.9,
# "s_per_frame":0.443,"gpu0_peak_gib":27.77,"gpu1_peak_gib":10.53,
# "total_s":38.5,"size_mb":1.3}}
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
五、运维注意
- 单实例串行：GPU 任务队列互斥，排队状态见 healthz 的 queue_len；扩容靠加节点（共绩 change_points）。
- 任务状态存内存：实例重启丢任务记录；产线客户端需超时重提。
- 结果文件不自动清理：
/work/api/out/累积需清理或挂 NAS。 - 瘦镜像变体（裸机挂载场景）：
docker run -v /path/to/weights:/weights:ro ... flashvsr:1.1-5090 api，共绩上用 fat 版。 - 质量 vs 速度选型：追求质量/长视频 → FlashVSR（0.35 s/帧）；追求吞吐/批量 → RTX VSR（~0.09s/帧 + 3 并发）。