# ul-imgen

**Repository Path**: ulthon/ul-imgen

## Basic Information

- **Project Name**: ul-imgen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ul-imgen

统一AI图片生成网关 - Docker一键启动，支持多种模型和API。

## 特性

- 🚀 **一键启动** - 通过 Docker Compose 快速部署，开箱即用
- 🎨 **多模型支持** - 支持 diffusers 本地模型、多模态 LLM、以及云端 API
- 🔌 **统一接口** - 提供 Ollama 风格和 OpenAI 兼容的 API 接口
- 🌐 **Web UI** - 内置现代化的 Web 界面，支持任务队列和图片预览
- 📦 **模块化架构** - Worker 设计，按需扩展
- 🎭 **三种生成模式**:
  - **文生图** - 根据文字描述生成图片
  - **图生图** - 基于参考图片进行风格转换或修改
  - **图片编辑 (Inpainting)** - 浏览器内绘制蒙版，局部重绘图片

## 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/ulthon/ul-imgen.git
cd ul-imgen
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置必要的环境变量：

```bash
# 服务配置
PORT=32521
MAX_VRAM_USAGE=0.9

# HuggingFace 镜像（中国用户推荐）
HF_ENDPOINT=https://hf-mirror.com
HF_TOKEN=hf_xxx
HF_HUB_DISABLE_XET=1

# 第三方API密钥（可选）
OPENAI_API_KEY=sk-xxx
ZHIPU_API_KEY=xxx
ALIYUN_API_KEY=xxx
```

> 💡 **中国用户**: 项目已预配置清华 pip 镜像和 HuggingFace 镜像，首次构建和下载模型会更快。

### 3. 启动服务

```bash
docker compose up -d
```

### 4. 访问服务

- **Web UI**: http://localhost:32521/ （自动重定向到Vue前端）
- **API 文档**: http://localhost:32521/docs
- **API 端点**: http://localhost:32521

## Web UI 功能

新版Web UI基于Vue 3构建，提供现代化的用户界面：

### 主要功能
- 📋 **任务队列管理** - 实时查看所有任务状态（pending、running、completed、failed、cancelled）
- ⚡ **随时添加任务** - 无需等待当前任务完成，支持并发任务队列
- 🚫 **取消任务** - 支持取消正在运行的任务（pending立即取消，running等待当前步骤完成）
- 🎨 **参数预设** - 6个内置预设（快速、标准、高质量、竖版人像、横版风景、4K超清）
- 🖼️ **图片预览** - 全屏查看生成的图片，支持键盘切换
- 📱 **响应式布局** - 支持桌面（3列）、平板（2列）、移动端（单列）
- 🎭 **蒙版编辑器** - 浏览器内绘制蒙版，支持 Inpainting 局部重绘

### 支持的生成模式

| 模式 | 说明 | 使用方式 |
|------|------|----------|
| **文生图** | 根据文字描述生成图片 | 选择任意模型，输入提示词即可 |
| **图生图** | 基于参考图片进行风格转换或修改 | 上传参考图片，设置 strength 参数 |
| **图片编辑 (Inpainting)** | 对图片特定区域进行智能修复或替换 | 选择 Inpainting 模型，上传图片并绘制蒙版 |

### 蒙版编辑器使用

选择支持 Inpainting 的模型（如 SD 1.5 Inpainting 或 Flux Fill）后，上传参考图片即可使用蒙版编辑器：

1. **画笔工具** - 绘制需要修改的区域（白色表示重绘区域）
2. **橡皮擦工具** - 擦除已绘制的蒙版
3. **画笔大小** - 调整画笔粗细（10-100像素）
4. **清除按钮** - 清空所有蒙版

**使用技巧**：
- 蒙版中白色区域会被重绘，黑色区域保持不变
- 边缘可以稍微画宽一些，以便更好地融合
- Flux Fill 不使用 strength 参数，重绘程度完全由蒙版控制

### 开发模式
如需本地开发 Vue 前端（支持热重载）：

