使用文档
MT Copilot
产品概述
MT Copilot 是 MT Photos 照片管理器的 AI 扩展，旨在提供业界领先的的 CLIP 语义搜索、OCR 文字识别和人脸识别能力。本文档涵盖安装配置、功能说明
CLIP 语义搜索
将图片和文本转换为向量嵌入，支持以图搜图、以文搜图。支持 Google Gemini 和阿里百炼两种 Embedding 模型。
OCR 文字识别
从图片中提取文字内容，使用 PaddleOCR-vl-1.6模型。
人脸识别
基于人脸识别模型 检测图片中的人脸并提取特征向量，支持 Direct ML 加速。
识别逻辑
MT Copilot 通过云端请求调用 AI 能力，结果写入 MT Photos PostgreSQL 数据库。
安装与启动
环境要求
- Windows 10/11 64 位系统
- MT Photos 已安装并运行
- 至少 4GB 可用内存
配置说明
所有配置通过项目根目录的 .env 文件管理。以下是关键配置项：
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
HTTP_PORT | 8060 | 后端服务端口 |
API_AUTH_KEY | mt_photos_ai_extra | MT Photos 调用时的鉴权 Key |
Embedding 模型配置
| 变量 | 默认值 | 说明 |
|---|---|---|
CLIP_MODEL | qwen3-vl-embedding | Embedding 模型选择 |
EMBED_DIMENSION | 768 | 向量维度（128~4096） |
USE_THUMBNAIL | true | 使用缩略图加速处理 |
FUSION_MODE | false | 融合向量模式（OCR+视觉特征） |
人脸与 OCR 配置
| 变量 | 默认值 | 说明 |
|---|---|---|
FORCE_CUDA | true | 是否使用 GPU 加速人脸识别 |
数据库配置
| 变量 | 默认值 | 说明 |
|---|---|---|
MT_DB_HOST | 127.0.0.1 | MT Photos PostgreSQL 地址 |
MT_DB_PASSWORD | 自动读取 | 数据库密码（留空自动从安装目录获取） |
CLIP 识别
CLIP 识别将图片和文本转换为高维向量，通过向量相似度实现语义级别的搜索。
工作流程
- 1MT Copilot 从 MT Photos的数据库里面读取当前所有图片的识别信息
- 2后端调用 Embedding 模型生成图片向量
- 3MT Copilot将识别结果写入数据库，并将这张照片在数据库里面的识别状态修改为已完成状态
支持的模型
| 模型 |
|---|
qwen3-vl-embedding |
gemini-embedding-002 |
融合向量模式
开启该功能后，系统会将图片的 OCR 文字特征与视觉特征融合为单个向量，显著提升以文搜图的精度。
OCR 文字识别
从图片中提取文字内容，支持多种图片格式和 PDF 文件。
说明
由于MT Photos 数据库限制，超过2500字节的文字将会被截断。
人脸识别
使用业界最新的人脸模型提取特征向量。
GPU 加速
设置 FORCE_CUDA=true 可启用 CUDA 加速人脸检测。需要安装 CUDA Toolkit 和对应的 ONNX Runtime。
提示
人脸识别在本地运行，不消耗云端 Token，不产生额外费用。
前端界面
首页仪表盘
访问 http://localhost:5173 查看服务运行概览：
- 请求总数和计算设备信息（CPU/GPU）
- 缓存向量数量
- 当前模型配置（向量维度、推理后端、CLIP 模型、OCR 后端）
任务管理
在「任务」页面可以：
- 启动/停止三阶段批处理流水线
- 实时查看日志，了解处理进度
- 监控每阶段的处理速度和剩余数量
数据库浏览
在「数据库」页面可以：
- 查看 MT Photos PostgreSQL 连接状态和识别统计
- 浏览照片列表，支持按分类、关键字筛选和分页
- 查看照片详情：缩略图、OCR 内容、CLIP 状态、AI 分类
- 手动编辑并保存 OCR 文本
系统设置
在「设置」页面可以调整：
- 向量维度（128~4096 滑块）
- 是否使用缩略图
- 融合向量开关
修改配置后需点击「保存并重启」使配置生效。
常见问题
人脸识别需要付费吗？
人脸识别在本地运行，不消耗云端 Token，不产生额外费用