AI-Dressing API

基于 FastAPI 框架和阿里云 DashScope 接口的 AI 服务 API。

功能特点

• 集成阿里云 DashScope 的大模型 API，支持通义千问系列模型
• 提供图像生成 API，支持 Stable Diffusion XL、万相等模型
• 集成腾讯云 COS 对象存储服务，支持文件上传、下载等功能
• 使用 MySQL 数据库存储服装数据
• RESTful API 风格，支持异步处理
• 易于扩展的模块化设计

环境要求

• Python 3.8+
• 阿里云 DashScope API 密钥
• 腾讯云 API 密钥（用于 COS 对象存储）
• MySQL 5.7+ 数据库

数据库设置

在使用应用程序之前，您需要创建 MySQL 数据库。登录到 MySQL 并执行以下命令：

CREATE DATABASE ai_dressing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'ai_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON ai_dressing.* TO 'ai_user'@'%';
FLUSH PRIVILEGES;

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

复制 .env.example 文件为 .env，并填写您的 API 密钥：

cp .env.example .env

然后编辑 .env 文件：

# DashScope API密钥
DASHSCOPE_API_KEY=your_api_key_here

# 腾讯云配置
QCLOUD_SECRET_ID=your_secret_id_here
QCLOUD_SECRET_KEY=your_secret_key_here
QCLOUD_COS_REGION=ap-guangzhou
QCLOUD_COS_BUCKET=your-bucket-name
QCLOUD_COS_DOMAIN=https://your-bucket-name.cos.ap-guangzhou.myqcloud.com

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=ai_user
DB_PASSWORD=your_password
DB_NAME=ai_dressing

3. 数据库迁移

首次运行或模型变更后，需要创建或更新数据库表：

# 创建迁移（仅在模型变更时需要）
python create_migration.py create -m "初始化数据库"

# 应用迁移
python create_migration.py upgrade

4. 启动服务

python run.py

服务将在 http://localhost:9001 启动，您可以访问 http://localhost:9001/docs 查看 API 文档。

Docker 部署

本项目支持使用 Docker 进行部署，提供了完整的 Docker 配置文件。

前提条件

• 安装 Docker
• 安装 Docker Compose

使用 Docker 部署

1. 配置环境变量

   复制 .env.docker 文件为 .env，并填写您的 API 密钥：

   cp .env.docker .env
   

   编辑 .env 文件，填入您的 API 密钥和其他配置。

2. 构建并启动服务

   docker-compose up -d
   

   这将启动两个容器：

   • ai-dressing-app：运行 FastAPI 应用程序
   • ai-dressing-db：运行 MySQL 数据库

3. 初始化数据库

   应用启动后，执行迁移以创建数据库表：

   docker-compose exec app python3 create_migration.py upgrade
   

4. 访问服务

   服务将在 http://localhost:9001 启动，您可以访问 http://localhost:9001/docs 查看 API 文档。

Docker 环境管理

• 查看日志

  docker-compose logs -f app  # 查看应用日志
  docker-compose logs -f db   # 查看数据库日志
  

• 重启服务

  docker-compose restart app
  

• 停止服务

  docker-compose down  # 停止所有服务
  

• 停止并删除数据卷

  docker-compose down -v  # 谨慎使用，这将删除数据库中的所有数据
  

Docker构建和环境变量配置指南

使用.env文件构建Docker镜像

本项目提供了多种方式将.env文件中的环境变量传递到Docker容器中。

方法一：使用build.sh脚本（推荐）

这种方法会自动读取.env文件中的所有环境变量，并传递给Docker构建过程：

# 赋予执行权限
chmod +x build.sh

# 执行构建脚本
./build.sh

构建完成后，可以直接运行容器：

docker run -p 9001:8000 ai-dressing:latest

方法二：使用Docker Compose

使用专门的docker-compose文件进行构建，该文件会读取.env中的环境变量：

# 先加载.env文件到当前shell
export $(grep -v '^#' .env | xargs)

# 使用专用的构建配置文件
docker-compose -f docker-compose.build.yml build

# 启动服务
docker-compose -f docker-compose.build.yml up -d

方法三：手动构建

如果你希望手动指定部分环境变量，可以使用以下命令：

docker build \
  --build-arg DASHSCOPE_API_KEY=your_key \
  --build-arg DB_HOST=your_db_host \
  --build-arg DB_USER=your_db_user \
  --build-arg DB_PASSWORD=your_db_password \
  -t ai-dressing:latest .