```bash
# 方式 1: 直接运行（需要本地 Node.js）
cd web
npm install
npm run dev
# 访问 http://localhost:5173

# 方式 2: 使用 Docker（推荐）
docker build -t ul-imgen-web-dev -f web/Dockerfile ./web
docker run -d --name ul-imgen-web-dev -p 5173:5173 -v ${PWD}/web:/app -v /app/node_modules -e VITE_API_TARGET=http://host.docker.internal:32521 ul-imgen-web-dev
# 访问 http://localhost:5173

# 停止开发服务器
docker stop ul-imgen-web-dev && docker rm ul-imgen-web-dev
```

### 构建前端
Docker构建会自动编译Vue前端。如需手动构建：

```bash
cd web
npm run build
# 构建产物输出到 app/static/
```

## 配置

### 模型配置

在 `configs/models/` 目录下创建 YAML 文件配置模型：

#### 本地模型配置

```yaml
# configs/models/flux-dev.yaml
id: black-forest-labs/FLUX.1-dev
type: diffusers
name: FLUX.1 Dev
description: 高质量文生图模型

source:
  type: huggingface
  repo: black-forest-labs/FLUX.1-dev

defaults:
  width: 1024
  height: 1024
  steps: 30
  guidance_scale: 3.5

requirements:
  vram_min: 12GB
  vram_recommend: 24GB
```

**支持的 source 类型：**
- `huggingface`: 从 HuggingFace 下载，使用 `repo` 字段指定仓库 ID
- `local`: 本地模型，放在 `volumes/models/` 目录下

#### API 模型配置

API 模型同样放在 `configs/models/` 目录，每个模型一个文件：

```yaml
# configs/models/openai-dall-e-3.yaml
id: openai/dall-e-3
type: image_generation_api
provider: openai
name: DALL-E 3

api:
  endpoint: https://api.openai.com/v1
  key: ${OPENAI_API_KEY}
  timeout: 60

capabilities:
  - text_to_image

# 默认参数
defaults:
  width: 1024
  height: 1024
  quality: "standard"
```

### 系统配置

系统行为配置放在 `configs/` 根目录：

- `model_manager.yaml`: 模型管理器配置（系统行为）

**支持的 source 类型（本地模型）：**
- `huggingface`: 从 HuggingFace 下载，使用 `repo` 字段指定仓库 ID
- `local`: 本地模型，放在 `volumes/models/` 目录下

## API 使用

### 1. 文生图 (Text-to-Image)

根据文字描述生成图片：

```bash
curl -X POST http://localhost:32521/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stabilityai/stable-diffusion-xl-base-1.0",
    "prompt": "a beautiful sunset over the ocean, golden hour lighting",
    "width": 1024,
    "height": 1024
  }'
```

### 2. 图生图 (Image-to-Image)

基于参考图片进行风格转换或修改：

```bash
curl -X POST http://localhost:32521/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stabilityai/stable-diffusion-xl-base-1.0",
    "prompt": "convert to oil painting style",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "strength": 0.75
  }'
```

**参数说明**：
- `image`: 输入图片（Base64 Data URI 格式）
- `strength`: 转换强度（0.0-1.0），0.3=轻微修改，0.75=平衡，1.0=完全重绘

### 3. 图片编辑 (Inpainting)

对图片特定区域进行智能修复或替换：

```bash
curl -X POST http://localhost:32521/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runwayml/stable-diffusion-inpainting",
    "prompt": "a fluffy white cat",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "mask": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgBB..."
  }'
```

**参数说明**：
- `image`: 原图（Base64 Data URI 格式）
- `mask`: 蒙版图片，白色/透明区域会被重绘，黑色区域保持不变

**支持的 Inpainting 模型**：
| 模型 | 显存需求 | 特点 |
|------|----------|------|
| `runwayml/stable-diffusion-inpainting` | 4-8GB | 经典 SD 1.5 Inpainting，支持 strength 参数 |
| `black-forest-labs/FLUX.1-Fill-dev` | 16-24GB | 高质量专业修复，不使用 strength 参数 |

