aidress/README.md

# 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 并执行以下命令：

```sql
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. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

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

```bash
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. 数据库迁移

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

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

# 应用迁移
python create_migration.py upgrade
```

### 4. 启动服务

```bash
python run.py
```

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

## Docker 部署

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

### 前提条件

- 安装 [Docker](https://docs.docker.com/get-docker/)
- 安装 [Docker Compose](https://docs.docker.com/compose/install/)

### 使用 Docker 部署

1. **配置环境变量**

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

   ```bash
   cp .env.docker .env
   ```

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

2. **构建并启动服务**

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

   这将启动两个容器：
   - `ai-dressing-app`：运行 FastAPI 应用程序
   - `ai-dressing-db`：运行 MySQL 数据库

3. **初始化数据库**

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

   ```bash
   docker-compose exec app python3 create_migration.py upgrade
   ```

4. **访问服务**

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

### Docker 环境管理

- **查看日志**

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

- **重启服务**

  ```bash
  docker-compose restart app
  ```

- **停止服务**

  ```bash
  docker-compose down  # 停止所有服务
  ```

- **停止并删除数据卷**

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

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

## 使用.env文件构建Docker镜像

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

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

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

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

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

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

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

### 方法二：使用Docker Compose

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

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

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

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

### 方法三：手动构建

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

```bash
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 .
```

## 验证环境变量

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

```bash
# 查看容器日志
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. 首先从服务端获取临时上传凭证：
```javascript
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. 使用临时凭证进行文件上传：
```javascript
// 使用腾讯云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