ai_tagging_images/README.md

AI 图片标签衍生系统

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

功能概述

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

标签衍生流程

流程说明：

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

pip install -r requirements.txt

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

# 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. 运行离线脚本

# 处理全部待处理数据
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 服务

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	待处理列表

示例请求

单张图片衍生：

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": "高血压"
  }'

响应：

{
  "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