mmandrille/imatch

Match：可扩展的反向图像搜索工具

镜像概述和主要用途

Match 是一个基于 Kubernetes 和 Elasticsearch 的可扩展反向图像搜索工具，旨在简化相似图像的搜索过程。它使用先进的感知哈希技术，能够不受图像缩放和90度旋转的影响进行匹配。通过 HTTP API 可快速集成到各类反向图像搜索应用中，结合 Kubernetes 和 Elasticsearch 的强大能力，可轻松扩展至数十亿图像规模，同时让用户完全控制数据存储位置。Match 底层主要使用 https://github.com/ascribe/image-match 处理图像搜索核心工作。

核心功能和特性

• 先进的图像匹配技术：采用感知哈希算法，对图像缩放和90度旋转具有不变性
• 可扩展架构：基于 Kubernetes 和 Elasticsearch，支持数十亿图像存储与搜索
• 灵活的 HTTP API：提供简洁易用的 API 接口，支持图像添加、删除、搜索、比较等操作
• 高度可配置：通过环境变量自定义工作节点数量、Elasticsearch 连接参数等
• 容器化部署：以 Docker 容器形式打包，确保高度可移植性

使用场景和适用范围

• 图像版权检测与追踪
• 相似图像推荐系统
• 图像数据库管理与检索
• 社交媒体内容审核
• 电子商务产品图像匹配

详细使用方法和配置说明

快速开始

已运行 Elasticsearch 时

直接通过 Docker 运行 Match 容器，指定 Elasticsearch 连接地址：

bash
$ docker run -e ELASTICSEARCH_URL=https://daisy.us-west-1.es.amazonaws.com -it dsys/match

本地运行（包含 Elasticsearch）

需先安装 docker-compose，克隆仓库后执行：

bash
$ make dev

环境变量配置

Match 支持通过以下环境变量进行配置：

• WORKER_COUNT
  默认值：4
  Gunicorn 工作节点数量

• ELASTICSEARCH_URL
  默认值：elasticsearch:9200
  Elasticsearch 数据库 URL，用于存储图像签名。若不想自建 Elasticsearch 集群，可考虑使用 AWS Elasticsearch Service

• ELASTICSEARCH_INDEX
  默认值：images
  Elasticsearch 中存储图像签名的索引名称

• ELASTICSEARCH_DOC_TYPE
  默认值：images
  存储图像签名的文档类型

在 Kubernetes 集群中使用

可通过以下配置文件部署到 Kubernetes 集群：

服务配置（match-service.yml）

yaml
apiVersion: v1
kind: Service
metadata:
  name: match
spec:
  ports:
  - name: http
    port: 80
    protocol: TCP
  selector:
    app: match

复制控制器配置（match-rc.yml）

yaml
apiVersion: v1
kind: ReplicationController
metadata:
  name: match
spec:
  replicas: 1
  selector:
    app: match
  template:
    metadata:
      labels:
        app: match
    spec:
      containers:
      - name: match
        image: dsys/match:latest
        ports:
        - containerPort: 80
        env:
        - name: WORKER_COUNT
          value: "4"
        - name: ELASTICSEARCH_URL
          valueFrom:
            secretKeyRef:
              name: match
              key: elasticsearch.url
        - name: ELASTICSEARCH_INDEX
          valueFrom:
            secretKeyRef:
              name: match
              key: elasticsearch.index
        - name: ELASTICSEARCH_DOC_TYPE
          valueFrom:
            secretKeyRef:
              name: match
              key: elasticsearch.doc-type

密钥配置（match-secret.yml）

yaml
apiVersion: v1
kind: Secret
metadata:
  name: match
data:
  # https://daisy.us-west-1.es.amazonaws.com（请修改为实际地址）
  elasticsearch.url: aHR0cHM6Ly9kYWlzeS51cy13ZXN0LTEuZXMuYW1hem9uYXdzLmNvbQ==

  # images
  elasticsearch.index: aW1hZ2Vz

  # images
  elasticsearch.doc-type: aW1hZ2Vz

API 接口说明

Match 提供简单的 HTTP API，所有请求参数通过 application/x-www-form-urlencoded 或 multipart/form-data 格式传递。

POST /add

添加图像签名到数据库。

参数

• url 或 image（必填）
  要添加的图像，可通过 url 参数提供图像 URL，或通过 image 参数以 multipart/form-data 格式上传文件

• filepath（必填）
  图像在数据库中的存储路径，若该路径已存在图像，将被覆盖

• metadata（默认：None）
  附加到图像的任意 JSON 格式元数据

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "add",
  "result": []
}

DELETE /delete

从数据库中删除图像签名。

参数

• filepath（必填）
  数据库中图像签名的路径

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "delete",
  "result": []
}

POST /search

搜索数据库中的相似图像，相似度分数范围为 0-100，100 为完全匹配。

参数

• url 或 image（必填）
  要搜索的图像，可通过 url 参数提供图像 URL，或通过 image 参数以 multipart/form-data 格式上传文件

• all_orientations（默认：true）
  是否搜索图像的 90 度旋转版本

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "search",
  "result": [
    {
      "score": 99.0,
      "filepath": "http://static.wixstatic.com/media/0149b5_345c8f862e914a80bcfcc98fcd432e97.jpg_srz_614_709_85_22_0.50_1.20_0.00_jpg_srz"
    }
  ]
}

POST /compare

比较两张图像的相似度，分数范围为 0-100，100 为完全匹配。

参数

• url1 或 image1，url2 或 image2（必填）
  要比较的两张图像，可通过 url1/url2 提供 URL，或通过 image1/image2 以 multipart/form-data 格式上传文件

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "compare",
  "result": [
    {
      "score": 99.0
    }
  ]
}

GET /count

统计数据库中的图像签名数量。

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "list",
  "result": [420]
}

GET /list

列出数据库中图像签名的文件路径。

参数

• offset（默认：0）
  开始列出图像路径的位置

• limit（默认：20）
  要获取的图像路径数量

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "list",
  "result": [
    "http://img.youtube.com/vi/iqPqylKy-bY/0.jpg",
    "https://i.ytimg.com/vi/zbjIwBggt2k/hqdefault.jpg",
    "https://s-media-cache-ak0.pinimg.com/736x/3d/67/6d/3d676d3f7f3031c9fd91c10b17d56afe.jpg"
  ]
}

GET /ping

检查服务器健康状态。

示例响应

json
{
  "status": "ok",
  "error": [],
  "method": "ping",
  "result": []
}

开发指南

bash
$ export ELASTICSEARCH_URL=https://daisy.us-west-1.es.amazonaws.com
$ make build
$ make run
$ make push

推送到 Docker.io

1. 登录 Docker Hub，创建仓库：https://hub.docker.com/repositories
2. 执行以下命令推送镜像：

bash
docker login
docker build -t mmandrille/imatch:latest -f Dockerfile .
docker push mmandrille/imatch:latest

许可和致谢

Match 基于 https://github.com/ascribe/image-match 开发，而后者又基于论文《An image signature for any kind of image》（Goldberg et al）。另有一个 参考实现 可能更适合特定需求。

Match 本身采用 https://github.com/dsys/match/blob/master/LICENSE 发布，ascribe/image-match 采用 Apache 2.0 许可证发布。