多模态检索演示项目

基于 CLIP 模型构建的轻量级以文搜图、以图搜图系统，提供命令行工具与 Flask Web 演示界面，适合二次开发和功能扩展。

功能亮点

• 同时支持文本与图片查询，底层统一为向量相似度检索。
• 自带示例数据生成脚本，几分钟即可完成体验。
• 模块拆分明确，便于替换模型、接入数据库或扩展 API。
• 提供 Typer CLI 与 Web 页面，方便开发调试与对外演示。

目录结构

multimodal_search/
├── app/                   # 核心业务逻辑
│   ├── config.py          # 路径、模型等集中配置
│   ├── dataset.py         # 图片与元数据加载
│   ├── embeddings.py      # CLIP 模型封装
│   ├── index.py           # 向量索引读写与检索
│   ├── search_service.py  # 面向应用的检索服务
│   └── web.py             # Flask Web 界面
├── data/
│   ├── images/            # 图片资源（示例或自备数据）
│   └── embeddings/        # 索引文件输出目录
├── scripts/
│   └── demo_data.py       # 示例图片生成脚本
├── static/                # Web 静态资源
├── templates/             # Web 页面模板
├── manage.py              # 项目管理 CLI
├── requirements.txt       # 依赖列表
└── README.md

快速开始

1. 创建虚拟环境并安装依赖

   cd multimodal_search
   python3 -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt

2. 准备示例图片（可选）

   python manage.py prepare-demo

3. 构建索引

   python manage.py ingest

4. 启动 Web 演示

   python manage.py web --host 0.0.0.0 --port 5000

   浏览器访问 http://127.0.0.1:5000，即可体验以文搜图与以图搜图。

命令行能力

python manage.py search-text "夜晚的城市灯光"
python manage.py search-image data/images/sunset_bay.png

自定义数据

1. 将图片放入 data/images，支持 png/jpg/jpeg/webp。
2. 可选：在同级目录新建 metadata.json，结构示例：

   [
     {
       "filename": "my_photo.jpg",
       "id": "photo-001",
       "title": "沙滩夕阳",
       "tags": ["海边", "日落"],
       "description": "金色的沙滩与天空"
     }
   ]

3. 重新运行 python manage.py ingest 更新索引。

开发与扩展建议

• 模型替换：更新 app/config.py 内的 MODEL_NAME，并根据需要调整 EmbeddingBackend。
• 索引持久化：目前使用 JSON，便于调试；生产可替换为向量数据库或 FAISS。
• 接口扩展：若需 REST 接口，可在 SearchService 基础上新增 FastAPI/Flask Blueprint。
• 任务调度：可结合 Celery/Supervisor，实现定时增量索引或批量更新。

Git 管理

首次初始化仓库：

cd multimodal_search
git init
git add .
git commit -m "初始化多模态检索项目骨架"

建议在功能开发、模型调整前创建主题分支，保持主分支稳定。