# ICHP-AI

**Repository Path**: ayako17/ichp-ai

## Basic Information

- **Project Name**: ICHP-AI
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feature/txt2img-english-prompt-adapter
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 非遗纹样 AI 设计平台

非遗纹样 AI 设计平台是一个面向传统纹样数字化展示、智能生成与创新应用的 Web 平台。项目围绕“非遗纹样资源展示 + AI 创作 + 作品管理 + 推理服务优化”展开，结合微服务后端、Vue 前端和 Python AI 推理服务，为非遗纹样的浏览、再设计和应用落地提供一套可扩展的技术原型。

本仓库当前已经包含前端页面、Java 微服务、Python AI 适配层、图生图/文生图推理服务实验代码，以及本地 Docker 依赖环境。

## 项目亮点

- **非遗纹样资源展示**：支持纹样列表、关键词检索、分类/标签筛选、纹样详情和收藏状态展示。
- **AI 图生图创作**：支持选择纹样和载体模板，调用远端图像编辑服务生成应用效果图，并支持任务轮询、取消、结果转存和作品保存。
- **AI 文生图创作**：支持中文描述输入、Prompt 模板、纹样类型和复杂度配置，后端自动构建更适合 Flux/LoRA 推理的英文 Prompt，并可接入 RAG/LLM Prompt 改写。
- **作品管理**：支持登录用户与匿名设备的作品保存和列表展示。
- **微服务架构**：后端按网关、纹样、图生图、文生图、用户等核心服务拆分，并预留推荐、文件等扩展服务，便于后续扩展和独立部署。
- **推理服务工程化优化**：仓库包含 `t2i-pure` 与 `i2i-pure`，分别用于文生图和图生图远端推理服务，已加入队列调度、限流、熔断、缓存、批处理和性能测试相关实现。

## 技术架构

平台采用前后端分离和微服务化架构。前端基于 Vue 3 和 Vite 构建，通过统一请求封装访问后端接口；后端入口由 Spring Cloud Gateway 承担，负责路由转发、跨域处理、请求日志和鉴权相关逻辑。

业务服务按领域拆分为多个 Spring Boot 服务：`pattern-service` 负责纹样资源查询与详情展示，`img2img-service` 负责任务式图生图创作编排，`txt2img-service` 负责任务式文生图创作编排，`user-service` 负责用户、作品、收藏和后台配置。`recommend-service` 与 `file-service` 作为推荐统计和统一文件能力的扩展服务保留在工程中。

AI 能力由 Java 服务和 Python 服务协同完成。图生图链路由 `img2img-service` 对接 `i2i-pure` 图像编辑推理服务，支持远端任务提交、状态轮询、取消和结果转存；文生图链路由 `txt2img-service` 调用 `ai-service` 适配层，再按配置对接 DashScope 或 `t2i-pure` Flux 推理服务。`ai-service` 同时提供 embedding 和 Prompt rewrite 等辅助能力。

基础设施方面，项目使用 MySQL 保存业务数据，Redis 支撑缓存和验证码等辅助能力，RabbitMQ 负责任务和事件消息，MinIO 用于图片对象存储，Chroma 用于向量检索，Nginx 用于本地静态纹样和模板资源代理。

## 技术栈

### 前端

- Vue 3
- Vite
- Vue Router
- Pinia
- Axios
- Element Plus
- Tailwind CSS

### Java 后端

- Java 21
- Maven 多模块
- Spring Boot 3.3.x
- Spring Cloud Gateway
- Spring MVC / WebFlux
- MyBatis
- RabbitMQ
- Redis
- MinIO
- MySQL 8

### Python AI 服务

- FastAPI
- Uvicorn
- DashScope
- OpenAI SDK 兼容接口
- Flux / LoRA 文生图服务适配
- Qwen Image Edit 图生图服务适配

## 仓库结构

```text
ichp-ai
├─ api-client                    # 服务间调用 DTO 与契约
├─ common                        # 通用返回、分页、异常、工具类
├─ common-webmvc                 # WebMVC 统一响应和异常处理
├─ config-repo                   # 配置样例
├─ docker                        # 本地依赖容器与初始化脚本
├─ frontend                      # Vue3 前端工程
├─ ai-service                    # Python FastAPI AI 适配层
├─ t2i-pure                      # 文生图推理服务纯净版与测试结果
├─ i2i-pure                      # 图生图推理服务纯净版与测试结果
├─ scripts                       # 启停、构建、部署辅助脚本
└─ services
   ├─ gateway                    # API 网关
   ├─ pattern-service            # 纹样资源服务
   ├─ img2img-service            # 图生图任务服务
   ├─ txt2img-service            # 文生图任务服务
   ├─ user-service               # 用户、作品、收藏、平台配置服务
   ├─ recommend-service          # 推荐统计扩展服务（预留）
   └─ file-service               # 文件上传扩展服务（预留）
```

