一款用 Python、Ruby 和 Docker 自托管的迷因搜索引擎

利用 AI 根据内容和文本为你的迷因建立索引，让你轻松检索，尽享迷因大战的乐趣。

所有处理——从图像转文本提取、向量嵌入到搜索——均在本地完成。

本仓库包含代码、教程笔记本以及用于索引、搜索和基于语义搜索内容与文本轻松检索迷因的应用程序。

本 README 剩余部分的目录：

• 迷因搜索

  • 功能
  • 要求
  • 安装说明
  • 首次生成/下载模型所需时间
  • 索引你的迷因
  • 自定义应用端口
  • 使用 Docker 在本地构建应用
  • 运行测试

• Discord 服务器

• 更新日志

• 功能请求与贡献

迷因搜索

功能

迷因搜索的功能包括：

1. 多种图像转文本模型

   根据你的需求和资源选择合适的图像转文本模型——从小型（约 2 亿参数）到大型（约 20 亿参数）。

   目前迷因搜索可用的图像转文本模型如下，以默认模型开始：

   • Florence-2-base —— 微软开发的一系列流行的轻量级视觉语言模型，包括 2.5 亿参数的基础版和 7 亿参数的大版。*这是迷因搜索中使用的默认模型*。
   • Florence-2-large —— Florence-2 系列中的 7 亿参数视觉语言模型变体。
   • SmolVLM-256 —— Hugging Face 开发的 2.56 亿参数视觉语言模型。
   • SmolVLM-500 —— Hugging Face 开发的 5 亿参数视觉语言模型。
   • Moondream2 —— 用于图像描述或提取图像文本的 20 亿参数视觉语言模型。
   • Moondream2-INT8 —— 针对内存受限硬件的 Moondream2 INT8 量化版本。可在几乎不损失质量的情况下将内存占用从约 5GB 降至 1.5–2GB，非常适合仅配备 CPU 的设备。

2. 自动生成迷因描述

   可以针对特定迷因而非整个目录进行自动描述生成。

3. 手动编辑迷因描述

   为了获得更好的搜索结果，可以手动编辑或添加描述；如果你不想等待自动生成功能，也可以直接进行操作。

4. 标签

   为迷因创建、编辑并分配标签，以便更好地组织和筛选搜索结果。

5. 快速向量搜索

   基于 Postgres 和 pgvector，享受更快速的关键词和向量搜索，同时优化数据库事务流程。

6. 目录路径

   可以将迷因组织到多个子目录中，无需全部存储在一个文件夹内。

7. 新的组织工具

   按标签、目录路径和描述嵌入进行筛选，并在关键词搜索和向量搜索之间切换，以实现更精细的控制。

8. 批量描述生成

   可以一次性为多个迷因生成描述，从而加快索引速度。

9. 暗色模式

   在任何环境下都能舒适浏览，可切换浅色和暗色主题。

10. 目录重新扫描

    自动检测并索引你目录中新添加的迷因。

11. 拖放上传

    通过网页界面支持拖放上传迷因。文件会存储在 direct-uploads 目录中（可通过 Docker 卷挂载进行配置），并自动扫描以进行索引。支持 JPG、PNG 和 WEBP 格式，可批量上传（最多 50 个文件），实时跟踪进度，并自动处理重复文件名问题。

要求

对于 Docker 部署（推荐）：

• Docker 和 Docker Compose

对于本地开发：

• Ruby 3.4.2
• Rails 8.0.4
• Python 3.12
• Node.js 20 LTS
• PostgreSQL 17 并带有 pgvector 扩展

我们建议使用 mise 来管理 Ruby、Python 和 Node.js 的版本。详细设置说明请参阅 CLAUDE.md。

安装说明

要启动应用，请拉取此仓库并使用 docker-compose 启动服务器集群：

docker compose up

这将拉取并启动应用、数据库和自动描述生成器的容器。应用本身将在端口 3000 上运行，可通过以下地址访问：

http://localhost:3000

如果只想单独启动应用，请拉取仓库并进入 meme_search/meme_search/meme_search_app 目录。进入后，执行以下命令以在开发模式下启动应用：

./bin/dev

