# search-images

**Repository Path**: withthesea/search-images

## Basic Information

- **Project Name**: search-images
- **Description**: 搜图
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 溯图 · 精准以图搜源

宁可慢一点，也要准一点。上传图片后，后台多源持续深挖；只有交叉验证通过，才交付出处。

## 架构

| 目录 | 作用 |
|------|------|
| `web/` | Next.js：上传、任务详情、2s 轮询 |
| `worker/` | Python：感知哈希、多源适配器、交叉验证、指数退避 |
| `data/` | SQLite（`data/db/souto.db`）与上传原图 |

两端共享同一 SQLite。Worker 轮询 `queued` / `still_searching`，未达置信阈值会一直找下去。

**本地已确认库：** 每次交叉验证通过后，把 pHash/dHash + 出处写入 `local_origins`。下次再遇到相同/极近图片，先查本地库，可秒级确认，无需再跑外网。

## 快速启动

### 1. 环境变量

```bash
cp .env.example .env
```

默认 `ENABLE_MOCK_ADAPTER=false`，只展示真实查询结果。本地演示退避基数为 5 秒；生产请改为 60+。

### 2. Web

```bash
cd web
npm install
npm run dev
```

打开 http://localhost:3000

### 3. Worker

```bash
cd worker
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.py
```

健康检查：http://127.0.0.1:8091/health

## 免费优先方案（推荐起步）

**不申请任何 Key**，只靠公开站点：

| 源 | 费用 | 说明 |
|----|------|------|
| IQDB | 免费公开查询 | 已内置，无 Key |
| ascii2d | 免费优先 | 已内置，无 Key |
| Trace.moe | 免费优先 | 番剧截图场景，无 Key |
| SauceNAO / Bing / TinEye | 要注册或付费 | Key 留空即不会调用 |

配置：

```env
SAUCENAO_API_KEY=
BING_VISUAL_SEARCH_KEY=
TINEYE_API_KEY=
TINEYE_API_SECRET=
ENABLE_MOCK_ADAPTER=false
```

改完后重启 Worker。注意：公开站点可能限流或改版，适合个人/小流量；要稳定海量检索只能自建图库索引或买商业 API。

## API Key（可选，非免费保障）

| 变量 | 说明 |
|------|------|
| `SAUCENAO_API_KEY` | SauceNAO（有免费额度，非无限） |
| `BING_VISUAL_SEARCH_KEY` | 旧 Bing API 已退役，不再启用 |
| `TINEYE_API_KEY` / `TINEYE_API_SECRET` | TinEye（商用付费） |
| `CONFIDENCE_THRESHOLD` | 默认 `0.85` |
| `BASE_BACKOFF_SECONDS` | 默认演示 `5`，生产建议 `60` |
| `ENABLE_MOCK_ADAPTER` | 演示用；免费优先真搜请 `false` |
| `LOCAL_INDEX_ENABLED` | 本地已确认库，默认 `true` |
| `LOCAL_PHASH_MAX_DISTANCE` | pHash 汉明距离阈值，默认 `8` |
| `ADAPTER_TIMEOUT_SECONDS` | 单源超时，默认 `35` |
| `EMPTY_ROUNDS_BEFORE_PAUSE` | 连续空结果后暂停为「暂时未找到」 |
| `MAX_ATTEMPTS` | 最大检索轮次，默认 `12` |
| `REVERIFY_ENABLED` | 候选缩略图二次哈希核验 |

## 精准策略

1. 提取 pHash / dHash  
2. 多源检索；第 2+ 轮追加裁边 / 对比度变体（仅用于检索，不改用户原图）  
3. URL 归一化聚合：高相似度、多源交叉、作者页、时间线索  
4. 分数 ≥ 阈值 → `found` + 证据链；否则 `still_searching` 并退避重试  

## 状态机

`queued` → `analyzing` → `searching` → `verifying` → `found`  
未达标 → `still_searching` → 到期再检索。任务页可取消。


## 扩大覆盖（2026-10）

任务详情提供 Google Lens、Yandex、必应、百度、SauceNAO、TinEye 网页入口，需要在外站手动上传原图，结果不自动回传。可用水印/台词/用户名组合站点限制在 Google、必应和百度查询。自动图库仍以插画/番剧为主，不能保证覆盖全网；公开服务可能限流、验证码或不可达。

修复：默认展示弱候选；对比度变体轮换实际参与检索；IQDB 同查 2D/3D；ascii2d 保留颜色与特征两组结果并读取作品链接；请求失败写入记录；URL 保留帖子 ID 查询参数，避免不同帖子错误合并。ascii2d 不再伪造相似度。

Bing Search API 已于 2025-08-11 退役，移除自动调用，保留网页入口。新依赖需运行 `worker/.venv/Scripts/python -m pip install -r worker/requirements.txt`，然后重启 Worker 和 Web。

## 综合引擎自动搜索（2026-10-08）

通过 PicImageSearch 3.12.11（https://github.com/kitUIN/PicImageSearch）尝试 Yandex、百度、Google Lens、必应网页搜索，无需付费 API Key。本机实际图片测试中，Yandex 和百度各返回 30 条候选；Lens、必应仍有页面解析或访问限制，不保证可用。结果页链接保留在检索记录里，供手动复查。候选不代表同图或原出处，不伪造来源未提供的相似度。百度同图候选优先保留；缩略图检查四路并发且单项总超时 12 秒。