| --- |
| license: agpl-3.0 |
| language: |
| - en |
| - zh |
| pipeline_tag: zero-shot-image-classification |
| tags: |
| - 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)](https://wiki.sipeed.com/hardware/zh/maixIV/m4ndock/m4ndock.html) |
| - [**M.2 Accelerator card**](https://axcl-docs.readthedocs.io/zh-cn/latest/doc_introduction.html#id4) |
|
|
| # 四、支持模型 |
|
|
| 在 Immich 项目中，CLIP 模型是实现智能相册功能且计算需求最高的核心组件。为了进一步提升识别准确率，我们采用了参数量更大的模型：**CLIP-L/14-336** 和 **CN-CLIP-L/14-336**。 |
|
|
| 针对爱芯元智（Axera）AI 加速卡优化后的预编译模型，可参考以下版本获取： |
|
|
| - [**CLIP-L/14-336 (English)**](https://huggingface.co/AXERA-TECH/ViT-L-14-336__axera) |
| - [**CN-CLIP-L/14-336 (Chinese)**](https://huggingface.co/AXERA-TECH/ViT-L-14-336-CN__axera) |
| # 五、部署操作 |
|
|
| ## **1. 系统配置与代码获取** |
|
|
| ### （1）前置准备与依赖安装（必做） |
|
|
| 在开始部署前，必须更新系统并安装核心依赖组件。 |
| ```bash |
| apt-get update |
| apt-get install -y unzip libgl1 |
| ``` |
|
|
| ### **扩充存储空间（可选）** |
| - **挂载 SD Card**：若系统内部空间不够，可选择挂载 SD Card 来存放数据。首先需将 SD Card 格式化为 `ext4` 格式并挂载。 |
| ```bash |
| 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 目录）。 |
|
|
| ```bash |
| apt-get install git-lfs |
| git clone https://huggingface.co/AXERA-TECH/immich |
| ``` |
|
|
| - **方案二：使用 HuggingFace**：若 Git 因为网络问题导致拉取失败，可安装 `huggingface_hub` 工具并使用 `hf download` 进行本地下载。 |
|
|
| ```bash |
| 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` 环境变量文件。 |
|
|
| ```bash |
| 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 启动容器服务。 |
|
|
| ```bash |
| 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` 以节省空间。 |
|
|
| ```bash |
| apt-get install -y python3.11-venv |
| python3.11 -m venv /mnt/sdcard/immich_venv |
| ``` |
|
|
| ### （2）安装 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 |
| ``` |
|
|
| **虚拟环境安装** |
|
|
| 为了避免存储不够，安装时可通过 `TMPDIR` 和 `-cache-dir` 参数将临时文件与缓存放到 SD Card 上。 |
|
|
| ```bash |
| # 激活虚拟环境（若使用了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**](https://github.com/AXERA-TECH/pyaxengine) |
|
|
| ### （3） 启动 ML 服务（必做） |
|
|
| - **算力卡检测**：若需要使用算力卡，通过指令 axcl-smi 确定算力卡是否正常，可见类似输出: |
|
|
| ```bash |
| 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` 服务(若使用虚拟环境需要注意是否处于虚拟环境中)。 |
| |
| **标准启动：** |
|
|
| ```bash |
| IMMICH_HOST=0.0.0.0 IMMICH_PORT=3003 python -m immich_ml |
| ``` |
|
|
| **指定缓存目录启动方式（推荐空间不足者使用）：** |
|
|
| 若需进一步节省根分区空间，可指定 `MACHINE_LEARNING_CACHE_FOLDER` 与 `HF_HOME` 环境变量将模型缓存存放至 SD Card。 |
|
|
| ```bash |
| 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)**](https://huggingface.co/AXERA-TECH/ViT-L-14-336-CN__axera)模型，拉取模型放到模型目录（实际目录可根据immich_ml日志进行查看），可能目录如下： |
| |
| ```bash |
| #采用标准启动，可能路径为: |
| /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` 进行启动，如: |
| |
| ```bash |
| 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 |