执行此操作时，请确保本地已运行一个可用的 PostgreSQL 实例，且监听端口为 5432。

注意：Linux 用户：为了实现容器间的通信，您可能需要在 meme_search 服务中添加以下 extra_hosts 配置：

extra_hosts:
    - "host.docker.internal:host-gateway"

首次生成/模型下载时间

首次自动生成表情包描述所需的时间会比平时更长，因为此时需要下载并缓存图像转文本模型的权重。后续的生成速度会更快。

您可以在应用的设置选项卡中下载其他模型。

索引您的表情包

您可以通过创建自己的描述或自动生成功能来索引您的表情包，如下所示。

要开始索引您自己的表情包，首先调整 compose 文件，在 meme_search 和 image_to_text_generator 服务中添加 volume 挂载，以便将您本地的表情包子目录正确连接到应用。

例如，假设您的某个表情包目录名为 new_memes，位于您机器上的以下路径：/local/path/to/my/memes/new_memes。

要将该子目录正确挂载到 meme_search 服务，需将其配置中的 volumes 部分调整为如下内容：

volumes:
  - ./meme_search/memes/:/app/public/memes # <-- 示例仓库中的表情包目录
  - /local/path/to/my/memes/new_memes/:/rails/public/memes/new_memes # <-- 您的个人表情包集合，必须挂载到容器内的 /rails/public/memes 目录下

注意：您的 new_memes 目录必须挂载到容器内部的 /rails/public/memes 目录中，如上所示。

同样，要将该子目录正确挂载到 image_to_text_generator 服务，需将其配置中的 volumes 部分调整为如下内容：

volumes:
  - ./meme_search/memes/:/app/public/memes # <-- 示例仓库中的表情包目录
  - /local/path/to/my/memes/new_memes/:/app/public/memes/new_memes # <-- 您的个人表情包集合，必须挂载到容器内的 /app/public/memes 目录下
...

注意：您的 new_memes 目录必须挂载到容器内部的 /app/public/memes 目录中，如上所示。

如果您担心应用程序会修改您现有的表情包库，作为预防措施，您可以在卷挂载行中添加 ro 参数，使其变为只读模式，如下所示：

volumes:
  - ./meme_search/memes/:/app/public/memes # <-- 示例仓库中的表情包目录
  - /local/path/to/my/memes/new_memes/:/app/public/memes/new_memes:ro
...

现在重启应用，并通过 UI 注册 new_memes 目录，路径为：设置 -> 路径 -> 创建新路径，如下图所示。在提供的字段中输入 new_memes 并按回车键。

一旦在应用中注册成功，您的表情包就可以进行索引、打标签等操作了！

模型下载

用于自动生成表情包描述的图像转文本模型均为开源模型，且大小不一。

自定义应用端口

您可以轻松自定义应用的端口，以便更方便地与 Unraid 或 Portainer 等工具配合使用，或者是因为您已经在默认的 meme_search 应用端口 3000 上运行了其他服务。

要自定义主应用端口，请在目录根目录下创建一个 .env 文件。在此文件中，您可以定义以下自定义环境变量，用于指定如何访问应用、图像转文本生成器和数据库。这些值如下：

APP_PORT= # 应用的端口，默认为3000

该值会通过 docker-compose-pro.yml 文件自动检测并加载到各个服务中。

使用 Docker 在本地构建应用

Docker 镜像仅支持手动构建，没有针对发布版本或标签的自动化 CI 构建流程。

要构建应用（包括 docker-compose.yml 文件中定义的所有服务），请在终端中运行本地的 compose 文件：

docker compose -f docker-compose-local-build.yml up --build

对于多平台构建（AMD64 + ARM64）以及推送到 GitHub Container Registry 的操作，可以使用本地构建脚本：

bash scripts/build_and_push.sh

这将构建应用、数据库和自动描述生成器的 Docker 镜像，并在 http://localhost:3000 启动应用。

运行测试

要在本地运行测试，请拉取仓库并进入 meme_search/meme_search/meme_search_app 目录。安装所需的 gem 包：

bundle install

然后可以运行测试：

bash run_tests.sh

执行此操作时，请确保本地已运行一个可用的 PostgreSQL 实例，且监听端口为 5432。

