Skip to content
MuskChengPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Memoir — ZecTrix Note4 岁月史书推送系统 📸

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 设备

🚀 快速开始(3 分钟)

Docker(推荐)

# 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/系统/已运行时长)与评分数据概览。


🐳 Docker 部署详情

环境要求

组件 最低配置 推荐配置
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 是否排除截图/文档/物品局部特写等无意义照片

GPU 加速

编辑 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 命令(进阶用户)

所有 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。


📊 性能参考(i5-12500H / CPU 模式)

下表为 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 张,几分钟完成

❓ 常见问题

没有 NVIDIA GPU 能用吗?

能。本项目设计目标就是 CPU 也能跑,图片已缩放到 512px。

水印字体在哪下载?

水印使用的像素字体 Ark Pixel Font 是开源项目。 项目仓库不包含字体文件,请自行下载。

缺少字体不影响主要功能运行,水印会回退使用系统默认字体(中文可能显示异常)。

模型没安装,系统会自动拉吗?

会。启动时自检(v1.3.5 新增),无需人工干预:

  • Ollama 在线但模型没装 → 后台自动拉取,拉完自动预热;进度在面板「Ollama 状态」卡片实时显示(⬇️ 拉取中 37%),日志页也会记录每 20% 的进度
  • Ollama 还没起来 → 前 3 次每分钟重试,之后每 5 分钟,一直重试到成功
  • 模型名写错 / 仓库不存在 → 立即停止并提示检查配置中的模型名(这类错误重试也没用,不会刷屏)

拉取期间定时评分类任务会自动跳过本次调度(见「⏰ 定时任务」),不会因为缺模型刷一堆报错。 想手动触发:配置页「推荐模型」点「拉取」,或在「自定义模型」填名称后点「拉取」(等价于调 POST /api/models/pull)。

日志里一堆 Bad request version 400 报错?

那不是本服务的问题:报文里那串乱码是 TLS 握手字节,说明有人在用 https:// 打到 5000 这个纯 HTTP 端口(浏览器/HSTS 自动升级、反向代理后端误配成 HTTPS、端口扫描都会这样)。

这类噪声已在日志里过滤掉,只留每 50 次的汇总记录。想根治:确认用 http:// 访问;若前面挂了反向代理,后端协议选 HTTP(TLS 终止应放在代理层)。

怎么排查问题?

  1. 看 Web UI「📋 日志」页(最新在前)
  2. 检查 Ollama:curl http://localhost:11434/api/tags(Docker 内用 http://ollama:11434)
  3. Web UI「🔧 操作」→ 试跑「⏳ 增量评分」,观察实时进度与错误信息

数据库在哪?

配置文件中的 paths.score_db(默认 /data/zectrix_scores.sqlite),单文件可直接拷贝迁移。

想换 / 换回 AI 模型怎么办?

改 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 查看。

截图、文档、物品局部特写被推送了怎么办?

这些由无意义照片过滤拦截。如果还在推:

  1. 先确认过滤开着:content_filter.enabled / apply_to_push 均为 true
  2. 老照片可能还没有语义字段,跑一次 python score.py rescore 补评
  3. 想更激进就把 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 — 自由使用、修改、发布。

🔗 相关链接

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages