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

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 轮询与下载

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




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