## 功能模块

### 1. 纹样博物馆

纹样博物馆用于展示和检索非遗纹样资源，当前支持：

- 纹样分页列表
- 关键词搜索
- 分类、子分类、朝代、标签筛选
- 纹样详情展示
- 浏览量统计
- 收藏状态展示
- 标签和分类聚合查询

主要接口：

```text
GET /api/patterns
GET /api/patterns/{id}
GET /api/patterns/tags
GET /api/patterns/categories
```

### 2. 图生图创作

图生图模块用于将传统纹样应用到具体载体或模板上，例如服饰、文创产品、包装、日用品等场景。

当前能力包括：

- 选择纹样库图片或上传本地纹样
- 选择模板或上传目标载体图
- 创建图生图任务
- 远端 i2i 推理任务提交与轮询
- 任务取消
- 结果图和预览图转存 MinIO
- 图生图成功事件 Outbox 可靠发布
- 登录用户和匿名设备双归属
- 作品保存与作品列表展示

主要接口：

```text
GET  /api/img2img/templates
GET  /api/img2img/templates/{id}
POST /api/img2img/images/upload
POST /api/img2img/tasks
GET  /api/img2img/tasks/no/{taskNo}
POST /api/img2img/tasks/{taskId}/cancel
GET  /internal/img2img/tasks/{taskId}/snapshot
POST /internal/img2img/tasks/claim
```

图生图服务可对接 `i2i-pure`：

```text
GET  /health
POST /v1/images/edits
POST /v1/jobs
GET  /v1/jobs/{request_id}
POST /v1/jobs/{request_id}/cancel
```

### 3. 文生图创作

文生图模块用于根据用户输入的纹样描述生成新的纹样图像。当前链路重点增强了中文 Prompt 到英文 Prompt 的适配能力，并支持远端 Flux 服务。

当前能力包括：

- Prompt 模板选择
- 中文描述输入
- 纹样类型和复杂度扩展
- 规则英文 Prompt 构建
- 可选 RAG 增强
- 可选 SiliconFlow/OpenAI 兼容 Prompt 改写
- 文生图任务异步生成
- 多结果保存与展示
- 结果图转存 MinIO
- 任务超时和匿名任务过期处理

主要接口：

```text
GET  /api/txt2img/prompt-templates
POST /api/txt2img/tasks
GET  /api/txt2img/tasks/{taskNo}
POST /api/txt2img/rag/debug
PUT  /internal/txt2img/tasks/claim
GET  /internal/txt2img/tasks/{taskId}/snapshot
```

文生图链路通过 `ai-service` 统一适配：

```text
GET  /health
POST /api/ai/flux/txt2img
POST /api/ai/flux/embeddings
POST /api/ai/flux/rewrite-prompt
```

`ai-service` 可继续对接：

- DashScope 文生图/Embedding
- `t2i-pure` 远端 Flux 推理服务
- SiliconFlow/OpenAI 兼容 Prompt rewrite 服务

### 4. 用户、作品与收藏

用户服务当前承担认证、资料、作品、收藏和后台配置能力。

当前能力包括：

- 用户注册和登录
- 管理员登录
- 当前用户信息
- 用户资料修改
- 头像上传
- 图生图作品保存
- 文生图作品保存后端能力
- 登录用户作品列表
- 匿名设备图生图作品列表
- 作品逻辑删除
- 作品公开状态修改
- 纹样收藏/取消收藏
- 作品收藏/取消收藏
- 收藏事件 Outbox
- 后台用户管理
- 平台配置管理

主要接口示例：

```text
POST /api/auth/register
POST /api/auth/login
POST /api/auth/admin/login
GET  /api/users/me
PUT  /api/users/profile
POST /api/users/avatar

POST /api/users/me/works/img2img
POST /api/users/me/works/txt2img
GET  /api/users/me/works
DELETE /api/users/me/works/{workId}
PATCH  /api/users/me/works/{workId}/visibility

POST /api/users/device/works/img2img
GET  /api/users/device/works

POST   /api/favorites/patterns/{patternId}
DELETE /api/favorites/patterns/{patternId}
POST   /api/favorites/work/{workId}
DELETE /api/favorites/work/{workId}
```

### 5. 推理服务优化实验

本项目不仅包含业务系统，也包含面向 AI 推理服务的工程化优化实验。

`t2i-pure` 当前包含：

- Flux 文生图服务
- 多 GPU worker
- 队列调度
- Micro-batching
- Prompt embedding cache
- Session affinity
- 令牌桶限流
- 熔断器
- 队列等待时间估算
- Benchmark 与流量测试结果

