README.md

---
title: CLIP Image Retrieval System
emoji: 🔎
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
python_version: "3.11"
suggested_hardware: cpu-basic
short_description: CLIP-based semantic image retrieval.
models:
  - sentence-transformers/clip-ViT-B-32
tags:
  - image-retrieval
  - clip
  - gradio
preload_from_hub:
  - sentence-transformers/clip-ViT-B-32
pinned: false
---

# 基于 CLIP 的图像检索系统

## 仓库简介

本仓库实现了一个面向课程作业的图像检索系统，支持文本检索与以图搜图。系统使用 CLIP 生成向量表示，并通过向量检索服务完成相似度搜索，前端基于 Gradio 构建。

本地部署需要按照下面的流程下载模型与数据集。

在线访问链接：[待补充]()

## 仓库目录

```
app.py
README.md
requirements.txt
assets/
  custom.css
  favorite_modal.js
data/
  metadata.csv
  favorites/
  images/
report/
  report_template.md
scripts/
  _bootstrap.py
  build_metadata.py
  clear_index.py
  import_grocery_dataset.py
  index_images.py
src/
  __init__.py
  clip_embedder.py
  config.py
  dataset.py
  favorites.py
  runtime.py
  search_service.py
  utils.py
  vector_store.py
  ui/
    __init__.py
    callbacks.py
    constants.py
    formatters.py
    layout.py
    types.py
tests/
  test_refactor.py
```

## 部署流程

1. 创建并激活虚拟环境。

```bash
python -m venv .venv
```

Windows PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
```

Windows CMD:

```cmd
.venv\Scripts\activate.bat
```

macOS/Linux:

```bash
source .venv/bin/activate
```

2. 安装依赖。

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

3. 配置 Upstash Vector（若仓库包含 `.env.example`）。

```bash
cp .env.example .env
```

Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

在 `.env` 中填写：

```env
UPSTASH_VECTOR_REST_URL=
UPSTASH_VECTOR_REST_TOKEN=
UPSTASH_VECTOR_NAMESPACE=image-retrieval-lab3
```

4. 下载数据集。

```bash
python scripts/import_grocery_dataset.py
```

5. 生成元数据并构建向量索引。

```bash
python scripts/build_metadata.py
python scripts/index_images.py
```

6. 启动应用。

```bash
python app.py
```

终端会输出本地访问地址（通常为 `http://127.0.0.1:7860`）。