AI 驱动的照片筛选与推送系统,专为 ZecTrix Note4 便利贴 设计。
一键部署,让 E-Ink 便利贴每天自动推送一张"值得放在桌面"的回忆照片。
| 特性 | 说明 |
|---|---|
| 🌐 浏览器管理 | 无需学习命令行,打开浏览器即可操作全部功能 |
| 🎨 赛博朋克控制台 | NEON OS 深色主题:霓虹辉光、HUD 切角按钮、SVG 矢量图标 |
| 🤖 AI 识图评分 | 基于 qwen3.5:4b 理解照片内容,输出评分/描述/场景/主体/景别/回忆价值 |
| ⚡ 一键全流程 | 点一次按钮完成「建索引 + AI 评分 + 选片推送」,无需分步操作 |
| 📑 首次启动引导 | 首次运行自动弹出设置向导,引导配置路径、建索引、创建定时任务 |
| 🎯 规则过滤 | 模糊/截屏/表情包/过暗过曝/文档板书/镜头遮挡 — 低质量照片自动跳过 |
| ⚖️ 年份公平选片 | 兼顾各年份照片,不让某一年垄断推送 |
| 🧹 无意义照片过滤 | 截图/文档/板书/票据/遮挡/空场景 + AI 判定的物品局部特写,自动排除在推送之外 |
| 🖼️ 自动水印 | 右下角黑色铭牌 + 白色日期文字,像素字体 |
| 🧭 方向自动纠正 | 选片后按 EXIF Orientation 旋转到正确方向,竖拍/倒置照片不再歪着上屏 |
| 🧠 模型自动拉取 | 启动自检:模型未安装就在后台自动拉取并重试,进度实时可见,无需手动进容器执行命令 |
| 🚀 断点续传 | 哈希去重 + SQLite 数据库,中断后自动跳过已处理照片 |
| 🐳 Docker 一行启动 | 支持 NAS 部署、GPU 加速 |
| 📡 极趣云推送 | Web UI 点一下直接推送到 ZecTrix Note4 设备 |
# 1. 下载项目
git clone https://github.com/MuskCheng/Memoir.git
cd Memoir
# 2. 准备目录和水印字体
mkdir -p photos data # 照片目录 + 数据目录
# 下载水印字体到项目根目录(中文显示必需)
# 下载后解压,将 .ttf 文件重命名为 ark-pixel-12px-monospaced-zh_cn.ttf 放在项目根目录
# 3. 构建并启动服务(首次会自动构建 Docker 镜像,约需 2-5 分钟)
# 配置文件首次运行自动生成,也可通过环境变量覆盖
docker compose up -d
# 5. AI 模型(约 4GB):v1.3.5 起启动后自动在后台拉取,无需人工干预
# (进度看 Web UI 面板的「Ollama 状态」卡片;想提前手动拉也可以)
docker compose exec ollama ollama pull qwen3.5:4b模型可在
config.json的ollama.model里更换(如更轻量的qwen3.5:2b),见视觉模型。 在配置页「推荐模型」里点「拉取」,或在「自定义模型」填好完整名称后点「拉取」即可,无需进容器执行命令(启动时若发现未安装也会自动补拉)。 换模型后必须重新评分,否则新旧分数混在一起会让选片失真。
镜像构建说明:项目包含
Dockerfile,首次执行docker compose up -d会自动构建镜像。 也可提前单独构建:docker compose build
打开浏览器访问 http://NAS_IP:5000,首次启动会自动弹出设置向导。
有 NVIDIA GPU? 编辑
docker-compose.yml,取消 Ollama 服务中deploy部分的注释,安装 NVIDIA Container Toolkit 后重启。
Memoir 的所有功能都可以通过浏览器完成,无需接触命令行。
打开 Web UI 后,设置向导会自动弹出,引导你完成 3 步:
| 步骤 | 说明 |
|---|---|
| ① 确认照片目录 | 设置你的照片存放位置 |
| ② 建立索引 | 扫描目录,生成照片清单 |
| ③ 创建定时任务 | 设置每日自动评分和推送时间 |
跳过也无妨,随时可以通过页面操作。
打开 Web UI 后默认进入「📊 面板」,顶部是快捷操作区,最常用的两个功能一步直达:
- ⚡ 一键全流程:建索引 + AI 评分 + 选片推送(推荐日常入口)
- 📡 选片并推送:选择设备后一键推送到 ZecTrix Note4
下方为系统状态概览:
- 评分概览:已评分照片数、待处理数、失败数
- Ollama 状态:
- 🟢
模型 ✅— 服务在线且模型已就绪 - 🟡
模型 ⚠️ 未安装— 服务在线但模型还没装;系统会自动在后台拉取,此时显示⬇️ 拉取中 37% · pulling … - 🔴
Ollama 未连接— 服务没起来,后台线程会持续重试直到它就绪
- 🟢
- 任务进度:后台任务实时进度条
- 配置摘要:当前照片目录、AI 模型、推送设备等关键信息
「🔧 操作」页面提供全部功能按钮(最常用的两个已上移至面板顶部):
| 按钮 | 作用 | 使用时机 |
|---|---|---|
| 📑 建立索引 | 仅扫描目录,更新照片清单 | 新增照片后 |
| 🤖 AI评分(全量) | 对所有照片逐个 AI 评分 | 需要重新评全部照片 |
| ⏳ 增量评分 | 只评未评过的新照片 | 日常使用 |
| ♻️ 补评语义字段 | 给老照片补上「主体/景别/回忆价值」,用于过滤截图、文档、物品局部特写 | 升级后跑一次(v1.3.5 起支持) |
| 🎯 选片预览 | 选一张照片但不推送 | 想看今天会推什么 |
| 🔄 重试失败 | 重置并重新评分失败的照片 | 出现批量错误后 |
任务执行时自动切到面板的实时进度条,支持中途停止。
「🖼️ 已评分」页面可按评分排序、按场景筛选、搜索照片,浏览所有已评分照片和 AI 生成的描述。
「⏰ 定时任务」页面支持创建和管理定时计划,无需系统级 cron:
| 推荐任务 | 建议频率 | 说明 |
|---|---|---|
一键全流程 score_full |
每 30 分钟 | 增量建索引 + AI评分 + 选片推送(上一轮未结束自动跳过) |
选片并推送 push_push |
每天 8:00 | 仅选片推送(已有评分时) |
补评语义字段 rescore |
一次性 | 升级后跑一次(v1.3.5 起支持),给老照片补「主体/景别/回忆价值」 |
直接在浏览器里创建,支持 cron 表达式、间隔、一次性三种调度方式。
模型未就绪时(刚启动、模型还在后台自动拉取中),评分类任务会自动跳过本次调度并记一条日志(
⏭️ 模型未安装…,跳过本次),等模型就绪后下次调度自然成功;同步索引、选片推送不受影响。
所有配置可在浏览器中在线编辑:照片目录、Ollama 地址/模型/线程数、推送设备等。页面整体为圆角矩形风格;已去掉原来的「当前配置预览」JSON 块,配置即改即存。
「🤖 Ollama 配置」区分选模型和取模型两步:
| 区域 | 说明 |
|---|---|
| 使用模型 | 最终决定本项目评分用哪个模型(下拉 = 已安装模型 + 当前配置的模型,没装的标注**「(未安装)」**,避免保存时被静默替换),选好点底部「💾 保存配置」生效 |
| 推荐模型 | 本项目精选的 3 个模型(qwen3.5:4b 默认 / qwen3.5:2b / minicpm-v4.6),标注体积与适用场景,显示**「✓ 已安装 / ● 使用中」状态,一键「拉取」** |
| 自定义模型 | 手动填写准确的模型名称(须与 Ollama 仓库完全一致,含冒号后的尺寸),点「拉取」即向 Ollama 发送指令;名称格式会在服务端校验,填错立即报错 |
| 拉取进度 | 有任务时出现进度条(百分比 + 当前阶段),3 秒刷新一次,启动自检触发的自动拉取同样显示在这里 |
浏览器中实时查看运行日志,最新在前,无需翻到底部。日志框铺满页面宽度,随浏览器窗口自适应(高度也随视口伸缩),日志行自动换行不产生横向滚动。
已自动过滤两类噪声:HTTP 访问日志(太吵)、以及非 HTTP 流量探测产生的 Bad request version / syntax 400(用 https:// 访问 5000 端口、端口扫描等,与本服务无关)。每 50 次探测会留一条汇总记录,便于发现异常访问。
「ℹ️ 关于」页面显示当前版本与更新状态(自动检查 GitHub 最新 Release,离线时优雅降级)、运行环境(Python/系统/已运行时长)与评分数据概览。
| 组件 | 最低配置 | 推荐配置 |
|---|---|---|
| CPU | x86_64 4核 | x86_64 8核+ |
| RAM | 8GB | 16GB+ |
| 磁盘 | 10GB | 50GB+ |
| Docker | 24+ | 最新版 |
| GPU(可选) | NVIDIA + CUDA | 显存 ≥6GB |
memoir/
├── docker-compose.yml # 服务编排(启动全部服务)
├── .env # 环境变量配置(可选,从 .env.example 复制)
├── photos/ # 你的照片目录(挂载)
└── data/ # 数据目录(自动创建)
├── config.json # 配置文件(首次运行自动生成)
├── zectrix_scores.sqlite # 评分数据库
├── zectrix_photo_index.txt # 照片索引
├── zectrix_shown.txt # 已推送记录(跨年自动重置)
├── zectrix_today.jpg # 今日推送的图片
└── push_history.json # 推送历史(面板"今日推送"卡片)
可通过环境变量覆盖配置,无需手动编辑 config.json:
| 变量 | 默认值 | 说明 |
|---|---|---|
OLLAMA_BASE_URL |
http://ollama:11434 |
Ollama 服务地址 |
OLLAMA_MODEL |
qwen3.5:4b |
AI 模型 |
CPU_THREADS |
0(自动检测) |
CPU 线程数 |
API_KEY |
— | 极趣云 API Key |
DEVICE_MAC |
— | 设备 MAC 地址 |
PHOTO_DIR |
/photos |
照片目录 |
DATA_DIR |
/data |
数据目录 |
FILTER_ENABLED |
true |
是否启用规则过滤 |
EXIF_AUTO_ROTATE |
true |
推送前是否按 EXIF 方向旋转照片到正确方向 |
CONTENT_FILTER_ENABLED |
true |
是否排除截图/文档/物品局部特写等无意义照片 |
编辑 docker-compose.yml,取消 GPU 配置注释,安装 NVIDIA Container Toolkit 即可。
配置文件首次运行自动生成,也可以在 Web UI「⚙️ 配置」页面在线编辑。
{
"paths": {
"photo_dir": "/photos", // 照片目录
"project_dir": "/data", // 数据目录(索引、数据库)
"score_db": "/data/zectrix_scores.sqlite"
},
"ollama": {
"base_url": "http://ollama:11434", // Docker 内使用服务名;本地运行改为 http://localhost:11434
"model": "qwen3.5:4b", // 视觉模型,可换成 qwen3.5:2b / minicpm-v4.6
"num_thread": 0, // 0=自动检测CPU核心数
"temperature": 0.7,
"disable_think": true // 关闭模型的"思考"输出,避免污染 JSON
},
"devices": [
{
"name": "客厅 Note4",
"device_mac": "20:6E:...",
"api_key": "zt_..."
}
]
}手机竖拍、相机倒持拍摄的照片会在 EXIF 里写入方向(Orientation)标签:像素本身可能是"横躺"的。 Memoir 在选片之后、裁切缩放之前会按这个标签把照片旋转到人眼看到的正确方向(默认开启):
- 竖拍照片按竖构图裁切,不会连同画面一起"躺倒"上屏
- 倒置照片恢复到正常朝向
- HEIC 之外的主流格式(JPEG/PNG/WebP 等带 EXIF 方向标签)均支持
如确认照片方向已全部正常,可在 config.json 中关闭:
{
"image_processing": {
"exif_auto_rotate": false
}
}Docker 部署也可用环境变量 EXIF_AUTO_ROTATE=false 关闭。
所有 CLI 命令均可在 Web UI「🔧 操作」页面一键完成。以下供自动化脚本或排查问题使用。
# 一键全流程(建索引 + 评分 + 选片推送)
python score.py auto --build-index --push
# 建立索引
python score.py index /photos -o /data/index.txt
# 全量评分
python score.py auto
# 增量评分(日常使用)
python score.py run
# 补评/重评语义字段(v1.3.5 新增)
# 不带参数:只给缺少「主体/景别/回忆价值」的老照片补评
# --all:全库重新评分(规则过滤与语义判定都会刷新)
python score.py rescore
python score.py rescore --all
# 选片并推送
python push.py push
# 查看统计
python score.py stats
# 查看高分照片
python score.py top --limit 10
# 按场景搜索
python score.py search 风景
# 重试失败照片
python score.py retry选片推送前会自动排除两类对"日常回忆"没有价值的照片,已默认开启:
| 层级 | 判定方式 | 覆盖内容 |
|---|---|---|
| 规则层 | 文件名 + 分辨率 + 画面特征(零成本) | 截图、录屏、表情包、缩略图、书页/票据/板书/PPT 等文档类、镜头遮挡、大面积纯色、模糊/过暗/过曝 |
| 语义层 | AI(复用现有 VLM,每张只多输出 3 个字段) | 屏幕类翻拍、文档资料一律排除;物品/美食的局部特写排除,完整主体(全景/中景)保留 |
{
"content_filter": {
"enabled": true,
"apply_to_push": true, // false = 只记录不排除
"reject_document_like": true, // 文档/板书/票据/PPT 类画面
"reject_blocked_lens": true, // 镜头遮挡/大面积纯色
"reject_empty_scene": false, // 空场景弱判(误杀略高)
"ai_enabled": true,
"exclude_subjects": ["文档", "屏幕"],
"exclude_detail_subjects": ["物品", "美食"], // 这些主体只保留全景/中景
"exclude_low_memory": false // 打开后 AI 判「回忆价值=低」也排除(较激进)
}
}回填历史照片(新字段只对新评分生效,老照片默认放行不会误杀):
python score.py rescore # 只补评缺语义字段的照片
python score.py rescore --all # 全库重新评分候选池被清空时会在日志明确提示并给出调整建议,不会静默不推送。
默认使用 qwen3.5:4b(3.3–4.0GB)理解照片内容、生成评分与描述。相比早期的 qwen2.5vl:7b(4.7GB):
- 体积小 ~30%,prompt token 从 1112 降到 408,CPU 上更快
- 2026-10 的新统一多模态家族,视觉理解与描述生成同代更新
- 评分、描述、场景、主体、景别、回忆价值全部由同一个模型一次输出
需要更轻量时可自行更换(改 ollama.model 即可,无需改代码):
| 模型 | 体积 | 适合场景 |
|---|---|---|
qwen3.5:4b(默认) |
3.3–4.0GB | 质量与速度平衡 |
qwen3.5:2b |
2.7–3.1GB | 内存/CPU 吃紧,接受轻微质量损失 |
minicpm-v4.6 |
1.6GB | 极限轻量,1.8MP 图只编 640 token |
⚠️ 换模型后必须重新评分(python score.py rescore --all):不同模型的分数不可横向比较。 建议先python score.py auto --limit 20验证:JSON 解析成功率 >95%、描述与「主体/景别/回忆价值」判读正常,再全量跑。 若模型输出里混入思考/推理文字导致解析失败,把ollama.disable_think保持true(默认已开启)。
memoir/
├── score.py # AI 评分引擎 + 索引构建(score.py index)
├── push.py # 选片 + 推送
├── filter.py # 规则过滤 + 无意义内容判定
├── orientation.py # 照片方向检查与修正(EXIF Orientation)
├── config_module.py # 统一配置模块 + 路径工具
├── Dockerfile # Docker 构建
├── docker-compose.yml # Docker 编排
├── webui/ # 🌐 Web 管理面板(主推入口)
│ ├── app.py # Flask 后端
│ ├── health.py # 启动自检 + 环境检测
│ ├── scheduler.py # 定时任务
│ └── templates/index.html # 单页管理界面
└── docs/
└── local-operation-guide.md # 大批量照片处理指南
📥
ark-pixel-12px-monospaced-zh_cn.ttf(水印字体)需自行下载,见 FAQ。
下表为
qwen2.5vl:7b时代的实测值。自 v1.3.5 默认模型换成qwen3.5:4b(更小、prompt 更短)后,单张耗时会明显低于表中数值,建议以--limit 100实测为准。
| 图片缩放 | 单张耗时 | 1,000 张 | 10,000 张 |
|---|---|---|---|
| 512px(默认) | ~55 秒 | ~15 小时 | ~6.4 天 |
| 384px(快速) | ~35 秒 | ~10 小时 | ~4 天 |
- 规则过滤:毫秒级,自动标记约 20-30% 低质量照片(截图、文档、连拍等)
- 无意义照片过滤:规则层同样毫秒级;语义层复用同一次 AI 评分,无额外开销
- GPU 加速(NVIDIA):预计提速 3-5 倍
- 增量处理:每天新增 ≤50 张,几分钟完成
能。本项目设计目标就是 CPU 也能跑,图片已缩放到 512px。
水印使用的像素字体 Ark Pixel Font 是开源项目。 项目仓库不包含字体文件,请自行下载。
缺少字体不影响主要功能运行,水印会回退使用系统默认字体(中文可能显示异常)。
会。启动时自检(v1.3.5 新增),无需人工干预:
- Ollama 在线但模型没装 → 后台自动拉取,拉完自动预热;进度在面板「Ollama 状态」卡片实时显示(
⬇️ 拉取中 37%),日志页也会记录每 20% 的进度 - Ollama 还没起来 → 前 3 次每分钟重试,之后每 5 分钟,一直重试到成功
- 模型名写错 / 仓库不存在 → 立即停止并提示检查配置中的模型名(这类错误重试也没用,不会刷屏)
拉取期间定时评分类任务会自动跳过本次调度(见「⏰ 定时任务」),不会因为缺模型刷一堆报错。
想手动触发:配置页「推荐模型」点「拉取」,或在「自定义模型」填名称后点「拉取」(等价于调 POST /api/models/pull)。
那不是本服务的问题:报文里那串乱码是 TLS 握手字节,说明有人在用 https:// 打到 5000 这个纯 HTTP 端口(浏览器/HSTS 自动升级、反向代理后端误配成 HTTPS、端口扫描都会这样)。
这类噪声已在日志里过滤掉,只留每 50 次的汇总记录。想根治:确认用 http:// 访问;若前面挂了反向代理,后端协议选 HTTP(TLS 终止应放在代理层)。
- 看 Web UI「📋 日志」页(最新在前)
- 检查 Ollama:
curl http://localhost:11434/api/tags(Docker 内用http://ollama:11434) - Web UI「🔧 操作」→ 试跑「⏳ 增量评分」,观察实时进度与错误信息
配置文件中的 paths.score_db(默认 /data/zectrix_scores.sqlite),单文件可直接拷贝迁移。
改 config.json 的 ollama.model 一个字段即可,无需改代码;Docker 部署也可以直接改 .env 的 OLLAMA_MODEL:
# 例:换更轻量的 2B —— 配置页「推荐模型」里点「拉取」即可(或在
# 「自定义模型」输入框填完整名称后点拉取);习惯命令行的话等价于:
docker compose exec ollama ollama pull qwen3.5:2b
sed -i 's/^OLLAMA_MODEL=.*/OLLAMA_MODEL=qwen3.5:2b/' .env
docker compose up -d webui改完执行 python score.py rescore --all 重新评分(不同模型分数不可横向比较)。
备选见视觉模型,若输出里混入推理文字导致解析失败,确认 ollama.disable_think 为 true。
已部署的机器升级注意:默认模型需要较新的 Ollama。升级项目后先
docker compose pull && docker compose up -d ollama,再拉模型,否则可能报 412 / 无法加载。 Ollama 版本可用docker compose exec ollama ollama --version查看。
这些由无意义照片过滤拦截。如果还在推:
- 先确认过滤开着:
content_filter.enabled/apply_to_push均为true - 老照片可能还没有语义字段,跑一次
python score.py rescore补评 - 想更激进就把
content_filter.exclude_low_memory打开(AI 判「回忆价值=低」也排除)
content_filter 可能过滤过度。日志会打印当前候选数量和「排除 N 张」的提示,按需放宽:
apply_to_push: false临时关掉推送侧过滤(仍会记录)reject_document_like/reject_blocked_lens/exclude_detail_subjects逐项调- 只对某类照片误判时,把该主体从
exclude_subjects里去掉
见照片方向纠正。默认按 EXIF Orientation 自动旋转;若照片本身是横竖混排的扫描件,可临时设 image_processing.exif_auto_rotate: false。
MIT License — 自由使用、修改、发布。