# image_search

**Repository Path**: kte66/image_search

## Basic Information

- **Project Name**: image_search
- **Description**: 课设
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图像搜索系统使用说明 (SOP)

## 项目概述

本项目是一个基于多模态模型的中文图像搜索系统，支持CLIP、InternVL、Qwen-VL、Jina-CLIP-v2和Nomic Embed Vision五种模型，可以根据需求切换使用不同的模型进行图像和文本的语义匹配。

## 目录结构

```
image_search/
├── encoders/                 # 编码器模块
│   ├── __init__.py          # 编码器工厂
│   ├── base.py              # 基础编码器接口
│   ├── clip_encoder.py      # CLIP模型编码器
│   ├── internvl_encoder.py  # InternVL模型编码器
│   ├── qwenvl_encoder.py    # Qwen-VL模型编码器
│   ├── jina_clip_v2_encoder.py # Jina-CLIP-v2模型编码器
│   └── nomic_embed_encoder.py  # Nomic Embed Vision模型编码器
├── images/                  # 图像数据目录
├── build_index.py           # 构建索引脚本
├── search.py                # 搜索脚本
├── requirements.txt         # 依赖包列表
└── USAGE.md               # 本使用说明
```

## 环境配置

### 1. 创建虚拟环境 (推荐)

为了确保项目的依赖包不会与系统其他Python项目冲突，建议创建独立的虚拟环境：

#### 使用 venv 创建虚拟环境 (Python内置方法):
```bash
# 创建虚拟环境 (Python 3.7+)
python -m venv image_search_env

# 激活虚拟环境
# Windows:
image_search_env\Scripts\activate
# macOS/Linux:
source image_search_env/bin/activate
```

#### 或使用 conda 创建虚拟环境:
```bash
# 创建虚拟环境
conda create -n image_search_env python=3.9

# 激活虚拟环境
conda activate image_search_env
```

### 2. 安装依赖包

激活虚拟环境后，安装项目依赖包：

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

> 注意：在虚拟环境中运行此命令，确保依赖包安装在虚拟环境中而不是系统环境中

### 3. 确保环境要求

- Python >= 3.7
- PyTorch (支持CUDA可选)
- Transformers库
- Faiss库 (CPU版本)

## 数据准备

### 1. 准备图像数据

将需要进行搜索的图像文件放入 `images/` 目录中，支持以下格式：
- JPG
- PNG

### 2. 检查图像目录

确保 `images/` 目录中至少包含一张图像文件。

## 模型选择

系统支持三种模型：

### 1. CLIP模型 (默认)
- 模型维度: 512维
- 特点: 通用性强，适合英文和中文查询
- 模型名称: `clip`


### 2. Jina-CLIP-v2模型
- 模型维度: 768维
- 特点: 支持89种语言，图像分辨率支持更高，更强的多语言对齐能力
- 模型名称: `jina_clip_v2`
- 模型ID: jinaai/jina-clip-v2

### 3. Nomic Embed Vision模型
- 模型维度: 768维
- 特点: 轻量级多模态嵌入模型，文本和图像使用不同模型
- 模型名称: `nomic`
- 模型ID: nomic-ai/nomic-embed-vision-v1.5 (图像) + nomic-ai/nomic-embed-text-v1.5 (文本)

## 索引构建

### 1. 构建CLIP模型索引

```bash
python build_index.py clip
```

### 2. 构建Jina-CLIP-v2模型索引

```bash
python build_index.py jina_clip_v2
```

### 3. 构建Nomic Embed Vision模型索引

```bash
python build_index.py nomic
```

### 6. 索引文件说明

构建索引后会生成两个文件：
- `image_[model_name].index` - Faiss索引文件
- `image_paths_[model_name].npy` - 对应的图像路径文件

> 注意：构建索引只需运行一次，更换模型后需要重新构建

## 图像搜索

### 1. 使用CLIP模型搜索

