DiffuGen - Advanced Local Image Generator with MCP Integration

DiffuGen - 集成 MCP 的高级本地图像生成器

直接嵌入代码中的 AI 艺术工作室。通过这款功能强大的 MCP 服务，为 Cursor、Windsurf 和其他兼容 IDE 生成、迭代并完善视觉创意；借助先进的 Flux 和 Stable Diffusion 模型，无需中断开发流程。

⭐ 新功能：现已支持 OpenAPI 服务，并可与 OpenWebUI OpenAPI Tools（需要 OWUI 0.60.0 版本）集成，以便在聊天界面中无缝生成和显示图像！OpenAPI 与 MCP 服务相互独立，可集成到你自己的项目中！

📃 目录

• 简介
• 了解 MCP 和 DiffuGen
• 功能
• 系统要求
• 安装
• IDE 设置说明
• 用法
  • OpenAPI 服务用法
  • 各模型的默认参数
  • 让大模型生成图像
  • 参数参考
  • 各模型的参数建议
  • 默认参数变更
  • 命令行使用说明
• 配置
  • 配置方法
  • 环境变量覆盖
  • 设置 IDE 专属配置
  • 关键配置项
  • IDE 专属选项
  • 自定义默认参数
  • 更新配置文件
• 高级用法
  • 使用 OpenAPI 服务
• 许可证
• 致谢
• 联系

🚀 简介

DiffuGen 是一款基于 MCP 的强大图像生成系统，可将先进的 AI 模型直接引入你的开发工作流。它将 Flux 模型（Flux Schnell、Flux Dev）和 Stable Diffusion 系列模型（SDXL、SD3、SD1.5）无缝整合到统一界面中，让你无需切换工具，就能发挥各模型系列的独特优势。DiffuGen 支持全面的参数控制和多 GPU，可从在普通硬件上快速绘制概念草图，扩展到在高性能系统上生成可用于生产环境的高质量视觉内容。

DiffuGen 基于高度优化的 stable-diffusion.cpp 实现构建，即使在普通硬件上也能提供卓越性能，同时保持高质量输出。

🧠 了解 MCP 和 DiffuGen

什么是 MCP？

MCP（模型上下文协议）是一种让 LLM（大语言模型）能够访问自定义工具和服务的协议。简而言之，MCP 客户端（例如 Cursor、Windsurf、Roo Code 或 Cline）可以向 MCP 服务发送请求，以访问其提供的工具。

作为 MCP 服务的 DiffuGen

DiffuGen 作为 MCP 服务，提供文本生成图像功能。它实现了 MCP 协议，使兼容的 IDE 能够发送生成请求并接收生成的图像。

该服务提供两个主要工具：

1. generate_stable_diffusion_image：使用 Stable Diffusion 模型生成图像
2. generate_flux_image：使用 Flux 模型生成图像

技术架构

DiffuGen 由几个关键组件组成：

• setup-diffugen.sh：完整的安装工具、模型下载器和管理器
• diffugen.py：实现 MCP 服务功能并定义生成工具的核心 Python 脚本
• diffugen.sh：用于设置环境并启动 Python 服务的 Shell 脚本启动器
• diffugen.json：用于将 MCP 集成到各种 IDE 的模板配置文件（需复制到 IDE 的 MCP 配置中）
• stable-diffusion.cpp：用于实际图像生成的优化版 C++ 实现

系统的工作流程如下：

1. 从 MCP 客户端接收提示词和参数数据
2. 通过 Python 服务处理请求
3. 使用相应的参数调用 stable-diffusion.cpp 二进制文件
4. 将生成的图像保存到配置的输出目录
5. 将生成图像的路径和元数据返回给客户端

关于 stable-diffusion.cpp

stable-diffusion.cpp 是 Stable Diffusion 算法的高度优化 C++ 实现。与 Python 参考实现相比，它具有以下优势：

• 推理速度显著更快（最高可快 3–4 倍）
• 内存占用更低（显存仅需 4GB 的 GPU 也能运行）
• 针对 NVIDIA GPU 优化了 CUDA 内核
• 支持多种采样方法和模型格式
• 支持模型量化，以提升性能
• 核心生成流程不依赖 Python