对 /app 子目录运行代码风格检查：

rubocop app

以确保代码整洁且格式规范。

在本地运行 CI（可选）

您可以通过 act 在本地运行完整的 GitHub Actions CI 流程：

# 安装 act（macOS）
brew install act

# 运行所有 CI 作业
act --container-architecture linux/amd64 -P ubuntu-latest=catthehacker/ubuntu:act-latest

# 运行特定作业
act -j pro_app_unit_tests --container-architecture linux/amd64 -P ubuntu-latest=catthehacker/ubuntu:act-latest

这可以帮助您在推送到 GitHub 之前验证更改是否符合 CI 规范。

Docker 端到端测试（仅限本地验证）

Docker 端到端测试会验证完整的微服务栈（Rails + Python + PostgreSQL）在隔离的 Docker 容器中是否正常工作。这些测试基于全新的 Docker 构建，用于测试服务间的通信、Webhook 以及类似生产环境的部署。

当前状态：7 项烟雾测试中有 6 项通过（覆盖率 85%）——详情请参阅 playwright-docker/README.md。

# 运行所有 Docker 端到端测试
npm run test:e2e:docker

# 使用 UI 模式运行（推荐用于调试）
npm run test:e2e:docker:ui

这些测试涵盖的内容：

• 完整的图像处理流水线（Rails → Python → Rails Webhook）
• 带有嵌入生成的向量搜索
• 关键字搜索功能
• 并发处理与任务队列
• 嵌入刷新操作

重要提示：由于 Docker 构建时间较长（约 10–15 分钟）以及资源需求，这些测试不会在 CI 环境中运行。贡献者必须在本地运行这些测试，然后再提交以下方面的 Pull Request：

• Docker 配置
• 跨服务通信
• 图像转文本生成工作流
• 嵌入生成

请参阅 playwright-docker/README.md 获取完整文档。

Discord 服务器

加入我们的 Discord 服务器 ，讨论新功能、Bug 修复以及其他开源项目（例如 ytgify——一款可以直接从 YouTube 播放器截取 GIF 的浏览器扩展！）

更改日志

Meme Search 目前正处于积极开发中！请查看此仓库中的 CHANGELOG.md 文件，了解最近的更改记录。

功能请求与贡献

我们欢迎功能请求和贡献！

请访问此仓库的讨论区，提出您对功能改进的建议，并参与讨论或投票！

有关贡献的基本规则，请参阅 CONTRIBUTING.md 文件。

以下是使用 gitdiagram 生成的仓库结构图，清晰展示了其主要组件及相互关系：

flowchart TD
    %% 全局实体
    User["用户"]:::user

    %% Docker & Compose 编排
    Docker["Docker & Compose 编排"]:::docker

    %% 主要服务
    Rails["Rails Meme Search 应用程序"]:::rails
    Python["图像转文本生成器（Python）"]:::python
    DB["PostgreSQL 数据库（带 pgvector 插件）"]:::database

    %% 共享文件卷子图
    subgraph "共享模因文件"
        PublicMemes["公开模因"]:::volume
        MemeDir["模因目录"]:::volume
    end

    %% 相互交互
    User -->|"交互"| Rails
    Rails -->|"数据库查询更新"| DB
    Rails -->|"API 请求"| Python
    Python -->|"API 响应"| Rails

    %% 卷挂载访问
    Rails ---|"卷挂载访问"| PublicMemes
    Python ---|"卷挂载访问"| MemeDir

    %% Docker 编排链接
    Docker ---|"编排"| Rails
    Docker ---|"编排"| Python
    Docker ---|"编排"| DB

    %% 点击事件
    click Rails "https://github.com/neonwatty/meme-search/tree/main/meme_search/meme_search_app"
    click Python "https://github.com/neonwatty/meme-search/tree/main/meme_search/image_to_text_generator"
    click DB "https://github.com/neonwatty/meme-search/blob/main/meme_search/meme_search_app/config/database.yml"
    click Docker "https://github.com/neonwatty/meme-search/blob/main/docker-compose.yml"
    click PublicMemes "https://github.com/neonwatty/meme-search/tree/main/meme_search/meme_search_app/public/memes"
    click MemeDir "https://github.com/neonwatty/meme-search/tree/main/meme_search/memes"

    %% 样式定义
    classDef user fill:#fceabb,stroke:#d79b00,stroke-width:2px;
    classDef rails fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef python fill:#bbdefb,stroke:#1976d2,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5 5;
    classDef docker fill:#d1c4e9,stroke:#673ab7,stroke-width:2px,stroke-dasharray: 3 3;
    classDef volume fill:#ffcdd2,stroke:#e53935,stroke-width:2px,stroke-dasharray: 2 2;

