ScalarForensic/ScalarForensic

# ScalarForensic 大规模图像向量索引工具，用于取证用途。使用两个互补的神经模型将图像嵌入 Qdrant 向量数据库，以支持相似性搜索和去重——专为证据室设计，用于查找完全相同的副本、编辑过的版本以及数万个文件中视觉相关的图像。 **→ [安装与设置指南](INSTALL.md)** **→ [适用于隔离环境的 Docker 捆绑包](INSTALL.md#docker-bundle-single-file-transfer)** **→ [性能评估](docs/performance.md)** ## 功能 ScalarForensic 使用两个互补的神经模型将图像目录索引到 Qdrant 向量数据库，并通过 Web UI 查询匹配结果。 ### 索引（CLI） ``` uv run sfn --dino --sscd ``` 递归扫描目录，对每张图像计算哈希值以跳过重复项，并将嵌入向量插入或更新到 Qdrant。一次运行即可完成两个模型的处理——图像仅读取和解码一次。 ### 查询（Web UI） ``` uv run sfn-web # → http://localhost:8080 ``` 上传一个或多个查询图像，选择搜索模式，并通过阈值和结果数量滑块探索结果。命中图像会根据需要从服务器文件系统中流式读取。 ## 搜索模式 | 模式 | 查找内容 | 模型 | |------|----------|------| | **Exact** | 字节级完全相同的文件（SHA-256 匹配） | — | | **Altered** | 被裁剪、重新着色或轻微修改的副本 | SSCD ResNet-50（Meta），512 维 | | **Semantic** | 相同场景、主题或视觉风格 | DINOv2 ViT-L（Meta），1024 维 | 如果尚未为对应集合建立索引，UI 中会自动禁用相关模式。所有三种模式可在单个查询中组合使用。 ## 特性 **支持的图像格式：** `.jpg`、`.jpeg`、`.png`、`.bmp`、`.tiff`、`.tif`、`.webp`、`.gif`、`.jp2`、`.ico`、`.psd`，以及通过可选依赖组支持的 `.heic`/`.heif`。 **去重模式**（由 `SFN_DUPLICATE_CHECK_MODE` 控制）： | 模式 | 行为 | |------|------| | `hash` | 跳过 SHA-256 已存在于集合中的图像（默认） | | `filepath` | 跳过绝对路径已存储的图像——对大文件更快 | | `both` | 如果哈希或路径任一已存在则跳过 | **EXIF 元数据提取**（`SFN_EXTRACT_EXIF=true`）：为每个索引点存储两个布尔字段——`exif`（是否存在任何 EXIF 数据）和 `exif_geo_data`（是否存在 GPS 坐标）。 **默认隔离/离线环境：**HuggingFace SDK 在运行时被阻止发起任何网络请求。仅允许与 Qdrant 和配置的远程嵌入端点建立连接。如需首次下载模型，请传入 `--allow-online`（或设置 `SFN_ALLOW_ONLINE=true`）；后续运行无需此选项。模型和 Python 轮子也可预先打包，以实现完全隔离的部署。详见 [INSTALL.md § 网络策略](INSTALL.md#network-policy) 和 [INSTALL.md § 离线部署](INSTALL.md#offline--airgapped-deployment)。 **GPU 加速：**同时支持 NVIDIA CUDA（默认）和 AMD ROCm，包括在 ROCm 6.4 上原生支持的 RDNA 4（RX 9070 / 9070 XT）。详见 [INSTALL.md § GPU 设置](INSTALL.md#gpu--hardware-acceleration)。 ## 快速开始 ``` git clone https://github.com/ScalarForensic/ScalarForensic cd ScalarForensic uv sync --group web cp .env.example .env # 启动 Qdrant docker run -p 6333:6333 qdrant/qdrant # 仅下载模型（需要互联网 — 下载后在 .env 中设置 SFN_MODEL_DINO=models/dinov2-large） uv run python scripts/download_models.py # 索引文件夹（默认离线 — 模型本地化后无需标志） uv run sfn --dino --sscd # 启动 Web UI uv run sfn-web # → http://localhost:8080 ``` 完整的设置说明、GPU 配置、离线部署和配置参考请参见 **[INSTALL.md](INSTALL.md)**。 ## 第三方许可证 捆绑资源及其许可证列在 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md)。所有许可证均与 GPL-3 兼容。

标签：CLIP, DINOv2, Docker 捆绑, Qdrant, ResNet-50, SSCD, TCP SYN 扫描, Web UI, 元数据去重, 元数据哈希, 内容基于图像检索, 去重, 可扩展向量搜索, 向量相似性搜索, 图像去重, 图像取证, 图像向量数据库, 大尺度图像索引, 安装与配置指南, 嵌入式推理, 性能评估, 批量索引, 数字取证, 文件系统流式读取, 法医取证, 流式响应, 相似度检索, 空气隔绝部署, 精确匹配, 结果数量控制, 自动化脚本, 证据管理, 语义搜索, 请求拦截, 跨模态检索, 逆向工具, 阈值滑动条, 零样本图像检索, 高性能索引