因此，即使在配置一般的硬件上，DiffuGen 也能提供高质量的图像生成和卓越的性能。

✨ 功能特性

• 支持多种模型：使用多种模型生成图像，包括 Flux Schnell、Flux Dev、SDXL、SD3 和 SD1.5
• MCP 集成：可与支持 MCP 的 IDE 无缝集成（Cursor、Windsurf、Roo Code、Cline 等）
• OpenAPI 服务：提供额外的 REST API 接口，可通过 HTTP 直接使用图像生成功能
• 跨平台：支持 Linux、macOS 和 Windows（原生运行或通过 WSL）
• 参数控制：通过以下选项微调生成效果：
  • 图像尺寸（宽度/高度）
  • 采样步数
  • CFG scale
  • 种子值
  • 负面提示词（仅适用于 SD 模型；Flux 不支持负面提示词。）
  • 采样方法
• CUDA 加速：利用 GPU 加速提升图像生成速度
• 自然语言接口：使用简单的自然语言命令生成图像
• 智能错误恢复：提供稳健的错误处理和针对操作的恢复流程
• 易用的设置流程：交互式设置脚本，改进了中断处理
• 资源跟踪：基于会话的资源管理，便于高效清理
• 可自定义界面：支持自定义 ANSI 艺术字 Logo 和视觉增强效果

💻 系统要求

最低要求：

• CPU：4 核处理器（Intel i5/AMD Ryzen 5 或同等型号）
• RAM：8GB 系统内存
• 存储空间：5GB 可用磁盘空间（建议使用 SSD，以加快模型加载速度）
• Python：3.8 或更高版本
• GPU：集成显卡或入门级独立显卡（可选）
• 网络：用于下载模型的宽带连接（5 Mbps 以上）

推荐配置：

• CPU：8 核及以上处理器（Intel i7/i9 或 AMD Ryzen 7/9）
• 内存：16GB 及以上系统内存
• GPU：显存为 6GB 及以上的 NVIDIA GPU（为获得最佳性能，推荐 RTX 2060 或更高型号）
• 存储：20GB 及以上可用 SSD 空间
• Python：3.10 或更高版本（3.11 性能最佳）
• 网络：高速连接（20 Mbps 及以上），以便高效下载模型

📥 安装

自动安装（推荐）

安装 DiffuGen 最简单的方法是使用提供的设置脚本：

git clone https://github.com/CLOUDWERX-DEV/diffugen.git
cd DiffuGen
chmod +x diffugen.sh
chmod +x setup_diffugen.sh
./setup_diffugen.sh

按照交互式提示完成安装。

设置脚本将：

• 安装必要的依赖项
• 克隆并构建 stable-diffusion.cpp
• 创建 Python 虚拟环境
• 下载所选模型（注意：部分模型还需要 Clip\VAE Models）
• 为你的系统配置文件路径

手动安装

如果你希望手动安装，请按照以下步骤操作：

1. 克隆代码库：

git clone https://github.com/CLOUDWERX-DEV/diffugen.git
cd DiffuGen
git clone --recursive https://github.com/leejet/stable-diffusion.cpp

2. 构建 stable-diffusion.cpp：

cd stable-diffusion.cpp
mkdir -p build && cd build

使用 CUDA：

cmake .. -DCMAKE_BUILD_TYPE=Release -DSD_CUDA=ON
make -j$(nproc)
cd ../..

不使用 CUDA：

cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
cd ../..

3. 创建并激活 Python 虚拟环境：

python3 -m venv diffugen_env
source diffugen_env/bin/activate  # On Windows: diffugen_env\Scripts\activate
pip install -r requirements.txt

4. 下载所需模型（目录结构如下所示）：

stable-diffusion.cpp/models/
├── ae.sft                           # VAE model
├── clip_l.safetensors               # CLIP model
├── flux/
│   ├── flux1-schnell-q8_0.gguf     # Flux Schnell model (default)
│   └── flux1-dev-q8_0.gguf          # Flux Dev model
├── sd3-medium.safetensors           # SD3 model
├── sdxl-1.0-base.safetensors        # SDXL model
├── sdxl_vae-fp16-fix.safetensors    # SDXL VAE
├── t5xxl_fp16.safetensors           # T5 model
└── v1-5-pruned-emaonly.safetensors  # SD1.5 model

