你好，我是 AdAgent

🎯 项目简介

AdAgent 是一个面向跨境电商的 AI 广告智能体：上传一张产品图， 自动识别产品信息，经「产品分析 → 营销定位 → 卖点提炼 → 广告策划 → 合规审查 → 提示词生成 → 图片生成」LangGraph 七阶段流水线， 一键产出多语言广告文案与平面广告图（含 Amazon 主图规格）。

🧩 技术栈

层次	技术选型	说明
后端	Python 3.11 · FastAPI · LangGraph	智能体流水线编排 + REST API
LLM	OpenAI 兼容接口 · Anthropic · Mock 兜底	工厂模式切换，无 Key 时可全流程演示
存储	SQLite · Alembic 迁移 · MinIO	任务/产品数据与生成图片对象存储
向量	Chroma / Milvus · BGE Embedding	知识库向量检索
RAG	BM25 混合检索 · Rerank · 文本切分	合规与文化知识增强检索
图像	Pillow 模板合成 · 背景移除 · 品类自适应版式	按平台尺寸合成广告图，hero / magazine 版式自适应
前端	原生 HTML / CSS / ES Module	零构建模块化单页应用，nginx 反代部署
部署	Docker Compose · Uvicorn · Nginx	backend / web / postgres / redis / minio

🗂 项目结构

ad-agent/
├── backend/                    # FastAPI 后端
│   ├── app/
│   │   ├── main.py             # 应用入口（路由挂载、CORS、静态文件）
│   │   ├── api/v1/             # REST 接口层
│   │   │   ├── products.py     #   产品识别（多模态 Vision）
│   │   │   ├── ads.py          #   广告任务：创建/详情/SSE 流式进度/取消/局部重生成
│   │   │   ├── history.py      #   历史任务分页查询
│   │   │   ├── kb.py           #   知识库文档管理
│   │   │   ├── health.py       #   健康检查与运行配置
│   │   │   └── router.py       #   路由聚合（前缀 /api/v1）
│   │   ├── agents/             # LangGraph 智能体
│   │   │   ├── graph.py        #   状态图：7 节点流水线编排 + 合规回环
│   │   │   ├── nodes.py        #   各节点实现（分析/定位/卖点/策划/合规/提示词/生图）
│   │   │   ├── category_rules.py   # 品类 → 背景/灯光/标签/图标适配规则
│   │   │   ├── state.py        #   共享状态定义
│   │   │   └── tools.py        #   节点工具函数
│   │   ├── services/           # 业务服务层
│   │   │   ├── task_service.py #   任务生命周期 + 后台执行 + SSE 推送
│   │   │   ├── product_service.py  # 产品识别与持久化
│   │   │   ├── kb_service.py   #   知识库入库与检索
│   │   │   ├── storage.py      #   MinIO/本地对象存储
│   │   │   └── llm/            #   LLM 客户端（factory 多供应商）
│   │   ├── rag/                # RAG 检索
│   │   │   ├── embedding.py · vector_store.py · milvus_store.py
│   │   │   ├── retriever.py    #   混合检索 + Rerank
│   │   │   ├── bm25.py · splitter.py
│   │   ├── image/              # 图像合成
│   │   │   ├── composer.py     #   模板版式合成
│   │   │   ├── generator.py · preprocess.py
│   │   │   └── fonts.py
│   │   ├── prompts/            # LLM 提示词模板（.txt × 6）
│   │   ├── models/ · schemas/  # SQLAlchemy 模型 / Pydantic 契约
│   │   └── core/               # 配置、数据库、日志、限流、异常
│   ├── alembic/                # 数据库迁移
│   └── tests/                  # pytest（产品/任务/知识库）
│
├── web/                        # 聊天式前端（零构建原生 ESM）
│   ├── index.html              # 单页结构：侧边栏 + 聊天气泡 + 三个管理页
│   ├── css/style.css           # 设计系统与全部样式
│   ├── js/
│   │   ├── main.js             # 入口：模块装配、事件绑定、启动探测
│   │   ├── shell.js            # 视图切换与侧边栏
│   │   ├── config.js           # API 地址配置（控制台可 setApiBase 切换）
│   │   ├── constants.js        # 国家/语言/平台/风格/尺寸/流程节点
│   │   ├── core/               # api（超时与错误信封）/ dom / state / modal / wiring
│   │   └── views/              # composer / chat / history / kb / settings
│   └── tools/                  # 版本戳 stamp.mjs · 模块链接检查 check.mjs · jsdom 集成测试 dom-test.mjs
│
├── docker-compose.yml          # backend · web · postgres · redis · minio
├── start.bat / start.sh        # 一键启动（后端 8000 + 前端 8502）
└── stop.bat / stop.sh          # 一键停止

🔄 生成流水线（七阶段）

1. 产品分析 — 多模态模型识别产品外观/材质/结构，并支持人工修正覆盖
2. 营销定位 — 结合知识库输出产品类型、目标用户、使用场景与情绪基调
3. 卖点提炼 — 提炼 3~5 个核心卖点，每条带事实依据与转化优先级
4. 广告策划 — 确定广告主题 + 构图 + 版式，产出多版多语言文案与平台适配
5. 合规审查 — RAG 检索当地广告法规，标记风险词并给修改建议（不过则重写）
6. 提示词生成 — 把策划结论落实为可直接生图的背景提示词与配色/版式参数
7. 图片生成 — 生成背景主视觉，与真实产品合成（产品 100% 保真不变形）

🔌 主要接口

方法	路径	用途
POST	/api/v1/products/analyze	上传图片识别产品
POST	/api/v1/ads/generate	创建广告生成任务
GET	/api/v1/ads/{id}/stream	SSE 实时进度推送
POST	/api/v1/ads/{id}/cancel	取消任务
POST	/api/v1/ads/{id}/regenerate	按模式局部重生成
GET	/api/v1/history	历史任务分页
POST	/api/v1/kb/documents · /api/v1/kb/search	知识库入库 / 检索
GET	/api/v1/health · /api/v1/settings	健康检查 / 运行配置
GET	/api/v1/metrics	运行指标（任务成功率 / LLM 调用与成本）

🚀 快速启动

# Docker（推荐，含前端/后端/存储全家桶）
docker compose up -d --build

# 本地开发：双击 start.bat（或 ./start.sh）
#   后端 API   → http://localhost:8000/docs
#   聊天界面   → http://localhost:8502