# faiss_dog_cat_question

**Repository Path**: YXY0216/faiss_dog_cat_question

## Basic Information

- **Project Name**: faiss_dog_cat_question
- **Description**: 本项目使用FAISS库实现了基于K近邻的图像分类器。该分类器可以使用CPU或GPU进行训练，并支持两种特征提取方法：flat和vgg。用户可以选择使用sklearn或faiss库实现K近邻算法。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 377
- **Created**: 2025-10-22
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 项目简介

基于 K 近邻（KNN）的猫狗二分类示例，提供两种特征提取方式（flat 与 vgg）以及两种 KNN 实现（sklearn 与 faiss）。

- KNN（faiss 版）使用 FAISS 的 IndexFlatL2 进行向量近邻检索。
- 预测采用多数投票；score 返回准确率。
- 数据首次处理会缓存特征到磁盘，加速后续运行。

已在 Windows + Python 3.12 环境验证运行（PowerShell）。

## 目录结构

```
faiss_dog_cat_question/
   FaissKNeighbors.py   # FAISS 版 KNN 实现
   train.py             # 训练/评估脚本（参数：-m/-f/-l）
   util.py              # 数据集读取与特征提取、缓存
   data/
      train/             # 训练数据（猫狗数据集，见下）
   readme.md
```

数据集命名要求（与 Kaggle Dogs vs Cats 相同）：

- cat.N.jpg / dog.N.jpg（如 cat.0.jpg、dog.1.jpg）
- 标签约定：dog → 1，其他（cat）→ 0

请将图片置于 `data/train/` 目录。

## 安装依赖（Windows/PowerShell）

以下依赖为最小集合，按所选特征方法可能不同：

- 核心：numpy、tqdm、opencv-python、scikit-learn
- FAISS（CPU 版）：faiss-cpu（Windows 推荐）
- 可选：imutils（用于列举图片，缺失时有本地回退）
- 仅 vgg 需要：tensorflow（含 keras）

示例（仅 flat 特征，无需 TensorFlow）：

```powershell
pip install numpy tqdm opencv-python scikit-learn faiss-cpu imutils
```

使用 vgg 特征时再安装：

```powershell
pip install tensorflow
```

说明：Windows 下通常只有 faiss-cpu 可直接安装；GPU 版（带 `StandardGpuResources`）一般需在 Linux + conda 环境安装。

## 运行方式

进入项目目录后运行（推荐从 flat 开始，速度更快）：

```powershell
Set-Location "C:\Users\<你的用户名>\Desktop\实验3-2\faiss_dog_cat_question"

# CPU + FLAT + sklearn（快速起步）
python .\train.py -m cpu -f flat -l sklearn

# 使用 FAISS（CPU 版）
python .\train.py -m cpu -f flat -l faiss

# 选择 VGG 特征（需安装 tensorflow）
python .\train.py -m cpu -f vgg -l faiss
```

参数说明：

- `-m, --mode`：cpu 或 gpu（Windows + faiss-cpu 使用 gpu 会自动降级为 cpu）
- `-f, --feature`：flat 或 vgg
   - flat：OpenCV 读灰度、32x32、拉平
   - vgg：VGG16(include_top=False, pooling=max)，需 tensorflow/keras
- `-l, --library`：sklearn 或 faiss

首次运行会读取全部图片并在项目目录缓存 `X.pkl`、`y.pkl`；后续复用缓存会显著加速。

注意：当前缓存文件未按特征方法区分。如果你切换了特征方法（flat ↔ vgg），请删除旧的 `X.pkl`/`y.pkl` 后再运行，以避免读取到不匹配的缓存。

## 常见问题（FAQ）

1) Windows 中文路径导致 OpenCV 读取失败？

- 代码已对 flat 分支采用 `np.fromfile + cv2.imdecode` 方案，兼容中文/特殊字符路径。

2) 指定 `-m gpu` 报错或无效？

- Windows 下 pip 安装的 `faiss-cpu` 不包含 GPU 接口。`train.py` 会检测不到 `StandardGpuResources` 时自动降级为 CPU。若需要 GPU，请使用 Linux + `faiss-gpu`（建议 conda 安装）。

3) 运行 vgg 提示找不到 TensorFlow？

- 仅使用 vgg 特征时才需要安装 `tensorflow`。flat 模式不依赖 TF。

4) 首次运行很慢？

- 首次会构建整个数据集特征并写入缓存。建议先用 flat + sklearn 验证流程，或减少数据量后再全量运行。

## 实现细节速览

- `FaissKNeighbors`
   - 索引：IndexFlatL2
   - 预测：k 近邻标签投票（np.bincount/argmax）
   - 评分：准确率 `(y_pred == y).mean()`
   - GPU：若提供 `res`（且可用）则迁移至 GPU，否则保持 CPU

- `util.createXY`
   - 列举图片（imutils.paths.list_images；缺失则使用本地回退）
   - flat：灰度→32x32→拉平
   - vgg：VGG16 + preprocess_input（延迟导入 TF，仅在使用 vgg 时导入）
   - 缓存：项目目录 `X.pkl`/`y.pkl`（与特征方法未区分）
   - 标签：文件名前缀 dog→1，否则→0

## 许可证与声明

仅用于课程与学习目的。

---

如需进一步优化（可选）：

- 按方法区分缓存文件（如 X_flat.pkl / X_vgg.pkl）
- 增加 `--limit` 小样本参数用于快速验证
- 增量式构建与断点续跑

## 个人信息

- 姓名：尹星宇
- 学号：202352320208
- 专业：智能科学与技术