你可以从以下来源下载模型：

# Create model directories
mkdir -p stable-diffusion.cpp/models/flux

# Flux models
# Flux Schnell - Fast generation model (Q8 Quantized,requires t5xxl, clip-l, vae)
curl -L https://huggingface.co/leejet/FLUX.1-schnell-gguf/resolve/main/flux1-schnell-q8_0.gguf -o stable-diffusion.cpp/models/flux/flux1-schnell-q8_0.gguf

# Flux Dev - Development model with better quality (Q8 QUantized, requires t5xxl, clip-l, vae)
curl -L https://huggingface.co/leejet/FLUX.1-dev-gguf/resolve/main/flux1-dev-q8_0.gguf -o stable-diffusion.cpp/models/flux/flux1-dev-q8_0.gguf

# Required models for Flux
# T5XXL Text Encoder
curl -L https://huggingface.co/Sanami/flux1-dev-gguf/resolve/main/t5xxl_fp16.safetensors -o stable-diffusion.cpp/models/t5xxl_fp16.safetensors

# CLIP-L Text Encoder
curl -L https://huggingface.co/Sanami/flux1-dev-gguf/resolve/main/clip_l.safetensors -o stable-diffusion.cpp/models/clip_l.safetensors

# VAE for image decoding
curl -L https://huggingface.co/pretentioushorsefly/flux-models/resolve/main/models/vae/ae.safetensors -o stable-diffusion.cpp/models/ae.sft

# Stable Diffusion models
# SDXL 1.0 Base Model (requires sdxl-vae)
curl -L https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors -o stable-diffusion.cpp/models/sd_xl_base_1.0.safetensors

# SDXL VAE (required for SDXL)
curl -L https://huggingface.co/madebyollin/sdxl-vae-fp16-fix/resolve/main/sdxl_vae-fp16-fix.safetensors -o stable-diffusion.cpp/models/sdxl_vae-fp16-fix.safetensors

# Stable Diffusion 1.5 (standalone)
curl -L https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors -o stable-diffusion.cpp/models/v1-5-pruned-emaonly.safetensors

# Stable Diffusion 3 Medium (standalone)
curl -L https://huggingface.co/leo009/stable-diffusion-3-medium/resolve/main/sd3_medium_incl_clips_t5xxlfp16.safetensors -o stable-diffusion.cpp/models/sd3_medium_incl_clips_t5xxlfp16.safetensors

注意：模型下载所需时间取决于你的网络连接。SDXL 模型约为 6GB，SD3 约为 13GB，SD1.5 约为 4GB，Flux 模型各为 8-13GB。

5. 更新配置中的文件路径：

将 shell 脚本设为可执行文件

chmod +x diffugen.sh

配置方式： DiffuGen 使用单个配置文件（diffugen.json）作为所有设置的唯一事实来源。操作流程如下：

1. 在 DiffuGen 根目录中编辑 diffugen.json，设置所需选项
2. 在 setup_diffugen.sh 中运行选项 5，自动更新此文件中的路径
3. 将 diffugen.json 的内容复制到 IDE 的 MCP 配置文件中

该文件包含所有必要的设置：

• 文件路径（command、SD_CPP_PATH、models_dir、output_dir）
• 默认模型参数（steps、cfg_scale、sampling_method）
• VRAM 使用设置
• IDE 集成元数据

