AlbumAI

AI 驱动的桌面相册管理工具 · AI-powered desktop photo album manager

---

💡 提示：从 GitHub Releases 下载的安装包已内嵌 Python 后端（CPU-only），无需手动配置 Python 环境，开箱即用。

---

安装 · Installation

方式一：下载安装包（推荐）

从 Releases 下载对应平台的安装包：

平台	文件	说明
Windows	AlbumAI.Setup.*.exe	NSIS 安装包
Windows	AlbumAI.*.exe	便携版
macOS	AlbumAI-*.dmg	DMG 安装包
Linux	AlbumAI-*.AppImage	AppImage

首次启动较慢（10-30 秒），因为后端解压和防病毒扫描。之后秒开。

方式二：从源码运行

# 1. 后端依赖
pip install -r backend/requirements.txt

# 2. 前端依赖
pnpm install

# 3. 启动开发服务器
pnpm dev          # web: http://localhost:3000

# 或启动桌面应用
pnpm electron:dev

打包构建

# 编译 Python 后端为独立 exe（自动建 venv + CPU-only torch）
python scripts/build-backend.py

# 打包安装包
pnpm package:win      # Windows
pnpm package:mac      # macOS
pnpm package:linux    # Linux

---

截图 · Screenshots

相册主页 · Library	人脸标注 · Face Labeling	人物管理 · People

---

功能 · Features

中文	English
文字搜图（CLIP 语义 + 描述文本 + 人名）	Text search (CLIP semantic + caption + person name)
以图搜图（上传/拍照，自动检测人脸可选）	Image search (upload/camera, optional face detection)
人脸搜索（上传图片选脸 / 已标注人物 / 未标注聚类）	Face search (pick face from upload / known person / unknown cluster)
中文图片描述（Florence-2 + 英译中）	Chinese captioning (Florence-2 + EN→ZH translation)
人脸检测 + 512 维特征提取 (InsightFace)	Face detection + 512-dim embedding (InsightFace)
人物管理：批量标注、聚类去重	Person management: batch label, cluster dedup
Lightbox 预览 + 人脸框叠加	Lightbox preview with face box overlays
批量操作：多选删除/移动	Batch operations: multi-select delete/move
Electron 桌面封装，自动启停 Python 后端	Electron desktop app, auto-manages Python backend

---

核心流程 · Core Flow

AI 处理管线 · Processing Pipeline

flowchart LR
  A[Upload] --> B{>5MB?}
  B -->|Yes| C[Resize 1920px]
  B -->|No| D[Save JPEG]
  C --> D
  D --> E[ThreadPool ×3]
  E --> F[CLIP Embed]
  E --> G[Florence-2 + EN→ZH]
  E --> H[InsightFace Detect]
  F --> I[(FAISS)]
  G --> K[(SQLite Caption)]
  H --> K[(SQLite Face)]

Loading

搜索流程 · Search

flowchart TD
  S[Search] --> T{Type}
  T -->|Text| C[CLIP + LIKE + Name]
  C --> R[Rank & Show]
  T -->|Image| U[Upload/Camera]
  U --> D[Detect Faces]
  D --> Q{Faces?}
  Q -->|Yes| P[Pick Face → Match]
  Q -->|No| V[CLIP Search]
  P --> R
  V --> R
  T -->|Person| L[Select Labeled/Unknown]
  L --> F[Face Descriptor → Euclid Dist]
  F --> R

Loading

---

技术栈 · Tech Stack

Layer	Tech
Frontend	Next.js 16 + React 19 + Tailwind v4 + shadcn/ui
Desktop	Electron 42 (contextIsolation)
Backend	FastAPI (Python async)
Database	SQLite + SQLAlchemy 2.0 async
Vector Search	FAISS (CPU, IndexFlatIP)
Text/Image Embedding	Chinese-CLIP ViT-B/16
Image Captioning	Florence-2 + MarianMT
Face Recognition	InsightFace buffalo_l

---

项目结构 · Structure