`i2i-pure` 当前包含：

- Qwen Image Edit 图像编辑服务
- 多 GPU worker
- 同步和异步任务接口
- 任务取消
- FIFO / SJF 调度
- Aging 防饥饿机制
- Uncond branch cache
- 限流与熔断
- 等待时间估算
- 参数扫描、质量验证和分布式测试结果

这些内容为后续真实部署、性能优化和高并发推理提供了基础。

## 前端页面

当前前端已接入的页面包括：

- 首页：`/`
- 纹样博物馆：`/patterns`
- 纹样详情：`/patterns/:id`
- 图生图创作：`/img2img`
- 文生图创作：`/txt2img`
- 我的作品：`/works`
- 登录：`/login`
- 注册：`/register`
- 个人资料：`/profile`
- 后台登录：`/admin/login`
- 后台用户管理：`/admin/users`
- 后台配置管理：`/admin/configs`

其中图生图页面已经包含较完整的任务提交、轮询、取消、结果展示和保存作品流程。文生图页面已经支持任务创建、轮询和多结果展示，作品保存入口可继续完善。

## 本地依赖与端口

### Docker 依赖

`docker/docker-compose.yml` 提供以下本地依赖：

| 组件 | 端口 | 说明 |
|---|---:|---|
| MySQL | 3306 | 业务数据库 |
| Redis | 6379 | 缓存、验证码等辅助能力 |
| RabbitMQ | 5672 / 15672 | 消息队列 / 管理台 |
| Chroma | 8000 | 向量检索服务 |
| MinIO | 9000 / 9001 | 对象存储 / 控制台 |
| Nginx | 80 | 静态纹样和模板资源代理 |

### Java / 前端 / AI 服务端口

| 服务 | 默认端口 |
|---|---:|
| Gateway | 8080 |
| Pattern Service | 8081 |
| Img2Img Service | 8082 |
| Txt2Img Service | 8083 |
| User Service | 8084 |
| Recommend Service | 8085 |
| File Service | 8086 |
| Frontend Vite | 5173 |
| ai-service | 5000 |
| i2i-pure | 8000 |
| t2i-pure | 由启动参数决定 |

> 注意：Chroma 和 `i2i-pure` 默认都可能使用 8000 端口，同机启动时需要调整其中一个端口，或通过 SSH 隧道/反向代理区分。

## 快速启动

### 1. 启动本地依赖

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

启动后建议检查：

```bash
docker compose ps
```

并确认 MySQL、RabbitMQ、MinIO、Nginx 所需资源已经初始化。

### 2. 编译后端

```bash
mvn compile -DskipTests
```

要求：

- Java 21
- Maven 3.9+ 推荐

### 3. 启动后端服务

可根据需要单独启动服务：

```bash
mvn -pl services/gateway spring-boot:run -Dspring-boot.run.profiles=local
mvn -pl services/pattern-service spring-boot:run -Dspring-boot.run.profiles=local
mvn -pl services/img2img-service spring-boot:run -Dspring-boot.run.profiles=local
mvn -pl services/txt2img-service spring-boot:run -Dspring-boot.run.profiles=local
mvn -pl services/user-service spring-boot:run -Dspring-boot.run.profiles=local
```

首次联调建议分服务启动，便于定位数据库、消息队列、对象存储或 AI 服务配置问题。

### 4. 启动前端

```bash
cd frontend
npm install
npm run dev
```

构建：

```bash
npm run build
```

### 5. 启动 AI 适配层

```bash
cd ai-service
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 5000
```

健康检查：

```bash
curl http://127.0.0.1:5000/health
```

### 6. 启动图生图推理服务

```bash
cd i2i-pure
pip install -r requirements.txt
python run_service.py
```

健康检查：

```bash
curl http://127.0.0.1:8000/health
```

### 7. 启动文生图推理服务

```bash
cd t2i-pure
# t2i-pure 当前保留纯净服务代码，依赖请按实际 GPU/模型环境安装
# 典型依赖包括 torch、diffusers、transformers、fastapi、uvicorn 等
export T2I_BASE_MODEL=/path/to/flux-model
export T2I_GPU_IDS=0
python src/run_service.py
```

## 关键配置

### 数据库配置

本地 Docker MySQL 默认：

```text
host: localhost
port: 3306
database: ichp_ai
username: root
password: root
```

部分服务本地配置文件支持通过环境变量覆盖，例如：

```text
DB_HOST
DB_PORT
DB_NAME
DB_USERNAME
DB_PASSWORD
MYSQL_HOST
MYSQL_PORT
MYSQL_DATABASE
MYSQL_USERNAME
MYSQL_PASSWORD
```