{
  "mcpServers": {
    "diffugen": {
      "command": "/home/cloudwerxlab/Desktop/Servers/MCP/Tools/DiffuGen/diffugen.sh",
      "args": [],
      "env": {
        "CUDA_VISIBLE_DEVICES": "0",
        "SD_CPP_PATH": "path/to/stable-diffusion.cpp",
        "default_model": "flux-schnell"
      },
      "resources": {
        "models_dir": "path/to/stable-diffusion.cpp/models",
        "output_dir": "path/to/outputs",
        "vram_usage": "adaptive"
      },
      "metadata": {
        "name": "DiffuGen",
        "version": "1.0",
        "description": "Your AI art studio embedded directly in code. Generate, iterate, and perfect visual concepts through this powerful MCP server for Cursor, Windsurf, and other compatible IDEs, utilizing cutting-edge Flux and Stable Diffusion models without disrupting your development process.",
        "author": "CLOUDWERX LAB",
        "homepage": "https://github.com/CLOUDWERX-DEV/diffugen",
        "usage": "Generate images using two primary methods:\n1. Standard generation: 'generate an image of [description]' with optional parameters:\n   - model: Choose from flux-schnell (default), flux-dev, sdxl, sd3, sd15\n   - dimensions: width and height (default: 512x512)\n   - steps: Number of diffusion steps (default: 20, lower for faster generation)\n   - cfg_scale: Guidance scale (default: 7.0, lower for more creative freedom)\n   - seed: For reproducible results (-1 for random)\n   - sampling_method: euler, euler_a (default), heun, dpm2, dpm++2s_a, dpm++2m, dpm++2mv2, lcm\n   - negative_prompt: Specify elements to avoid in the image\n2. Quick Flux generation: 'generate a flux image of [description]' for faster results with fewer steps (default: 4)"
      },
      "cursorOptions": {
        "autoApprove": true,
        "category": "Image Generation",
        "icon": "🖼️",
        "displayName": "DiffuGen"
      },
      "windsurfOptions": {
        "displayName": "DiffuGen",
        "icon": "🖼️",
        "category": "Creative Tools"
      },
      "default_params": {
        "steps": {
          "flux-schnell": 8,
          "flux-dev": 20,
          "sdxl": 20,
          "sd3": 20,
          "sd15": 20
        },
        "cfg_scale": {
          "flux-schnell": 1.0,
          "flux-dev": 1.0,
          "sdxl": 7.0,
          "sd3": 7.0, 
          "sd15": 7.0
        },
        "sampling_method": {
          "flux-schnell": "euler",
          "flux-dev": "euler",
          "sdxl": "euler",
          "sd3": "euler",
          "sd15": "euler"
        }
      }
    }
  }
}

🔧 IDE 设置说明

在 Cursor 中设置

1. 下载并安装 Cursor
2. 前往 Cursor 设置 > MCP，然后点击“添加新的全局 MCP 服务”
3. 复制 DiffuGen 的 diffugen.json 文件内容并粘贴到 ~/.cursor/mcp.json
4. 在设置 > MCP 中刷新 MCP 服务
5. 打开 AI 聊天面板（Ctrl+K 或 Cmd+K），请求生成图像，即可使用 DiffuGen

在 Windsurf 中设置

1. 下载并安装 Windsurf
2. 前往 Windsurf > 设置 > 高级设置，或打开命令面板 > 打开 Windsurf 设置页面
3. 向下滚动到 Cascade 部分，点击“添加服务” > “添加自定义服务 +”
4. 复制 DiffuGen 的 diffugen.json 文件内容并粘贴到 ~/.codeium/windsurf/mcp_config.json
5. 通过 Cascade 聊天界面使用 DiffuGen

在 Roo Code 中设置

1. 下载并安装 Roo Code
2. 找到 Roo Code 的 MCP 配置文件
3. 将 DiffuGen 的 diffugen.json 文件内容复制到 Roo Code 的 MCP 配置中
4. 通过 AI 助手功能使用 DiffuGen

在 Cline 中设置

1. 下载并安装 Cline
2. 将 DiffuGen 的 diffugen.json 文件内容复制到 Cline 的 MCP 设置中
3. 通过 AI 聊天或命令界面使用 DiffuGen

在 Anthropic Console 中使用 Claude

如果你已在系统上将 DiffuGen 设置为 MCP 服务，Claude 就可以使用它。请求 Claude 生成图像时，请明确指定使用 DiffuGen，并提供你想使用的参数。

🎮 使用方法

手动启动 DiffuGen 服务：

cd /path/to/diffugen
./diffugen.sh

也可以直接使用 Python 启动：

cd /path/to/diffugen
python -m diffugen

服务成功启动后，你应该会看到：DiffuGen ready。

