# 照片识别整理工具

**Repository Path**: MakerLi/PhotoClassifierWithAI

## Basic Information

- **Project Name**: 照片识别整理工具
- **Description**: 调用图像模型整理照片的工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📸 PhotoClassifierWithAI

一个智能的照片整理工具，使用 AI 识别照片内容，自动重命名和分类存放。

## ✨ 功能特性

- **🏷️ AI 智能重命名** — 自动识别照片地点和内容，格式：`YYYYMMDD-地点 - 内容.jpg`
- **📂 智能分类** — 按地点（家/公司/自定义）、出行分组、内容类型自动分类
- **💾 自动备份** — 整理前自动备份原文件，安全无忧
- **📍 GPS 识别** — 支持从照片 EXIF 提取 GPS 坐标，精准定位
- **🤖 多模型支持** — 支持 Ollama 本地模型、OpenAI 及兼容 API
- **🖥️ 图形界面** — 简洁易用的界面，右侧内置使用说明
- **📸 格式支持** — JPG、PNG、GIF、BMP、WebP、**HEIC/HEIF**（iPhone 照片）

## ⚠️ 首次使用必读

**本工具需要配置 AI 图像识别模型才能使用重命名功能。**

- ✅ **分类功能**：可不依赖 AI，仅根据 GPS 和文件名分类
- ⚠️ **重命名功能**：必须配置 AI 模型（Ollama 或 OpenAI）

推荐新手先配置 Ollama 本地模型，免费且隐私安全。

## 🚀 下载与使用

### 方式一：直接使用 EXE（推荐，无需安装 Python）

1. **下载程序**
   - 从 [GitHub Releases](https://github.com/FunkyALi/PhotoClassifierWithAI/releases) 或 [Gitee Releases](https://gitee.com/funkyali/PhotoClassifierWithAI/releases) 下载最新版
   - 或自行打包（见下方"源码运行"）

2. **配置 AI 模型**（首次使用）
   - 双击运行 `PhotoClassifierWithAI.exe`
   - 点击"🤖 AI 模型配置"
   - 参考下方"AI 模型配置"章节完成设置

3. **开始整理**
   - 点击"📁 浏览"选择照片文件夹
   - 勾选需要的功能（重命名/分类/备份）
   - 点击"🚀 开始整理"

### 方式二：源码运行（需要 Python 环境）

1. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

2. **运行程序**
   ```bash
   python src/photo_classifier_gui.py
   ```

3. **打包 EXE**（可选）
   ```bash
   python build_exe.py
   ```

## ⚙️ AI 模型配置

### 方案 A：Ollama 本地模型（推荐，免费）

1. **安装 Ollama**
   - 访问 https://ollama.com 下载并安装
   - Windows 用户直接运行安装包

2. **拉取视觉模型**（打开命令行）
   ```bash
   ollama pull qwen3-vl:8b
   ```
   约 5GB，首次下载需要一些时间

3. **在程序中配置**
   - 运行程序后点击"🤖 AI 模型配置"
   - 点击"🔍 检测 Ollama"自动识别
   - 模型选择 `qwen3-vl:8b`
   - 保存配置

### 方案 B：OpenAI 兼容 API

- 提供商：选择 `openai` 或 `custom`
- Base URL: API 地址（如 `https://api.openai.com/v1`）
- API Key: 你的密钥
- 模型：如 `gpt-4-vision-preview`

## 📍 地点配置（分类功能需要）

点击"📍 地点管理"配置常用地点：

1. 输入地点名称（如"家"、"公司"、"父母家"）
2. 输入经纬度，或点击"📍 从照片获取 GPS"选择一张带 GPS 的照片自动提取
3. 设置识别半径（默认 500 米）

**默认预设地点**（示例坐标，建议修改）：
- 家：北京 (39.9042, 116.4074)
- 公司：上海 (31.2304, 121.4737)

## 📁 分类规则

| 类型 | 说明 | 存放文件夹 |
|------|------|-----------|
| 屏摄/截图 | 直接拍摄屏幕或系统截图 | `屏摄截图/` |
| 证件 | 身份证、银行卡等证件 | `证件/` |
| 家 | GPS 匹配到"家"的照片 | `家/` |
| 公司 | GPS 匹配到"公司"的照片 | `公司/` |
| 自定义地点 | GPS 匹配到其他配置地点 | `{地点名}/` |
| 出行 | 连续几天的异地照片（≥3 张） | `YYYY/YYYYMMDD_出行/` |
| 内容分类 | 未匹配地点的照片按内容分类 | `YYYY/{人物/美食/风景/...}/` |

## 📋 命名格式

重命名后的文件格式：
```
YYYYMMDD-地点 - 内容.jpg
示例：20260301-商场 - 两人喝咖啡.jpg
```

特殊标识：
- `[证件]` 开头：证件照片
- `[屏摄]` 开头：屏幕拍摄/截图

## 🔒 隐私说明

- 配置文件（`photo_classifier_config.json`）包含个人地点坐标和 API 密钥，**请勿上传到公开仓库**
- 项目已配置 `.gitignore` 自动排除配置文件
- 使用 Ollama 本地模型时，照片不会上传到云端

## 🛠️ 技术栈

- Python 3.x
- Pillow（图片处理）
- pillow-heif（HEIC/HEIF 支持）
- Tkinter（图形界面）
- Ollama / OpenAI（图像识别）
- PyInstaller（打包）

## ❓ 常见问题

**Q: 重命名功能报错"无法识别"？**  
A: 检查 Ollama 是否正常运行，模型是否已下载。在程序中点击"AI 模型配置"→"测试连接"。

**Q: 分类后照片没有按地点归类？**  
A: 检查照片是否包含 GPS 信息，并在"地点管理"中配置对应地点的坐标。

**Q: 处理速度太慢？**  
A: AI 识别需要时间，平均每张照片 5-15 秒。可使用本地 Ollama 或更快的模型。

**Q: EXE 文件被杀毒软件拦截？**  
A: 这是 PyInstaller 打包的常见误报。可将 EXE 添加到杀毒软件白名单，或使用源码运行。

## 📄 开源协议

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📬 联系方式

- 开发者：阿离 (Ali)
- 微信：FUNKYAL

## 🔗 项目地址

- **Gitee**: https://gitee.com/funkyali/PhotoClassifierWithAI
- **GitHub**: https://github.com/FunkyALi/PhotoClassifierWithAI