FastAPI+Ollama搭建本地文生图服务实践

1. 项目背景与核心价值

最近在折腾一个特别有意思的实践 - 用FastAPI搭建本地化的文生图服务接口。这个方案完美结合了ollama的模型管理能力和diffusers库的稳定扩散能力，实测下来生成效果相当惊艳。相比直接调用云端API，本地部署最大的优势就是可以完全掌控生成过程，不用受限于第三方服务的各种约束。

我最初做这个项目是因为在工作中经常需要批量生成产品概念图，但发现市面上的AI绘画服务要么贵得离谱，要么对生成内容限制太多。后来发现用开源模型本地部署其实完全可行，而且效果不比商业服务差。经过几轮迭代优化，现在这个方案已经能稳定支持团队日常的创意需求了。

2. 技术栈选型解析

2.1 为什么选择FastAPI

FastAPI作为Python生态中最快的Web框架之一，特别适合这种需要实时交互的AI服务场景。它的异步特性让图像生成这种耗时操作不会阻塞整个服务，实测单台普通开发机就能轻松支撑10+并发请求。另外，自动生成的Swagger文档也让接口调试变得异常简单。

对比过Flask和Django：

  • Flask虽然轻量但缺少原生异步支持
  • Django功能全面但太重
  • FastAPI刚好在两者间取得完美平衡

2.2 ollama的独特优势

ollama这个工具可能很多人还不熟悉，它相当于本地版的模型管理神器。主要解决了三个痛点：

  1. 自动下载和缓存模型文件
  2. 提供统一的模型调用接口
  3. 支持模型版本管理

我们用的Stable Diffusion模型动辄几个GB，用ollama管理后部署效率提升明显。它的CLI工具用起来也很顺手：

ollama pull stabilityai/stable-diffusion-xl-base-1.0

2.3 diffusers库的核心能力

diffusers是HuggingFace推出的专业扩散模型库，封装了各种文生图的高级功能：

  • 支持多种采样器（DDIM、DPMSolver等）
  • 提供精细化的参数控制
  • 内置安全过滤器

最实用的是它的Pipeline抽象，几行代码就能完成复杂生成逻辑：

from diffusers import StableDiffusionPipeline pipe = StableDiffusionPipeline.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16 )

3. 系统架构设计

3.1 整体工作流程

这个服务的核心流程可以分为四个阶段：

  1. HTTP请求接收：FastAPI处理传入的文本提示词和参数
  2. 模型加载：ollama确保所需模型已就绪
  3. 图像生成：diffusers执行实际的扩散过程
  4. 结果返回：将生成的图片以Base64或文件流形式响应

3.2 关键组件交互

设计时特别注意了组件间的解耦：

  • Web层只负责协议转换
  • 模型管理层处理硬件资源分配
  • 生成层专注算法执行

这种架构使得后续替换某个组件（比如换用其他Web框架）变得非常容易。

4. 详细实现步骤

4.1 环境准备

首先需要配置支持CUDA的Python环境，推荐使用conda：

conda create -n sd-api python=3.10 conda activate sd-api pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu118

4.2 核心接口实现

主服务代码结构如下：

from fastapi import FastAPI from pydantic import BaseModel class GenerationRequest(BaseModel): prompt: str negative_prompt: str = "" steps: int = 20 guidance_scale: float = 7.5 app = FastAPI() @app.post("/generate") async def generate_image(request: GenerationRequest): # 这里实现实际生成逻辑 return {"image": "base64_encoded_image"}

4.3 生成逻辑优化

经过多次测试，发现这几个参数对生成质量影响最大：

  1. guidance_scale：建议7-8之间
  2. num_inference_steps：20-30步性价比最高
  3. eta：影响创意程度

最佳实践是提供预设参数组合：

PRESETS = { "standard": {"steps": 25, "guidance": 7.5}, "creative": {"steps": 30, "guidance": 5.0}, "detailed": {"steps": 50, "guidance": 8.0} }

5. 性能优化技巧

5.1 模型缓存策略

ollama默认会把模型放在~/.ollama目录，对于大模型建议修改存储位置：

export OLLAMA_MODELS=/mnt/ssd/models ollama pull stabilityai/stable-diffusion-xl-base-1.0

5.2 GPU内存管理

遇到CUDA out of memory错误时可以尝试：

  1. 启用模型卸载：