OpenAPI 服务用法

OpenAPI 服务提供 REST API 接口，可通过 HTTP 直接使用 DiffuGen 的图像生成能力。除了 MCP 集成外，它还适用于：

• 直接通过 HTTP API 访问
• 与不支持 MCP 的其他工具集成
• 需要以编程方式访问的自定义应用

如需详细的设置说明和高级配置选项，请参阅 OpenAPI 集成指南。

启动 OpenAPI 服务：

python diffugen_openapi.py

如果需要，可以将服务配置为使用其他主机或端口。默认情况下，它运行于：

• 主机：0.0.0.0
• 端口：8080

服务将在 http://0.0.0.0:8080 提供，交互式文档位于 http://0.0.0.0:8080/docs。

生成的图像默认保存到 /output 目录。如果无法访问此目录，服务会自动在当前工作目录中创建 output 目录。图像通过 /images 端点提供。

OpenWebUI 集成

1. 打开 OpenWebUI 设置（齿轮图标）
2. 前往“工具”部分
3. 点击“+”按钮，添加新的工具服务
4. 输入以下详细信息：
   • URL：http://0.0.0.0:5199
   • API Key：（留空）
5. 点击“保存”

添加后，在聊天界面中点击工具图标时，DiffuGen 将显示在可用工具列表中。以下端点将可用：

• generate_stable_image_generate_stable_post：使用 Stable Diffusion 生成
• generate_flux_image_endpoint_generate_flux_post：使用 Flux Models 生成
• list_models_models_get：列出可用模型

使用 curl 的示例：

curl -X POST "http://0.0.0.0:5199/generate/flux" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "A beautiful sunset", "model": "flux-schnell"}'

使用 Python requests 的示例：

import requests

response = requests.post(
    "http://0.0.0.0:5199/generate/flux",
    json={
        "prompt": "A beautiful sunset",
        "model": "flux-schnell"
    }
)
result = response.json()

各模型的默认参数

每个模型都有针对最佳效果优化的特定默认参数：

模型	默认步数	默认 CFG Scale	最适用于
flux-schnell	8	1.0	快速草稿、概念图像
flux-dev	20	1.0	质量更高的 Flux 生成结果
sdxl	20	7.0	高质量细节丰富的图像
sd3	20	7.0	最新一代模型，生成质量良好
sd15	20	7.0	经典基准模型

可以在 IDE 的 MCP 配置文件中添加 default_params 部分，自定义这些默认参数：

"default_params": {
  "steps": {
    "flux-schnell": 12,  // Customize steps for better quality
    "sdxl": 30           // Increase steps for more detailed SDXL images
  },
  "cfg_scale": {
    "sd15": 9.0          // Higher cfg_scale for stronger prompt adherence
  }
}

只需指定要覆盖的参数即可——任何未指定的值都将使用内置默认值。

注意：如需特定模型的命令行示例和建议，请参阅特定模型的参数建议部分。

让大模型生成图像

以下是让 AI 助手使用 DiffuGen 生成图像的示例：

基本请求：

Generate an image of a cat playing with yarn

Create a picture of a futuristic cityscape with flying cars

指定模型：

Generate an image of a medieval castle using the sdxl model

Create a flux image of a sunset over mountains

使用高级参数：

Generate an image of a cyberpunk street scene, model=flux-dev, width=768, height=512, steps=25, cfg_scale=1.0, seed=42

Create an illustration of a fantasy character with model=sd15, width=512, height=768, steps=30, cfg_scale=7.5, sampling_method=dpm++2m, negative_prompt=blurry, low quality, distorted

参数参考

DiffuGen 可以通过命令行使用，基本语法如下：

./diffugen.sh "Your prompt here" [options]

示例：

./diffugen.sh "A futuristic cityscape with flying cars"

此命令使用默认参数（flux-schnell 模型、512x512 分辨率等）生成图像，并将其保存到配置的输出目录。

以下是 DiffuGen 支持的参数（适用于 MCP 接口和命令行）：

