Skip to content

VaneBlien/sd-backend

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
app
app
 
 
docs
docs
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
init.bat
init.bat
 
 
requirements-lock.txt
requirements-lock.txt
 
 
requirements.txt
requirements.txt
 
 
run.py
run.py
 
 

Repository files navigation

📄 docs/README.md

# SD Backend

Stable Diffusion 图片生成后端服务，基于 FastAPI + diffusers 构建。
对接 WordPress 插件 `sd-wordpress-plugin` 的 FastAPI 模式。

## 功能

- 🎨 文本到图片生成（txt2img）
- 🔐 可选的 Bearer Token 鉴权
- ⏱ 请求限流保护
- 📐 自动尺寸校验（8 的倍数对齐）
- 🩺 健康检查端点
- 📖 自动生成 OpenAPI 文档

## 技术栈

| 层级 | 技术 |
|------|------|
| Web 框架 | FastAPI |
| 推理引擎 | diffusers (HuggingFace) |
| 模型格式 | safetensors |
| GPU 加速 | CUDA + xformers |
| 配置管理 | pydantic-settings |
| 进程管理 | uvicorn |

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt

2. 下载模型

mkdir -p models
# 示例：下载 DreamShaper 8 (SD 1.5)
wget -P models/ https://huggingface.co/Lykon/DreamShaper/resolve/main/DreamShaper_8_pruned.safetensors

3. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，设置 API Key、模型路径等

4. 启动服务

python run.py

或直接使用 uvicorn：

uvicorn app.main:app --host 0.0.0.0 --port 8000

5. 访问 API 文档

浏览器打开 http://localhost:8000/docs

项目结构

sd-backend/
├── app/
│   ├── main.py              # FastAPI 入口，路由注册
│   ├── config.py            # 配置管理
│   ├── models/
│   │   └── schemas.py       # Pydantic 数据模型
│   ├── services/
│   │   └── generator.py     # SD 推理服务
│   └── utils/
│       └── image_utils.py   # 图片编解码
├── models/                  # 模型文件存放目录
├── outputs/                 # 临时输出（预留）
├── docs/                    # 文档
├── run.py                   # 启动入口
├── requirements.txt         # Python 依赖
├── .env.example             # 环境变量模板
└── .gitignore


---

## 📄 docs/API.md

```markdown
# API 接口文档

## 基础信息

- 基础路径: `http://<host>:8000`
- 文档地址: `/docs` (Swagger UI) / `/redoc` (ReDoc)
- 请求格式: `application/json`
- 响应格式: `application/json`

## 鉴权

如果配置了 `SD_API_KEY`，所有生成接口需要在请求头中携带：

Authorization: Bearer <API_KEY>


未配置则不验证。

---

## 端点列表

### 1. 健康检查

GET /health


**响应**:
```json
{
    "status": "ok",
    "model_loaded": true,
    "device": "cuda"
}

2. 生成图片

POST /api/v1/generate

请求头:

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体:

参数 类型 必填 默认值 说明
prompt string ✓ - 正向提示词，最长 1000 字符
negative_prompt string ✗ "" 反向提示词
width int ✗ 512 图片宽度，256-2048，自动对齐到 8
height int ✗ 512 图片高度，256-2048，自动对齐到 8
num_inference_steps int ✗ 20 推理步数，10-100
guidance_scale float ✗ 7.0 CFG 引导系数，1.0-30.0
seed int ✗ -1 随机种子，-1 为随机

示例:

{
    "prompt": "a cat wearing a spacesuit on mars, highly detailed, 8k",
    "negative_prompt": "blurry, low quality, distorted, bad anatomy",
    "width": 512,
    "height": 512,
    "num_inference_steps": 20,
    "guidance_scale": 7.0,
    "seed": -1
}

成功响应 200:

{
    "success": true,
    "image": {
        "format": "png",
        "data": "iVBORw0KGgo...(base64编码，不含 data:image 前缀)",
        "width": 512,
        "height": 512
    },
    "metadata": {
        "seed": 4294967295,
        "model": "./models/dreamshaper_8.safetensors",
        "generation_time": 3.42,
        "parameters": {
            "prompt": "a cat wearing a spacesuit...",
            "negative_prompt": "blurry, low quality...",
            "width": 512,
            "height": 512,
            "steps": 20,
            "guidance_scale": 7.0
        }
    }
}

错误响应:

status code 说明
400 INVALID_PARAMS 参数校验失败
401 AUTH_FAILED API Key 无效
429 RATE_LIMITED 请求过于频繁
500 CUDA_OUT_OF_MEMORY 显存不足
500 GENERATION_FAILED 生成过程异常
503 MODEL_NOT_LOADED 模型尚未加载

错误响应格式:

{
    "success": false,
    "error": {
        "code": "CUDA_OUT_OF_MEMORY",
        "message": "显存不足，请尝试降低分辨率或步数后重试"
    }
}

限流说明

默认每分钟最多 10 次请求，可通过 SD_RATE_LIMIT_PER_MINUTE 环境变量调整。

限流采用滑动窗口实现，仅基于内存（重启后清零）。

与 WordPress 插件对接

本 API 的请求/响应格式与 sd-wordpress-plugin 的 FastAPI 模式完全对齐。

在 WordPress 插件设置中：

  • API 地址: http://<host>:8000
  • API Key: 与 .env 中 SD_API_KEY 一致
  • API 模式: fastapi

---

## 📄 docs/DEPLOY.md

```markdown
# 部署指南

