logo

FLUX.1私有化部署与接口调用实战指南

作者:谁偷走了我的奶酪2026.11.18 11:28浏览量:0

简介:本教程讲解FLUX.1系列模型的私有化部署流程,包括版本核对、单卡与多卡启动、文生图、单图编辑和多图参考三类接口调用,以及4096×4096出图的显存估算、验收标准和排错方法。读完后,你可以搭建一套可复用、可健康检查的图像推理服务。非商用许可风险需先行确认。

一、选型与许可确认

本教程以FLUX.1系列为例。文生图使用 black-forest-labs/FLUX.1-dev,单图编辑使用 black-forest-labs/FLUX.1-Kontext-dev。两个模型在Hugging Face上采用非商用许可,只允许研究、学习和非商业测试。私有化部署完成不等于可以商用。进入商业业务前,需要阅读模型卡中的许可条款,并联系权利方取得书面授权。本文不提供商用授权,也不替代法务判断。

模型名称和版本会更新,部署前以模型卡为准。在Hugging Face的模型页面点击同意条款,并在账号设置中生成只读Access Token。Token通过环境变量注入,不要写入代码或日志。

二、版本矩阵

下表是示例组合。部署前必须在目标机器上逐项核对,并以模型卡和各框架的发布说明为准。

组件 示例版本 核对命令 说明
操作系统 Ubuntu 22.04 LTS cat /etc/os-release 其他发行版需自行验证驱动和CUDA安装
NVIDIA驱动 支持所选CUDA版本的驱动 nvidia-smi 顶部显示的CUDA Version是驱动支持的上限
CUDA 12.1或12.4,与PyTorch官方wheel匹配 nvcc --version 只装运行时时可能没有nvcc,以PyTorch安装页为准
Python 3.10或3.11 python3 --version 其他版本可能缺少依赖的预编译包
PyTorch 2.x,对应CUDA版本的官方wheel python -c "import torch;print(torch.__version__, torch.version.cuda)" 版本号与CUDA版本必须对应
diffusers 包含FluxKontextPipeline的发布版本 python -c "from diffusers import FluxPipeline, FluxKontextPipeline" 导入失败时升级diffusers
transformers 与diffusers要求匹配的版本 pip show transformers 以diffusers的依赖声明为准
accelerate 支持CPU卸载的版本 pip show accelerate 调用enable_model_cpu_offload时必需
sentencepiece、protobuf 随T5分词器安装 pip show sentencepiece protobuf 缺失时加载会报错
fastapi、uvicorn、pillow 接口服务与图片处理 pip show fastapi uvicorn pillow 服务层依赖

部署完成后,用 pip freeze > /data/flux/requirements.lock.txt 固化版本,便于复现。

三、显存估算与实测口径

权重显存的粗略估算方法是:参数量 × 每参数字节数。bf16每个参数占2字节。

组件 参数量 bf16权重显存
FLUX.1-dev 主干 约120亿 约24 GB
T5-XXL 文本编码器 约47亿 约9.5 GB
CLIP编码器与VAE 较小 未单独计入
合计 约35 GB以上

这个数字不包含推理时的激活张量、中间缓存和CUDA上下文。选卡时,把35 GB当作下限并预留余量。单张24 GB显卡无法在bf16下同时常驻全部组件,需要开启CPU卸载,或选择显存更大的卡。

估算只用于选卡。最终显存以实测为准,记录方法如下:

  1. import torch
  2. torch.cuda.reset_peak_memory_stats()
  3. image = pipe(prompt="a lighthouse at dawn", width=4096, height=4096).images[0]
  4. peak_gb = torch.cuda.max_memory_allocated() / 1024**3
  5. print(f"峰值显存 {peak_gb:.2f} GB")

每次压测都记录峰值显存、耗时和是否成功,并保留原始日志。

四、部署方式:单卡与多卡

多卡推荐多实例并行:每张卡运行一个模型实例,前面用负载均衡分发请求。实现简单,吞吐随卡数增加,单张图的延迟不变。只有单卡放不下模型,且业务无法接受CPU卸载延迟时,才考虑把文本编码器和主干网络拆到不同卡上,这需要手动迁移组件并处理跨卡张量传递,实现成本较高。