参数	说明	默认值	有效值	命令行标志
model	用于生成的模型	flux-schnell/sd15	flux-schnell、flux-dev、sdxl、sd3、sd15	--model
width	图像宽度（像素）	512	256-2048	--width
height	图像高度（像素）	512	256-2048	--height
steps	扩散步数	依模型而定	1-100	--steps
cfg_scale	无分类器引导缩放	依模型而定	0.1-30.0	--cfg-scale
seed	用于确保结果可复现的随机种子	-1（随机）	-1 或任意整数	--seed
sampling_method	扩散采样方法	euler	euler、euler_a、heun、dpm2、dpm++2s_a、dpm++2m、dpm++2mv2、lcm	--sampling-method
negative_prompt	图像中要避免的元素	""（空）	任意文本字符串	--negative-prompt
output_dir	图像保存目录	由配置定义	有效路径	--output-dir

使用 AI 助手生成图像或通过命令行界面操作时，都可以指定这些参数。参数格式因使用的接口而异：

• 在 MCP/AI 助手中：parameter=value（例如：model=sdxl, width=768, height=512）
• 在命令行中：--parameter value（例如：--model sdxl --width 768 --height 512）

这些默认值旨在以最短等待时间提供良好的开箱即用效果。若要生成质量更高的图像，可以增加 steps，或切换到 sdxl 等模型。

模型专属参数建议

注意：这些建议基于各模型的默认参数一节，并提供了实用示例。

通过命令行使用特定模型时，若要获得最佳效果：

Flux 模型（flux-schnell、flux-dev）

# Flux-Schnell (fastest)
./diffugen.sh "Vibrant colorful abstract painting" \
  --model flux-schnell \
  --cfg-scale 1.0 \
  --sampling-method euler \
  --steps 8

# Flux-Dev (better quality)
./diffugen.sh "Detailed fantasy landscape with mountains and castles" \
  --model flux-dev \
  --cfg-scale 1.0 \
  --sampling-method euler \
  --steps 20

标准 SD 模型（sdxl、sd3、sd15）

# SDXL (highest quality)
./diffugen.sh "Hyperrealistic portrait of a Celtic warrior" \
  --model sdxl \
  --cfg-scale 7.0 \
  --sampling-method dpm++2m \
  --steps 30

# SD15 (classic model)
./diffugen.sh "Photorealistic landscape at sunset" \
  --model sd15 \
  --cfg-scale 7.0 \
  --sampling-method euler_a \
  --steps 20

默认参数变更

如果配置中未另行指定，DiffuGen 的命令行界面会使用以下默认值：

• 默认模型：如果未指定，则使用与函数相对应的模型（Flux 函数使用 flux-schnell，SD 函数使用 sd15）
• 默认采样方法：euler（最适合 Flux 模型）
• 默认 CFG Scale：Flux 模型为 1.0，标准 SD 模型为 7.0
• 默认步数：flux-schnell 为 8，其他模型为 20
• 默认尺寸：512x512 像素

使用命令行时，除非要覆盖默认值，否则无需指定这些参数。如果经常使用特定参数，可以考虑将其添加到配置文件中，而不是每次运行命令时都指定。

命令行使用说明

• 生成的图像会保存到配置的输出目录，文件名根据时间戳和参数生成
• 多次运行命令即可依次生成多张图像
• 若要进行批量处理，可以创建一个调用 DiffuGen 并使用不同参数的 shell 脚本
• 若要查看所有可用的命令行选项，请运行 ./diffugen.sh --help
• MCP 接口和命令行工具使用相同的引擎，因此质量和功能完全相同

⚙️ 配置

配置方式

DiffuGen 采用以 diffugen.json 文件为核心的统一配置方式：

1. 主要配置文件：DiffuGen 根目录中的 diffugen.json 是所有设置的唯一真实来源
2. IDE 集成：将 diffugen.json 的内容复制到 IDE 的 MCP 配置文件中
3. 环境变量：对于高级用法，可以使用环境变量覆盖设置

环境变量覆盖

对于高级用法，可以使用环境变量覆盖设置：

• SD_CPP_PATH：覆盖 stable-diffusion.cpp 的路径
• DIFFUGEN_OUTPUT_DIR：覆盖输出目录
• DIFFUGEN_DEFAULT_MODEL：覆盖默认模型
• DIFFUGEN_VRAM_USAGE：覆盖 VRAM 使用设置
• CUDA_VISIBLE_DEVICES：控制用于生成的 GPU

