# AI 相册

## 一、简介

Axera 芯片本地 AI 私有云相册解决方案，通过将开源相册 Immich 深度适配至爱芯元智（Axera）边缘硬件，打造了一条完整的本地智能影像数据链路。

该方案可将搭载 AX650/AX8850 芯片的边缘设备（如 M4N-Dock 开发板、M5Stack AI Pyramid Pro 等）直接升级为隐私安全的“本地版 Google Photos”：

- **纯本地闭环：** 部署完毕后，数据存储与 AI 推理（语义、OCR、人脸比对）可100% 本地完成，零云端依赖，满足严苛的隐私保护与离线运行需求。
- **芯片级加速：** 深度调用 Axera NPU，为 CN-CLIP、PP-OCRv5 和 InsightFace 提供底层硬件加速，彻底释放 CPU 压力，实现海量照片毫秒级检索。
- **开箱即用：** 依托 Immich 成熟生态，原生自带精美的 Web/App 双端界面及多用户管理体系，免二次开发，极速落地。
- **多维 AI 检索：** 聚合人脸聚类图谱、自然语言模糊搜索及精确 OCR 文本提取，打造无死角检索体验。
- **极简部署：** 基于 Docker 环境，灵活适配各类轻量级边缘计算盒子与开发套件，部署成本极低。

## 二、适用场景

| 场景 | 典型需求 | 方案收益 |
| --- | --- | --- |
| 家庭/极客私有云相册 | 海量照片无感备份，按人脸自动管理，要求数据绝对隐私。 | **纯本地图谱：** 数据不出网，实现原画质极速备份、InsightFace 自动人脸聚类与动态足迹地图。 |
| 个人知识库与票据管理 | 快速找回堆积的证件照、发票、会议白板及带字截图。 | **OCR 图文提取：** 利用 PP-OCRv5 精准提取文字，将静态图片转化为即搜即得的本地资料库。 |
| 专业影像创作者/工作室 | 在缺少标签的海量图片素材底库中，快速精准提取目标。 | **自然语言找图：** 免除人工打标签，输入文字描述即可瞬间定位所需素材。 |
| 旅游博主与户外游记 | 旅途产生大量影像，需直观梳理行程轨迹，并方便后续向朋友或粉丝复盘分享。 | **动态足迹与共享：** 自动解析图文 EXIF 坐标并在地图生成专属旅行轨迹，结合多用户与相册共享功能，轻松实现无缝的游记分享。 |

## 三、示例效果

### 1.AI极速找图

照片入库后，Axera 芯片的 NPU 会立即接管高负载计算。系统运行 PP-OCRv5 和 CN-CLIP 等模型，对图片进行高维特征提取与文字识别，并在本地快速建立多维向量索引数据库。网页或APP端接收到检索请求时，系统直接在索引库中进行高维空间比对。

- **语义检索：** 响应模糊自然语言描述的匹配结果。
- **OCR 检索：** 精准锁定包含特定文字的图片。
- 免除人工打标签的繁琐，以及不受网络波动影响的毫秒级毫秒级无感检索体验。

在网页端进行“穿红色衣服的小孩”、“在黑色汽车上的猫”、“savor delicious food”等中英文描述搜索

<video src="../../_static/07_solutions/immich/web-clip.mp4" width="100%" autoplay loop muted playsinline>
</video>

在APP端使用OCR功能，进行图片水印、变形字体的搜索

<video src="../../_static/07_solutions/immich/app_ocr.mp4" style="max-width: 280px; width: 100%; border-radius: 16px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);" autoplay loop muted playsinline>
</video>

### 2.智能人物相册

当导入海量照片时，系统会在后台实时运行人脸识别算法，提取面部特征并进行高维度比对。系统会自动将同一人物的影像进行聚类，并在“探索”界面中生成独立的专属图片集。用户可对该集合进行自定义命名标签，后续当带有该人物的新照片上传时，系统会自动进行特征匹配并动态将其归入对应的档案中。

