Vixel
用一句话找到照片和视频里的那一刻。 本地 AI 照片 / 视频 / 音频搜索 —— 全程离线，数据不出设备，无需 API Key。 基于 Google EmbeddingGemma 2 · macOS / Windows / Docker（NAS） · 支持 MCP
AI-powered local search for photos, videos and audio. Private. Offline. No cloud.
中文 · English
它能做什么
自然语言搜索
输入"海边的日落""宝宝第一次走路"，直接找到对应的照片和视频片段。 EmbeddingGemma 2 把文字、图片、视频、音频放进同一个多语言向量空间， 再和图内文字、文件名一起做四路 RRF 融合 —— 中文、英文都行。 库里没有把握的东西，它会直说，而不是硬凑一屏结果。
连图片里的文字也能搜
本地 PaddleOCR v5 识别截图、票据、海报、路牌里的文字，结巴分词 + SQLite FTS5 全文检索。 搜"2024 财报"，即使那张截图从没被命名过也能找到。
任何应用里，一个快捷键
全局快捷键 ⇧⌘Space（Windows：Alt+Shift+Space）呼出 Spotlight 式快速搜索面板，搜整个库： ↩ 在 Vixel 中打开（视频 / 音频直接跳到命中片段），Space 快速查看，⌘C 把文件本身拷进剪贴板， 结果也可以直接拖进剪辑软件的时间轴。快捷键在 设置 → 通用 里修改。
自动标签 · 以图搜图 · 颜色
照片和视频会在本地获得至多三个自动标签（内置约 150 个中英文标签，✦ 标出，✓ 保留、× 移除， 不用模型下载、不联网）；把一张图拖进搜索框或 ⌘V 粘贴，以图搜图找相似照片、也找它出现过的 视频片段；筛选栏里还能按颜色筛，和搜索随意叠加。
视频：直接跳到那一刻
每个视频按 32 秒切段，每段的画面（每 4 秒 1 帧）和声音一起编码成一个向量； 画面里出现过的文字（招牌、字幕、白板）也会被识别。 搜"沙滩上狗在叫"，命中的是听到的和看到的；打开详情自动跳到命中的那一段， 时间轴上高亮显示。网格里悬停即可拖动预览。
音频可搜 · 悬停即览
mp3 / m4a / wav / flac 等独立音频文件同样按段进入向量空间；封面缺失时自动生成波形图。
按人物浏览
SCRFD 人脸检测 + MobileFaceNet 512 维特征 + sqlite-vec 近邻索引。 按人脸质量（大小 / 角度 / 清晰度）把关，只在很确定时自动归入，其余批量聚类； 双击命名、拖拽合并、"是同一个人吗？"合并建议、"不是此人"、隐藏路人。
明暗随心 · 进度可见
浅色 / 深色 / 跟随系统；状态栏点开任务抽屉，看当前正在处理的文件、每段进度、 预计剩余时间，失败任务可一键重试。索引在独立的低优先级进程里跑，界面始终跟手。
离线地图
带 GPS 的照片落在地图上，大量照片自动聚合。底图随应用打包，打开地图也不发任何网络请求。
以上均为真实界面截图与录屏。示例照片和视频来自 Immich test-assets（公有领域）。
还有
- 收藏 · 筛选 · 智能相册 —— F 键收藏；按方向、分辨率、时长、人物、颜色筛选，可和搜索叠加；把"搜索 + 筛选"存成侧栏里自动更新的智能相册。
- 设计文件 —— SVG / PSD / PDF / AI 按栅格预览索引（缩略图、语义搜索、OCR），网格有格式角标；Windows 上 AI / PDF 用内置 pdf.js 渲染，无需装任何东西。
- 清理相似照片 —— 找出连拍、重复导出、轻度编辑过的副本，推荐保留哪张；多余的可在 Vixel 里隐藏，或确认后移到废纸篓。
- 相似照片 —— 任意照片一键找视觉相近的。
- 去重 —— xxHash64 内容哈希，同一张照片在多个文件夹里只算一次、只索引一次。
- HEIC / RAW —— macOS 上通过系统
sips解码 CR2 / CR3 / NEF / ARW / DNG / RAF / ORF / RW2，保留 EXIF。 - 快速查看 —— 空格预览，⌘1–5 切换 全部 / 图片 / 视频 / 音频 / 地图。
- 命令行 ——
vixel search "海边" --json，方便脚本和 Agent 调用（见下文）；结果里的matchedBy说明是画面、图中文字还是文件名命中。 - 链接进笔记 —— 右键「拷贝链接 / 拷贝 Markdown 链接 / 拷贝 Markdown（带缩略图）」得到
http://localhost:…/open?…链接，任何笔记、聊天、文档软件都能识别成可点的链接；在本机点开回到 Vixel 定位到那一项（视频 / 音频直接跳到时间点），Markdown 还能直接显示缩略图。开了「本地接口」的局域网访问后，链接换成局域网地址，手机上点开是网页查看页；NAS 版网页里同样能拷贝。链接按内容哈希定位，清库重建、移动文件后仍然有效（需要 Vixel 在运行）。 - 本地接口（默认关闭） —— 设置 → 通用 → 本地接口：在本机开出网页界面和 HTTP API，手机浏览器也能访问桌面的资料库（局域网访问必须设口令）；同一服务的
/mcp是给 AI 客户端的只读 MCP 接口（见下文）。 - 中英文界面 —— 跟随系统语言，也可在 设置 → 通用 里切换。
- 诊断 ——
vixel doctor/vixel bench体检和测速，VIXEL_PROFILE=1打印慢操作，见 docs/debugging.md。
和同类工具比
隐私
- 完全离线，没有例外：所有模型随应用分发，在本机运行；没有账号、没有遥测、没有云端。 地图用随应用打包的离线底图（Natural Earth，公有领域）， 渲染进程的一切网络请求都会被拦截。
- 照片原文件只读不写；索引、缩略图都存在本机的应用数据目录里。
- 收集箱的两个说明（v0.4 起）：
- 从浏览器把图片拖进 Vixel 时，如果拖动里只有图片地址（没有图片数据），主进程会只为这一个地址、 只在你松手的这一刻下载一次（限大小、类型和超时，并把来源记在「来源」里）。这是整个应用唯一的 主动联网场景，由你的显式拖放触发；界面（渲染进程）的网络白名单仍然为空。
- 浏览器扩展用的本地收集服务默认关闭，开启后也只监听
127.0.0.1、要求随机配对令牌， 从不发起任何对外请求——图片由扩展在浏览器里取好，把字节交给 Vixel。
下载
下载最新版：macOS（Apple Silicon）.dmg · Windows（x64）.exe，模型已内置（约 600 MB），装好即可离线使用。
安装包暂未经过 Apple / 微软签名：
- macOS：第一次打开被拦截时，到 系统设置 → 隐私与安全性 点「仍要打开」；或在终端执行
xattr -dr com.apple.quarantine /Applications/Vixel.app。 - Windows：SmartScreen 提示“已保护你的电脑”时，点「更多信息 → 仍要运行」。
语义模型默认用 GPU（macOS 上是 Metal，Windows 上是 Direct3D 12），没有可用 GPU 时自动退回 CPU。
服务器 / NAS 版（Docker）
同一套索引和搜索跑在你自己的 NAS / 服务器上，手机和电脑浏览器直接访问（支持
linux/amd64 和 linux/arm64，群晖 Container Manager 可用）。模型内置在镜像里，
运行时零出站请求；照片目录只读挂载，永不改动原文件。
docker run -d -p 8080:8080 \
-e VIXEL_PASSWORD='你的口令' \
-v /path/to/photos:/photos:ro \
-v vixel-data:/data \
ghcr.io/rgb-loop/vixel:latest
支持哪些群晖 / NAS：语义搜索（用一句话找照片、视频片段、声音，以图搜图）需要较新的 CPU。
"不支持"的机器也能装：图内文字（OCR）、人脸、文件名、标签、筛选、地图、收藏照常可用，界面会说明语义搜索不可用。
拿不准就在 NAS 上执行 grep -o -w avx /proc/cpuinfo | head -1，有输出就是完整支持（ARM 机型看 grep -o asimddp /proc/cpuinfo）。
部署细节（docker compose、群晖逐步说明、权限设置、反代 HTTPS、备份、限制）见 docs/server/README.md。
从源码运行
需要 Node.js 20+。主要在 macOS（Apple Silicon）上开发，Windows x64 已验证可用。
npm install
npm run models:download # 下载 EmbeddingGemma 2（LiteRT）+ LiteRT 运行时 + PaddleOCR，约 500 MB（只需一次）
npm run dev # 开发模式（开发期也会显示 Vixel 名称和图标）
打包：
npm run build && npm run package # 产物在 release/
第一次使用
- ⌘O 或 设置 → 文件夹，添加照片文件夹。
- 自动开始索引：缩略图 → 语义向量 → 视频 / 音频分段 → 图内文字（OCR）。点状态栏可以看进度、暂停。
- 人物页点一次扫描人脸；之后新加入的照片和视频都会自动识别人物。
- 在搜索框（⌘F）里用自然语言描述你要找的东西。库里确实没有相关内容时，Vixel 会如实告诉你，而不是凑满一屏。
语义模型经 LiteRT-LM 推理：默认用 GPU（macOS 上是 Metal）， 不可用时自动退回 CPU；设置 → 模型 里可以固定为 GPU 或 CPU。
支持的格式
PSD/PSB 读取文件内的合并合成图（Photoshop 默认开启"最大兼容"）；AI 需要以"创建 PDF 兼容文件"保存 （Illustrator 默认开启）。PDF / AI 在 Windows / Linux 上由内置的 pdf.js 离线渲染，无需安装任何东西。 EPS 不支持（macOS 已移除 PostScript 解码，其它平台需要用户自装 Ghostscript）。
内置播放器播不了的编码（如部分 mkv / avi）会提示用系统播放器打开，搜索和索引不受影响。
工作原理
┌───────────────────────────────┐ postMessage ┌──────────────────────────────────┐
│ Main 进程 │ ─────────────► │ 推理进程（utilityProcess, nice 10）│
│ SQLite + sqlite-vec + FTS5 │ ◄───────────── │ EmbeddingGemma 2 · LiteRT（GPU） │
│ 文件监听 (chokidar) │ │ SCRFD + MobileFaceNet 人脸 │
│ 索引队列 · 四路 RRF 搜索 │ │ PaddleOCR v5 图内文字 │
│ vixel:// 协议（缩略图 / 流媒体） │ └──────────────────────────────────┘
└──────────────┬────────────────┘
│ spawn ffmpeg-static：抽帧 / 音轨 / 封面 / 悬停预览图
│ contextBridge
┌──────────────▼────────────────┐
│ Renderer (React + Tailwind) │ 网格 · 详情 · 人物 · 地图 · 任务抽屉 · 设置
└───────────────────────────────┘
数据位置（macOS）：
~/Library/Application Support/vixel/
├── library.db # SQLite (WAL)：照片、向量、OCR、人脸、人物、任务队列
├── thumbnails/ # 按内容哈希共享的缩略图
├── video_frames/ # 视频代表帧、音频封面 / 波形、悬停预览图
└── backups/ # 每日自动备份，保留 3 份
更多设计细节见 Vixel_Tech.md，产品需求见 Vixel_PRD.md。
命令行
npm run cli -- search "海边的日落" --limit 10 --json
npm run cli -- similar 42
npm run cli -- people
npm run cli -- stats
支持 search · info · similar · people · stats · caption · folders · mcp，
--json 输出便于脚本和 AI Agent 调用。需要先运行一次应用以创建照片库。
MCP（让 AI 客户端查你的库）
vixel mcp 把同一套查询变成 stdio 形态的 MCP 服务器（工具全部只读：search_media /
get_media / find_similar），Claude Desktop、Cursor、Claude Code 等本地 AI 客户端
不开任何网络服务就能搜你的库；结果里的 vixel:// 链接点开直接回到应用并定位（视频跳到时间点）。
需要源码仓库（npm install && npm run build:cli；已安装的 Vixel.app 里的语义模型会被自动找到），
客户端里这样配置（Claude Desktop 的 claude_desktop_config.json、Cursor 的 mcp.json 同形）：
{
"mcpServers": {
"vixel": {
"command": "/绝对路径/Vixel/node_modules/.bin/electron",
"args": ["/绝对路径/Vixel/dist/cli/cli/index.js", "mcp"],
"env": { "ELECTRON_RUN_AS_NODE": "1" }
}
}
}
为什么用 Electron 当运行时：仓库的 better-sqlite3 按 Electron 的 ABI 构建，普通
node加载不了；ELECTRON_RUN_AS_NODE=1下 Electron 就是一个纯 Node，不会弹窗口。
不想碰源码：桌面应用 设置 → 通用 → 本地接口 打开后，同样的工具在 http://127.0.0.1:41721/mcp
（Streamable HTTP + Bearer 令牌，设置页里拷贝）；服务器版设 VIXEL_MCP_TOKEN 同理，
见 docs/server/README.md。
开发
src/
├── main/ # Electron 主进程：IPC、菜单、vixel:// 协议、推理进程入口
├── preload/ # contextBridge API
├── shared/ # main / renderer 共享类型
├── core/ # 与 UI 无关的核心：db · watcher · indexer · search · fusion
│ ├── embedding/ # EmbeddingGemma 2（本地 / 转发到推理进程）
│ ├── inference/ # 推理进程转发协议
│ ├── face/ # 检测 · 对齐 · 特征 · 质量 · 聚类
│ ├── ocr/ # PaddleOCR det / cls / rec
│ ├── video/ audio/ media/ image/ text/
├── renderer/src/ # React UI：shell · media · tasks · settings · inspector …
└── cli/ # vixel 命令行
npm test # vitest 单元测试
npx tsc --noEmit -p tsconfig.web.json # 类型检查（renderer）
npx tsc --noEmit -p tsconfig.node.json
欢迎贡献，见 CONTRIBUTING.md；变更记录见 CHANGELOG.md。
许可
MIT。
