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` (default)、`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 與網頁介面，並內建基準測試與閾值校準功能——全部不需要自行訓練模型。