设置特定于 IDE 的配置

DiffuGen 允许你在各个 IDE 的 MCP 配置中使用环境变量，为不同 IDE 设置不同配置。这样，你可以维护一个统一的基础 diffugen.json，同时针对每个 IDE 自定义参数。

配置优先级如下：

1. 环境变量（优先级最高）
2. 本地 diffugen.json 文件中的设置（基础配置）

示例：为不同 IDE 设置不同的输出目录

Cursor（位于 ~/.cursor/mcp.json）：

"env": {
  "CUDA_VISIBLE_DEVICES": "0",
  "SD_CPP_PATH": "/path/to/stable-diffusion.cpp",
  "DIFFUGEN_OUTPUT_DIR": "/cursor/specific/output/directory",
  "default_model": "flux-schnell"
}

Windsurf（位于 ~/.codeium/windsurf/mcp_config.json）：

"env": {
  "CUDA_VISIBLE_DEVICES": "0",
  "SD_CPP_PATH": "/path/to/stable-diffusion.cpp",
  "DIFFUGEN_OUTPUT_DIR": "/windsurf/specific/output/directory",
  "default_model": "sdxl"
}

示例：设置不同的默认模型和 VRAM 设置

"env": {
  "CUDA_VISIBLE_DEVICES": "0",
  "SD_CPP_PATH": "/path/to/stable-diffusion.cpp",
  "default_model": "flux-dev", 
  "DIFFUGEN_VRAM_USAGE": "maximum"
}

这种方式让你可以针对每个 IDE 自定义 DiffuGen 的行为，同时继续使用同一套底层安装。

关键配置项

命令和参数

• command：diffugen.sh 脚本的完整路径（必须是绝对路径）
• args：传递给脚本的其他命令行参数（通常留空）

环境变量

• CUDA_VISIBLE_DEVICES：控制用于生成的 GPU

  • "0"：仅使用第一块 GPU
  • "1"：仅使用第二块 GPU
  • "0,1"：同时使用第一和第二块 GPU
  • "-1"：禁用 CUDA，仅使用 CPU

• SD_CPP_PATH：stable-diffusion.cpp 安装目录的路径

  • 用于定位 stable-diffusion.cpp 二进制文件和模型

• default_model：未指定模型时使用的默认模型

资源配置

• models_dir：模型文件所在目录

  • 应指向 stable-diffusion.cpp 安装目录中的 models 目录

• output_dir：生成图像的保存目录

  • 运行 DiffuGen 的用户必须对此目录具有写入权限

• vram_usage：控制 VRAM 使用策略

  • "adaptive"：根据可用 VRAM 自动调整内存使用量
  • "minimal"：以牺牲速度为代价，尽量减少 VRAM 使用量
  • "balanced"：平衡内存使用量和速度（默认）
  • "maximum"：使用最大可用 VRAM，以获得最佳性能

特定于 IDE 的选项

你可以在 diffugen.json 文件中自定义各个 IDE 的特定选项：

Cursor 选项

"cursorOptions": {
  "autoApprove": true,
  "category": "Image Generation",
  "icon": "🖼️",
  "displayName": "DiffuGen"
}

Windsurf 选项

"windsurfOptions": {
  "displayName": "DiffuGen",
  "icon": "🖼️",
  "category": "Creative Tools"
}

自定义默认参数

你可以在 default_params 部分自定义各个模型的默认参数：

"default_params": {
  "steps": {
    "flux-schnell": 12,
    "sdxl": 30
  },
  "cfg_scale": {
    "sd15": 9.0
  },
  "sampling_method": {
    "flux-schnell": "euler",
    "sdxl": "dpm++2m"
  }
}

更新配置文件

使用自动设置脚本时，运行选项 5 会创建一个配置正确的 diffugen.json 文件，其中包含适用于你系统的正确路径。要将 DiffuGen 集成到 IDE 中：

