# base_dedupe

**Repository Path**: haobingwen/dedupe_code

## Basic Information

- **Project Name**: base_dedupe
- **Description**: 支持多种文本去重算法（MinHash+LSH、SimHash、MD5、精确匹配）的高效 Web 应用程序，适用于中大规模文本数据处理。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能数据去重工具

支持多种文本去重算法（MinHash+LSH、SimHash、MD5、精确匹配）的高效 Web 应用程序，适用于中大规模文本数据处理。

## 功能特性

- 🚀 **高效去重**: 提供 MinHash+LSH、SimHash、MD5、精确匹配多种算法
- 🌐 **Web界面**: 友好的Web界面，支持拖拽上传和实时进度监控
- 📊 **详细统计**: 提供完整的处理统计信息，包括重复率、相似对等
- ⚙️ **参数可调**: 各算法可配置（MinHash 的阈值/签名；SimHash 的位数/汉明距离阈值等）
- 📁 **多格式输出**: 生成去重结果、过滤数据和相似对详情文件
- 🛑 **可控处理**: 支持手动停止处理过程

## 技术架构

### 核心算法
- **MinHash + LSH**: 近似 Jaccard 相似度 + 分桶召回相似候选
- **SimHash**: 基于局部敏感哈希的签名，使用“最大汉明距离”阈值判定相似
- **MD5**: 精确去重或滚动哈希近似去重（可选）
- **Exact**: 精确文本匹配
- **Union-Find (并查集)**: 用于候选合并与去重分组

### 主要组件
- **前端**: HTML + Bootstrap + JavaScript
- **后端**: Flask Web框架
- **算法**: Python实现的核心去重逻辑

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 1. 启动应用

```bash
python app.py
```

应用将在 `http://localhost:5000` 启动。

页面入口：
- 去重页面：`http://localhost:5000/dedupe`
- 相似度可视化：`http://localhost:5000/visualize`
- 帮助页：`http://localhost:5000/help`
- 示例下载：`http://localhost:5000/samples/dedupe_input_sample.jsonl`

### 2. 使用Web界面

1. **上传文件**: 拖拽或选择JSONL格式的文件
2. **选择算法与设置参数**:
   - 算法：MinHash + LSH / SimHash / MD5 / 精确匹配
   - 统一参数：最小文本长度（默认 50）
   - MinHash 参数：相似度阈值、N-gram 大小、band_size、signature_len
   - SimHash 参数：bits（64/128）、max_hamming_distance、tokenizer（word/char）、ngram_n（当 tokenizer=char 时）
   - MD5 参数：大小写敏感、去空白、Unicode 标准化、哈希长度、是否滚动哈希、窗口大小
   - 精确匹配参数：大小写敏感、去空白
3. **开始处理**: 点击"开始去重处理"按钮
4. **监控进度**: 实时查看处理进度和阶段信息
5. **下载结果**: 处理完成后下载去重结果文件
6. **结果分析与可视化**:
   - 可一键把本次相似对打开到可视化页面

### 3. 输入文件格式

输入文件应为JSONL格式，每行包含一个JSON对象，必须包含`text`字段：

```json
{"text": "这是第一条文本内容", "id": 1, "metadata": {...}}
{"text": "这是第二条文本内容", "id": 2, "metadata": {...}}
```

### 4. 输出文件

处理完成后会生成三个文件：

- **去重结果文件**: 包含去重后的数据
- **过滤数据文件**: 包含因长度或多样性不足被过滤的文本
- **相似对详情文件**: 包含检测到的相似文档对及其相似度


## 参数说明

### 通用
- 最小文本长度：过滤长度过短的文本（默认 50）

### MinHash + LSH
- 相似度阈值：0.1 - 1.0（默认 0.8），越高越严格
- N-gram 大小：2 - 10（默认 3）
- band_size：1 - 20（默认 3）
- signature_len：50 - 500（默认 100）

### SimHash
- bits：32/64/128（默认 64）
- max_hamming_distance：0 - 16（默认 3）
- tokenizer：word/char（默认 word）
- ngram_n：2 - 10（默认 3，当 tokenizer=char 时生效）
- 相似度换算：similarity ≈ 1 − (hamming_distance / bits)
   - 例：64 位且 d=3 ≈ 95.3% 相似

