# generative-ai-challenge

**Repository Path**: simpleworld/generative-ai-challenge

## Basic Information

- **Project Name**: generative-ai-challenge
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-21
- **Last Updated**: 2025-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图文数据对齐与零样本分类系统

## 项目概述

本项目实现了一个完整的图文数据对齐与零样本分类系统，基于多模态大模型和向量化技术，能够：

1. **图文数据对齐并生成Embedding向量** - 使用Qwen-VL-Plus模型生成图像描述，并通过text-embedding-v4模型生成向量表示
2. **零样本分类** - 针对给定的10类未见标签图像输出分类准确率
3. **可视化图文检索结果** - 计算相似度矩阵并生成可视化图表
4. **高性能图像搜索** - 支持文本查询图像，提供交互式和命令行两种模式

## 技术架构

### 核心技术栈
- **多模态大模型**: Qwen-VL-Plus (通义千问视觉语言模型)
- **向量化模型**: text-embedding-v4 (DashScope)
- **向量数据库**: ChromaDB
- **开发框架**: LangChain
- **数据处理**: Pandas, NumPy, OpenCV
- **可视化**: Matplotlib, Seaborn

### 系统架构
```
数据输入 → 多模态处理 → 向量化 → 存储 → 检索 → 分类 → 可视化
```

## 目录结构

```
generative-ai-challenge/
├── README.md                    # 项目说明文档
├── requirements.txt             # Python依赖包
├── common/
│   ├── __init__.py
│   └── config.py               # 配置文件
├── bin/                        # 核心模块目录
│   ├── README.md              # bin目录说明
│   ├── main.py                # 主程序入口
│   ├── data_processor.py      # 数据处理模块
│   ├── embedding_generator.py # 向量生成模块
│   ├── zero_shot_classifier.py # 零样本分类模块
│   ├── visualization.py       # 可视化模块
│   ├── optimized_processor.py # 优化处理器
│   ├── search_tool.py         # 统一搜索工具
│   ├── demo.py                # 统一演示脚本
│   └── zero_shot_demo.py     # 零样本分类演示
├── data/                      # 数据目录
│   ├── input/                 # 输入图像
│   └── output/                # 输出结果
└── models/                    # 模型目录
```

## 安装指南

### 1. 环境要求
- Python 3.8+
- 足够的磁盘空间用于存储处理后的数据
- 网络连接（用于API调用）

### 2. 创建虚拟环境
```bash
# 使用conda创建环境
conda create -n jupyter_notebook python=3.11
conda activate jupyter_notebook

# 或使用venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows
```

### 3. 安装依赖
```bash
pip install -r requirements.txt
```

### 4. 配置API密钥
在项目根目录创建 `.env` 文件：
```
DASHSCOPE_API_KEY=your_api_key_here
```

或者直接在 `common/config.py` 中修改API密钥。

### 5. 启动ChromaDB
```bash
# 启动ChromaDB服务器
chroma run --host localhost --port 8000
```

## 快速开始

### 1. 准备数据
将图像文件放入 `data/input/` 目录，按类别组织：
```
data/input/
├── 类别1/
│   ├── image1.jpg
│   └── image2.jpg
├── 类别2/
│   ├── image3.jpg
│   └── image4.jpg
└── ...
```

### 2. 快速演示
```bash
# 快速处理少量数据
python bin/demo.py --mode quick

# 完整处理所有数据
python bin/demo.py --mode full
```

### 3. 图像搜索
```bash
# 交互式搜索
python bin/search_tool.py --interactive

# 命令行搜索
python bin/search_tool.py --query "红色汽车" --top_k 5

# 搜索并保存可视化结果
python bin/search_tool.py --query "美丽的花朵" --save_plot
```

### 4. 零样本分类
```bash
# 运行零样本分类演示
python bin/zero_shot_demo.py
```

### 5. 完整流程
```bash
# 运行主程序
python bin/main.py --data_dir data/
```

## 核心模块说明

### 1. 数据处理模块 (`bin/data_processor.py`)
- 图像预处理和标准化
- 使用多模态模型生成图像描述
- 数据格式转换和保存
- 错误处理和重试机制

### 2. 向量生成模块 (`bin/embedding_generator.py`)
- 文本和图像Embedding生成
- ChromaDB向量数据库管理
- 相似度计算和搜索
- 批量处理支持

### 3. 零样本分类模块 (`bin/zero_shot_classifier.py`)
- 基于语义相似度的零样本分类
- 10个预定义类别的分类
- 分类结果评估和置信度计算
- 支持自定义类别

### 4. 可视化模块 (`bin/visualization.py`)
- 相似度矩阵热力图
- 分类结果图表
- 混淆矩阵
- Embedding分布图
- 搜索结果可视化

### 5. 优化处理器 (`bin/optimized_processor.py`)
- **批量处理**: 减少API调用次数
- **并行处理**: 使用多线程提高速度
- **缓存机制**: 避免重复处理
- **进度显示**: 实时显示处理进度
- **错误处理**: 完善的异常处理机制

### 6. 搜索工具 (`bin/search_tool.py`)
- **命令行模式**: 支持参数化搜索
- **交互式模式**: 友好的用户界面
- **可视化支持**: 可保存搜索结果图表
- **多格式输出**: 支持不同输出格式

