ai_tagging_images/README.md

# AI 图片标签衍生系统

基于千问视觉大模型（Qwen-VL）的医疗健康图片标签自动衍生系统。

## 功能概述

- **离线批量处理**：遍历数据库图片，批量调用大模型进行标签衍生
- **RESTful API 服务**：提供标签衍生的 HTTP 接口
- **智能重试机制**：API 调用失败自动重试，支持指数退避
- **统一配置管理**：支持环境变量配置，灵活部署
- **完整日志系统**：文件 + 控制台双输出，便于问题排查

## 标签衍生流程

![标签衍生流程图](docs/tag_derive_flow.png)

**流程说明：**
1. 遍历 `ai_image_tags` 表中每一条图片记录
2. 用 `tag_id` 查询 `ai_tags` 表，检查该标签是否为衍生标签
3. 如果不是衍生标签，调用千问大模型生成衍生标签
4. 将新标签插入 `ai_tags` 表（标记为衍生标签）
5. 更新 `ai_image_tags` 表中的 `tag_id` 和 `tag_name`

## 项目结构

```
ai_tagging_images/
├── config/
│   ├── __init__.py
│   └── settings.py          # 配置管理中心
├── logs/                     # 日志目录（自动创建）
├── promt/
│   └── qwen_tag_derive_prompt.py
├── database_config.py        # 数据库连接和 DAO
├── image_tag_derive.py       # 离线批量处理脚本
├── logger.py                 # 日志模块
├── retry_handler.py          # 重试机制
├── tag_derive_api.py         # FastAPI 服务
├── query_tags.py             # 标签查询工具
├── check_results.py          # 结果检查工具
├── requirements.txt          # 依赖清单
└── ai_article.sql            # 数据库结构
```

## 快速开始

### 1. 安装依赖

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

### 2. 配置环境变量（可选）

```bash
# Windows
set DASHSCOPE_API_KEY=your-api-key
set DB_HOST=localhost
set DB_PASSWORD=your-password

# Linux/Mac
export DASHSCOPE_API_KEY=your-api-key
export DB_HOST=localhost
export DB_PASSWORD=your-password
```

### 3. 运行离线脚本

```bash
# 处理全部待处理数据
python image_tag_derive.py

# 从指定ID开始处理（断点续传）
python image_tag_derive.py --start-id 100

# 指定ID范围处理
python image_tag_derive.py --start-id 100 --end-id 200

# 指定起始ID和批次大小
python image_tag_derive.py --start-id 100 --batch-size 3

# 按指定ID处理（单个或多个）
python image_tag_derive.py --id 16495
python image_tag_derive.py --id 16495 16496 16497
```

> 注意：所有模式都会检查衍生标签，已有衍生标签的记录会被跳过。

### 4. 启动 API 服务

```bash
python tag_derive_api.py
```

服务启动后访问：
- API 文档：http://127.0.0.1:8000/docs
- 健康检查：http://127.0.0.1:8000/health

## API 接口

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/` | 服务状态 |
| GET | `/health` | 健康检查 |
| POST | `/api/derive/single` | 单张图片标签衍生 |
| POST | `/api/derive/batch` | 批量标签衍生（最多5张） |
| POST | `/api/derive/async` | 异步批量任务 |
| GET | `/api/task/{task_id}` | 查询任务状态 |
| GET | `/api/stats` | 统计信息 |
| GET | `/api/pending` | 待处理列表 |

### 示例请求

**单张图片衍生：**
```bash
curl -X POST http://127.0.0.1:8000/api/derive/single \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "tag_name": "高血压"
  }'
```

**响应：**
```json
{
  "success": true,
  "original_tag": "高血压",
  "derived_tags": ["血压升高", "心血管疾病", "降压药", "血压监测"],
  "merged_tag": "#高血压##血压升高##心血管疾病##降压药##血压监测#"
}
```

## 配置说明

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `DASHSCOPE_API_KEY` | - | 千问 API Key |
| `DB_HOST` | localhost | 数据库主机 |
| `DB_PORT` | 3306 | 数据库端口 |
| `DB_USER` | root | 数据库用户 |
| `DB_PASSWORD` | - | 数据库密码 |
| `DB_DATABASE` | ai_article | 数据库名 |
| `BATCH_SIZE` | 3 | 每批处理图片数 |
| `QWEN_MAX_RETRIES` | 3 | 最大重试次数 |
| `LOG_LEVEL` | INFO | 日志级别 |
| `API_PORT` | 8000 | API 服务端口 |

## 技术栈

- **大模型**：阿里云千问 Qwen-VL-Max
- **Web 框架**：FastAPI
- **数据库**：MySQL 9.0
- **Python**：3.10+

## 数据表

主要涉及以下数据表：
- `ai_image_tags`：图片标签关联表
- `ai_tags`：标签主表

## 日志

日志文件保存在 `logs/` 目录，按日期命名：
```
logs/
└── tag_derive_20260130.log
```

## License

MIT