# 图片搜图片

**Repository Path**: wanglei6688/search-for-images

## Basic Information

- **Project Name**: 图片搜图片
- **Description**: 基于 openai/clip-vit-base-patch32 CLIP 模型 和 Faiss 向量数据库的高性能图像相似度搜索服务。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-06
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📷 以图搜图服务

基于 **CLIP 模型** 和 **Faiss 向量数据库** 的高性能图像相似度搜索服务。

无需定义任何标签，纯粹基于图像内容进行相似度搜索。上传一张图片，即可在图库中找到视觉上最相似的图片。

![Demo 演示](demo_screenshot.png)

---

## ✨ 功能特性

- **以图搜图** - 上传图片，搜索图库中最相似的图片
- **一键安装** - 提供 `requirements.txt`，一条命令安装所有依赖
- **高性能** - 支持 ONNX Runtime 加速（比 PyTorch 快 2-4 倍）
- **批量索引** - 多线程图片加载 + 批量推理，构建效率高
- **持久化存储** - 索引自动保存，重启后自动加载
- **离线运行** - 无需联网，模型本地加载
- **跨平台** - 支持 GPU (CUDA) 和 CPU 两种模式
- **现代化 Demo** - 提供美观的 Web 界面演示

---

## 🛠️ 技术栈

| 组件 | 技术 |
|------|------|
| **深度学习模型** | OpenAI CLIP (ViT-B/32) |
| **向量数据库** | Faiss (Facebook AI Similarity Search) |
| **Web 框架** | FastAPI + Uvicorn |
| **图像处理** | OpenCV + PIL |
| **模型推理** | PyTorch / ONNX Runtime |
| **前端演示** | HTML + CSS + JavaScript |

---

## 📁 项目结构

```
search-for-images/
├── app/ # Python 应用包
│ ├── __init__.py # 包初始化，导出核心组件
│ ├── config.py # 配置常量、环境变量、路径定义
│ ├── model.py # CLIP 模型加载、ONNX 初始化
│ ├── embedding.py # 图像/文字向量提取功能
│ ├── index.py # Faiss 索引管理（构建、保存、加载、搜索）
│ ├── search_items.py # 物品种类管理功能
│ └── api.py # FastAPI 路由定义
├── demo/ # 前端演示页面
│ ├── index.html # 主页面
│ ├── script.js # 交互逻辑
│ └── style.css # 样式文件
├── clip_onnx/ # ONNX 模型目录（可选加速）
│ ├── clip_vision.onnx # ONNX 模型文件
│ ├── clip_vision.onnx.data # ONNX 模型数据
│ └── clip_onnx.z01, z02... # 分片压缩包（见下方说明）
├── main.py # 应用入口
├── requirements.txt # Python 依赖列表
├── run.cmd # Windows 启动脚本
├── faiss_index.bin # Faiss 向量索引文件（运行时生成）
├── image_paths.pkl # 图片路径列表（运行时生成）
├── search_items.json # 物品种类配置（运行时生成）
└── demo_screenshot.png # 演示截图
```

---

## ⚠️ 关于 ONNX 模型文件

由于 GitHub 仓库文件大小限制，`clip_onnx` 目录中的 ONNX 模型文件已进行 **分片压缩**。

### 压缩包文件说明

| 文件名 | 大小 | 说明 |
|--------|------|------|
| `clip_onnx.z01` | 60MB | 分片 1 |
| `clip_onnx.z02` | 60MB | 分片 2 |
| `clip_onnx.z03` | 60MB | 分片 3 |
| `clip_onnx.zip` | 15MB | 主压缩包 (包含剩余部分) |

### 解压方法

```bash
# Windows 下使用 7-Zip 或 WinRAR 解压
# 只需右键 -> 解压到当前文件夹，会自动合并所有分片

# Linux/Mac 下使用 zip 命令
zip -s 0 clip_onnx.zip --out combined.zip
unzip combined.zip
```

> 💡 **注意**: 如果 `clip_vision.onnx` 和 `clip_vision.onnx.data` 已存在，则无需解压。

---

## 🎨 Demo 演示页面

项目内置了一个现代化的 Web 演示界面，位于 `demo/` 目录下。

### Demo 功能

- **📚 索引库管理** - 可视化查看索引状态，支持输入目录路径构建索引
- **🖼️ 以图搜图** - 支持点击/拖拽上传图片，显示预览
- **🔍 搜索结果** - 瀑布流展示相似图片，显示相似度百分比
- **📱 响应式设计** - 适配不同屏幕尺寸
- **🌙 深色主题** - 现代化暗色界面，视觉舒适

### 使用方式

1. 启动后端服务：`uvicorn main:app --host 0.0.0.0 --port 8000`
2. 用浏览器直接打开 `demo/index.html`
3. 在"索引库管理"中输入图片目录路径，点击"构建索引"
4. 上传待搜索的图片，点击"开始搜索"
5. 查看搜索结果，点击图片可放大查看详情

> 📌 Demo 默认连接 `http://192.168.3.185:8000`，如需修改请编辑 `demo/script.js` 中的 `API_BASE_URL` 常量。

---

## 🚀 快速开始

### 1. 一键安装依赖

项目提供了 `requirements.txt` 文件，包含所有必需和可选依赖：

```bash
# 一键安装所有依赖
pip install -r requirements.txt
```

**依赖包含：**