- 全自动化的人物特征提取与高精度聚类，彻底免去繁琐的人工挑图与分类建档工作。
- 建立动态生长的个人影像库，新上传的照片自动触发比对规则，实现无感自动入库。
- 高自由度的干预机制，支持用户对自动归类进行自定义命名与手动修正，确保图谱精准度。
  在“探索”界面直观管理所有人物图谱，让海量照片按人像自动井然有序，轻松构建专属的家庭成员或社交圈数字成长轨迹。

<video src="../../_static/07_solutions/immich/Insightface.mp4" width="100%" autoplay loop muted playsinline>
</video>

### 3.唤醒老照片

针对早期单反或扫描件等缺失 GPS 信息的照片，用户可以通过界面手动填写位置信息、图片描述等信息。系统接收并处理这些自定义信息后，会直接重写底层数据库的影像属性节点，并动态下发更新至所有终端。

- 对照片底层元数据（地理位置、时间等）的绝对编辑与控制权。
- 将散落的历史图片重新赋予空间维度，瞬间融入用户的全局数字轨迹中。
- 即时生效、跨端同步（Web端修改，APP端地图同步刷新）的数据一致性体验。

在网页端重新编辑图片地址信息，并同步到地图中，方便快速翻阅，快速打造属于自己的“旅行足迹”

<video src="../../_static/07_solutions/immich/map.mp4" width="100%" autoplay loop muted playsinline>
</video>

### 4.自动备份

在同一网络下，移动端生成新影像资产后，Immich 客户端会实时侦测并在后台建立传输通道。照片流推入 Axera 边缘硬件后，系统瞬间完成数据落盘，并自动提取和解析文件的 EXIF 元数据（包含经纬度、时间戳、设备参数）。系统将空间坐标转化为可视化锚点，并映射至全景地图中。

- 安全落盘的图片/视频原文件以及系统自动生成的轻量级缩略图。
- 基于时间轴与地理坐标双维度构建的结构化数字资产库。
- 直观呈现个人运动轨迹的动态地图与区域热力分布。

APP同步相册，拍照完成后，自动同步相册数据，并将位置信息同步到地图

<video src="../../_static/07_solutions/immich/Backup.mp4" style="max-width: 280px; width: 100%; border-radius: 16px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);" autoplay loop muted playsinline>
</video>

## 四、开发者接入示例

下面是核心配置片段，用于说明开发者需要关注的关键开关。完整部署请以资源包 README 和本站安装文档为准

### 1.导入并启动docker

• 加载离线 Docker 镜像包，并使用 Docker Compose 启动容器服务。

```bash
docker load -i ax-immich-server-aarch64.tar.gz
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
```

### 2.搭建ml环境并启动ml服务

```bash
#注意安装py 3.11版本(v2.7.5 immich官方指定)
curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11

# 安装依赖
pip install -r requirements.txt

#建议选择PyAXEngine最新版本 当前最新0.1.3.rc3
pip install https://github.com/AXERA-TECH/pyaxengine/releases/download/0.1.3.rc3/axengine-0.1.3-py3-none-any.whl

#安装Wheel包
pip install immich_ml-2.7.5-py3-none-any.whl
```

### 3.选择模型并启动任务

通过ip和端口进入网页，选择对应模型、运行任务后即可使用：

- CLIP模型：ViT-L-14-336-CN__axera
- 人脸识别模型(默认为AXERA模型)：buffalo_l_axera(AXERA)
- OCR模型（默认为AXERA模型）：PPOCR_v5_axera(AXERA)

## 五、性能评估

Immich 服务由 Docker 中的 `server/postgres/redis` 与宿主机 `immich_ml` 组成。由于模型懒加载、运行时缓存、数据库缓存以及AX CMM 分配策略等因素，MEM与 CMM 占用会受操作影响。下面固定测试场景进行性能评估：

本次测试模拟用户日常使用流程,使用AxEngineExecutionProvider：通过 Web 页面批量上传图片，随后由系统自动完成缩略图、元数据、人脸识别、OCR、重复检测和智能搜索索引等后台处理。

- 测试图片：2310 张
- 上传方式：Web 页面手动上传
- ML 模型：本地缓存加载`HF_HUB_OFFLINE=1`
- 测试模式：预热后的日常连续使用状态

