# retrieval — 图片名称检索平台

基于**图片名称**的三路检索并排对比,给对接业务做检索选型测试。

- **① BM25** —— jieba 分词 + rank_bm25(认字面/关键词)
- **② 向量** —— 本地 `BAAI/bge-m3`(1024 维,认语义;有 CUDA 走 GPU)
- **③ RRF 融合** —— 按排名融合两路:`Σ 1/(k + rank)`,k 默认 60(只看名次,绕开分数量纲不可比)

> 语义查询是向量的强项:查"碳酸饮料"能召回"可乐/雪碧"(字面零重叠),BM25 则无结果。

## 跑
```
run.bat            # 或 pip install -r requirements.txt && python server.py
```
- **图片目录**:默认读 **`<仓库>/crawler/images`**;想指别处 → 启动前 `set IMAGE_DIR=<绝对路径>`。
- 启动即扫描该目录、自动建索引;**首次**下 BGE-M3 ~2.3G(走 hf-mirror 镜像),之后约 25s 加载。
- 绑 `0.0.0.0`,控制台打印**局域网地址**;同事同网打开直接搜,无需选文件夹。防火墙放行 8799 入站。

## 接口
- `GET /api/status` — 建索引进度(`phase`: bm25/loadmodel/embedding、`device`、图片/名称数)
- `GET /api/search?q=&topk=&rrf_k=&w_bm25=&w_vec=` — 返回 `{bm25[], vector[], fusion[]}`,每条含图片文件名 + 在另两路的命中名次
- `GET /images/<文件名>` — 服务器直出图片(局域网里显示图靠它)

## 文件
| 文件 | 作用 |
| --- | --- |
| `server.py` | FastAPI:扫描目录 / 启动自动建索引 / status / search + serve 图片与前端 |
| `embed_local.py` | **本地 BGE-M3 向量**(GPU 自适应、落盘缓存;内含 HF 镜像/代理/torch 版本等环境坑处理) |
| `embed.py` | (备用)千问 DashScope 云端向量,含直连/自适应限速 |
| `bm25.py` / `fuse.py` | 中文 BM25(jieba + 补单字) / RRF 融合 |
| `static/` | 前端单页(纯搜索页,轮询 status 显示建索引进度) |

## 依赖 / 环境
`sentence-transformers`(+ torch)。检测到 CUDA 自动用 GPU;向量缓存落 `cache/`,模型落 `hf_home/`(均不进 git)。
`embed_local.py` 已处理:走 hf-mirror 镜像、绕系统代理直连、`HF_HUB_DISABLE_XET=1`、绕过 transformers 对 torch<2.6 加载 .bin 的限制。