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에 상주하므로 매우 큰 데이터셋은 배치 처리나 스트리밍이 필요할 수 있습니다.

추가 정보

패키지 – pip install semhash로 설치(PyPI 배지에서 현재 버전 확인).
소스 코드 – https://github.com/MinishLab/semhash
문서 및 예제 – README에는 텍스트, 이미지, 사용자 정의 인코더, Pandas 및 다양한 ANN 백엔드 사용에 대한 광범위한 코드 스니펫이 포함되어 있습니다.
커뮤니티 – 지원 및 토론을 위한 Discord 링크는 배지에 있습니다.
벤치마크 – 성능 수치는 benchmarks/README.md를 참조하세요(예: CPU에서 1.8M개의 텍스트 레코드를 약 74초 만에 처리).

요약

SemHash는 빠르고 멀티모달한 중복 제거 및 필터링 툴킷으로, 원시 데이터를 임베딩으로 변환하고 ANN 인덱스로 중복을 찾으며 결과를 검사하거나 재조정할 수 있게 해줍니다. 대규모 학습 코퍼스 정리, 데이터 누출 방지 및 대표 하위 집합 추출에 유용한, 의존성이 적은 경량 Python 패키지입니다.