immich

后续本网页不再持续维护，转为使用 https://github.com/AXERA-TECH/immich

目前hugging Face 版本固定为2.7.5,更新的3.0.1版本已在https://github.com/AXERA-TECH/immich

更多信息请关注https://github.com/AXERA-TECH/immich

一、项目简介

Immich 是一款支持本地 AI 检索与多端备份的开源自托管智能相册。将其深度适配并独立部署在 AX650 边缘算力板卡上，可让所有照片数据与 AI 推理均在本地物理隔离运行，从而实现100%的数据主权与最高级别的隐私安全保障。

原项目官方资源：

• 官方网站：https://immich.app/
• GitHub 仓库：https://github.com/immich-app/immich

本项目的目标是演示如何在AX650开发平台上部署 Immich，部署后可直接使用AX650板卡，或者外接 AX650 AI 算力卡 进行使用。

二、参考链接

我们已将针对 Immich 代码库的修改版本在 GitHub 上开源，目前版本对齐immich最新版本v2.7.5：

• 开源仓库：https://github.com/AXERA-TECH/immich/tree/ax650-v2.7.5

三、支持平台

• AX650 / AX8850
  • AX650N DEMO Board
  • M4N-Dock(爱芯派Pro)
  • M.2 Accelerator card

四、支持模型

在 Immich 项目中，CLIP 模型是实现智能相册功能且计算需求最高的核心组件。为了进一步提升识别准确率，我们采用了参数量更大的模型：CLIP-L/14-336 和 CN-CLIP-L/14-336。

针对爱芯元智（Axera）AI 加速卡优化后的预编译模型，可参考以下版本获取：

• CLIP-L/14-336 (English)
• CN-CLIP-L/14-336 (Chinese)

五、部署操作

1. 系统配置与代码获取

（1）前置准备与依赖安装（必做）

在开始部署前，必须更新系统并安装核心依赖组件。

apt-get update
apt-get install -y unzip libgl1

扩充存储空间（可选）

• 挂载 SD Card：若系统内部空间不够，可选择挂载 SD Card 来存放数据。首先需将 SD Card 格式化为 ext4 格式并挂载。

lsblk

#格式化SD Card 注意保存数据
# mkfs.ext4 /dev/mmcblk1p1

mkdir /mnt/sdcard
mount /dev/mmcblk1p1 /mnt/sdcard

• 配置开机自动挂载：通过 blkid /dev/mmcblk1p1 获取 UUID 后，修改 /etc/fstab 文件以实现开机自启。配置示例如 UUID=13054439-9d76-47ca-b8ed-c7cd8d208a5d /mnt/sdcard ext4 defaults 0 2。

（3） 获取部署代码（必做）

• 方案一：使用 Git：安装 git-lfs 后，直接从 HuggingFace 拉取代码仓库（空间不足时可选择拉取至 SD Card 目录）。

apt-get install git-lfs
git clone https://huggingface.co/AXERA-TECH/immich

• 方案二：使用 HuggingFace：若 Git 因为网络问题导致拉取失败，可安装 huggingface_hub 工具并使用 hf download 进行本地下载。

apt-get install -y python3.11

#若无法直接访问 可使用国内代理
export HF_ENDPOINT=https://hf-mirror.com

pip install -U huggingface_hub
hf download AXERA-TECH/immich --local-dir .

2. Docker 服务部署

（1） 解压配置文件（必做）

• 进入拉取的 immich 代码目录，解压部署文件并创建 .env 环境变量文件。

cd immich
unzip -o docker-deploy.zip
cp example.env .env

（2）Docker 环境配置（可选）

• 修改数据目录：若内部空间不够，可修改 Docker 镜像路径至 SD Card。创建 /mnt/sdcard/docker_data 目录后，修改 /lib/systemd/system/docker.service，在 ExecStart 后面添加 -data-root=/mnt/sdcard/docker_data 并重启服务。请务必确保 SD Card 已配置开机自动挂载。
• 设置 Docker 代理：若由于网络问题无法访问外部镜像，可为 Docker 添加 HTTP/HTTPS 代理配置（写入 /etc/systemd/system/docker.service.d/http-proxy.conf 并重启服务）或直接改用国内镜像源。

（3）导入并启动镜像（必做）

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

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

• 可通过 docker ps 查看容器状态。若长时间处于 "starting" 状态，建议使用 docker logs immich_server --tail 20 等命令排查启动日志。
• 启动正常后，通过浏览器访问 http://<开发板IP>:2283 即可进入网页端进行注册和登录。

3. 机器学习 (ML) 服务部署

（1）配置 Python 虚拟环境（可选）

• 若主存储空间不够，可安装 python3.11-venv 并在 SD Card 上创建虚拟环境 /mnt/sdcard/immich_venv 以节省空间。