### MD5
- case_sensitive：是否大小写敏感
- strip_whitespace：是否去首尾空白
- normalize_unicode：是否标准化 Unicode
- hash_length：1 - 16（默认 16）
- use_rolling_hash：是否启用滚动哈希（近似）
- window_size：10 - 1000（默认 50）

### 精确匹配（Exact）
- case_sensitive：是否大小写敏感
- strip_whitespace：是否去首尾空白

## 项目结构

```
.
├── app.py                          # Flask应用主文件
├── dedup_mul_union_with_progress.py # 历史工具（保留 filter_len 等兼容）
├── dedup_mul_union.py              # 历史工具
├── requirements.txt                # Python依赖
├── README.md                       # 项目说明
├── src/
│   ├── base_deduper.py            # 去重算法基类与方法注册表
│   ├── dedup_factory.py           # 工厂：创建/校验算法实例
│   ├── dedupunion.py              # 并查集
│   ├── minhash_deduper.py         # MinHash+LSH 实现
│   ├── simhash_deduper.py         # SimHash 实现（新增）
│   ├── md5_deduper.py             # MD5 实现（支持滚动哈希）
│   └── exact_deduper.py           # 精确匹配实现
├── templates/
│   └── index.html                 # 去重处理页面模板
├── data/                          # 测试/示例数据集
│   ├── test_data.jsonl
│   ├── large_test_data.jsonl
│   ├── dedupe_input_sample.jsonl
│   └── similarity_pairs_sample.jsonl
└── test_*.py                      # 算法级测试脚本
```

## 核心算法流程（MinHash 示例）

1. **数据读取**: 读取JSONL文件，提取文本内容
2. **数据过滤**: 过滤长度不足或字符多样性不足的文本
3. **特征提取**: 使用n-gram和MinHash生成文档签名
4. **LSH分桶**: 使用局部敏感哈希将相似文档分到同一桶中
5. **相似度计算**: 在桶内计算文档间的 Jaccard 相似度
6. **去重处理**: 使用并查集合并相似文档，保留代表文档
7. **结果输出**: 生成去重后的数据和统计信息

## 性能优化

- **分批处理**: 避免内存爆炸，支持大规模数据
- **延迟计算**: 按需计算n-gram和MinHash签名
- **内存监控**: 实时监控内存使用情况
- **进度回调**: 支持实时进度更新

## 接口与测试

### Web 接口（/dedupe/upload）
表单字段（multipart/form-data）：
- file：JSONL 文件（每行一个 JSON 对象，需含 text 字段）
- dedup_method：minhash | simhash | md5 | exact
- min_length：整数（默认 50）

按算法附加字段：
- minhash：sim_threshold, ngram_n, band_size, signature_len
- simhash：bits, max_hamming_distance, tokenizer(=word|char), ngram_n（当 tokenizer=char 时）
- md5：case_sensitive, strip_whitespace, normalize_unicode, hash_length, use_rolling_hash, window_size
- exact：case_sensitive, strip_whitespace

可选 cURL 示例（在运行服务后）：

```bash
curl -F "file=@data/test_data.jsonl" \
   -F "dedup_method=simhash" \
   -F "bits=64" \
   -F "max_hamming_distance=3" \
   -F "tokenizer=word" \
   -F "min_length=50" \
   http://localhost:5000/dedupe/upload
```

### 其它常用接口
- 去重任务状态：`GET /dedupe/status/<task_id>`
- 停止任务：`POST /dedupe/stop/<task_id>`
- 下载结果：`GET /dedupe/download/<task_id>/<file_type>`（`file_type` 为 `result`/`filtered`/`pairs`）
- 相似对摘要：`GET /dedupe/pairs_summary/<task_id>`
- 去重结果一键进入可视化：`GET /visualize/from_task/<task_id>`
- 帮助页：`GET /help`
- 示例下载：`GET /samples/<filename>`

项目包含多个测试文件：

```bash
# 运行算法级测试脚本
python test_md5_deduper.py
python test_simhash_deduper.py
```

## 注意事项

1. 确保输入文件为UTF-8编码
2. 处理大文件时请确保有足够的内存
3. MinHash 的相似度阈值与 SimHash 的“最大汉明距离阈值”含义不同；SimHash 可用公式 similarity ≈ 1 − d/bits 近似换算
4. 参数设置会影响处理时间和去重效果

## 许可证

本项目仅供学习和研究使用。