4.1 环境安装

  1. sudo mkdir -p /data/flux/{models,outputs,logs}
  2. sudo chown -R $USER:$USER /data/flux
  3. python3 -m venv /data/flux/venv
  4. source /data/flux/venv/bin/activate
  5. pip install --upgrade pip
  6. pip install torch --index-url https://download.pytorch.org/whl/cu121
  7. pip install diffusers transformers accelerate sentencepiece protobuf fastapi uvicorn pillow
  8. python -c "from diffusers import FluxPipeline, FluxKontextPipeline; print('ok')"

目录权限只授予运行服务的用户。模型和输出目录不要放在系统盘的临时目录中。

4.2 模型下载

  1. pip install -U "huggingface_hub[cli]"
  2. export HF_TOKEN=从密钥管理读取
  3. export HF_HOME=/data/flux/models
  4. huggingface-cli download black-forest-labs/FLUX.1-dev
  5. huggingface-cli download black-forest-labs/FLUX.1-Kontext-dev

新版huggingface_hub提供 hf download 命令,旧版使用 huggingface-cli download,以本机版本为准。下载完成后检查磁盘占用,两个模型合计需要数十GB空间。

4.3 服务代码

保存为 /data/flux/server.py。同一个实例只加载一种模型,由环境变量 MODE 决定。

  1. import asyncio
  2. import base64
  3. import io
  4. import os
  5. import time
  6. import uuid
  7. import torch
  8. from fastapi import FastAPI, HTTPException
  9. from fastapi.responses import JSONResponse
  10. from pydantic import BaseModel, Field
  11. from PIL import Image
  12. MODE = os.getenv("MODE", "t2i") # t2i 或 kontext
  13. MAX_QUEUE = int(os.getenv("MAX_QUEUE", "4")) # 排队上限,超过返回429
  14. TIMEOUT_S = float(os.getenv("INFER_TIMEOUT", "300"))
  15. OUT_DIR = os.getenv("OUT_DIR", "/data/flux/outputs")
  16. MULTI_REF_OK = os.getenv("MULTI_REF_OK") == "1" # 仅在验证通过后设为1
  17. app = FastAPI()
  18. gpu_lock = asyncio.Semaphore(1) # 单卡同一时间只跑一个任务
  19. pending = 0
  20. pipe = None
  21. @app.on_event("startup")
  22. def load_model():
  23. global pipe
  24. from diffusers import FluxPipeline, FluxKontextPipeline
  25. if MODE == "t2i":
  26. pipe = FluxPipeline.from_pretrained(
  27. "black-forest-labs/FLUX.1-dev", torch_dtype=torch.bfloat16)
  28. else:
  29. pipe = FluxKontextPipeline.from_pretrained(
  30. "black-forest-labs/FLUX.1-Kontext-dev", torch_dtype=torch.bfloat16)
  31. pipe.enable_model_cpu_offload() # 显存充足时可改为 pipe.to("cuda")
  32. pipe.vae.enable_tiling() # VAE分块解码,降低大图峰值
  33. class T2IRequest(BaseModel):
  34. prompt: str = Field(..., min_length=1, max_length=1000)
  35. width: int = Field(1024, ge=256, le=4096, multiple_of=16)
  36. height: int = Field(1024, ge=256, le=4096, multiple_of=16)
  37. steps: int = Field(28, ge=1, le=100)
  38. guidance: float = Field(3.5, ge=0, le=10)
  39. seed: int | None = None
  40. class EditRequest(BaseModel):
  41. prompt: str = Field(..., min_length=1, max_length=1000)
  42. image_b64: str
  43. steps: int = Field(28, ge=1, le=100)
  44. guidance: float = Field(2.5, ge=0, le=10)
  45. seed: int | None = None
  46. class ReferenceRequest(BaseModel):
  47. prompt: str = Field(..., min_length=1, max_length=1000)
  48. images_b64: list[str] = Field(..., min_length=2, max_length=4)
  49. steps: int = Field(28, ge=1, le=100)
  50. guidance: float = Field(2.5, ge=0, le=10)
  51. seed: int | None = None
  52. def decode_image(b64: str) -> Image.Image:
  53. try:
  54. img = Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGB")
  55. except Exception:
  56. raise HTTPException(422, "图片无法解码")
  57. img.thumbnail((2048, 2048)) # 限制输入尺寸,控制显存
  58. return img
  59. def _infer(**kwargs):
  60. seed = kwargs.pop("seed", None)
  61. if seed is not None:
  62. kwargs["generator"] = torch.Generator("cpu").manual_seed(seed)
  63. torch.cuda.reset_peak_memory_stats()
  64. t0 = time.time()
  65. image = pipe(**kwargs).images[0]
  66. return image, time.time() - t0, torch.cuda.max_memory_allocated() / 1024**3
  67. async def submit(**kwargs):
  68. global pending
  69. if pending >= MAX_QUEUE:
  70. raise HTTPException(429, "队列已满,请稍后重试")
  71. pending += 1
  72. try:
  73. async with gpu_lock:
  74. return await asyncio.wait_for(
  75. asyncio.to_thread(_infer, **kwargs), timeout=TIMEOUT_S)
  76. except asyncio.TimeoutError:
  77. raise HTTPException(504, "推理超时")
  78. except torch.cuda.OutOfMemoryError:
  79. torch.cuda.empty_cache()
  80. raise HTTPException(503, "显存不足,请降低分辨率或步数")
  81. finally:
  82. pending -= 1
  83. def save_result(image, elapsed, peak):
  84. name = f"{uuid.uuid4().hex}.png"
  85. path = os.path.join(OUT_DIR, name)
  86. image.save(path)
  87. return {"file": path, "width": image.width, "height": image.height,
  88. "elapsed_s": round(elapsed, 2), "peak_vram_gb": round(peak, 2)}
  89. @app.get("/healthz")
  90. def healthz():
  91. ok = pipe is not None and torch.cuda.is_available()
  92. return JSONResponse(
  93. status_code=200 if ok else 503,
  94. content={"status": "ok" if ok else "unavailable", "mode": MODE,
  95. "gpu": torch.cuda.get_device_name(0) if ok else None,
  96. "pending": pending})
  97. @app.post("/v1/generate")
  98. async def generate(req: T2IRequest):
  99. if MODE != "t2i":
  100. raise HTTPException(400, "当前实例不是文生图模式")
  101. image, elapsed, peak = await submit(
  102. prompt=req.prompt, width=req.width, height=req.height,
  103. num_inference_steps=req.steps, guidance_scale=req.guidance,
  104. seed=req.seed)
  105. return save_result(image, elapsed, peak)
  106. @app.post("/v1/edit")
  107. async def edit(req: EditRequest):
  108. if MODE != "kontext":
  109. raise HTTPException(400, "当前实例不是编辑模式")
  110. image, elapsed, peak = await submit(
  111. image=decode_image(req.image_b64), prompt=req.prompt,
  112. num_inference_steps=req.steps, guidance_scale=req.guidance,
  113. seed=req.seed)
  114. return save_result(image, elapsed, peak)
  115. @app.post("/v1/reference")
  116. async def reference(req: ReferenceRequest):
  117. if MODE != "kontext":
  118. raise HTTPException(400, "当前实例不是编辑模式")
  119. if not MULTI_REF_OK:
  120. raise HTTPException(501, "多图输入尚未在当前环境验证")
  121. images = [decode_image(b) for b in req.images_b64]
  122. image, elapsed, peak = await submit(
  123. image=images, prompt=req.prompt,
  124. num_inference_steps=req.steps, guidance_scale=req.guidance,
  125. seed=req.seed)
  126. return save_result(image, elapsed, peak)