### OpenAI 兼容 API

```bash
curl -X POST http://localhost:32521/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stabilityai/stable-diffusion-xl-base-1.0",
    "prompt": "a beautiful sunset over the ocean",
    "size": "1024x1024"
  }'
```

### 响应示例

```json
{
  "created": 1234567890,
  "data": [
    {
      "url": "http://localhost:32521/output/xxx.png"
    }
  ]
}
```

### 任务管理 API

#### 批量查询任务状态

```bash
curl -X POST http://localhost:32521/api/tasks/query \
  -H "Content-Type: application/json" \
  -d '{
    "task_ids": ["task-id-1", "task-id-2", "task-id-3"]
  }'
```

**特性**：
- 一一对应返回：返回的 tasks 数组长度 === 请求的 task_ids 数组长度
- 不存在的任务也会返回，状态为 `not_found`
- 支持查询任何状态的任务（pending, running, completed, failed, cancelled）

**响应示例**：

```json
{
  "tasks": [
    {"task_id": "task-id-1", "status": "completed", "images": [{"url": "..."}]},
    {"task_id": "task-id-2", "status": "not_found", "error": "Task not found or expired"},
    {"task_id": "task-id-3", "status": "running"}
  ]
}
```

#### 查询单个任务

```bash
curl http://localhost:32521/api/tasks/{task_id}
```

#### 取消任务

```bash
curl -X DELETE http://localhost:32521/api/tasks/{task_id}
```

#### 查看活跃任务

```bash
curl http://localhost:32521/api/tasks
```

返回当前队列中的 pending 和 running 任务，不包含历史任务。

## 支持的模型类型

| 类型 | Worker | 描述 |
|------|--------|------|
| `diffusers` | worker-diffusers | 本地扩散模型 (SD, Flux, CogView 等) |
| `llm_multimodal` | worker-llm | 多模态大模型 (GLM-4V, Qwen-VL 等) |
| `image_generation_api` | worker-http-api | **通用云端 API**（统一处理 OpenAI、智谱、阿里云等）|
| `downloader` | worker-downloader | 模型下载队列服务（单任务串行下载） |

### 云端 API 模型配置

所有云端 API 模型统一使用 `image_generation_api` 类型，由 `worker-http-api` 处理：

```yaml
# configs/models/openai-dall-e-3.yaml
id: openai/dall-e-3
type: image_generation_api
provider: openai
name: DALL-E 3

api:
  endpoint: https://api.openai.com/v1
  key: ${OPENAI_API_KEY}
  timeout: 60

defaults:
  size: "1024x1024"
  quality: "standard"
```

**支持的云服务提供商**：
- OpenAI (DALL-E)
- 智谱 AI (CogView)
- 阿里云 (Wanx)
- 任何兼容 OpenAI Images API 格式的服务

### 预配置模型

#### 文生图模型

| 模型 ID | 类型 | 显存需求 | 说明 |
|---------|------|----------|------|
| `stabilityai/stable-diffusion-xl-base-1.0` | diffusers | 8-12GB | SDXL 高质量 |
| `runwayml/stable-diffusion-v1-5` | diffusers | 4-8GB | SD 1.5 经典版 |
| `black-forest-labs/FLUX.1-schnell` | diffusers | 8-16GB | Flux 极速版 |

#### 图生图模型

支持 `image_to_image` 能力的模型可用于图生图：

| 模型 ID | 显存需求 | 说明 |
|---------|----------|------|
| `stabilityai/stable-diffusion-xl-base-1.0` | 8-12GB | SDXL，高质量转换 |
| `runwayml/stable-diffusion-v1-5` | 4-8GB | SD 1.5，经典版 |
| `Lykon/dreamshaper-8` | 4-8GB | DreamShaper，全能型 |

#### 图片编辑模型 (Inpainting)

专用 Inpainting 模型，支持局部重绘：