| 类型 | 依赖包 | 说明 |
|------|--------|------|
| 核心 | `fastapi`, `uvicorn` | Web API 框架 |
| 核心 | `transformers`, `torch`, `torchvision` | CLIP 模型支持 |
| 核心 | `pillow`, `opencv-python` | 图像处理 |
| 可选 | `faiss-cpu` | 向量相似度搜索 |
| 可选 | `onnxruntime` | ONNX 加速推理 |

### 2. 启动服务

```bash
# 方式一：直接运行
python main.py

# 方式二：使用 uvicorn 启动（推荐生产环境）
uvicorn main:app --host 0.0.0.0 --port 8000
```

服务启动后，访问以下地址：
- **API 文档**: http://localhost:8000/docs
- **前端演示**: 用浏览器打开 `demo/index.html`

### 3. 构建图片索引

构建索引是使用以图搜图功能的前提：

```bash
# 方式一：通过 API 调用
curl -X POST "http://localhost:8000/buildIndex?path=E:\Images"

# 方式二：在前端页面操作
# 打开 demo/index.html，填写图片目录路径，点击"构建索引"
```

### 4. 开始搜索

索引构建完成后，上传任意图片即可搜索相似图片。

---

## 📖 API 接口

### 构建索引

```http
POST /buildIndex?path={图片目录}&batch_size={批量大小}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | string | ✅ | 图片目录的本地路径 |
| `batch_size` | int | ❌ | 每批处理数量，默认 512 |

**响应示例：**

```json
{
"message": "索引构建完成",
"path": "E:\\Images",
"indexed_count": 1000,
"error_count": 5,
"index_size": 1000
}
```

---

### 以图搜图

```http
POST /searchByImage
Content-Type: multipart/form-data

file: [图片文件]
top_k: 20
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | file | ✅ | 要搜索的图片文件 |
| `top_k` | int | ❌ | 返回结果数量，默认 20 |

**响应示例：**

```json
{
"query_image": "dog.jpg",
"index_size": 1000,
"result_count": 20,
"similar_images": [
{"image_path": "E:\\Images\\golden_retriever.jpg", "similarity": 0.9523},
{"image_path": "E:\\Images\\labrador.jpg", "similarity": 0.9124}
]
}
```

---

### 查询索引状态

```http
GET /indexStatus
```

**响应示例：**

```json
{
"faiss_available": true,
"index_loaded": true,
"index_size": 1000,
"index_file_exists": true,
"index_file_path": "E:\\Code\\api\\faiss_index.bin"
}
```

---

### 图片代理

```http
GET /image?path={图片本地路径}
```

由于浏览器安全限制，无法直接访问本地文件。此接口作为代理，让前端可以显示本地图片。

---

## ⚡ 性能优化

### 1. 启用 ONNX Runtime 加速

ONNX Runtime 推理比 PyTorch 快 2-4 倍：

```bash
# 安装 ONNX Runtime
pip install onnxruntime

# 解压分片压缩的 ONNX 模型（如需要）
cd clip_onnx
# Windows: 使用 7-Zip 或 WinRAR 解压 clip_onnx.zip
# Linux: zip -s 0 clip_onnx.zip --out combined.zip && unzip combined.zip
```

模型文件位于 `clip_onnx/clip_vision.onnx`，服务启动时会自动加载。

### 2. GPU 加速

如果有 NVIDIA GPU，安装 CUDA 版本的 PyTorch：

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu118
```

### 3. 调整批量大小

根据内存大小调整 `batch_size` 参数：
- **8GB 内存**: batch_size = 256
- **16GB 内存**: batch_size = 512
- **32GB+ 内存**: batch_size = 1024

---

## 🖼️ 支持的图片格式

- `.jpg` / `.jpeg`
- `.png`
- `.bmp`
- `.gif`
- `.webp`

---

## 📊 性能参考

测试环境：CPU 运行（无 GPU）

| 图片数量 | 构建索引耗时 | 单次搜索耗时 |
|----------|--------------|--------------|
| 1,000 张 | 约 2-5 分钟 | < 100ms | | 10,000 张 | 约 20-50 分钟 | < 100ms | | 100,000 张 | 约 4-8 小时 | < 100ms |> 💡 启用 ONNX
    Runtime 可减少 50-70% 的索引构建时间

    ---

    ## ❓ 常见问题

    ### Q: 模型加载失败怎么办？

    确保 CLIP 模型已下载到本地：

    ```bash
    # 手动下载模型
    from transformers import CLIPModel, CLIPProcessor
    model = CLIPModel.from_pretrained("openai/clip-vit-base-patch32")
    processor = CLIPProcessor.from_pretrained("openai/clip-vit-base-patch32")
    ```

    ### Q: Faiss 安装失败？

    ```bash
    # Windows
    pip install faiss-cpu

    # Linux
    pip install faiss-cpu
    # 或安装 GPU 版本
    pip install faiss-gpu
    ```

    ### Q: 如何更新图片索引？

    重新调用 `/buildIndex` 接口，会覆盖原有索引。

    ### Q: ONNX 模型文件解压失败？

    确保所有分片文件（`clip_onnx.z01`, `z02`, `z03`, `clip_onnx.zip`）都在同一目录下，然后使用支持分片压缩的解压工具（如 7-Zip、WinRAR）进行解压。

    ---

    ## 📄 许可证

    MIT License

    ---

    ## 🤝 贡献

    欢迎提交 Issue 和 Pull Request！