代码中的多图参考分支默认关闭。在目标环境用两张图完成一次调用并确认输出正确后,再设置 MULTI_REF_OK=1。如果当前diffusers版本不接受图像列表,不要用拼接大图代替,除非这种替代方案经过了画质验收。

服务代码有一个已知限制:asyncio.wait_for 超时后,后台线程仍会占用GPU,直到推理函数返回。遇到持续超时时,重启该实例即可释放资源。

4.4 启动与健康检查

每张卡启动一个进程,并且只能使用 --workers 1,否则模型会被重复加载。

  1. cd /data/flux
  2. source venv/bin/activate
  3. MODE=t2i CUDA_VISIBLE_DEVICES=0 OUT_DIR=/data/flux/outputs \
  4. uvicorn server:app --host 127.0.0.1 --port 8001 --workers 1

另开终端检查:

  1. curl -s http://127.0.0.1:8001/healthz

返回 "status": "ok" 且 gpu 字段显示目标显卡名称,才算启动成功。返回503说明模型未加载完成,查看启动日志中是否有显存或权限错误。

4.5 多卡负载均衡

两张卡的示例:卡0运行8001端口,卡1运行8002端口。nginx 配置如下:

  1. upstream flux_pool {
  2. least_conn;
  3. server 127.0.0.1:8001 max_fails=2 fail_timeout=30s;
  4. server 127.0.0.1:8002 max_fails=2 fail_timeout=30s;
  5. }
  6. server {
  7. listen 8080;
  8. location / {
  9. proxy_pass http://flux_pool;
  10. proxy_read_timeout 320s;
  11. }
  12. }