| 模型 ID | 显存需求 | 说明 |
|---------|----------|------|
| `runwayml/stable-diffusion-inpainting` | 4-8GB | SD 1.5 Inpainting，支持 strength 参数 |
| `black-forest-labs/FLUX.1-Fill-dev` | 16-24GB | Flux Fill，高质量专业修复 |

#### 多模态模型

| 模型 ID | 类型 | 显存需求 | 说明 |
|---------|------|----------|------|
| `THUDM/cogagent-9b-20241220` | llm_multimodal | 24GB | 智谱视觉语言模型 |

> ⚠️ **注意**: FLUX 等受限模型需要在 HuggingFace 上接受条款并配置 `HF_TOKEN` 环境变量。

### 服务端口

| 服务 | 端口 |
|------|------|
| Gateway (统一网关) | 32521 |

## 目录结构

```
ul-imgen/
├── app/                    # Gateway 主服务
├── workers/                # Worker 服务
│   ├── diffusers/          # 本地扩散模型 Worker (GPU)
│   ├── llm/                # 多模态 LLM Worker (GPU)
│   ├── http-api/           # 统一 HTTP API Worker (云端 API)
│   └── downloader/         # 模型下载 Worker（单任务串行）
├── web/                    # Vue 3 前端
│   └── src/
│       └── components/
│           ├── MaskEditor.vue    # 蒙版编辑器组件
│           └── config/
│               └── ConfigPanel.vue  # 配置面板（集成 MaskEditor）
├── configs/                # 配置文件目录
│   ├── models/             # 所有模型配置（本地模型 + API 模型）
│   │   ├── sd-1.5.yaml     # 本地模型 - 文生图
│   │   ├── sdxl-base.yaml  # 本地模型 - 文生图
│   │   ├── sd-1.5-inpaint.yaml  # 本地模型 - Inpainting
│   │   ├── flux-fill.yaml  # 本地模型 - Inpainting
│   │   ├── cogagent.yaml   # 本地模型 - 多模态
│   │   ├── openai-dall-e-3.yaml   # API 模型
│   │   ├── zhipu-cogview-3.yaml   # API 模型
│   │   └── aliyun-wanx-v1.yaml    # API 模型
│   └── model_manager.yaml  # 系统配置（模型管理器）
├── volumes/
│   ├── models/             # 本地模型文件存储
│   ├── output/             # 生成的图片输出
│   └── hf-cache/           # HuggingFace 模型缓存
├── docs/                   # 文档目录
│   ├── API_DOCUMENTATION.md    # API 接口文档
│   ├── CAPABILITIES.md     # 功能标签说明
│   ├── ARCHITECTURE.md     # 架构设计文档
│   └── DEPLOYMENT.md       # 部署指南
├── docker-compose.yml
├── .env.example
└── README.md
```

## 常见问题

### 任务生命周期

**自动清理**：
- 已完成/失败/取消的任务会在 1 小时后自动清理
- 清理任务每 5 分钟运行一次
- 清理后的任务查询会返回 `not_found` 状态

**前端持久化**：
- Web UI 使用 localStorage 存储用户创建的任务 ID
- 刷新页面后任务列表仍然显示（通过批量查询恢复）
- 最多保存 100 个任务 ID

### GPU 支持问题

确保已安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)：

```bash
# 验证 GPU 是否可用
docker run --rm --gpus all nvidia/cuda:11.8-base nvidia-smi
```

### 模型下载

前端切换模型不会自动下载，需要点击“下载模型”按钮后才会提交下载任务。中国用户已预配置 `hf-mirror.com` 镜像。

下载的模型会缓存到 Docker volume `hf-cache`，避免重复下载。

### 构建加速

项目已预配置中国镜像：
- **pip**: 清华大学镜像 (`pypi.tuna.tsinghua.edu.cn`)
- **apt**: 阿里云镜像 (`mirrors.aliyun.com`)
- **npm**: npmmirror (`registry.npmmirror.com`)
- **HuggingFace**: `hf-mirror.com`

如需使用其他镜像，修改对应 Dockerfile 中的镜像地址。

## License

MIT License