## 性能优化

### 优化特性
1. **批量处理**: 减少API调用次数，提高处理效率
2. **并行处理**: 使用多线程/多进程加速处理
3. **缓存机制**: 避免重复处理相同数据
4. **进度显示**: 实时显示处理进度和统计信息
5. **错误恢复**: 完善的错误处理和重试机制

### 性能配置
```python
# 优化处理器配置
config = ProcessingConfig(
    batch_size=10,      # 批量大小
    max_workers=4,      # 最大工作线程数
    cache_file="data/output/processing_cache.json",
    save_interval=50    # 保存间隔
)
```

## 使用示例

### 高级搜索功能
```python
from bin.search_tool import ImageSearchTool

# 初始化搜索工具
search_tool = ImageSearchTool()

# 搜索图像
results = search_tool.search_images("红色汽车", k=5)

# 显示结果
search_tool.display_results("红色汽车", results)

# 保存可视化
search_tool.save_results_plot("红色汽车", results)
```

### 优化处理
```python
from bin.optimized_processor import OptimizedProcessor, ProcessingConfig

# 配置处理参数
config = ProcessingConfig(
    batch_size=10,
    max_workers=4,
    cache_file="data/output/cache.json"
)

# 创建处理器
processor = OptimizedProcessor(config)

# 处理数据集
results = processor.process_dataset("data/input", max_files_per_category=5)

# 批量添加到向量数据库
processor.batch_add_to_vector_db(results)
```

## 输出结果

### 数据文件
- `data/output/processed_data.pkl` - 处理后的数据
- `data/output/embeddings.pkl` - Embedding向量
- `data/output/classification_results.csv` - 分类结果
- `data/output/evaluation_results.json` - 评估结果
- `data/output/processing_cache.json` - 处理缓存

### 可视化图表
- `data/output/similarity_matrix.png` - 相似度矩阵
- `data/output/classification_results.png` - 分类结果分布
- `data/output/confusion_matrix.png` - 混淆矩阵
- `data/output/search_results_*.png` - 搜索结果可视化

## 预定义类别

系统支持以下10个类别的零样本分类：

1. **动物** - 包含各种动物，如猫、狗、鸟、鱼等
2. **植物** - 包含各种植物，如树木、花卉、草等
3. **交通工具** - 包含各种交通工具，如汽车、飞机、火车等
4. **建筑** - 包含各种建筑物，如房屋、桥梁、塔楼等
5. **食物** - 包含各种食物，如水果、蔬菜、肉类等
6. **服装** - 包含各种服装，如衣服、鞋子、帽子等
7. **电子产品** - 包含各种电子产品，如手机、电脑、电视等
8. **自然景观** - 包含自然景观，如山川、河流、海洋等
9. **人物** - 包含人物，如儿童、成人、老人等
10. **日常用品** - 包含日常用品，如家具、餐具、工具等

## 配置说明

### 主要配置参数 (`common/config.py`)
```python
# API配置
BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
API_KEY = "your_api_key"

# 模型配置
TEXT_MODEL = "qwen3-235b-a22b"
VISION_MODEL = "qwen-vl-plus"
EMBEDDING_MODEL = "text-embedding-v4"

# 文件路径配置
DATA_DIR = "data"
INPUT_DIR = "data/input"
OUTPUT_DIR = "data/output"
MODEL_DIR = "models"

# 数据处理配置
IMAGE_SIZE = (224, 224)  # 图像标准化尺寸
MAX_TEXT_LENGTH = 512    # 文本最大长度

# 分类配置
NUM_CLASSES = 10         # 目标类别数量
SIMILARITY_THRESHOLD = 0.7  # 相似度阈值
```

## 故障排除

### 常见问题

1. **API调用失败**
   - 检查API密钥是否正确
   - 确认网络连接正常
   - 检查API配额是否充足

2. **ChromaDB连接失败**
   - 确认ChromaDB服务已启动
   - 检查端口8000是否被占用
   - 重启ChromaDB服务

3. **NumPy版本冲突**
   - 使用项目提供的requirements.txt
   - 在jupyter_notebook环境中运行
   - 避免混用不同版本的NumPy

4. **内存不足**
   - 减少批处理大小
   - 使用更小的图像尺寸
   - 分批处理数据

### 性能优化建议

1. **使用优化处理器**: 对于大量数据，使用 `bin/optimized_processor.py`
2. **调整批处理大小**: 根据内存情况调整 `batch_size`
3. **启用缓存**: 避免重复处理相同数据
4. **并行处理**: 根据CPU核心数调整 `max_workers`

## 扩展功能

### 自定义类别
可以通过修改 `bin/zero_shot_classifier.py` 中的 `_get_class_descriptions()` 方法来添加或修改类别。

### 自定义模型
可以通过修改配置文件来使用不同的模型：
- 更换多模态模型
- 更换Embedding模型
- 调整模型参数

### 批量处理
系统支持批量处理大量数据，可以通过以下方式优化：
- 并行处理
- 内存优化
- 缓存机制

## 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

## 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 GitHub Issue
- 发送邮件至项目维护者

---

**注意**: 使用本系统需要有效的DashScope API密钥，请确保您有足够的API配额来处理您的数据集。