MinishLab/semhash

什么是 SemHash？

SemHash 是一个 轻量级 Python 库，通过以下方式帮助您清理大型数据集合（文本、图像、音频或任何其他模态）：

移除重复项目（语义去重）
过滤离群值（剔除不符合数据集其余部分的项）
选择代表性样本（挑选能捕捉整体集合多样性的小型样本集）。

它的工作原理是将每条记录转换为向量嵌入（使用配套的 model2vec 库处理文本，或使用您提供的任何自定义编码器），然后通过 Vicinity（一个 ANN 库）执行快速相似度搜索。API 允许您对单个数据集进行操作，或比较两个数据集（例如，防止训练与测试数据泄露）。

为什么您需要它

速度 – 使用近似最近邻搜索，即使是数百万条记录也能在 CPU 上几秒钟内处理完毕。
多模态 – 开箱即用支持文本和图像；通过提供符合微型 encode 协议的编码器，可加入任何模态。
可解释性 – 去重后，您可以检查哪些项目被视为重复、查看相似度分数，并在不重新执行整个流程的情况下调整阈值。
灵活的数据格式 – 接受纯 Python 列表、字典、Pandas DataFrames 或 Hugging‑Face datasets 对象，并可处理多列记录（例如 QA 对）。

核心概念

概念	功能
Embedding	将原始数据（文本、图像等）转换为固定大小的数值向量。SemHash 默认使用 `model2vec` 处理文本，但您可以插入任何编码器（Sentence‑Transformers、CLIP、自定义视觉模型等）。
ANN backend	相似度搜索引擎。默认是 USearch（通过 Vicinity）以实现高召回率和速度；替代方案包括 FAISS 或简单的精确匹配后端。
SemHash instance	使用 `SemHash.from_records(...)`（或从预先计算的嵌入）创建。持有数据集以及所选的编码器/后端。
Operations	`self_deduplicate`、`deduplicate`、`self_filter_outliers`、`filter_outliers`、`self_find_representative`、`find_representative`。每个操作都会返回一个结果对象（`DeduplicationResult` 或 `FilterResult`）。
Result objects	提供 `.selected`（保留的记录）、`.filtered`（移除的记录）、统计数据（`duplicate_ratio` 等），以及辅助方法如 `get_least_similar_from_duplicates` 或 `rethreshold`。

快速入门示例（文本）

from datasets import load_dataset
from semhash import SemHash

texts = load_dataset("ag_news", split="train")["text"]
semhash = SemHash.from_records(records=texts)

# 1️⃣ 移除重复项目
clean = semhash.self_deduplicate().selected

# 2️⃣ 剔除离群值
clean = semhash.self_filter_outliers().selected

# 3️⃣ 挑选小型、多样化的子集
representative = semhash.self_find_representative().selected

一旦创建 SemHash 对象，这三个步骤都只需一行代码。

运作原理（高阶概述）

Embedding – 每条记录通过提供的编码器转换为稠密向量。
Indexing – 向量被插入到 Vicinity 的 ANN 索引中（默认是 USearch）。
Similarity search – 对于每个向量，检索其最近邻居。相似度阈值决定两个项目是否为重复或离群值。
Clustering – 重复项目被分组到簇中；保留最中心的项。
Representative selection – 贪婪的最远点算法挑选一个能最大化嵌入空间覆盖率的子集。

何时使用 SemHash

训练前的数据清理 – 移除可能导致模型偏差的近重复句子或图像。
泄露检测 – 确保您的测试集不包含与训练集过于相似的项目。
数据集摘要 – 创建一个小型、多样化的子集，用于快速原型设计或人工标注。
跨模态流程 – 任何可以嵌入项目的领域（音频、视频、代码）都可以使用自定义编码器进行去重。

限制与注意事项

质量取决于编码器 – 如果嵌入模型无法很好地捕捉语义，可能会遗漏重复项或出现误报。
阈值调整 – 默认相似度阈值适用于许多情况，但您可能需要进行调整；库提供了工具（rethreshold、get_least_similar_from_duplicates）来协助。
内存 – 虽然 ANN 减少了计算量，但完整的嵌入集仍存于 RAM 中；非常大的数据集可能需要批处理或流处理。

总结

SemHash 是一个快速、多模态的去重与过滤工具组，它将您的原始数据转换为嵌入，通过 ANN 索引寻找近重复项，并让您检查或重新调整结果。它对于清理大型训练语料库、防止数据泄露以及提取代表性子集非常有用，且是一个轻量级、依赖项少的 Python 包。