proxy_read_timeout 需要大于服务端的 INFER_TIMEOUT。两个数值都应根据实测耗时调整,不要直接沿用示例值。

五、三类接口调用

接口 实例模式 用途 关键参数
POST /v1/generate MODE=t2i 文生图 prompt、width、height、steps、guidance、seed
POST /v1/edit MODE=kontext 单图编辑 prompt、image_b64、steps、guidance、seed
POST /v1/reference MODE=kontext 多图参考 prompt、images_b64(2至4张)、steps、guidance、seed

文生图调用示例:

  1. curl -s -X POST http://127.0.0.1:8001/v1/generate \
  2. -H "Content-Type: application/json" \
  3. -d '{"prompt":"a red bicycle in a sunlit street","width":1024,"height":1024,"steps":28,"seed":42}'

单图编辑调用示例。图片需先转为base64:

  1. IMG=$(base64 -w 0 input.png)
  2. curl -s -X POST http://127.0.0.1:8002/v1/edit \
  3. -H "Content-Type: application/json" \
  4. -d "{\"prompt\":\"make the bicycle blue\",\"image_b64\":\"$IMG\"}"

请求体由调用方自行构造,参数值通过 JSON 库转义,不要直接拼接未经处理的用户输入到 shell 命令中。

成功时返回:

  1. {"file": "/data/flux/outputs/3f2a...png", "width": 1024, "height": 1024,
  2. "elapsed_s": 12.3, "peak_vram_gb": 22.1}

耗时和显存数值取决于硬件,这里只是字段格式示例。

错误码说明:

状态码 含义 处理方式
400 实例模式与接口不匹配 把请求发往对应模式的实例
422 参数校验失败或图片无法解码 检查字段类型、取值范围和图片格式
429 排队数超过 MAX_QUEUE 客户端指数退避后重试
501 多图输入未在当前环境验证 完成验证后设置 MULTI_REF_OK=1
503 显存不足或模型未就绪 降低分辨率或步数,检查 /healthz
504 超过 INFER_TIMEOUT 降低分辨率,或增大超时并确认实例未卡死

六、4K出图验收与排错

4096×4096约为1677万像素,是1024×1024的16倍。生成时token数随之增长,注意力相关计算量增长更快,激活显存也更高,因此4K出图比常用分辨率更容易失败。

两条路径如下:

  • 路径A:直接生成4096×4096。依赖VAE分块解码和CPU卸载,画面整体最直接,但耗时和成功率必须实测。
  • 路径B:先生成1024×1024或2048×2048,再用超分模型放大。耗时更可控,但超分会引入额外的细节差异,且超分模型的许可同样需要单独确认。

路径选择参考下表:

判断条件 倾向路径
业务要求画面一次生成且构图完整 路径A,前提是实测成功率达标
业务要求耗时稳定、可预估 路径B
硬件显存明显低于峰值实测值 路径B,或先降低分辨率
超分模型许可不明确 路径A,避免引入未确认授权的组件

验收前在目标硬件上统一定义指标,并把实测结果填入下表。以下数值由业务方设定,本文不给出任何预设值。

指标 定义 验收阈值 实测结果
成功率 成功返回图片的请求占比 待业务定义 待压测填写
耗时P95 95%请求的完成耗时 待业务定义 待压测填写
显存峰值 peak_vram_gb 的最大值 小于卡的可用显存并留余量 待压测填写
画质 人工或模型评分,统一样本集 待业务定义 待评审填写

OOM排错清单:

  1. 确认报错来自哪一步。加载阶段报错通常是权重或驱动问题,推理阶段报错才是激活显存不足。
  2. 检查是否开启了 enable_model_cpu_offload 和 vae.enable_tiling。
  3. 降低分辨率或步数,逐级确认峰值显存随尺寸的变化。
  4. 检查同一张卡上是否还有其他进程占用显存,用 nvidia-smi 查看。

发表评论

活动