apt-get install -y python3.11-venv
python3.11 -m venv /mnt/sdcard/immich_venv

（2）安装 ML 依赖包（必做）

• 可根据自身情况选择直接全局安装或进入虚拟环境安装(二选一)，建议使用虚拟环境。

全局安装：

#注意安装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

虚拟环境安装

为了避免存储不够，安装时可通过 TMPDIR 和 -cache-dir 参数将临时文件与缓存放到 SD Card 上。

# 激活虚拟环境（若使用了venv）
source /mnt/sdcard/immich_venv/bin/activate

# 安装依赖
TMPDIR=/mnt/sdcard pip install -r requirements.txt --cache-dir /mnt/sdcard/.pip_cache

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

#安装Wheel包
TMPDIR=/mnt/sdcard pip install immich_ml-2.7.5-py3-none-any.whl --cache-dir /mnt/sdcard/.pip_cache

PyAXEngine最新版本获取：PyAXEngine GitHub

（3） 启动 ML 服务（必做）

• 算力卡检测：若需要使用算力卡，通过指令 axcl-smi 确定算力卡是否正常，可见类似输出:

root@ax650:/opt/bin/axcl# ./axcl-smi
+------------------------------------------------------------------------------------------------+
| AXCL-SMI  V3.15.0_20260609020154                                Driver  V3.15.0_20260609020154 |
+-----------------------------------------+--------------+---------------------------------------+
| Card  Name                     Firmware | Bus-Id       |                          Memory-Usage |
| Fan   Temp                Pwr:Usage/Cap | CPU      NPU |                             CMM-Usage |
|=========================================+==============+=======================================|
|    0  AX8850                    V3.15.0 | 0001:81:00.0 |                148 MiB /      945 MiB |
|   --   39C                      -- / -- | 1%        0% |                 18 MiB /     7040 MiB |
+-----------------------------------------+--------------+---------------------------------------+

+------------------------------------------------------------------------------------------------+
| Processes:                                                                                     |
| Card      PID  Process Name                                                   NPU Memory Usage |
|================================================================================================|

• 启动immich_ml服务:激活对应的 Python 环境，配置主机与端口信息后启动 immich_ml 服务(若使用虚拟环境需要注意是否处于虚拟环境中)。

标准启动：

IMMICH_HOST=0.0.0.0 IMMICH_PORT=3003 python -m immich_ml

指定缓存目录启动方式（推荐空间不足者使用）：

若需进一步节省根分区空间，可指定 MACHINE_LEARNING_CACHE_FOLDER 与 HF_HOME 环境变量将模型缓存存放至 SD Card。

mkdir -p /mnt/sdcard/immich_ml_cache /mnt/sdcard/huggingface
MACHINE_LEARNING_CACHE_FOLDER=/mnt/sdcard/immich_ml_cache HF_HOME=/mnt/sdcard/huggingface IMMICH_HOST=0.0.0.0 IMMICH_PORT=3003 python -m immich_ml

使用本地模型启动（推荐网络无法访问者使用）：

immich在启动ml服务时，会通过网络检测有无模型更新需求，若无法访问网络，可以获取模型后使用本地模型启动。

如若使用CN-CLIP-L/14-336 (Chinese)模型，拉取模型放到模型目录（实际目录可根据immich_ml日志进行查看），可能目录如下：

#采用标准启动，可能路径为:
/root/.cache/immich_ml/clip/ViT-L-14-336-CN__axera
 
#指定目录启动，根据目录路径进行查找，比如：
/mnt/sdcard/immich_ml_cache/clip/ViT-L-14-336-CN__axera

指定 HF_HUB_OFFLINE=1 进行启动，如:

HF_HUB_OFFLINE=1 IMMICH_HOST=0.0.0.0 IMMICH_PORT=3003 python -m immich_ml

4. 功能验证与设置

（1）查询网关 IP：

在宿主机通过命令 docker network inspect immich_default | grep Gate 查看 IP（通常类似于 172.19.0.1）。

（2）配置 ML 服务：

登录 Immich 网页端，点击左上角头像，选择Administration，进入设置，选择机器学习设置，配置上一步获取到的 IP，并填写模型，如填为ViT-L-14-336-CN__axera。

（3）上传与测试：

• 在网页端上传图片
• 创建智能搜索任务
• 任务处理完毕后，执行智能搜索以验证 ML 服务是否正常解析图像特征。

（4）APP测试

• 下载app，并使手机在同一网络环境下
• 填写ip和账号密码进入
• 进行智能搜索

六、性能评估

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

AX650板卡采用 AxEngineExecutionProvider，处理182张图片。

智能搜索任务处理期间观察到的资源占用峰值约为：

• CPU：整机总 CPU 约 5%～6%
• MEM：约 1.5～1.6 GiB
• CMM：约 600 MiB