🇨🇳中文 | 🌐English | 📖文档/Docs | 🤖模型/Models

---

Similarities: 相似度计算与语义搜索

similarities: 一个用于相似度计算和语义搜索的工具包，支持文本和图像。相似度计算、语义匹配搜索工具包。

similarities 实现了多种文本和图片的相似度计算、语义匹配检索算法，支持亿级数据文搜文、文搜图、图搜图，python3开发，pip安装，开箱即用。

指南

• 功能特性
• 安装
• 使用方法
• 联系方式
• 致谢

功能特性

文本相似度计算 + 文本搜索

• 语义匹配模型【推荐】：本项目基于text2vec实现了CoSENT模型的文本相似度计算和文本搜索
  • 支持中英文、多语言多种SentenceBERT类预训练模型
  • 支持 Cos Similarity/Dot Product/Hamming Distance/Euclidean Distance 等多种相似度计算方法
  • 支持 SemanticSearch/Faiss/Annoy/Hnsw 等多种文本搜索算法
  • 支持亿级数据高效检索
  • 支持命令行文本转向量（多卡）、建索引、批量检索、启动服务
• 字面匹配模型：本项目实现了Word2Vec、BM25、RankBM25、TFIDF、SimHash、同义词词林、知网Hownet义原匹配等多种字面匹配模型

图像相似度计算/图文相似度计算 + 图搜图/文搜图

• CLIP(Contrastive Language-Image Pre-Training)模型：图文匹配模型，可用于图文特征（embeddings）、相似度计算、图文检索、零样本图片分类，本项目基于PyTorch实现了CLIP模型的向量表征、构建索引（基于AutoFaiss）、批量检索、后台服务（基于FastAPI）、前端展现（基于Gradio）功能
  • 支持openai/clip-vit-base-patch32等CLIP系列模型
  • 支持OFA-Sys/chinese-clip-vit-huge-patch14等Chinese-CLIP系列模型
  • 支持前后端分离部署，FastAPI后端服务，Gradio前端展现
  • 支持亿级数据高效检索，基于Faiss检索，支持GPU加速
  • 支持图搜图、文搜图、向量搜图
  • 支持图像embedding提取、文本embedding提取
  • 支持图像相似度计算、图文相似度计算
  • 支持命令行图像转向量（多卡）、建索引、批量检索、启动服务
• 图像特征提取：本项目基于cv2实现了pHash、dHash、wHash、aHash、SIFT等多种图像特征提取算法

演示

图像搜索演示：https://huggingface.co/spaces/shibing624/CLIP-Image-Search

文本搜索演示：https://huggingface.co/spaces/shibing624/similarities

安装

pip install torch # conda install pytorch
pip install -U similarities

或者

git clone https://github.com/shibing624/similarities.git
cd similarities
pip install -e .

使用方法

1. 文本向量相似度计算

示例：examples/text_similarity_demo.py

from similarities import BertSimilarity
m = BertSimilarity(model_name_or_path="shibing624/text2vec-base-chinese")
r = m.similarity('如何更换花呗绑定银行卡', '花呗更改绑定银行卡')
print(f"similarity score: {float(r)}")  # similarity score: 0.855146050453186

• model_name_or_path：模型名称或者路径，默认会从HF model hub下载并使用中文语义匹配模型shibing624/text2vec-base-chinese，如果需要多语言，可以替换为shibing624/text2vec-base-multilingual模型，支持中、英、韩、日、德、意等多国语言

2. 文本向量搜索

在文档候选集中找与query最相似的文本，常用于QA场景的问句相似匹配、文本搜索等任务。

SemanticSearch精准搜索算法，Cos Similarity + topK 聚类检索，适合百万内数据集

示例：examples/text_semantic_search_demo.py

Annoy、Hnswlib等近似搜索算法，适合百万级数据集

示例：examples/fast_text_semantic_search_demo.py

Faiss高效向量检索，适合亿级数据集

• 文本转向量，建索引，批量检索，启动服务：examples/faiss_bert_search_server_demo.py

• 前端python调用：examples/faiss_bert_search_client_demo.py

3. 基于字面的文本相似度计算和文本搜索

支持同义词词林（Cilin）、知网Hownet、词向量（WordEmbedding）、Tfidf、SimHash、BM25等算法的相似度计算和字面匹配搜索，常用于文本匹配冷启动。

示例：examples/literal_text_semantic_search_demo.py

4. 图像相似度计算和图片搜索

支持CLIP、pHash、SIFT等算法的图像相似度计算和匹配搜索，中文CLIP模型支持图搜图、文搜图、还支持中英文图文互搜。

示例：examples/image_semantic_search_demo.py

Faiss高效向量检索，适合亿级数据集

• 图像转向量，建索引，批量检索，启动服务：examples/faiss_clip_search_server_demo.py

• 前端python调用：examples/faiss_clip_search_client_demo.py

• 前端gradio调用：examples/faiss_clip_search_gradio_demo.py

5. 聚类

通过社群发现（community_detection）算法可以在大规模数据集上执行聚类，寻找聚类簇（即相似的句子组）。

示例：examples/text_clustering_demo.py

6. 图文语义去重

通过同义句挖掘（paraphrase_mining_embeddings）算法可以从大量句子或文档集中挖掘出具有相似意义的句子对，可用于冗余图文检测，语义去重。

• 文本语义去重：examples/text_duplicates_demo.py
• 图片语义去重：examples/image_duplicates_demo.py

命令行模式（CLI）

• 支持批量获取文本向量、图像向量（embedding）
• 支持构建索引（index）
• 支持批量检索（filter）
• 支持启动服务（server）

代码：cli.py

> similarities -h                                    

名称
    similarities

用法
    similarities COMMAND

