# Intelligent-item-recognition

**Repository Path**: mktime/object-detect

## Basic Information

- **Project Name**: Intelligent-item-recognition
- **Description**: 基于AI大模型的拍照识别APP，拍张照片，即可识别物品（提取录入物品特征）。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/mktime/object-detect
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能物品管理系统

基于AI的物品识别与管理系统，用户拍摄或上传图片即可通过AI识别物品。

[在B站观看使用功能](https://www.bilibili.com/video/BV1qMfZBuEBW/)

## 功能简介

- **AI物品识别**：使用DINOv2模型提取图像特征，通过FAISS实现快速相似度搜索
- **物品录入**：支持拍照或从相册选择图片录入新物品
- **物品管理**：查看所有录入物品，支持添加多角度特征图片
- **相似度设置**：可调整识别相似度阈值，控制识别精度

## 功能演示

### APP首页

![APP首页](./screenshots/screenshots1.PNG)

### 拍照识别

![拍照识别](./screenshots/screenshots2.gif)

## 技术架构

### 前端
- Vue 3 + Composition API
- Vant 4 (移动端UI组件库)
- Tailwind CSS
- Vue Router + Pinia

### 后端
- Python 3.8+
- FastAPI
- SQLAlchemy + SQLite
- FAISS (向量搜索引擎)
- Transformers (DINOv2模型)

### AI模型
- **DINOv2-Small**: 提取384维图像特征向量
- **FAISS**: 高效的向量相似度搜索

## 项目结构

```
ObjectDetect/
├── backend/              # 后端代码
│   ├── app/
│   │   ├── main.py       # FastAPI入口
│   │   ├── config.py     # 配置
│   │   ├── database.py   # 数据库连接
│   │   ├── models.py     # 数据模型
│   │   ├── schemas.py    # Pydantic模型
│   │   ├── image_processor.py  # 图像处理
│   │   ├── faiss_index.py      # FAISS索引管理
│   │   └── routers/
│   │       ├── auth.py   # 认证接口
│   │       ├── items.py  # 物品接口
│   │       └── settings.py     # 设置接口
│   ├── requirements.txt
│   └── start.sh          # 启动脚本
├── frontend/             # 前端代码
│   ├── src/
│   │   ├── views/        # 页面组件
│   │   ├── stores/       # Pinia状态管理
│   │   ├── api/          # API接口
│   │   └── router/       # 路由配置
│   └── package.json
└── README.md
```

## 快速开始

### 环境要求
- Python 3.8+
- Node.js 16+
- 支持CUDA的GPU（可选，CPU也可运行但速度较慢）

### 1. 克隆项目

```bash
git clone <repository-url>
cd ObjectDetect
```

### 2. 启动后端

```bash
cd backend

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

或者使用启动脚本：
```bash
chmod +x start.sh
./start.sh
```

后端服务启动后：
- API地址: http://localhost:8000
- API文档: http://localhost:8000/docs

### 3. 启动前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端服务启动后：
- 访问地址: http://localhost:3000

### 4. 登录系统

默认账号：
- 用户名: `admin`
- 密码: `admin123`

## 使用指南

### 识别物品
1. 点击首页【识别特征】按钮
2. 拍照或从相册选择图片
3. 系统会自动识别并显示相似物品列表
4. 可点击【录入】将当前图片关联到现有物品
5. 或点击物品查看详情

### 录入物品
1. 点击首页【录入物品】按钮
2. 拍照或选择图片
3. 输入物品名称
4. 选择【录入并返回】或【继续录入】添加更多角度

### 查看物品
1. 点击首页【查看所有物品】按钮
2. 浏览所有录入的物品列表
3. 点击物品查看详情
4. 在详情页可添加更多特征图片或删除物品

### 设置相似度阈值
1. 点击首页右上角设置按钮
2. 调整相似度滑块（0-1之间）
3. 点击【保存设置】

## API接口

### 认证
- `POST /auth/login` - 用户登录
- `POST /auth/logout` - 用户退出
- `GET /auth/me` - 获取当前用户信息

### 物品
- `POST /items/create` - 创建新物品
- `POST /items/{id}/add-feature` - 添加特征图片
- `POST /items/recognize` - 识别物品
- `GET /items/list` - 获取物品列表
- `GET /items/{id}` - 获取物品详情
- `DELETE /items/{id}` - 删除物品

### 设置
- `GET /settings/similarity-threshold` - 获取相似度阈值
- `POST /settings/similarity-threshold` - 更新相似度阈值

## 技术细节

### 图像处理流程
1. 前端上传图片前预处理为512x512分辨率
2. 后端使用DINOv2-Small模型提取384维特征向量
3. 向量归一化后存入FAISS索引
4. 识别时使用余弦相似度计算匹配度

### 相似度计算
- 使用内积（归一化后等价于余弦相似度）
- 相似度范围：0-1
- 默认阈值：0.8
- 超过阈值的物品被认为是同一物品

### 数据存储
- SQLite: 存储用户信息、物品信息、特征关联
- FAISS: 存储高维向量索引
- 文件系统: 存储上传的图片

## 部署建议

### 生产环境
1. 使用HTTPS确保数据传输安全
2. 配置适当的CORS策略
3. 使用Gunicorn/Uvicorn部署后端
4. 使用Nginx作为反向代理
5. 定期备份SQLite数据库

### 性能优化
1. 使用GPU加速模型推理
2. 配置Redis缓存热门查询
3. 使用CDN加速静态资源
4. 定期重建FAISS索引

## 常见问题

### Q: 首次启动慢？
A: 首次启动需要下载DINOv2模型（约300MB），请确保网络畅通。

### Q: 识别精度低？
A: 尝试调整相似度阈值，或为目标物品添加更多角度的特征图片。

### Q: 支持哪些图片格式？
A: 支持JPEG、PNG、WebP等常见格式。

### Q: 数据存储在哪里？
A: 
- 数据库: `data/db/items.db`
- FAISS索引: `data/db/faiss.index`
- 上传图片: `data/uploads/`

## License

MIT License

## 技术栈参考

- [Vue 3](https://vuejs.org/)
- [Vant 4](https://vant-ui.github.io/vant/)
- [Tailwind CSS](https://tailwindcss.com/)
- [FastAPI](https://fastapi.tiangolo.com/)
- [FAISS](https://github.com/facebookresearch/faiss)
- [DINOv2](https://github.com/facebookresearch/dinov2)

## 交流学习
![APP首页](./screenshots/qrcode.jpg)