Project Muse 是一个现代化的 B/S 架构视觉资产管理系统，定位于 AIGC 生产力的上游基础设施，致力于填补"图片收藏"与"模型训练"之间的巨大鸿沟。
系统集成了 WD14 Tagger（自动图片打标）和 CLIP（语义向量化）等 AI 模型，结合 LLM 驱动的对话式检索，为创作者提供从素材采集、智能整理到数据集输出的全链路解决方案。
- 🤖 自动图片打标: 使用 WD14 Tagger 模型自动生成 Danbooru 风格标签，无需手动标注
- 🔍 混合检索系统: 支持 SQL 标签搜索（精确筛选）与 CLIP 向量搜索（语义检索）的混合查询
- 📦 LoRA 数据集导出: 提供交互式标签编辑和 Kohya_ss 标准格式导出功能
- 📱 PWA 多端支持: 基于 PWA 技术，支持桌面端和移动端访问
- 💬 对话式检索: 集成 LLM（Deepseek），支持自然语言图像搜索
| 领域 | 技术选型 | 版本/规范 |
|---|---|---|
| 前端 (Frontend) | React 19 + TypeScript | Vite, Tailwind CSS, Shadcn/ui, PWA |
| 后端 (Backend) | Python FastAPI | Pydantic v2, SQLAlchemy 2.0 (AsyncIO) |
| 异步计算 (Worker) | Celery + ONNX Runtime | Redis (Broker), ONNX Runtime (Inference) |
| 元数据存储 | MySQL 8.0 | InnoDB 引擎, JSON 类型支持 |
| 向量存储 | Qdrant | HNSW 索引, Cosine 距离 |
| 对象存储 | MinIO | S3 兼容协议 |
| 基础设施 | Docker Compose | Nginx (Gateway), Nvidia Container Toolkit |
- Docker & Docker Compose (必需)
- Node.js 18+ 和 pnpm (仅前端开发需要)
- NVIDIA GPU (可选，用于加速 AI 推理，CPU 模式也可运行)
git clone <repository-url>
cd Muse在 deploy 目录下创建 .env 文件：
cd deploy
cp .env.example .env # 如果存在示例文件
# 或手动创建 .env 文件必需的环境变量：
# 数据库配置
MYSQL_DATABASE=muse_db
MYSQL_USER=muse_user
MYSQL_PASSWORD=muse_password
MYSQL_ROOT_PASSWORD=root_password
MYSQL_EXTERNAL_PORT=3306
# MinIO 对象存储
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_EXTERNAL_PORT_API=9000
MINIO_EXTERNAL_PORT_UI=9001
# Redis 消息队列
REDIS_EXTERNAL_PORT=6379
# Qdrant 向量数据库
QDRANT_EXTERNAL_PORT_API=6333
QDRANT_EXTERNAL_PORT_GRPC=6334
# 后端服务配置
SECRET_KEY=your-secret-key-here # 生产环境请使用强随机字符串
CORS_ORIGINS=http://localhost:5173,10.x.x.x # 允许的前端地址
# LLM API 配置（用于对话式检索功能）
DEEPSEEK_API_KEY=your-deepseek-api-key # 可选，用于"与我对话"功能
DEEPSEEK_BASE_URL=https://api.deepseek.com
# 管理员账户（首次启动时自动创建）
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
ADMIN_EMAIL=admin@example.com注意:
SECRET_KEY用于 JWT 令牌签名，生产环境请务必修改为强随机字符串DEEPSEEK_API_KEY为可选配置，不配置时"与我对话"功能将不可用CORS_ORIGINS支持特殊值10.x.x.x允许所有 10.x.x.x IP 地址访问
AI 模型文件需要单独下载，存储在 deploy/models 目录：
cd deploy
# 安装依赖
pip install "huggingface_hub[hf_transfer]"
# 下载模型
python download_models.py这将下载以下模型：
- WD14 Tagger: 用于自动图片打标（Danbooru 风格标签）
- CLIP ViT-L/14: 用于图片和文本的向量化（语义搜索）
提示: 模型文件较大（约 2-3 GB），首次下载可能需要较长时间。建议使用
hf_transfer加速下载。
cd deploy
docker-compose up -d这将启动以下服务：
- 基础设施: MySQL, MinIO, Redis, Qdrant
- 后端 API: FastAPI (端口 8000)
- AI Worker: Celery Worker（处理图片 AI 识别）
检查所有服务是否正常运行：
docker-compose ps访问以下地址验证：
- 后端 API 文档: http://localhost:8000/docs
- MinIO 控制台: http://localhost:9001 (账号/密码:
minioadmin/minioadmin) - Qdrant Dashboard: http://localhost:6333/dashboard
前端需要单独启动（开发模式，支持热重载）：
cd frontend
# 安装依赖 (使用 pnpm)
pnpm install
# 启动开发服务器
pnpm dev前端地址: http://localhost:5173
- 注册账户: 访问前端页面，使用配置的管理员账户登录，或注册新账户
- 上传图片: 点击上传按钮或拖拽图片到上传区域
- 等待处理: 图片上传后，系统会自动进行以下处理：
- 生成缩略图和预览图
- 提取 EXIF 元数据
- AI 自动打标（WD14 Tagger）
- 生成向量嵌入（CLIP）
- 建立索引（MySQL + Qdrant）
- 瀑布流展示: 类似 Pinterest 的极简视觉流
- 虚拟滚动: 支持大量图片的流畅浏览
- 图片查看器: 点击图片打开全屏查看器，支持缩放、旋转、切换
- 标签搜索: 在 Navbar 搜索框输入标签（如
1girl, solo, white_hair） - 语义搜索: 通过 MiuMiu 桌宠进行自然语言搜索（如"雨中的少女"）
- 混合搜索: 使用"与我对话"功能，LLM 驱动的智能搜索
- 标签清洗: 在图片详情页编辑标签，支持 Include/Exclude 切换
- 批量导出: 选择多张图片，一键导出为 Kohya_ss 标准格式（Image + Caption）
- 桌宠看板娘: 右下角常驻的 MiuMiu（缪缪）提供统一操作入口
- 功能菜单: 点击 MiuMiu 访问搜索、导出、上传等功能
- 进度跟踪: 导出和上传任务通过 MiuMiu 显示进度
Muse/
├── backend/ # FastAPI 后端服务
│ ├── app/ # 应用核心代码
│ │ ├── api/ # API 路由
│ │ ├── core/ # 核心配置
│ │ ├── models/ # 数据库模型
│ │ └── services/# 业务逻辑
│ └── requirements.txt
│
├── ai_worker/ # Celery 异步任务处理
│ ├── engines/ # AI 推理引擎
│ ├── tasks/ # Celery 任务定义
│ └── requirements.txt
│
├── frontend/ # React 前端应用
│ ├── src/
│ │ ├── components/ # 通用组件
│ │ ├── features/ # 功能模块
│ │ └── lib/ # 工具函数
│ └── package.json
│
└── deploy/ # Docker Compose 配置和基础设施
├── docker-compose.yml
├── download_models.py
└── models/ # AI 模型文件（需单独下载）
- 后端 Python: 遵循 Google Python Style Guide，包含完整的类型注解和文档字符串
- 前端 TypeScript: 遵循 Google TypeScript Style Guide，包含完整的类型注解和 JSDoc 注释
数据库迁移使用 Alembic，在容器启动时自动执行。如需手动迁移：
docker exec -it muse_api alembic upgrade head# 查看所有服务日志
docker-compose logs -f
# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f ai_worker# 重启所有服务
docker-compose restart
# 重启特定服务
docker-compose restart backend警告: 以下操作会删除所有数据，请谨慎使用！
cd deploy
# 1. 停止服务
docker-compose down
# 2. 删除数据卷 (数据库、MinIO、向量库全部清空)
docker volume rm deploy_mysql_data deploy_minio_data deploy_redis_data deploy_qdrant_data
# 3. 重新启动 (数据库会自动初始化)
docker-compose up -d| 服务 | 端口 | 说明 |
|---|---|---|
| MySQL | 3306 | 数据库连接端口 |
| MinIO API | 9000 | 对象存储 API |
| MinIO UI | 9001 | MinIO 管理控制台 |
| Redis | 6379 | 消息队列端口 |
| Qdrant | 6333/6334 | REST API / gRPC |
| 后端 API | 8000 | FastAPI 服务 |
| 前端 | 5173 | Vite 开发服务器（仅开发模式） |
- 设计文档 - 完整的系统架构和设计说明
问题: ai_worker 容器启动失败，提示找不到模型文件
解决: 确保已执行模型下载步骤，模型文件位于 deploy/models 目录
问题: AI Worker 使用 CPU 模式运行，速度较慢
解决:
- 确保已安装 NVIDIA Container Toolkit
- 检查
docker-compose.yml中的 GPU 配置 - 运行
nvidia-smi验证 GPU 是否可用
问题: 前端页面显示 API 请求失败
解决:
- 检查后端服务是否正常运行:
docker-compose ps - 检查
CORS_ORIGINS配置是否包含前端地址 - 查看后端日志:
docker-compose logs backend
问题: 上传图片后，AI 标签没有自动生成
解决:
- 检查 AI Worker 是否正常运行:
docker-compose logs ai_worker - 检查 Redis 队列是否有积压:
docker exec -it muse_redis redis-cli LLEN celery - 确认模型文件已正确下载
Project Muse - 让图片数据"活"起来 🎨