```bash
python search.py clip
```



### 2. 使用Jina-CLIP-v2模型搜索

```bash
python search.py jina_clip_v2
```

### 3. 使用Nomic Embed Vision模型搜索

```bash
python search.py nomic
```

### 6. 搜索操作流程

1. 运行搜索脚本后，系统会加载对应模型的索引
2. 输入中文查询文本
3. 系统返回最相似的5张图像
4. 输入 `q` 退出搜索

### 7. 搜索结果说明

搜索结果按相似度降序排列，格式如下：
```
1. images/example1.jpg (相似度: 0.8912)
2. images/example2.jpg (相似度: 0.7654)
...
```

## 高级功能

### 1. 模型切换

系统支持在运行时切换模型，只需在命令行参数中指定模型名称：
- `clip` - CLIP模型
- `jina_clip_v2` - Jina-CLIP-v2模型
- `nomic` - Nomic Embed Vision模型

### 2. 扩展新模型

如需添加新模型，需要：

1. 在 `encoders/` 目录下创建新编码器实现
2. 继承 `MultiModalEncoder` 抽象基类
3. 实现 `encode_text`、`encode_image` 和 `get_embedding_dim` 方法
4. 在 `encoders/__init__.py` 中添加新模型的导入和工厂函数

## 故障排除

### 1. 索引构建失败

**问题**: 系统提示 "images 文件夹为空"

**解决方案**: 确保 `images/` 目录中存在图像文件

### 2. 模型加载失败

**问题**: 下载模型失败或加载超时

**解决方案**:
- 检查网络连接
- 尝试使用代理
- 确保有足够的磁盘空间

### 3. 搜索性能问题

**问题**: 搜索速度慢

**解决方案**:
- 确保GPU可用并正确配置
- 考虑减少图像批次大小
- 优化Faiss索引类型

### 4. 不支持的模型名

**问题**: 系统提示 "Unknown encoder"

**解决方案**: 确认使用的模型名称是否正确 (支持 `clip`、`jina_clip_v2`、`nomic`)

### 5. Windows平台特定问题

**问题**: Jina-CLIP-v2模型加载失败或提示trust_remote_code相关错误

**解决方案**:
- 确保使用了更新后的编码器实现，已添加`trust_remote_code=True`参数
- 如果遇到SIGALRM错误（仅Windows平台），这通常是警告，不影响模型功能
- 可以设置环境变量避免缓存symlink警告：
  ```bash
  set HF_HUB_DISABLE_SYMLINKS_WARNING=1
  ```

**问题**: Transformers库在Windows上的信号处理问题

**解决方案**:
- 此为已知Windows兼容性问题，不影响模型运行
- 确保使用Transformers >= 4.34版本以获得更好的Windows支持
- 如仍有问题，可考虑在WSL2中运行或使用云端环境

## 性能优化建议

1. **使用GPU加速**: 确保CUDA和cuDNN正确安装
2. **批量处理**: 系统默认使用16张图像的批次，可根据硬件调整
3. **索引优化**: 对于大数据集，可考虑使用近似最近邻算法

## 注意事项

1. 首次运行时需要下载预训练模型，可能需要较长时间
2. 不同模型生成的索引文件不能混用
3. 建议定期更新模型权重以获得最佳效果
4. 对于中文查询，建议使用InternVL模型以获得更好效果
5. 使用虚拟环境可以避免依赖冲突问题
6. 记得在使用完虚拟环境后将其停用：`deactivate`

## 技术支持

如遇到问题，请检查以下内容：

- 环境配置是否正确
- 依赖包版本是否兼容
- 图像文件格式是否支持
- 模型名称拼写是否正确

## 版本信息

- 系统版本: 1.0
- 支持的模型: CLIP, Jina-CLIP-v2, Nomic Embed Vision
- 主要功能: 中文图像搜索, 模型切换, Faiss索引