### **1、整体处理能力**

上传2310张混合图片

| **阶段** | **耗时** | **处理能力** |
| --- | --- | --- |
| Web 批量上传 | 205 秒 | 约 11.3 张/秒 |
| 上传后后台 AI 处理 | 829 秒 | 约 2.8 张/秒 |
| 从开始上传到全部完成 | 1034 秒 | 约 17 分 14 秒 |

处理完成后，本批图片产生：

- 人脸记录：1660 条
- OCR 文本记录：710 条

### **2、存储占用**

| **目录** | **占用** |
| --- | --- |
| AXERA / Immich ML 模型缓存 | 637 MiB |
| HuggingFace 缓存 | 544 KiB |
| Immich 图库目录 | 585 MiB |

本次测试使用本地模型缓存运行，不依赖外网下载，适合边缘设备、内网部署和离线演示环境。

### **3、搜索能力**

- **后端搜索接口能力**
  使用脚本直接请求 Immich 搜索接口，分别覆盖元数据搜索 `/api/search/metadata` 和智能语义搜索 `/api/search/smart`。每个关键词连续执行 10 轮，第 1 轮作为首次查询参考，第 2-10 轮作为热查询统计。该指标反映服务端从接收搜索请求到返回 JSON 结果的耗时，不包含浏览器输入防抖、页面渲染、缩略图加载等前端开销。

| 能力项 | 测试内容 | 测试结果 | 产品化描述 |
| --- | --- | --- | --- |
| **中文语义搜索** | 查询“穿红色衣服的小孩” | 首次约 105 ms，热查询平均约 60 ms | 支持中文自然语言描述检索，可根据人物、颜色、衣着等复合语义查找图片。 |
| **英文语义搜索** | 查询“red clothes child” | 首次约 83 ms，热查询平均约 59 ms | 支持英文自然语言检索，适合中英文混合展示和国际化场景。 |
| **人物类搜索** | 查询“小孩 / child / 孩子” | 热查询平均约 60-63 ms | 可根据人物类别进行语义检索，适合快速查找人物相关照片。 |
| **颜色与衣着搜索** | 查询“红色衣服 / red shirt” | 热查询平均约 60-61 ms | 可识别图片中的颜色和衣着特征，支持更细粒度的图片查找。 |
| **组合条件搜索** | 查询“person in red” | 热查询平均约 59 ms | 支持人物与颜色等多条件组合描述，提升图库检索的直观性。 |
| **查询响应体验** | 每个关键词连续查询 10 轮 | 首次查询约 76-105 ms，热查询约 58-63 ms | 在 2310 张图片规模下，智能搜索响应保持在百毫秒级以内，适合现场演示和日常使用。 |
| **查询稳定性** | 中英文关键词多轮请求 | HTTP 状态均为 200，异常数 0 | 查询接口响应稳定，连续检索过程中未出现请求失败。 |

### **4、推荐部署余量**

基于本轮 2310 张图片测试结果，建议产品化部署预留以下资源：

| **项目** | **建议值** | **说明** |
| --- | --- | --- |
| OS 内存 | >= 3.5 GiB | 按实测总内存峰值约 2.62 GiB 增加 30% 余量 |
| CMM | >= 1.0 GiB | 按实测 CMM 峰值约 732 MiB 增加 30% 余量 |
| 推荐 CMM 配置 | 4 GiB | 本次测试配置余量充足，适合展示和扩展 |
| 模型缓存空间 | >= 1 GiB | 当前模型缓存约 637 MiB，建议留足更新空间 |
| 图库空间 | 原图空间 + 30% 以上 | 缩略图、索引、派生文件会随图库增长 |

## 六、相关链接指引

- [immich官网](https://immich.app/)
- [axera适配immich源码](https://github.com/AXERA-TECH/immich/tree/ax650-v2.7.5)
- [AXERA-TECH/immich](https://huggingface.co/AXERA-TECH/immich)
- [告别云相册订阅费！在 AI Pyramid Pro上一键部署本地满血 AI 智能搜索相册 Immich - 知乎](https://zhuanlan.zhihu.com/p/2051749029223183792)