lynote-ai/ai-image-detector

Open-source CLI, API, web UI, and reproducible benchmarks for probabilistic AI-generated image detection.

AI Image Detector – What It Is

AI Image Detector 是一个开源的命令行 / Python 库，用来告诉你给定图片是由 AI 图像生成器创建的可能性。它封装了多个研究级检测器（默认使用 UniversalFakeDetect —— 基于 CLIP 的模型，仅带一个小线性头），也可以混入外部检测器，如 Nonescape 与 Sentry。该工具遵循“一次安装、一次指令”理念，类似 yt‑dlp 或 rembg 等实用程序。

Key Features (as described in the README)

Feature	What It Does
Multiple back‑ends	`univfd`（默认）、`sentry‑convnext‑small`、`ultra`（内部 + 外部检测器的集成）、`nonescape‑mini`、`hybrid`、`hf`（任意 Hugging Face 图像分类 checkpoint）。
CLI	`aidetect detect <path>` – 单张图片或递归文件夹，支持可选的 `--csv`、`--json`、`--backend` 参数。
Python API	`create_detector(backend, device)` → `predict_path(image_path)` 返回包含 `probability_ai` 与标签的结果对象。
Web UI	安装 `web` extra 后运行 `aidetect serve` 即可获得 Gradio 界面。
FastAPI server	安装 `api` extra 后运行 `aidetect api …` 获得简易 HTTP 端点（`/detect`）。
Benchmarking utilities	用于评估文件夹、Hugging Face 数据集或本地 Tiny‑GenImage shard 的命令；会输出 CSV/JSON，包含准确率、F1、ROC‑AUC、单图分数与阈值扫描。
Threshold calibration	内置支持在校准子集上优化决策阈值，以平衡准确率或 F1 等指标。
Reproducible reports	所有命令均可生成确定性的 JSON 报告，包含模型元数据、数据集信息与每张图的预测。
Lightweight install	纯 Python 包，支持 Python 3.10+，可选 extras 用于评估、HF 后端、API 或 UI。

How to Install & Run (quick start)

# Clone the repo and set up a virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e .               # core package
pip install -e '.[web]'        # optional Gradio UI (or .[api] for FastAPI)

Detect a single image with the default model:

aidetect detect image.jpg

Detect a whole folder and write a CSV report:

aidetect detect ./images --csv report.csv

Run the web UI:

aidetect serve   # then open http://localhost:7860

What the Output Means

probability_ai – 一个 [0, 1] 之间的浮点数，表示模型估计图像为 AI 生成的概率。
label – 默认规则为 probability_ai >= 0.5 → ai，否则为 human。
接近 0.45‑0.55 的分数属于 弱证据；README 建议在关键决策时检查多个后端。

Benchmarks & Performance (as reported)

小型 3 图检查的准确率在 33 %（UnivFD）到 67 %（其他大多数后端）之间。
在 200 图校准的 Tiny‑GenImage 子集上，UnivFD 经过阈值调优后达到 76 % 准确率，Hybrid 组合约为 67 %。
最强配置 ultra（Hybrid‑plus + Sentry）在 400 图测试集上取得 ≈ 86 % 准确率 / 0.86 平衡准确率 / 0.85 F1 / 0.92 ROC‑AUC。
性能随生成器不同而变化，例如 Midjourney 与真实图像的区分约 84 % 准确率，而旧模型如 VQDM 大约 78 %。

Limitations (explicitly listed)

没有检测器能够普遍适用——新生成器、重度重新压缩、截图、裁剪、放大或对抗性编辑都可能导致检测失效。
工具仅提供整图的可能性，不定位被编辑的区域。
基准测试为本地、小规模，若数据分布不同，可能会高估实际可靠性。

When to Use Which Backend

Backend	When to Pick It
`univfd`	想要最简单、最小依赖的基线。
`sentry‑convnext‑small`	需要单一强大的外部检测器且不想使用集成。
`ultra`	想要开箱即用的最高实用准确率（内部 + 外部集成）。
`nonescape‑mini`	作为额外信号使用；可在集成中加入。
`hf`	想测试自定义的 Hugging Face 图像分类 checkpoint。
`hybrid` / `hybrid‑plus`	想将 UnivFD 与 HF 分类器混合（可调权重）。

Citation

如果在研究中使用此工具，请按照 README 所示引用原始 UniversalFakeDetect 论文（CVPR 2023）。

Bottom Line

AI Image Detector 是一个实用且文档完整的工具，用于估计图像的合成可能性。它整合了多个最先进的检测器，提供简易的 CLI、API 与网页界面，并内置基准测试与阈值校准功能——全部无需自行训练模型。