1. 运行 setup_diffugen.sh 中的选项 5，更新 diffugen.json 中的路径
2. 复制生成的 diffugen.json 文件的全部内容
3. 将其粘贴到 IDE 的 MCP 配置文件中（例如 ~/.cursor/mcp.json）
4. 重启 IDE 以应用更改

这种方式的主要优势是配置只有一个真实来源，因此更易于维护和更新 DiffuGen 设置。

📃 高级用法

你可以在自己的 Python 脚本中导入 DiffuGen Python 模块并以编程方式使用：

from diffugen import generate_image

# Generate an image programmatically
result = generate_image(
    prompt="A starry night over a quiet village",
    model="sdxl",
    width=1024,
    height=768,
    steps=30,
    cfg_scale=7.0,
    seed=42,
    sampling_method="dpm++2m",
    negative_prompt="blurry, low quality"
)

print(f"Image saved to: {result['file_path']}")

使用 OpenAPI 服务

你也可以在应用程序中以编程方式使用 OpenAPI 服务：

import requests

def generate_image_via_api(prompt, model="flux-schnell", width=512, height=512):
    response = requests.post(
        "http://0.0.0.0:5199/generate/flux",
        json={
            "prompt": prompt,
            "model": model,
            "width": width,
            "height": height
        }
    )
    return response.json()

# Example usage
result = generate_image_via_api(
    prompt="A magical forest at night",
    model="flux-schnell",
    width=768,
    height=512
)
print(f"Generated image: {result['file_path']}")

🔍 故障排除

常见问题及解决方案

1. 缺少模型或路径不正确

   • 确保已下载所有模型文件，并将其放在正确的目录中
   • 检查配置文件中的路径是否设置正确
   • 确认文件权限允许读取模型文件

2. CUDA/GPU 问题

   • 确保 NVIDIA 驱动程序为最新版本
   • 将 CUDA_VISIBLE_DEVICES 设置为目标 GPU
   • 如果显存不足，请尝试使用较小的模型或降低尺寸

3. 图像质量问题

   • 增加步数以获得更好的质量（但会延长生成时间）
   • 调整 CFG scale：数值越高，越遵循提示词；数值越低，创造性越强
   • 尝试不同的采样方法（dpm++2m 通常效果不错）
   • 使用更详细的提示词，并具体描述风格

4. 文件权限错误

   • 确保运行 DiffuGen 的用户对输出目录具有写入权限
   • 检查所有脚本是否具有执行权限（chmod +x diffugen.sh）

获取帮助

如果你遇到此处未涵盖的问题，可以：

• 查看 GitHub 仓库中的问题及解决方案
• 启用调试日志运行：DEBUG=1 ./diffugen.sh "your prompt"
• 通过 GitHub issues 联系开发者

🌟 参与贡献

欢迎为 DiffuGen 做出贡献！参与方式：

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 提交 pull request

请确保你的代码遵循项目的编码规范，并包含适当的测试。

📄 许可证

本项目采用 Apache License 许可，详情请参阅 LICENSE 文件。

• 所有模型均根据各自的分发许可授权，并非由 CLOUDWERX.DEV 以任何方式授权或提供
• 使用 HuggingFace.co 下载模型；该网站与 CLOUDWERX.DEV 没有任何关联

🙏 致谢

• 感谢 stable-diffusion.cpp 提供优化的 C++ 实现
• 感谢 Stability AI 提供 Stable Diffusion 模型
• 感谢 Black Forest Labs 提供 Flux Models
• 感谢 Hugging Face 提供下载链接
• 感谢所有 MCP 协议贡献者

📬 联系方式

• GitHub：CLOUDWERX-DEV
• 网站：cloudwerx.dev
• 邮箱：[email protected]
• Discord：加入我们的服务器

                   ______   __   ___   ___         _______              
                  |   _  \ |__|.'  _|.'  _|.--.--.|   _   |.-----.-----.
                  |.  |   \|  ||   _||   _||  |  ||.  |___||  -__|     |
                  |.  |    \__||__|  |__|  |_____||.  |   ||_____|__|__|
                  |:  1    /                      |:  1   |             
                  |::.. . /                       |::.. . |             
                  `------'                        `-------'             

由 CLOUDWERX LAB 用 ❤️ 制作