# imagext-system

**Repository Path**: hashcode1/imagext-system

## Basic Information

- **Project Name**: imagext-system
- **Description**: FDE 作业5：文本↔图像创作系统（文生图/图生文/品牌模板批量）FastAPI + 原生前端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ImageXTSystem · 文本↔图像创作系统

> FDE 实战项目 · 作业 5 · 选题 **③图文系统**
> 「文本↔图像」创作系统：文生图（海报/配图）、图生文（口播脚本/朋友圈文案/选题/配文）、品牌模板批量。

---

## 🎯 项目定位

| 维度 | 内容 |
|---|---|
| 目标用户 | 服装电商品牌方 / 内容运营 / 抖店小红书卖家 |
| 核心价值 | 把"一段中文需求"变成"可发布的成片（图片+文案）"，并支持品牌风格统一批量 |

---

## ⚡ 三大能力

| # | 接口 | 输入 | 输出 | LLM |
|---|---|---|---|---|
| ① | `POST /api/v1/text2image` | 主题/调性/尺寸 | N 张图片 URL | 豆包 Seedream (T2I) |
| ② | `POST /api/v1/image2text` | 图片 URL/Base64 + 文案类型 | 结构化 JSON 文案 | 豆包 1.5 Vision Pro |
| ③ | `POST /api/v1/brand-template/batch` | 模板 ID + N 条文案 | N 张统一风格海报 | 豆包 Seedream (T2I) |

---

## 🏗️ 架构（30 秒理解）

```
┌────────────────────────────────────────────────────────┐
│  Frontend (Vanilla HTML+JS)                            │
│  3 个 Tab · 一键演示 · 实时成本/缓存可视化             │
└─────────────────────────┬──────────────────────────────┘
                          │ HTTP/JSON
┌─────────────────────────▼──────────────────────────────┐
│  FastAPI Backend (Python 3.11+)                        │
│  ┌───────────┬───────────┬────────────┐                │
│  │  文生图    │  图生文    │ 模板批量   │  Routers     │
│  └─────┬─────┴─────┬─────┴──────┬─────┘                │
│        ▼           ▼            ▼                       │
│  ┌──────────────────────────────────────────┐         │
│  │       LLMClient（核心工程层）             │         │
│  │  - Key 池 + 轮询                          │         │
│  │  - 滑窗限流 (RPM/TPM per key)             │         │
│  │  - 全局并发闸门                            │         │
│  │  - 指数退避 + 多 Key 故障转移              │         │
│  │  - 成本追踪 + 单日预算                    │         │
│  │  - TTL 缓存                                │         │
│  └──────────────────────────────────────────┘         │
│                          │                              │
│                          ▼                              │
│              OpenAI-Compatible Providers                │
│              (豆包火山方舟 / Kimi / DeepSeek)            │
└────────────────────────────────────────────────────────┘
```

---

## 🚀 快速开始

```bash
# 1. 安装依赖
cd imagext-system
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 2. 配置密钥（至少 1 个 DOUBAO_API_KEY 才能跑真实模型；不配也能以 mock 模式跑通）
cp .env.example .env
# 编辑 .env 填入 DOUBAO_API_KEYS=sk-xxx,sk-yyy

# 3. 启动后端
cd backend
uvicorn main:app --reload --port 8000

# 4. 打开前端（任选一种）
# 方式 A：直接打开
open ../frontend/index.html   # 或浏览器拖入

# 方式 B：起一个静态服务（避免 CORS 干扰）
cd ../frontend && python -m http.server 5500
# 访问 http://localhost:5500
```

启动后访问：
- 前端：http://localhost:5500
- API 文档（Swagger UI）：http://localhost:8000/docs
- 健康检查：http://localhost:8000/health

---

## 📂 目录结构

```
imagext-system/
├── backend/
│   ├── core/              # 核心工程层
│   │   ├── config.py          # 配置（pydantic-settings + .env）
│   │   ├── exceptions.py      # 自定义异常 + 重试策略
│   │   ├── logger.py          # 统一日志
│   │   ├── cache.py           # TTL 内存缓存
│   │   ├── rate_limiter.py    # 密钥池 + 滑窗限流
│   │   ├── cost_tracker.py    # 成本追踪 + 日预算
│   │   └── llm_client.py      # OpenAI 兼容客户端
│   ├── prompts/           # 结构化提示词库（评分 20%）
│   │   ├── templates.py
│   │   ├── image_prompts.py
│   │   ├── vision_prompts.py
│   │   └── __init__.py        # 模板 prompt 合成
│   ├── routers/           # 业务路由
│   │   ├── text2image.py
│   │   ├── image2text.py
│   │   ├── template.py
│   │   └── __init__.py
│   ├── models/
│   │   └── schemas.py     # Pydantic 契约
│   ├── tests/             # 单元测试
│   └── main.py            # FastAPI 入口
├── frontend/              # 单页前端
│   ├── index.html
│   ├── style.css
│   └── app.js
├── docs/                  # 完整文档
│   ├── architecture.md
│   ├── api-cost-design.md
│   ├── prompts.md
│   ├── deployment.md
│   └── demo-script.md
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md
```

---

## 📊 评分项覆盖一览

| 评分项 | 权重 | 落地点 |
|---|---|---|
| **功能完善** | 30% | 3 个核心路由 + 模板系统 + 缓存 + 健康检查 + Swagger 文档 |
| **提示词结构化质量** | 20% | `backend/prompts/` + `docs/prompts.md`：BRTR 框架 + JSON Schema 强制 + 自检规则 |
| **API 成本与限流设计** | 20% | `core/rate_limiter.py` + `core/cost_tracker.py` + `docs/api-cost-design.md` |
| **工程健壮性/错误处理** | 15% | 自定义异常体系 + 指数退避 + 多 Key 故障转移 + 预算降级 + schema 校验 |
| **文档与演示** | 15% | `docs/` 五份完整文档 + 可一键启动的 demo + 部署指南 |

---

## 🧪 测试

```bash
cd backend
pytest tests/ -v
```

覆盖：
- 缓存命中/失效
- 限流器状态统计
- 异常类型映射
- 提示词构造器
- JSON Schema 校验

---

## 📝 License

仅作 FDE 实战作业演示，不用于生产。