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卸载,或选择显存更大的卡。
估算只用于选卡。最终显存以实测为准,记录方法如下:
import torchtorch.cuda.reset_peak_memory_stats()image = pipe(prompt="a lighthouse at dawn", width=4096, height=4096).images[0]peak_gb = torch.cuda.max_memory_allocated() / 1024**3print(f"峰值显存 {peak_gb:.2f} GB")
每次压测都记录峰值显存、耗时和是否成功,并保留原始日志。
四、部署方式:单卡与多卡
多卡推荐多实例并行:每张卡运行一个模型实例,前面用负载均衡分发请求。实现简单,吞吐随卡数增加,单张图的延迟不变。只有单卡放不下模型,且业务无法接受CPU卸载延迟时,才考虑把文本编码器和主干网络拆到不同卡上,这需要手动迁移组件并处理跨卡张量传递,实现成本较高。
4.1 环境安装
sudo mkdir -p /data/flux/{models,outputs,logs}sudo chown -R $USER:$USER /data/fluxpython3 -m venv /data/flux/venvsource /data/flux/venv/bin/activatepip install --upgrade pippip install torch --index-url https://download.pytorch.org/whl/cu121pip install diffusers transformers accelerate sentencepiece protobuf fastapi uvicorn pillowpython -c "from diffusers import FluxPipeline, FluxKontextPipeline; print('ok')"
目录权限只授予运行服务的用户。模型和输出目录不要放在系统盘的临时目录中。
4.2 模型下载
pip install -U "huggingface_hub[cli]"export HF_TOKEN=从密钥管理读取export HF_HOME=/data/flux/modelshuggingface-cli download black-forest-labs/FLUX.1-devhuggingface-cli download black-forest-labs/FLUX.1-Kontext-dev
新版huggingface_hub提供 hf download 命令,旧版使用 huggingface-cli download,以本机版本为准。下载完成后检查磁盘占用,两个模型合计需要数十GB空间。
4.3 服务代码
保存为 /data/flux/server.py。同一个实例只加载一种模型,由环境变量 MODE 决定。
import asyncioimport base64import ioimport osimport timeimport uuidimport torchfrom fastapi import FastAPI, HTTPExceptionfrom fastapi.responses import JSONResponsefrom pydantic import BaseModel, Fieldfrom PIL import ImageMODE = os.getenv("MODE", "t2i") # t2i 或 kontextMAX_QUEUE = int(os.getenv("MAX_QUEUE", "4")) # 排队上限,超过返回429TIMEOUT_S = float(os.getenv("INFER_TIMEOUT", "300"))OUT_DIR = os.getenv("OUT_DIR", "/data/flux/outputs")MULTI_REF_OK = os.getenv("MULTI_REF_OK") == "1" # 仅在验证通过后设为1app = FastAPI()gpu_lock = asyncio.Semaphore(1) # 单卡同一时间只跑一个任务pending = 0pipe = None@app.on_event("startup")def load_model():global pipefrom diffusers import FluxPipeline, FluxKontextPipelineif MODE == "t2i":pipe = FluxPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", torch_dtype=torch.bfloat16)else:pipe = FluxKontextPipeline.from_pretrained("black-forest-labs/FLUX.1-Kontext-dev", torch_dtype=torch.bfloat16)pipe.enable_model_cpu_offload() # 显存充足时可改为 pipe.to("cuda")pipe.vae.enable_tiling() # VAE分块解码,降低大图峰值class T2IRequest(BaseModel):prompt: str = Field(..., min_length=1, max_length=1000)width: int = Field(1024, ge=256, le=4096, multiple_of=16)height: int = Field(1024, ge=256, le=4096, multiple_of=16)steps: int = Field(28, ge=1, le=100)guidance: float = Field(3.5, ge=0, le=10)seed: int | None = Noneclass EditRequest(BaseModel):prompt: str = Field(..., min_length=1, max_length=1000)image_b64: strsteps: int = Field(28, ge=1, le=100)guidance: float = Field(2.5, ge=0, le=10)seed: int | None = Noneclass ReferenceRequest(BaseModel):prompt: str = Field(..., min_length=1, max_length=1000)images_b64: list[str] = Field(..., min_length=2, max_length=4)steps: int = Field(28, ge=1, le=100)guidance: float = Field(2.5, ge=0, le=10)seed: int | None = Nonedef decode_image(b64: str) -> Image.Image:try:img = Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGB")except Exception:raise HTTPException(422, "图片无法解码")img.thumbnail((2048, 2048)) # 限制输入尺寸,控制显存return imgdef _infer(**kwargs):seed = kwargs.pop("seed", None)if seed is not None:kwargs["generator"] = torch.Generator("cpu").manual_seed(seed)torch.cuda.reset_peak_memory_stats()t0 = time.time()image = pipe(**kwargs).images[0]return image, time.time() - t0, torch.cuda.max_memory_allocated() / 1024**3async def submit(**kwargs):global pendingif pending >= MAX_QUEUE:raise HTTPException(429, "队列已满,请稍后重试")pending += 1try:async with gpu_lock:return await asyncio.wait_for(asyncio.to_thread(_infer, **kwargs), timeout=TIMEOUT_S)except asyncio.TimeoutError:raise HTTPException(504, "推理超时")except torch.cuda.OutOfMemoryError:torch.cuda.empty_cache()raise HTTPException(503, "显存不足,请降低分辨率或步数")finally:pending -= 1def save_result(image, elapsed, peak):name = f"{uuid.uuid4().hex}.png"path = os.path.join(OUT_DIR, name)image.save(path)return {"file": path, "width": image.width, "height": image.height,"elapsed_s": round(elapsed, 2), "peak_vram_gb": round(peak, 2)}@app.get("/healthz")def healthz():ok = pipe is not None and torch.cuda.is_available()return JSONResponse(status_code=200 if ok else 503,content={"status": "ok" if ok else "unavailable", "mode": MODE,"gpu": torch.cuda.get_device_name(0) if ok else None,"pending": pending})@app.post("/v1/generate")async def generate(req: T2IRequest):if MODE != "t2i":raise HTTPException(400, "当前实例不是文生图模式")image, elapsed, peak = await submit(prompt=req.prompt, width=req.width, height=req.height,num_inference_steps=req.steps, guidance_scale=req.guidance,seed=req.seed)return save_result(image, elapsed, peak)@app.post("/v1/edit")async def edit(req: EditRequest):if MODE != "kontext":raise HTTPException(400, "当前实例不是编辑模式")image, elapsed, peak = await submit(image=decode_image(req.image_b64), prompt=req.prompt,num_inference_steps=req.steps, guidance_scale=req.guidance,seed=req.seed)return save_result(image, elapsed, peak)@app.post("/v1/reference")async def reference(req: ReferenceRequest):if MODE != "kontext":raise HTTPException(400, "当前实例不是编辑模式")if not MULTI_REF_OK:raise HTTPException(501, "多图输入尚未在当前环境验证")images = [decode_image(b) for b in req.images_b64]image, elapsed, peak = await submit(image=images, prompt=req.prompt,num_inference_steps=req.steps, guidance_scale=req.guidance,seed=req.seed)return save_result(image, elapsed, peak)
代码中的多图参考分支默认关闭。在目标环境用两张图完成一次调用并确认输出正确后,再设置 MULTI_REF_OK=1。如果当前diffusers版本不接受图像列表,不要用拼接大图代替,除非这种替代方案经过了画质验收。
服务代码有一个已知限制:asyncio.wait_for 超时后,后台线程仍会占用GPU,直到推理函数返回。遇到持续超时时,重启该实例即可释放资源。
4.4 启动与健康检查
每张卡启动一个进程,并且只能使用 --workers 1,否则模型会被重复加载。
cd /data/fluxsource venv/bin/activateMODE=t2i CUDA_VISIBLE_DEVICES=0 OUT_DIR=/data/flux/outputs \uvicorn server:app --host 127.0.0.1 --port 8001 --workers 1
另开终端检查:
curl -s http://127.0.0.1:8001/healthz
返回 "status": "ok" 且 gpu 字段显示目标显卡名称,才算启动成功。返回503说明模型未加载完成,查看启动日志中是否有显存或权限错误。
4.5 多卡负载均衡
两张卡的示例:卡0运行8001端口,卡1运行8002端口。nginx 配置如下:
upstream flux_pool {least_conn;server 127.0.0.1:8001 max_fails=2 fail_timeout=30s;server 127.0.0.1:8002 max_fails=2 fail_timeout=30s;}server {listen 8080;location / {proxy_pass http://flux_pool;proxy_read_timeout 320s;}}
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 |
文生图调用示例:
curl -s -X POST http://127.0.0.1:8001/v1/generate \-H "Content-Type: application/json" \-d '{"prompt":"a red bicycle in a sunlit street","width":1024,"height":1024,"steps":28,"seed":42}'
单图编辑调用示例。图片需先转为base64:
IMG=$(base64 -w 0 input.png)curl -s -X POST http://127.0.0.1:8002/v1/edit \-H "Content-Type: application/json" \-d "{\"prompt\":\"make the bicycle blue\",\"image_b64\":\"$IMG\"}"
请求体由调用方自行构造,参数值通过 JSON 库转义,不要直接拼接未经处理的用户输入到 shell 命令中。
成功时返回:
{"file": "/data/flux/outputs/3f2a...png", "width": 1024, "height": 1024,"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排错清单:
- 确认报错来自哪一步。加载阶段报错通常是权重或驱动问题,推理阶段报错才是激活显存不足。
- 检查是否开启了
enable_model_cpu_offload和vae.enable_tiling。 - 降低分辨率或步数,逐级确认峰值显存随尺寸的变化。
- 检查同一张卡上是否还有其他进程占用显存,用
nvidia-smi查看。

登录后可评论,请前往 登录 或 注册