实际启动前请统一数据库密码，避免 Docker 与服务配置不一致。

### 图生图远端服务配置

`img2img-service` 支持通过环境变量配置远端 i2i 服务：

```text
REMOTE_I2I_BASE_URL
REMOTE_I2I_EDIT_PATH
REMOTE_I2I_JOBS_PATH
REMOTE_I2I_RETURN_IMAGE
REMOTE_I2I_SAVE_IMAGE
REMOTE_I2I_PROFILE
I2I_SSH_ENABLED
I2I_SSH_HOST
I2I_SSH_USERNAME
I2I_SSH_PRIVATE_KEY
I2I_SSH_LOCAL_PORT
I2I_SSH_REMOTE_HOST
I2I_SSH_REMOTE_PORT
```

可用于本地直连，也可用于 SSH 隧道访问远端 GPU 服务。

### 文生图远端服务配置

`txt2img-service` 调用 `ai-service`，`ai-service` 再根据 provider 调用 DashScope 或 `t2i-pure`：

```text
AI_SERVICE_BASE_URL
T2I_PROVIDER
REMOTE_T2I_BASE_URL
REMOTE_T2I_TOKEN
REMOTE_T2I_STEPS
DASHSCOPE_API_KEY
```

Prompt rewrite 和 RAG 相关配置：

```text
TXT2IMG_PROMPT_REWRITE_ENABLED
TXT2IMG_PROMPT_REWRITE_URL
TXT2IMG_RAG_ENABLED
TXT2IMG_RAG_CHROMA_BASE_URL
SILICONFLOW_API_KEY
SILICONFLOW_BASE_URL
SILICONFLOW_MODEL
```

## 数据库现状

当前初始化脚本位于：

```text
docker/mysql/init.sql
```

当前使用单库：

```text
ichp_ai
```

主要业务表包括：

- `patterns`
- `pattern_tags`
- `pattern_tag_rel`
- `templates`
- `img2img_tasks`
- `img2img_outbox_events`
- `txt2img_tasks`
- `txt2img_task_results`
- `prompt_records`
- `users`
- `platform_configs`
- `works`
- `favorites`
- `outbox_events`
- `pattern_favorite_event_log`

当前单库结构便于本地联调和演示。后续如果需要更严格的微服务数据库隔离，可以逐步改造为独立库、事件快照或服务间查询模型。

## 当前演示建议

推荐优先展示以下能力：

1. 首页和整体视觉风格。
2. 纹样博物馆列表、筛选和详情。
3. 用户注册、登录和个人资料。
4. 图生图创作：选择纹样、选择模板、提交任务、查看进度、取消任务、展示结果、保存作品。
5. 我的作品：查看图生图生成结果。
6. 文生图创作：输入描述、选择模板/类型、生成多张候选结果。
7. 后台用户管理和平台配置。

## 后续规划

项目后续可以继续完善以下方向：

- 文生图结果保存到我的作品。
- 我的作品页增强：删除、公开/私密切换、图生图/文生图统一展示。
- 匿名任务登录后认领。
- 收藏列表和批量收藏状态。
- 推荐统计与热门纹样推荐。
- file-service 作为统一上传入口。
- 公开作品详情与作品分享。
- 自动化测试和端到端 Smoke Test。
- 多服务配置统一和部署脚本完善。
- 多库拆分和更完整的微服务治理。

## 验证建议

演示或提交前建议至少执行：

```bash
# 后端编译
mvn compile -DskipTests

# 前端构建
cd frontend
npm run build

# AI 适配层健康检查
cd ../ai-service
uvicorn app.main:app --host 0.0.0.0 --port 5000
curl http://127.0.0.1:5000/health
```

关键接口可按需验证：

```text
GET  /api/patterns
GET  /api/img2img/templates
POST /api/img2img/tasks
GET  /api/img2img/tasks/no/{taskNo}
POST /api/users/device/works/img2img
GET  /api/users/device/works
POST /api/txt2img/tasks
GET  /api/txt2img/tasks/{taskNo}
```

## 总结

非遗纹样 AI 设计平台当前已经具备完整的前后端工程结构、可演示的纹样浏览与 AI 创作链路，以及面向真实推理服务的工程化优化基础。图生图链路在任务编排、远端推理、任务取消、结果转存和作品保存方面已经较为完整；文生图链路也已经接入英文 Prompt 适配、远端 Flux 服务和流控/缓存实验。

后续重点是继续打磨作品管理、收藏推荐、匿名认领、部署配置和自动化验证，让平台从“可联调、可演示”的原型进一步走向稳定可复用的非遗纹样 AI 创作系统。