pipe.enable_model_cpu_offload()
  1. 使用内存优化版Pipeline：
from diffusers import StableDiffusionPipeline pipe = StableDiffusionPipeline.from_pretrained(..., variant="fp16")

5.3 并发请求处理

FastAPI的异步特性要配合合适的worker数量：

uvicorn main:app --workers 2 --host 0.0.0.0 --port 8000

注意：worker数不应超过GPU显存能支持的并行数。

6. 实用功能扩展

6.1 实时进度反馈

通过Server-Sent Events实现生成进度推送：

from sse_starlette.sse import EventSourceResponse @app.get("/stream-generate") async def stream_generate(prompt: str): def generate(): for step in pipe(prompt): yield {"step": step, "progress": step/num_steps} return EventSourceResponse(generate())

6.2 批量生成接口

支持一次请求生成多个变体：

@app.post("/batch-generate") async def batch_generate(request: BatchRequest): return [ generate_image(GenerationRequest( prompt=p, negative_prompt=request.negative_prompt )) for p in request.prompts ]

7. 常见问题解决

7.1 图像质量不稳定

典型表现：

  • 画面元素错乱
  • 细节模糊
  • 色彩异常

解决方案：

  1. 检查提示词是否明确
  2. 调整guidance_scale到7-9之间
  3. 增加inference steps到30+

7.2 生成速度慢

优化方向：

  1. 使用更小的模型变体（如sd-v1-5）
  2. 启用xFormers加速：
pipe.enable_xformers_memory_efficient_attention()
  1. 降低输出分辨率

7.3 显存不足

应对策略：

  1. 使用--lowvram模式
  2. 启用CPU卸载
  3. 减少并发请求数

8. 安全注意事项

  1. 生产环境一定要加身份验证：
from fastapi.security import HTTPBearer security = HTTPBearer() @app.post("/generate") async def generate_image( request: GenerationRequest, credentials: HTTPAuthorizationCredentials = Depends(security) ): verify_token(credentials.credentials)
  1. 建议启用nsfw过滤器：
from diffusers import StableDiffusionPipeline pipe = StableDiffusionPipeline.from_pretrained(..., safety_checker=...)
  1. 日志记录所有生成请求

9. 部署方案

9.1 开发环境

推荐使用Docker compose编排服务：

version: '3' services: api: image: sd-api:latest ports: - "8000:8000" environment: - OLLAMA_MODELS=/models volumes: - ./models:/models deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

9.2 生产环境

建议的部署架构：

  1. 前端：Nginx反向代理
  2. 服务层：FastAPI + Gunicorn
  3. 模型层：专用GPU节点

监控指标：

  • 生成耗时P99
  • GPU利用率
  • 失败请求率

10. 效果对比与调优

经过反复测试，不同模型的表现差异明显：

模型名称生成速度图像质量显存占用
SD 1.52.3s/it★★★☆4GB
SD XL4.1s/it★★★★☆8GB
LCM-Lora0.8s/it★★☆3GB

调优建议：

  • 创意设计：优先SD XL
  • 快速原型：选择LCM-Lora
  • 平衡选择：SD 1.5

11. 进阶功能探索

11.1 LoRA模型集成

支持动态加载风格化LoRA：

pipe.load_lora_weights( "path/to/lora", adapter_name="anime_style" )

11.2 ControlNet控制

添加姿势/边缘控制：

from diffusers import ControlNetModel controlnet = ControlNetModel.from_pretrained( "lllyasviel/sd-controlnet-openpose" )

11.3 自定义调度器

实验不同的噪声调度策略：

from diffusers import DPMSolverSinglestepScheduler pipe.scheduler = DPMSolverSinglestepScheduler.from_config(pipe.scheduler.config)

12. 项目总结与展望

这个本地化文生图方案经过三个月的迭代已经相当稳定，目前支撑着我们团队日均500+的生成请求。最大的收获是发现开源模型的能力其实已经足够应对大多数商业场景，关键是要掌握正确的调优方法。

几个特别实用的经验：

  1. 负面提示词比正面提示词更重要
  2. 随机种子对结果一致性影响巨大
  3. 适当降低分辨率反而能提升细节质量

后续计划加入img2img和inpainting支持，让创作流程更加完整。已经测试成功的T2I-Adapter也准备集成进来，实现更精准的画面控制。