验证环境变量

构建完成后，你可以通过以下命令验证环境变量是否正确加载：

# 查看容器日志
docker logs ai-dressing-app

# 或者进入容器查看环境变量
docker exec -it ai-dressing-app bash -c "env | sort"

环境变量优先级

环境变量的加载优先级从高到低如下：

1. docker run或docker-compose启动时通过-e或environment指定的环境变量
2. 通过卷挂载到容器中的.env文件
3. 构建时通过--build-arg传入并保存到容器内.env.built文件的变量
4. 代码中的默认值

注意事项

• 生产环境中应避免将敏感信息硬编码在Dockerfile中
• 敏感信息应通过环境变量或Docker secrets进行管理
• 建议将.env文件添加到.gitignore中，避免意外提交

API 文档

启动服务后，访问以下地址查看自动生成的 API 文档：

• Swagger UI: http://localhost:9001/docs
• ReDoc: http://localhost:9001/redoc

主要 API 端点

大模型对话

POST /api/dashscope/chat

图像生成

POST /api/dashscope/generate-image

获取支持的模型列表

GET /api/dashscope/models

文件上传到腾讯云 COS

POST /api/qcloud/upload

从腾讯云 COS 获取文件列表

GET /api/qcloud/files

生成 COS 临时上传凭证

POST /api/qcloud/sts-token

服装管理 API

# 创建服装
POST /api/dresses/

# 获取服装列表
GET /api/dresses/

# 获取单个服装
GET /api/dresses/{dress_id}

# 更新服装
PUT /api/dresses/{dress_id}

# 删除服装
DELETE /api/dresses/{dress_id}

项目结构

.
├── alembic/                # 数据库迁移相关文件
│   ├── versions/           # 迁移版本文件
│   ├── env.py              # 迁移环境配置
│   └── script.py.mako      # 迁移脚本模板
├── app/                    # 应用主目录
│   ├── __init__.py
│   ├── main.py             # FastAPI 应用程序
│   ├── database/           # 数据库相关
│   │   └── __init__.py
│   ├── models/             # 数据库模型
│   │   ├── __init__.py
│   │   └── dress.py
│   ├── routers/            # API 路由
│   │   ├── __init__.py
│   │   ├── dashscope_router.py
│   │   ├── qcloud_router.py
│   │   └── dress_router.py
│   ├── schemas/            # Pydantic 模型
│   │   ├── __init__.py
│   │   └── dress.py
│   ├── services/           # 业务逻辑服务
│   │   ├── __init__.py
│   │   ├── dashscope_service.py
│   │   └── qcloud_service.py
│   └── utils/              # 工具类
│       ├── __init__.py
│       └── config.py
├── .env.example            # 环境变量示例
├── alembic.ini             # Alembic 配置
├── create_migration.py     # 数据库迁移工具
├── requirements.txt        # 项目依赖
├── README.md               # 项目文档
└── run.py                  # 应用入口

开发指南

添加新的路由

1. 在 app/routers/ 目录下创建新的路由文件
2. 在 app/main.py 中注册新的路由

添加新的数据库模型

1. 在 app/models/ 目录下创建新的模型文件
2. 在 app/schemas/ 目录下创建对应的 Pydantic 模型
3. 创建数据库迁移: python create_migration.py create -m "添加新模型"
4. 应用迁移: python create_migration.py upgrade

添加新的服务

在 app/services/ 目录下创建新的服务类。

腾讯云 COS 使用指南

前端直传文件

1. 首先从服务端获取临时上传凭证：

const response = await fetch('/api/qcloud/sts-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'allow_prefix=uploads/&duration_seconds=1800'
});
const stsData = await response.json();

2. 使用临时凭证进行文件上传：

// 使用腾讯云COS SDK上传
const cos = new COS({
  getAuthorization: function(options, callback) {
    callback({
      TmpSecretId: stsData.credentials.tmpSecretId,
      TmpSecretKey: stsData.credentials.tmpSecretKey,
      SecurityToken: stsData.credentials.sessionToken,
      ExpiredTime: stsData.expiration
    });
  }
});

cos.putObject({
  Bucket: stsData.bucket,
  Region: stsData.region,
  Key: 'uploads/example.jpg',
  Body: file,
  onProgress: function(progressData) {
    console.log(progressData);
  }
}, function(err, data) {
  if (err) {
    console.error('上传失败', err);
  } else {
    console.log('上传成功', data);
  }
});

许可证

MIT