命令
    COMMAND 是以下之一：

     bert_embedding
       计算一系列句子的嵌入向量

     bert_index
       使用 autofaiss 从文本嵌入构建索引

     bert_filter
       bert 滤波器的入口点，用于批量搜索索引

     bert_server
       bert 搜索后端的主要入口点，启动服务器

     clip_embedding
       使用 CLIP 模型对文本和图像进行嵌入

     clip_index
       使用 autofaiss 从嵌入构建索引

     clip_filter
       CLIP 滤波器的入口点，用于批量搜索索引

     clip_server
       CLIP 搜索后端的主要入口点，启动服务器

运行：

pip install similarities -U
similarities clip_embedding -h

# 示例
cd examples
similarities clip_embedding data/toy_clip/

• bert_embedding等是二级命令，bert开头的是文本相关，clip开头的是图像相关。
• 各二级命令使用方法见similarities clip_embedding -h。
• 上面示例中data/toy_clip/是clip_embedding方法的input_dir参数，即输入文件目录（必填）。

联系方式

• 提问与建议：
• 邮件联系：xuming: xuming624@qq.com
• 微信联系：请加我微信号：xuming624，并备注“姓名-公司-NLP”，即可加入NLP交流群。

引用

如果你在研究中使用了similarities，请按如下格式引用：

APA:

Xu, M. Similarities: Compute similarity score for humans (Version 1.0.1) [Computer software]. https://github.com/shibing624/similarities

BibTeX:

@misc{Xu_Similarities_Compute_similarity,
  title={Similarities: similarity calculation and semantic search toolkit},
  author={Xu Ming},
  year={2022},
  howpublished={\url{https://github.com/shibing624/similarities}},
}

许可证

本项目采用 Apache License 2.0 许可协议，可免费用于商业用途。请在产品说明中附上similarities的链接及许可证信息。

贡献

目前项目代码仍较为粗糙，欢迎大家对代码进行改进并提交回本项目。在提交之前，请注意以下两点：

• 在tests目录下添加相应的单元测试。
• 使用python -m pytest运行所有单元测试，确保所有测试均通过。

确认无误后即可提交 Pull Request。

致谢

• A Simple but Tough-to-Beat Baseline for Sentence Embeddings[Sanjeev Arora 和 Yingyu Liang 及 Tengyu Ma，2017]
• https://github.com/liuhuanyong/SentenceSimilarity
• https://github.com/qwertyforce/image_search
• ImageHash - 官方 GitHub 仓库
• https://github.com/openai/CLIP
• https://github.com/OFA-Sys/Chinese-CLIP
• https://github.com/UKPLab/sentence-transformers
• https://github.com/rom1504/clip-retrieval

感谢这些优秀的工作！

Similarities 快速上手指南

Similarities 是一个功能强大的相似度计算与语义搜索工具包，支持文本和图片的向量化、相似度计算及大规模检索（文搜文、文搜图、图搜图）。基于 Python 开发，支持亿级数据高效检索。

1. 环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.5+ (推荐 3.8+)
• 前置依赖：
  • torch (PyTorch)：用于加载深度学习模型。
  • 网络连接：首次运行时会自动从 Hugging Face 下载预训练模型（如网络受限，建议配置镜像或手动下载模型至本地）。

2. 安装步骤

推荐使用 pip 进行安装。为确保依赖完整，请先安装 PyTorch，再安装 similarities。

方式一：pip 安装（推荐）

# 1. 安装 PyTorch (根据官网指引选择适合你环境的命令，或使用 conda)
pip install torch

# 2. 安装 similarities
pip install -U similarities

提示：如果下载速度慢，可添加国内镜像源参数，例如： pip install -U similarities -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：源码安装

git clone https://github.com/shibing624/similarities.git
cd similarities
pip install -e .

3. 基本使用

场景一：文本相似度计算

最简单的用法是计算两个句子的语义相似度。默认使用中文预训练模型。

from similarities import BertSimilarity

# 初始化模型（首次运行会自动下载 shibing624/text2vec-base-chinese）
m = BertSimilarity(model_name_or_path="shibing624/text2vec-base-chinese")

# 计算相似度
r = m.similarity('如何更换花呗绑定银行卡', '花呗更改绑定银行卡')

print(f"similarity score: {float(r)}")
# 输出示例：similarity score: 0.855146050453186

注：如需多语言支持，可将 model_name_or_path 替换为 shibing624/text2vec-base-multilingual。

场景二：图像/图文搜索 (CLIP)

支持图搜图、文搜图。以下示例展示如何使用 CLIP 模型提取特征并进行搜索（需确保已安装 torch 和 torchvision）。

from similarities import ClipSimilarity

# 初始化 CLIP 模型 (支持中文 CLIP 模型，如 OFA-Sys/chinese-clip-vit-huge-patch14)
m = ClipSimilarity(model_name_or_path="OFA-Sys/chinese-clip-vit-huge-patch14")

# 示例：计算图片与文本的相似度
# 需要准备图片路径和文本查询
score = m.similarity_query_image("一只可爱的猫", "data/cat.jpg") 
print(f"score: {score}")

场景三：命令行工具 (CLI)

工具包内置了命令行接口，适合批量处理向量提取、建索引和启动服务。

# 查看帮助
similarities -h

# 示例：批量提取图片向量 (输入目录为 data/toy_clip/)
similarities clip_embedding data/toy_clip/

# 示例：构建索引
similarities clip_index --embeddings_dir <embedding_output_dir>

# 示例：启动搜索服务
similarities clip_server

常用命令说明：

• bert_ 开头：处理文本任务（embedding, index, filter, server）。
• clip_ 开头：处理图像/图文任务（embedding, index, filter, server）。