bikemazzell/tuonella-sift

# 🧹 Tuonella Sift ✨ 一款高性能、低内存占用的 CSV 去重工具，使用 Rust 构建，支持可选的 CUDA GPU 加速和高级性能优化。该工具以芬兰神话中的冥界 Tuonella 命名——在那里灵魂会被筛选和过滤——正如这款工具在海量数据集中筛选出唯一数据并去除重复项一样。 旨在处理海量数据集（百 GB 到 TB 级别），具备智能字段检测、外部排序、GPU 加速、并行处理和智能检查点等功能。 ## ✨ 特性 - **🗄️ 外部排序**：使用基于磁盘的排序处理超过可用内存的大型数据集 - **⚡ CUDA 加速**：提供可选的 GPU 加速，用于字符串规范化和处理 - **🧵 并行处理**：具有可配置线程池的多线程文件处理 - **📝 智能检查点**：支持从中断处恢复处理，最大程度减少数据丢失 - **🔍 跨文件去重**：高效去除多个输入文件中的重复项 - **💾 内存管理**：可配置的内存使用策略，支持自动溢出到磁盘 - **📈 高可扩展性**：线性复杂度 O(N log N)，确保最佳性能 ## 🔨 构建 ### 前置条件 - **🦀 Rust 1.70+** - 从 [rustup.rs](https://rustup.rs/) 安装 - **🧠 内存**：至少 8GB RAM（针对大型数据集建议 16-64GB） - **💽 存储**：充足的磁盘空间（约为输入数据大小的 2 倍） ### 可选的 CUDA 前置条件 - **🖥️ NVIDIA GPU**：计算能力 (Compute Capability) 3.5 或更高 - **🧰 CUDA Toolkit 11.0+** - 通过包管理器或 NVIDIA 网站安装 - **🚗 NVIDIA 驱动程序**（建议使用最新版本） ### 构建命令 ``` # 克隆 repository git clone https://github.com/bikemazzell/tuonella-sift cd tuonella-sift # Standard CPU build（如果检测到 CUDA toolkit，将 build 支持 GPU） ./build.sh ``` 构建脚本会自动检测 CUDA 的可用性，并在可能的情况下启用 GPU 加速。 ## 🚀 使用 ### 基本用法 ``` # 处理 directory 中的 CSV files ./tuonella-sift --input /path/to/csv/files --output /path/to/output.csv # 附带 verbose output ./tuonella-sift --input /path/to/csv/files --output /path/to/output.csv --verbose # 从中断处的 checkpoint 恢复 ./tuonella-sift --input /path/to/csv/files --output /path/to/output.csv --resume # 使用自定义 configuration ./tuonella-sift --input /path/to/csv/files --output /path/to/output.csv --config my-config.json ``` ### 命令行选项 - `--input `：包含 CSV 文件的输入目录（必填） - `--output `：去重结果的输出文件（必填） - `--config `：配置文件路径（默认：config.json） - `--resume`：如果可用，从检查点恢复 - `--verbose`：启用详细输出 - `--help`：显示帮助信息 ## ⚙️ 配置 该工具使用 JSON 配置文件（默认：`config.json`）： ``` { "memory_usage_percent": 50.0, "chunk_size_mb": 1024, "io_buffer_size_kb": 128, "processing_threads": 8, "enable_cuda": true, "cuda_batch_size": 200000, "cuda_memory_percent": 50.0, "temp_directory": "./temp", "enable_compression": false, "merge_buffer_size_kb": 512, "case_sensitive": false, "normalize_urls": true, "email_only_usernames": false, "verbose": true, "merge_progress_interval_seconds": 15 } ``` ### 主要配置选项 **💾 内存与性能** - `memory_usage_percent`：系统 RAM 使用百分比（10-90%，默认：50%） - `chunk_size_mb`：处理块大小，单位 MB（64-4096，默认：1024） - `processing_threads`：并行处理线程数（1-32，默认：8） **🎮 CUDA 设置** - `enable_cuda`：启用 GPU 加速（默认：true） - `cuda_batch_size`：GPU 批处理大小（1000-1000000，默认：200000） - `cuda_memory_percent`：GPU 显存使用百分比（10-90%，默认：50%） **🧹 去重设置** - `case_sensitive`：用户名是否区分大小写（默认：false） - `normalize_urls`：启用 URL 规范化（默认：true） - `email_only_usernames`：要求用户名必须是电子邮件地址（默认：false） **📁 I/O 设置** - `temp_directory`：临时文件目录（默认：“./temp”） - `io_buffer_size_kb`：I/O 缓冲区大小，单位 KB（默认：128） - `merge_buffer_size_kb`：合并缓冲区大小，单位 KB（默认：512） ## 💾 检查点与恢复 该工具为长时间运行的操作提供了强大的检查点功能： - **⏰ 自动保存**：在处理过程中自动保存检查点 - **🛑 优雅关闭**：按下 `Ctrl+C` 中断并保存检查点 - **🚀 恢复**：使用 `--resume` 标志从上次中断的地方继续 - **📊 进度跟踪**：显示完成百分比和统计数据 ``` # 如果处理被中断，请使用以下命令恢复： ./tuonella-sift --input /path/to/csv/files --output /path/to/output.csv --resume ``` ## 🧙‍♂️ 工作原理 ### 架构 **阶段 1：文件处理** - 使用线程池并行处理多个文件 - 在每个线程中使用 CUDA 进行电子邮件/URL 规范化 - 创建已排序的数据块，并进行块内去重 - 每个文件处理完成后保存进度检查点 **阶段 2：K路归并 (K-Way Merge)** - 使用优先级队列同时合并所有已排序的数据块 - 在合并期间应用最终去重 - 流式输出以防止内存膨胀 - 按数据块范围保存合并进度的检查点 ### 字段检测与去重 该工具使用智能模式识别自动识别包含用户名、密码和 URL 的 CSV 列。如果记录具有相同的规范化用户名和 URL，则将其视为重复项。URL 规范化会处理常见的变体（www、mobile、https/http），从而捕获语义上的重复项。 ## 📜 许可证 MIT License Copyright (c) 2024 Tuonella Sift Contributors 特此免费授予任何获得本软件副本和相关文档文件（“软件”）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、再授权和/或出售该软件副本，以及再授权被配发了本软件的人遵守上述义务，但须符合以下条件： 上述版权声明和本许可声明应包含在该软件的所有副本或实质成分中。 本软件按“原样”提供，不提供任何形式的担保，包括但不限于适销性、特定用途的适用性和非侵权性。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，由本软件或本软件的使用或其他交易引起、与之相关或与之相连。 ### 开发设置 1. Fork 本仓库 2. 克隆你 Fork 的仓库：`git clone ` 3. 从 [rustup.rs](https://rustup.rs/) 安装 Rust 1.70+ 4. 构建项目：`./build.sh` ### 进行更改 1. 创建一个功能分支：`git checkout -b feature-name` 2. 进行更改并添加测试 3. 运行测试：`cargo test --lib external_sort::tests` 4. 确保代码格式化：`cargo fmt` 5. 检查问题：`cargo clippy` ### 提交更改 1. 使用清晰的提交信息提交你的更改 2. 推送到你的 Fork 仓库：`git push origin feature-name` 3. 创建一个 pull request，包含以下内容： - 清晰的更改说明 - 测试结果 - 性能影响（如果适用） 如有问题或讨论，请先开一个 issue。

标签：CSV去重, CUDA, EB级数据处理, ETL工具, Homebrew安装, Rust, TB级数据, Vectored Exception Handling, 内存优化, 可视化界面, 外部排序, 大数据处理, 字符串处理, 并行处理, 开源, 数据清洗, 数据筛选, 数据预处理, 断点续传, 海量数据, 网络流量审计, 跨文件去重, 通知系统