Meme Search 快速上手指南

Meme Search 是一个支持自托管的 AI 表情包搜索引擎，利用本地运行的视觉语言模型（VLM）自动提取图片中的文字和语义内容，并通过向量数据库实现高效的语义搜索。所有数据处理均在本地完成，无需上传云端。

环境准备

系统要求

推荐使用 Docker 部署（最简单且隔离性好）。

前置依赖：

• Docker
• Docker Compose

本地开发模式（可选，仅用于二次开发）：

• Ruby 3.4.2 + Rails 8.0.4
• Python 3.12
• Node.js 20 LTS
• PostgreSQL 17 (需安装 pgvector 扩展)
• 推荐工具：使用 mise 管理多版本运行环境。

注意：首次运行时会自动下载 AI 模型权重（约几百 MB 到几 GB），请确保网络连接通畅。国内用户若遇到 HuggingFace 下载缓慢问题，建议配置镜像源或在宿主机预先下载模型映射到容器内。

安装步骤

1. 克隆项目

git clone https://github.com/neonwatty/meme-search.git
cd meme-search

2. 启动服务

使用 Docker Compose 一键启动应用、数据库及 AI 生成器服务：

docker compose up

注：首次启动时，系统会拉取镜像并下载默认的图像转文本模型（Florence-2-base），耗时取决于网络状况。

3. 访问应用

服务启动完成后，在浏览器中访问：

http://localhost:3000

4. 自定义端口（可选）

如果 3000 端口被占用，可在项目根目录创建 .env 文件指定端口：

echo "APP_PORT=8080" > .env
docker compose up

基本使用

第一步：挂载表情包目录

为了索引你本地的表情包，需要修改 docker-compose.yml 文件，将本地文件夹映射到容器内部。

假设你的表情包存放在 /home/user/my_memes，请按以下方式修改 volumes 配置：

对于 meme_search 服务：

volumes:
  - ./meme_search/memes/:/app/public/memes
  - /home/user/my_memes:/rails/public/memes/my_memes

对于 image_to_text_generator 服务：

volumes:
  - ./meme_search/memes/:/app/public/memes
  - /home/user/my_memes:/app/public/memes/my_memes

关键点：容器内的路径必须分别位于 /rails/public/memes 和 /app/public/memes 下，且子目录名称（如 my_memes）需保持一致。若担心数据被修改，可在路径后添加 :ro 设为只读。

修改配置后重启容器：

docker compose down
docker compose up

第二步：注册目录

1. 登录 Web 界面 (http://localhost:3000)。
2. 进入 Settings (设置) -> Paths (路径)。
3. 点击 Create New，输入刚才映射的子目录名称（例如 my_memes），按回车确认。

第三步：生成描述与搜索

• 自动生成：系统会自动扫描新目录，利用 AI 模型为表情包生成文字描述和标签。你可以在界面上看到生成进度。
• 手动编辑：点击任意表情包，可手动修正描述或添加自定义标签（Tags）以优化搜索结果。
• 语义搜索：在搜索框输入自然语言（如“一只悲伤的猫”或“关于加班的梗图”），系统将基于向量相似度返回结果，而不仅仅是匹配文件名。
• 拖拽上传：支持直接将图片拖入网页进行上传（文件将保存至 direct-uploads 目录并自动索引）。

高级功能提示

• 切换模型：在设置中可根据硬件性能切换不同的视觉模型（如显存较小可选择 Moondream2-INT8 或 SmolVLM 系列）。
• 批量操作：支持批量重新生成描述或重新扫描目录以同步新增文件。
• 深色模式：界面右上角可切换深色/浅色主题。