AlbumAI/
├── app/                  # Next.js pages
├── components/           # React components
│   ├── model-download-panel.tsx # AI model download manager
│   ├── model-status-banner.tsx  # Model status prompt banner
│   ├── processing-panel.tsx     # AI processing progress
│   ├── settings-dialog.tsx      # Settings with model management
│   └── ...                # Other UI components
├── lib/                  # Frontend lib
├── electron/             # Electron main process + preload
├── backend/              # Python backend
│   ├── api/              # REST endpoints
│   │   ├── models.py     # Model download & status management
│   │   ├── process.py    # AI processing pipeline
│   │   ├── photos.py     # Photo CRUD & batch upload
│   │   ├── search.py     # Text/image/face search
│   │   ├── faces.py      # Face detection & labeling
│   │   ├── people.py     # Person management
│   │   ├── groups.py     # Face cluster management
│   │   ├── captions.py   # Caption CRUD
│   │   ├── settings_api.py # Settings API
│   │   └── health.py     # Health check
│   ├── core/             # App config, DB init, FAISS index
│   ├── db/               # SQLAlchemy models + CRUD
│   └── models/           # AI model wrappers
│       ├── clip_engine.py
│       ├── caption_engine.py
│       └── face_engine.py
├── scripts/              # Build & utility scripts
│   ├── build-backend.py  # PyInstaller backend build
│   └── generate-icons.mjs
└── docs/                 # Screenshots

---

常见问题 · FAQ

安装包打开后一直显示"正在连接后端服务"

1. 按 F12 打开开发者工具 → Console 看错误信息
2. 检查 %APPDATA%\AlbumAI\logs\backend-err.log 日志文件
3. 如后端无法自动启动，可手动运行 resources/backend/albumai-backend.exe 后再打开主程序
4. 如看到 ERR_FILE_NOT_FOUND（前端 JS 加载失败），请重新下载最新安装包

AI 模型下载失败

• 模型从 HuggingFace 和 GitHub 下载，国内网络可能被屏蔽
• 可尝试开启代理后重试
• 点击"下载全部"按钮会自动重试

切换语言后图片描述还是中文

语言设置只影响新导入的照片。已生成的中文描述不会自动重新翻译。重新导入照片后会使用当前语言生成描述。

已导入的照片未触发 AI 处理

• 首次使用需要先下载 AI 模型
• 模型下载完成后会自动开始处理已导入的照片
• 如卡在"AI 处理中"，重启应用即可

---

---

Changelog

v0.1.20 (2026-06-17)

• Face matching: Switched from Euclidean distance to cosine similarity throughout the stack (backend + frontend). Threshold range updated to 0.5–0.99. Backend API returns similarity instead of distance.
• Thread safety: All AI engines (CLIP, Caption, Face) now use threading.Lock in their load() methods, with double-checked locking pattern for safe concurrent access.
• Process pipeline rewrite: process-all now uses asyncio.Lock to prevent concurrent execution, independent async sessions for saving results (avoids session-in-thread conflicts), and periodic FAISS index saves (every 50 photos).
• Bundled InsightFace: Models can be shipped inside the installer (scripts/download-insightface.py + PyInstaller --add-data). Skip download for bundled builds.
• Image compression: Client-side auto-compression (maybeCompress) resizes images >1024px before upload to reduce bandwidth and processing time.
• API retry: Retry logic with exponential backoff (up to 2 retries) for transient network failures. Server errors (4xx/5xx) and abort errors are not retried.
• Memory leak fixes: Proper URL.revokeObjectURL lifecycle management in FaceDetailDialog (useEffect cleanup) and FaceThumb (useRef for tracking current blob).
• People view: Replaced browser confirm() with shadcn ConfirmDialog component for delete person action.
• Electron static serving: main.js now tries exact path → path.html → dir/index.html → fallback to index.html. macOS activate event preserves the frontend port.
• Dev experience: New electron/dev-wait.js — waits for backend + Next.js readiness before launching Electron. pnpm dev launches all three processes concurrently (backend, frontend, Electron).
• CI/CD: Corepack-based pnpm setup, ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION env, disk space cleanup for Linux builds, bundled InsightFace download step.
• Settings: Auto-close dialog 1.5s after model download completes. Default caption max length 30.
• FAISS index: Thread-safe threading.Lock on all mutations. Reverse _photo_to_fid map for O(1) lookup instead of O(n) linear scan for removal.
• CORS 500 handler: Custom Starlette exception handler adds Access-Control-Allow-Origin: * to 500 responses.
• Eager model preloading: Backend preloads CLIP + Face + Caption models in background task at startup, so they're ready when user imports photos.
• Photo preview: Safe index clamping prevents out-of-bounds access when currentIndex > photos.length.
• Dead code: Removed orphaned const photo = photos[currentIndex] in PhotoPreview.

License

MIT © 2026 guorui999