RTX VSR API 镜像使用说明

基座：NVIDIA Maxine VFX（nvidia-vfx 0.1.0.1）· RTX VIDEO SUPER RESOLUTION

适配：RTX 5090 单卡 · 驱动 580+（镜像内置 590 NGX 运行库，无需宿主机额外安装）

已内置：nvidia-vfx 全套模型（1.1GB）+ cupy-cuda12x + ffmpeg（NVENC 硬编码）

用途：H3/AIGC 生成视频 2× 超分（768p→1536p），质量档位可调，量产车道

一、镜像信息

镜像地址	`harbor.suanleme.cn/public-hub/rtxvsr:0.1.0-5090`
基座镜像	`python:3.12-slim`
暴露端口	8000（FastAPI + uvicorn 单 worker）
GPU 需求	1× RTX 5090（32GB），显存占用 ~3GB
推荐规格	5090 单卡
并发模型	单实例 3 并发（`VSR_MAX_CONCURRENCY=3`，每任务独立子进程）

二、部署（共绩弹性部署）

2.1 创建任务

资源：5090 单卡
镜像：harbor.suanleme.cn/public-hub/rtxvsr:0.1.0-5090
必须环境变量：

NVIDIA_DRIVER_CAPABILITIES=compute,utility,video

video 能力必须开启（NVENC 硬编码依赖）；缺省时容器只挂 compute，输出编码会回退/失败。

2.2 健康检查（可选，建议配）

探针	配置
startup_probe	httpGet `/healthz`:8000，initial_delay 60s，period 15s，failure_threshold 10
liveness_probe	httpGet `/healthz`:8000，period 30s，failure_threshold 3

三、API

3.1 端点总览

方法	路径	说明
GET	`/healthz`	健康检查（`concurrency.running` 为当前并发；`queue_visible` 为历史任务总数而非待处理数，实测语义确认）
POST	`/api/v1/upscale`	JSON 提交（video_b64 或 video_url）
POST	`/api/v1/upscale/file`	multipart 文件上传（推荐，≤200MB）
GET	`/api/v1/tasks/{task_id}`	轮询进度
GET	`/api/v1/tasks/{task_id}/result`	下载成品（MP4）

3.2 提交任务

multipart 上传（推荐）：

curl -F "file=@input.mp4" -F "quality=HIGH" -F "scale=2.0" \
     http://<服务地址>/api/v1/upscale/file
# → {"task_id":"e37328fa0092","status":"queued","poll":"/api/v1/tasks/e37328fa0092"}

JSON（URL 拉取）：

curl -X POST http://<服务地址>/api/v1/upscale \
     -H "Content-Type: application/json" \
     -d '{"video_url":"https://.../input.mp4","quality":"HIGH","scale":2.0}'

3.3 参数

参数	类型	默认	说明
`quality`	str	`HIGH`	质量档位，见 3.4
`scale`	float	`2.0`	放大倍率（当前仅 2.0）
`vcodec`	str	`h264_nvenc`	编码器（h264_nvenc / hevc_nvenc / libx264）
`bitrate`	str	`50M`	输出码率

3.4 质量档位（QUALITY_MAP）

档位	QualityLevel	适用
`BICUBIC`	0-0	对照基线（bicubic 插值）
`LOW`	1-4	快速档，AI 效果弱
`MEDIUM`	5-7	平衡档
`HIGH`	8-11	推荐默认，去噪+超分
`ULTRA`	12-15	最高质量（去模糊增强）
`HIGHBITRATE_LOW/MEDIUM/HIGH`	16-19	高码率源专用（H3 直出视频码率不足时不适用）

3.5 轮询与下载

# 轮询（done/error 终态）
curl http://<服务地址>/api/v1/tasks/e37328fa0092
# → {"task_id":"...","status":"done","progress":1.0,"error":null,
#    "meta":{"total_s":32.4,"size_mb":98.5,"quality":"HIGH","scale":2.0}}

# 下载
curl -o out.mp4 http://<服务地址>/api/v1/tasks/e37328fa0092/result

四、性能实测（RTX 5090 单卡）

输入	输出	耗时	吞吐
1376×768, 362 帧, 15.1s, aac 音轨	2752×1536	32.4s 端到端	~11 s 处理 1s 视频

音轨自动透传（-c:a copy），无需二次 mux
单实例 3 并发时 GPU 利用率未饱和（瓶颈在 ffmpeg 解码/编码 IO），可按需提高 VSR_MAX_CONCURRENCY