CLIPImageFinder

基于 openclip + FAISS 的本地图像语义检索系统

项目概述 · 系统架构 · 快速开始 · 目录结构 ·

---

项目概述

CLIPImageFinder 是一个轻量级的本地图像语义检索系统，基于OpenCLIP(ViT-B/32)实现用户图片库的快速语义构建和查询，核心能力包括：

• 以图搜图：将查询图像编码为向量，检索 Top-K 相似图片
• 以文搜图：将文本查询编码为向量，检索语义相关图片
• 索引持久化：使用 FAISS 保存向量索引，并用 meta.jsonl 维护图像元信息
• 前后端分离：后端负责建索引与检索服务，前端提供简单的交互页面

本仓库不包含任何数据集图片与生成的索引文件。请将你的图片放在 data/images/，运行系统上传图片生成索引。

---

系统架构

• Embedding：open_clip（图像/文本编码）

  模型默认使用 OpenCLIP ViT-B/32（可在 config 中调整）

• Index：FAISS（向量索引）

• Metadata：data/index/meta.jsonl（图像路径、显示名等）

• Service：后端提供 build/search 接口；前端展示检索结果

---

功能特性

• open_clip 模型加载与特征提取
• FAISS 索引构建、保存、加载
• 文本查询 / 图像查询检索
• 结果去重与 Top-K 返回

---

快速开始

1) 安装依赖（后端）

在/backend根目录下

cd backend
pip install -r requirements.txt

推荐使用虚拟环境（conda），确保使用GPU时CUDA等环境匹配。

2）启动后端

在/backend根目录下打开终端执行

uvicorn app.main:app --reload

启动成功后，请确保你的 backend/data 文件夹结构如下（由程序自动生成）：

• backend/data/images/
• backend/data/thumbs/
• backend/data/index/

下一步： 服务启动后，你可以尝试在浏览器打开 http://127.0.0.1:8000/api/health 访问健康检查接口，如果返回 {"ok": True, ...} 则说明后端运行正常。

3）运行前端界面

前端文件 index.html 在 /frontend 中，index.html 是一个独立的前端文件，它通过 fetch 请求与后端通信。不需要通过 uvicorn 来访问这个 HTML。

在文件资源管理器中找到 index.html，双击用 Chrome 或 Edge 浏览器打开即可。

或者

在 index.html 所在的文件夹打开另一个终端，运行：

python -m http.server 3000

然后在浏览器访问 http://127.0.0.1:3000。

4）运行测试

现在后端已经在 8000 端口守护，前端也已就绪。你可以按照以下步骤开始业务逻辑测试：

1. 切换到“库管理”标签页：选择一个包含少量图片的文件夹（建议 10-50 张）进行上传。
2. 观察后端控制台：
   • 你应该会看到大量的 POST /api/dataset/upload 日志。
   • 上传完成后，你会看到 POST /api/index/build 开始执行。
3. 开始搜索：回到“语义检索”标签页，输入文字（如“a photo of a cat”）点击搜索。

注意： 第一次运行搜索时，后端会自动下载 CLIP 模型权重文件（约 600MB-900MB），如果网络较慢，搜索接口可能会卡住或超时，请耐心等待命令行显示下载进度。

目录结构

CLIP/
  backend/
    app/
      core/
        config.py                 # 全局配置（相对路径）
      services/
        clip_model.py             # open_clip 模型加载与 embedding
        index.py                  # FAISS 索引构建/加载/保存
        search.py                 # 文本/图像检索逻辑
        storage.py                # 数据目录、meta.jsonl、thumbs 管理
        jobs.py                   # 简单任务状态（内存字典，demo 用）
      main.py                     # 后端入口
      data/                           # 不纳入版本控制（运行时生成）
    	images/                       # 你的图片
    	index/                        # faiss.index / ids.npy / meta.jsonl
    	thumbs/                       # 缩略图缓存
    requirements.txt
  frontend/
    index.html

参考

• open_clip: 提供CLIP模型与预训练参数来对文字和图像进行向量化处理
• FAISS: 向量近似性搜索库

Please refer to the respective projects' licenses for redistribution and usage terms.

License

This project is licensed under the MIT - see the LICENSE file for details.