454 lines
10 KiB
Markdown
454 lines
10 KiB
Markdown
# 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响应格式
|
||
|
||
系统支持两种API响应格式，可以通过环境变量进行配置：
|
||
|
||
### 标准响应格式 (USE_STANDARD_RESPONSE=1)
|
||
|
||
所有API接口都会返回统一的标准格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
错误响应示例：
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "请求参数错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 简洁响应格式 (USE_STANDARD_RESPONSE=0)
|
||
|
||
API接口直接返回数据，不包含额外的包装：
|
||
|
||
```json
|
||
{ ... } // 直接返回业务数据
|
||
```
|
||
|
||
错误响应仍然保持标准格式，以确保错误信息清晰：
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "请求参数错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
> 注意：健康检查端点 `/health` 和 `/` 始终返回简洁格式，不受环境变量影响。
|
||
|
||
## 主要 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 |