## 环境要求

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| Python | 3.10 | 3.10+ |
| GPU | 4GB VRAM | 8GB+ VRAM (RTX 3090+) |
| CUDA | 11.8 | 12.1 |
| 内存 | 16GB | 32GB |
| 磁盘 | 20GB | 50GB+ (存放模型) |

---

## 阿里云 ECS 部署流程

### 1. 创建实例

- 实例类型: GPU 计算型 (如 gn6v ecs.gn6v-c8g1.2xlarge)
- 镜像: Ubuntu 22.04
- 系统盘: 40GB+
- 安全组: 开放 8000 端口（仅限你的 WordPress 服务器 IP）

### 2. 环境初始化

```bash
# 更新系统
apt update && apt upgrade -y

# 安装 Python 3.10
apt install -y python3.10 python3.10-venv python3-pip

# 创建虚拟环境
python3.10 -m venv /opt/sd-backend/venv
source /opt/sd-backend/venv/bin/activate

# 安装 CUDA 依赖（选择对应版本）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

3. 部署代码

# 上传代码
cd /opt/sd-backend
# 通过 scp 或 git clone 上传项目文件

# 安装依赖
pip install -r requirements.txt
pip install xformers --index-url https://download.pytorch.org/whl/cu121

4. 下载模型

mkdir -p /opt/sd-backend/models

# 方式 A: 直接 wget
wget -P models/ <模型下载地址>

# 方式 B: 使用 huggingface-cli
pip install huggingface_hub
huggingface-cli download Lykon/DreamShaper DreamShaper_8_pruned.safetensors --local-dir models/

5. 配置环境变量

cp .env.example .env
nano .env

必填项：

SD_API_KEY=你的密钥
SD_MODEL_PATH=./models/DreamShaper_8_pruned.safetensors

6. 配置 systemd 服务

nano /etc/systemd/system/sd-backend.service
[Unit]
Description=SD Backend API
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/sd-backend
Environment=PATH=/opt/sd-backend/venv/bin
ExecStart=/opt/sd-backend/venv/bin/python run.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable sd-backend
systemctl start sd-backend
systemctl status sd-backend

7. 验证

curl http://localhost:8000/health

Nginx 反向代理（可选）

server {
    listen 80;
    server_name sd-api.yourdomain.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;
    }
}

性能优化建议

  1. 显存管理: 设置 SD_ENABLE_VAE_SLICING=true 和 SD_ENABLE_VAE_TILING=true
  2. 半精度推理: SD_TORCH_DTYPE=float16（默认开启）
  3. xformers 加速: SD_USE_XFORMERS=true
  4. 限制尺寸: 设置 SD_MAX_WIDTH 和 SD_MAX_HEIGHT 防止 OOM
  5. 无请求关机: 配合阿里云 API 实现空闲自动停机

---

## 📄 docs/ARCHITECTURE.md

```markdown
# 架构设计

## 整体架构

┌──────────────────────────────────────────────────────┐ │ WordPress 插件 │ │ POST /api/v1/generate (Bearer Token) │ └──────────────────────────┬───────────────────────────┘ │ HTTP ┌──────────────────────────▼───────────────────────────┐ │ FastAPI 服务 (app) │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 路由层 │ │ 中间件层 │ │ │ │ main.py │ │ - CORS │ │ │ │ /api/v1/* │ │ - 鉴权 │ │ │ └──────┬───────┘ │ - 限流 │ │ │ │ └──────────────┘ │ │ ┌──────▼───────┐ │ │ │ 模型层 │ │ │ │ schemas.py │ Pydantic 数据校验 │ │ └──────┬───────┘ │ │ │ │ │ ┌──────▼───────┐ │ │ │ 服务层 │ │ │ │ generator.py│ SD 推理引擎 │ │ └──────┬───────┘ │ │ │ │ │ ┌──────▼───────┐ │ │ │ 工具层 │ │ │ │ image_utils │ PIL ↔ base64 转换 │ │ └──────────────┘ │ │ │ │ ┌──────────────┐ │ │ │ 配置层 │ │ │ │ config.py │ pydantic-settings │ │ └──────────────┘ │ └──────────────────────────────────────────────────────┘ │ ┌──────▼──────┐ │ GPU (CUDA) │ │ diffusers │ │ + xformers │ └─────────────┘


## 请求处理流程
  1. 请求到达 POST /api/v1/generate
  2. CORS 中间件处理跨域
  3. verify_api_key() 验证 Bearer Token
  4. check_rate_limit() 检查限流
  5. GenerateRequest 自动校验参数
  6. generator.generate() 执行推理
  7. pil_to_base64() 编码图片
  8. 返回 GenerateResponse

## 应用生命周期

启动 (lifespan start) ├── 创建 StableDiffusionGenerator 实例 ├── 加载模型到 GPU └── 启用 xformers / VAE slicing / VAE tiling

运行中 └── 处理 HTTP 请求

关闭 (lifespan end) ├── 删除 pipeline ├── torch.cuda.empty_cache() └── 退出


## 错误处理层

异常类型 → HTTP 状态码 ───────────────────────────────────────── 参数校验失败 → 400 API Key 校验失败 → 401 限流触发 → 429 torch.cuda.OutOfMemory → 500 (CUDA_OUT_OF_MEMORY) 其他推理异常 → 500 (GENERATION_FAILED) 模型未加载 → 503 (MODEL_NOT_LOADED) 未知异常 → 500 (INTERNAL_ERROR)

四份项目文档已写好：

文档 内容
docs/README.md 项目概述、快速开始、目录结构
docs/API.md 接口规范、参数说明、错误码
docs/DEPLOY.md 阿里云部署流程、systemd 配置
docs/ARCHITECTURE.md 架构设计、请求流程

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages