swatchion/simhash

A PHP implementation of SimHash algorithm for fast document similarity detection

v1.0.0 2025-05-28 05:35 UTC

Requires

• php: >=8.0
• ext-mbstring: *

Requires (Dev)

• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^9.0|^10.0

MIT

• Swatchion

• text
• document
• hash
• SimHash
• comparison
• similarity

README

一个高效的 PHP 8.0+ SimHash 算法实现库，用于快速文档相似性检测和去重。

功能特点

• 🚀 高性能的 SimHash 算法实现
• 📊 支持文本相似度计算和比较
• 🔧 灵活的配置选项（哈希位数、K-shingles）
• 🌍 支持中文和多语言文本处理
• 📦 标准 Composer 包，易于集成
• ✅ 完整的单元测试覆盖
• 📖 详细的文档和示例

安装

使用 Composer 安装：

composer require swatchion/simhash

快速开始

基本使用

<?php
require_once 'vendor/autoload.php';

use Swatchion\SimHash\SimHashFactory;

// 快速相似度检查
$text1 = "这是一个测试文本";
$text2 = "这是一个测试文档";

$similarity = SimHashFactory::similarity($text1, $text2);
echo "相似度: {$similarity}%";

// 检查是否相似（默认阈值85%）
$isSimilar = SimHashFactory::isSimilar($text1, $text2);
echo $isSimilar ? "相似" : "不相似";

高级使用

<?php
use Swatchion\SimHash\SimHash;

// 创建自定义配置的SimHash实例
$simHash = new SimHash(64, 2); // 64位哈希，2-shingles

// 生成哈希值
$hash1 = $simHash->hash($text1);
$hash2 = $simHash->hash($text2);

// 计算汉明距离
$distance = $simHash->hammingDistance($hash1, $hash2);

// 转换为十六进制
$hexHash = $simHash->toHex($hash1);

API 参考

SimHash 类

构造函数

public function __construct(int $hashBits = 64, int $kShingles = 2)

主要方法

• hash(string $text): string - 生成文本的SimHash值
• similarity(string $text1, string $text2): float - 计算两个文本的相似度百分比
• isSimilar(string $text1, string $text2, float $threshold = 85.0): bool - 判断两个文本是否相似
• hammingDistance(string $hash1, string $hash2): int - 计算两个哈希值的汉明距离
• toHex(string $binaryHash): string - 转换为十六进制
• fromHex(string $hexHash): string - 从十六进制转换回二进制

SimHashFactory 类

便捷的静态方法：

• SimHashFactory::create(): SimHash - 创建默认实例
• SimHashFactory::similarity(string $text1, string $text2): float - 快速相似度计算
• SimHashFactory::isSimilar(string $text1, string $text2, float $threshold = 85.0): bool - 快速相似性判断

算法原理

SimHash 是一种局部敏感哈希算法，具有以下特点：

1. 相似文档生成相似的哈希值
2. 通过汉明距离快速比较相似性
3. 适合大规模文档去重和相似性检测

性能特点

• 时间复杂度: O(n)，其中 n 是文本长度
• 空间复杂度: O(1)
• 支持大规模文档处理
• 内存占用低

开发

运行测试

composer test

代码分析

composer analyse

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！