Qwen-Image-NVFP4 API 完全参考:OpenAI 兼容接口每个参数详解
Qwen-Image-NVFP4 API 完全参考:OpenAI 兼容接口每个参数详解
Qwen-Image-NVFP4 是 NVIDIA 推出的 NVFP4 量化版文生图模型,部署后提供与 OpenAI Images API 兼容的 REST 接口。本文逐个拆解 /v1/images/generations 端点的全部请求参数、返回格式与调优建议,帮你一次用对每一个字段。
📡 接口概览:一个端点搞定文生图
整个服务只暴露两个关键 HTTP 端点,全部参数通过 POST 请求的 JSON Body 传递:
| 端点 | 方法 | 用途 |
|---|---|---|
/v1/images/generations |
POST | 文生图核心接口,参数都在请求体里 |
/health |
GET | 健康检查,确认服务已就绪 |
服务基于 TensorRT-LLM VisualGen 启动,官方推荐的启动方式与调用样例分别位于 serving/ 目录,可直接参考 serving/generate_sample.py 中的最小调用实现。
先确认服务存活,再生成图片:
curl --fail http://127.0.0.1:8000/health
🧩 请求参数详解:逐字段拆解
以下参数表基于仓库内的官方调用样例 serving/generate_sample.py 整理:
payload = {
"model": "/model",
"prompt": "A realistic photograph of a red ceramic teapot ...",
"negative_prompt": " ",
"size": "512x512",
"num_inference_steps": 50,
"guidance_scale": 4.0,
"seed": 42,
"response_format": "b64_json",
"format": "png",
}
| 参数 | 类型 | 示例值 | 作用 |
|---|---|---|---|
model |
string | /model |
模型挂载路径,保持服务启动时传入的路径 |
prompt |
string | 英文/中文提示词 | 生成内容的主描述,最多 1024 个 token(默认 512) |
negative_prompt |
string | " " |
负向提示词;本模型建议传单空格占位 |
size |
string | 512x512 |
输出分辨率,宽x高,建议取 16 的倍数 |
num_inference_steps |
int | 50 |
去噪迭代步数,决定质量与耗时 |
guidance_scale |
float | 4.0 |
提示词引导强度(CFG) |
seed |
int | 42 |
随机种子,同参数可复现结果 |
response_format |
string | b64_json |
响应编码方式 |
format |
string | png |
输出图片格式 |
下面对几个关键参数展开说明。
prompt:中英文提示词都能用
这是影响结果最大的参数。上游模型原生支持中英文双工作流,官方示例集中就包含中文场景。例如生成带招牌汉字的茶馆图:
对应提示词为:一家温暖的中国茶馆,门口招牌上清晰写着“春日茶馆”四个汉字,木质门窗,柔和的日光。(seed 44,512x512)
小贴士:模型最多接收 1024 个 prompt token,复杂长描述可以放心写,无需刻意压缩。
negative_prompt:为什么是"一个空格"
OpenAI 系图像 API 习惯要求负向提示词字段存在,但本模型(FlowMatch 调度器 + CFG 4.0)在评估与示例中统一使用单个空格 " " 作为占位值。除非有特殊需求,直接照抄即可。
size:分辨率怎么选
- 官方示例使用
512x512和1024x1024两档 - 宽高建议都是 16 的倍数,否则可能被自动缩放
- 高分辨率(1024 及以上)适合人像特写等细节场景,耗时相应变长
上图为 1024x1024、seed 42 的人像特写效果,景深与皮肤细节表现稳定。
num_inference_steps 与 guidance_scale:质量与速度的权衡
| 目标 | num_inference_steps |
guidance_scale |
说明 |
|---|---|---|---|
| 快速出图(草稿) | 20~30 | 3.5~4.0 | 适合批量试 prompt |
| 均衡(推荐起步) | 50 | 4.0 | 官方评估与示例统一配置 |
| 高质量 | 50+ | 4.0 | 量化版在 50 步下与 BF16 基线打平甚至略优 |
guidance_scale 过低会偏离提示词,过高容易出现过饱和伪影;4.0 是本模型验证过的稳妥值。
seed:复现与 A/B 对比的关键
固定 seed(如官方统一使用的 42)后,相同参数会得到可复现的结果。做量化对比、调参实验时,务必锁死 seed 再改其他变量。
response_format 与 format:拿到图片的两种方式
response_format: "b64_json":响应内嵌 Base64 数据,本地解码即可保存,是样例脚本的默认选择format: "png":控制解码后的图像编码格式
响应体结构如下:
{
"data": [
{ "b64_json": "iVBORw0KGgo..." }
]
}
解码只需一行:base64.b64decode(result<a href="https://link.gitcode.com/i/0ad97b14333ccaf9b8a5f8a5284bb1eb" target="_blank">"data"][0]["b64_json"]),完整流程见 [serving/generate_sample.py。
⚙️ 服务端配置:参数背后的支撑
请求参数之外,服务端行为由 VisualGen 配置控制,仓库提供了两套模板:
- 朴素模式(默认推荐):serving/visualgen-eager.yaml —— 关闭 torch.compile 与 CUDA Graph,加载快、兼容性好
- 编译加速模式:serving/visualgen-compiled.yaml —— 开启 torch.compile,并对固定分辨率(如
[[512, 512]])做编译预热,适合服务单一规格的高吞吐场景
模型侧结构可在 model_index.json 中确认:Qwen2.5-VL 文本编码器 + 60 层 Qwen-Image Transformer + FlowMatch Euler 调度器(参数见 scheduler/scheduler_config.json)。量化细节上,784 个 Transformer 线性矩阵以 NVFP4 存储,文本编码器与 VAE 保持高精度,因此量化后在 Qwen-Image-Bench 上得分 49.754,与 BF16 基线(48.986)基本无损。
🛠 常见问题速查
| 现象 | 排查方向 |
|---|---|
| 连接被拒 / 超时 | 先用 /health 确认服务就绪;大分辨率生成耗时较长,客户端超时建议设 600s(参考样例) |
输出尺寸与 size 不符 |
宽高是否 16 的倍数 |
| 图片与提示词偏差大 | 适当调高 guidance_scale;检查 prompt 是否过于笼统 |
| 想复现上一次结果 | 固定 seed、size、num_inference_steps 全部参数 |
📚 相关资料
- 完整部署流程(下载、Docker 启动、生成):README.md
- 最小可运行调用脚本:serving/generate_sample.py
- 服务端配置模板:serving/visualgen-eager.yaml、serving/visualgen-compiled.yaml
- 模型管线定义:model_index.json
- 官方示例图(BF16 对比):assets/
掌握以上 9 个参数后,你就可以用一套 OpenAI 风格的调用方式稳定驱动 Qwen-Image-NVFP4 文生图服务了。


