Update README.md

README.md

@@ -8,152 +8,180 @@ tags:
 - immich
 ---
 
+# 一、项目简介
 
-# Immich
+Immich 是一款支持本地 AI 检索与多端备份的开源自托管智能相册。将其深度适配并独立部署在 AX650 边缘算力板卡上，可让所有照片数据与 AI 推理均在本地物理隔离运行，从而实现100%的数据主权与最高级别的隐私安全保障。
 
+**原项目官方资源：**
 
-<p align="center">
-<img src="asset/immich-logo.png" width="300" title="Login With Custom URL">
-</p>
-<h3 align="center">High performance self-hosted photo and video management solution</h3>
-<br/>
-<a href="https://immich.app">
-<img src="asset/immich-screenshots.png" title="Main Screenshot">
-</a>
-<br/>
-<p align="center">
+- 官方网站：https://immich.app/
+- GitHub 仓库：https://github.com/immich-app/immich
 
-Immich is an open-source intelligent photo album application that allows you to easily back up, organize, and manage your photos on your own server. 
-Immich helps you browse, search, and organize your photos and videos with ease, without compromising your privacy. 
-For the original project's official website and GitHub repository, please visit 
+本项目的目标是演示如何在AX650开发平台上部署 Immich，部署后可直接使用**AX650板卡**，或者外接 **AX650 AI 算力卡** 进行使用。
 
-- https://immich.app/
-- https://github.com/immich-app/immich.
+# 二、参考链接
 
-The goal of our project is to demonstrate deploying Immich on Raspberry Pi 5 or other x86-based main control platforms, extended with AX650N/AX8850 AI acceleration cards. 
-By leveraging these accelerator cards for computational offloading, we aim to enhance Immich's efficiency in processing photos.
-Through this example, we hope to guide Immich users in expanding high-efficiency deployments of Immich across a broader range of hardware platforms by adding dedicated AI accelerator cards.
+我们已将针对 Immich 代码库的修改版本在 GitHub 上开源，目前版本对齐immich最新版本v2.7.5：
 
-## Reference Links  
+- **开源仓库**：https://github.com/AXERA-TECH/immich/tree/ax650-v2.7.5
 
-We have open-sourced the modifications to the Immich codebase on GitHub: https://github.com/ZHEQIUSHUI/immich
+# 三、支持平台
 
-## Support Platform
+- **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)
 
-- 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)
+# 四、支持模型
 
-## Support Models
+在 Immich 项目中，CLIP 模型是实现智能相册功能且计算需求最高的核心组件。为了进一步提升识别准确率，我们采用了参数量更大的模型：**CLIP-L/14-336** 和 **CN-CLIP-L/14-336**。
 
-In the Immich project, the CLIP model is the primary component with high computational demands for smart album features. To further improve accuracy, 
-we have adopted larger-parameter models: **CLIP-L/14-336** and **CN-CLIP-L/14-336**. Precompiled models optimized for Axera AI accelerator cards are available at the following links:
+针对爱芯元智（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)
+- [**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)
+# 五、部署操作
 
-### Performance Benchmarks
+## **1. 系统配置与代码获取**
 
-| Model | Input Shape | Latency (ms) | CMM Usage (MB) |
-|-------|-------------|--------------|----------------|
-| `cnclip_vit_l14_336px_vision_u16u8.axmodel` | 1 x 3 x 336 x 336 | 88.475 ms | 304 MB |
-| `cnclip_vit_l14_336px_text_u16.axmodel` | 1 x 52 | 4.576 ms | 122 MB |
+### （1）前置准备与依赖安装（必做）
 
-These models enable significantly faster image and text embedding generation on Axera-powered hardware, 
-greatly enhancing Immich's photo tagging, search, and organization capabilities while maintaining high accuracy.
+在开始部署前，必须更新系统并安装核心依赖组件。
+```bash
+apt-get update
+apt-get install -y unzip libgl1
+```
 
+### **扩充存储空间（可选）**
+- **挂载 SD Card**：若系统内部空间不够，可选择挂载 SD Card 来存放数据。首先需将 SD Card 格式化为 `ext4` 格式并挂载。
+```bash
+lsblk
 
-## How to use
+#格式化SD Card 注意保存数据
+# mkfs.ext4 /dev/mmcblk1p1
 
-We use the Raspberry Pi 5—a platform with one of the largest user bases—as our example for demonstration. 
-However, the setup process can also be referenced and adapted for other aarch64 or x86 host platforms.
+mkdir /mnt/sdcard
+mount /dev/mmcblk1p1 /mnt/sdcard
+```
 
-### Hardware Setup
+- **配置开机自动挂载**：通过 `blkid /dev/mmcblk1p1` 获取 UUID 后，修改 `/etc/fstab` 文件以实现开机自启。配置示例如 `UUID=13054439-9d76-47ca-b8ed-c7cd8d208a5d /mnt/sdcard ext4 defaults 0 2`。
 
-![](asset/rpi5-with-m.2-card.png)
+### （3） 获取部署代码（必做）
 
-Ensure the following hardware is properly configured:
+- **方案一：使用 Git**：安装 `git-lfs` 后，直接从 HuggingFace 拉取代码仓库（空间不足时可选择拉取至 SD Card 目录）。
 
-A Raspberry Pi 5 with an M.2 AI accelerator card (e.g., AX650N) correctly installed.
-Use a compatible M.2 HAT+ expansion board that supports 2280-length cards (most AX650 cards are 2280).
-Confirm that the PCIe connection is active by checking with lspci:
+```bash
+apt-get install git-lfs
+git clone https://huggingface.co/AXERA-TECH/immich
+```
 
+- **方案二：使用 HuggingFace**：若 Git 因为网络问题导致拉取失败，可安装 `huggingface_hub` 工具并使用 `hf download` 进行本地下载。
 
 ```bash
-lspci | grep -i axera
-```
+apt-get install -y python3.11
 
-Expected output:
+#若无法直接访问 可使用国内代理
+export HF_ENDPOINT=https://hf-mirror.com
 
-```text
-0001:01:00.0 Multimedia controller: Axera Semiconductor Co., Ltd Device 0650 (rev 01)
+pip install -U huggingface_hub
+hf download AXERA-TECH/immich --local-dir .
 ```
 
-### Software Environment Setup
-Follow these steps to prepare the software environment on Raspberry Pi 5 (or other supported platforms):
+## 2. Docker 服务部署
 
-#### Install AXCL Driver (Host-side)
-Refer to the official AXCL documentation for detailed instructions:
+### （1） 解压配置文件（必做）
 
-[AXCL Setup Guide - Raspberry Pi 5](https://axcl-docs.readthedocs.io/zh-cn/latest/doc_guide_setup.html#raspberry-pi-5)
+- 进入拉取的 `immich` 代码目录，解压部署文件并创建 `.env` 环境变量文件。
 
-Key steps include:
-
-Update Raspberry Pi firmware and enable PCIe:
 ```bash
-sudo rpi-eeprom-update -a
+cd immich
+unzip -o docker-deploy.zip
+cp example.env .env
 ```
 
-Modify /boot/firmware/config.txt to enable PCIe:
+### （2）Docker 环境配置（可选）
 
-```
-dtparam=pciex1
-[all]
-dtoverlay=pciex1-compat-pi5,no-mip
-```
+- **修改数据目录**：若内部空间不够，可修改 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 启动容器服务。
 
-Reboot and verify device detection using lspci.
-Install the AXCL .deb package:
 ```bash
-sudo apt install ./axcl_host_aarch64_Vxxx.deb
+docker load -i ax-immich-server-aarch64.tar.gz
+docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
 ```
 
-Source environment variables:
+- 可通过 `docker ps` 查看容器状态。若长时间处于 "starting" 状态，建议使用 `docker logs immich_server --tail 20` 等命令排查启动日志。
+- 启动正常后，通过浏览器访问 `http://<开发板IP>:2283` 即可进入网页端进行注册和登录。
+
+![image](https://cdn-uploads.huggingface.co/production/uploads/6a2ba64ddd73738eacc6ef57/d8BRCXOlN5j7ZCrtf8XB9.png)
+## 3. 机器学习 (ML) 服务部署
+
+### （1）配置 Python 虚拟环境（可选）
+
+- 若主存储空间不够，可安装 `python3.11-venv` 并在 SD Card 上创建虚拟环境 `/mnt/sdcard/immich_venv` 以节省空间。
+
 ```bash
-source /etc/profile
+apt-get install -y python3.11-venv
+python3.11 -m venv /mnt/sdcard/immich_venv
 ```
 
-#### Install PyAXEngine (Python NPU Runtime)
-Refer to the PyAXEngine documentation:
+### （2）安装 ML 依赖包（必做）
 
-[PyAXEngine GitHub](https://github.com/AXERA-TECH/pyaxengine)
+- 可根据自身情况选择直接**全局安装**或进入**虚拟环境安装**(二选一)，建议使用虚拟环境。
 
-Install the Python wheel package for NPU inference:
+**全局安装：**
 
 ```bash
-pip install axengine-x.x.x-py3-none-any.whl
+#注意安装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
 ```
 
-#### Verification: Check Installation Status
-After completing the setup, run the following command to verify that the accelerator card is recognized and functioning:
+**虚拟环境安装**
+
+为了避免存储不够，安装时可通过 `TMPDIR` 和 `-cache-dir` 参数将临时文件与缓存放到 SD Card 上。
 
 ```bash
-axcl-smi
+# 激活虚拟环境（若使用了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
 ```
 
-You should see output similar to:
+PyAXEngine最新版本获取：[**PyAXEngine GitHub**](https://github.com/AXERA-TECH/pyaxengine)
 
-```text
-(base) axera@raspberrypi:~/samples/immich $ axcl-smi
+### （3） 启动 ML 服务（必做）
+
+- **算力卡检测**：若需要使用算力卡，通过指令 axcl-smi 确定算力卡是否正常，可见类似输出:
+
+```bash
+root@ax650:/opt/bin/axcl# ./axcl-smi
 +------------------------------------------------------------------------------------------------+
-| AXCL-SMI  V3.6.4_20250819020149                                  Driver  V3.6.4_20250819020149 |
+| 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  AX650N                     V3.6.4 | 0001:01:00.0 |                164 MiB /      945 MiB |
-|   --   41C                      -- / -- | 1%        0% |                 18 MiB /     7040 MiB |
+|    0  AX8850                    V3.15.0 | 0001:81:00.0 |                148 MiB /      945 MiB |
+|   --   39C                      -- / -- | 1%        0% |                 18 MiB /     7040 MiB |
 +-----------------------------------------+--------------+---------------------------------------+
 
 +------------------------------------------------------------------------------------------------+
@@ -161,117 +189,86 @@ You should see output similar to:
 | Card      PID  Process Name                                                   NPU Memory Usage |
 |================================================================================================|
 ```
-If you see the AX650N card listed with valid memory usage, your hardware and software setup is successful.
 
-### Setup
+- **启动immich_ml服务**:激活对应的 Python 环境，配置主机与端口信息后启动 `immich_ml` 服务(若使用虚拟环境需要注意是否处于虚拟环境中)。
 
-Download
+**标准启动：**
 
+```bash
+IMMICH_HOST=0.0.0.0 IMMICH_PORT=3003 python -m immich_ml
 ```
-hf download AXERA-TECH/immich --local-dir AXERA-TECH/immich
-cd AXERA-TECH/immich
-```
-
-#### Setup immich server
 
-```
-sudo docker load -i ax-immich-server-aarch64.tar.gz
-unzip docker-deploy.zip
-cp example.env .env
-sudo docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
-```
+**指定缓存目录启动方式（推荐空间不足者使用）：**
 
-the following is
+若需进一步节省根分区空间，可指定 `MACHINE_LEARNING_CACHE_FOLDER` 与 `HF_HOME` 环境变量将模型缓存存放至 SD Card。
 
-```
-(immich) axera@raspberrypi:~/samples/immich $ sudo docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
-WARN[0000] /home/axera/samples/immich/docker-compose.override.yml: the attribute `version` is obsolete, it will be ignored, p                                               lease remove it to avoid potential confusion
-[+] Running 3/3
- ✔ Container immich_redis     Running                                                                                   0.0s
- ✔ Container immich_postgres  Started                                                                                   1.8s
- ✔ Container immich_server    Started                                                                                   1.3s
+```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
 ```
 
-#### Download clip axmodel
+**使用本地模型启动（推荐网络无法访问者使用）：**
 
-```
-cd ~/.cache/immich_ml/clip
-hf download AXERA-TECH/ViT-L-14-336-CN__axera --local-dir ViT-L-14-336-CN__axera
-```
+immich在启动ml服务时，会通过网络检测有无模型更新需求，若无法访问网络，可以获取模型后使用本地模型启动。
 
-the following is
+如若使用[**CN-CLIP-L/14-336 (Chinese)**](https://huggingface.co/AXERA-TECH/ViT-L-14-336-CN__axera)模型，拉取模型放到模型目录（实际目录可根据immich_ml日志进行查看），可能目录如下：
 
-```
-(base) axera@raspberrypi:~/.cache/immich_ml/clip $ tree
-.
-├── ViT-L-14-336-CN__axera
-    ├── config.json
-    ├── textual
-    │   ├── merges.txt
-    │   ├── model.axmodel
-    │   ├── special_tokens_map.json
-    │   ├── tokenizer_config.json
-    │   ├── tokenizer.json
-    │   └── vocab.json
-    └── visual
-        ├── model.axmodel
-        └── preprocess_cfg.json
+```bash
+#采用标准启动，可能路径为:
+/root/.cache/immich_ml/clip/ViT-L-14-336-CN__axera
+ 
+#指定目录启动，根据目录路径进行查找，比如：
+/mnt/sdcard/immich_ml_cache/clip/ViT-L-14-336-CN__axera
 ```
 
-#### Setup ml_immich
+指定 `HF_HUB_OFFLINE=1` 进行启动，如:
 
-Run the HTTP service of immich independently.
-
-```
-pip install -r requirements.txt
-pip install immich_ml-1.129.0-py3-none-any.whl
-python -m immich_ml
+```bash
+HF_HUB_OFFLINE=1 IMMICH_HOST=0.0.0.0 IMMICH_PORT=3003 python -m immich_ml
 ```
 
-the following is
+## 4. 功能验证与设置
 
-```
-(immich) axera@raspberrypi:~/samples/immich $ python -m immich_ml
-[10/08/25 11:11:40] INFO     Starting gunicorn 23.0.0
-[10/08/25 11:11:40] INFO     Listening at: http://[::]:3003 (3145057)
-[10/08/25 11:11:40] INFO     Using worker: immich_ml.config.CustomUvicornWorker
-[10/08/25 11:11:40] INFO     Booting worker with pid: 3145062
-[INFO] Available providers:  ['AXCLRTExecutionProvider']
-```
+### **（1）查询网关 IP**：
 
-### Run
+在宿主机通过命令 `docker network inspect immich_default | grep Gate` 查看 IP（通常类似于 `172.19.0.1`）。
 
-If the above setup completes successfully, and assuming your Raspberry Pi's IP address is 10.126.33.241, 
-you can access the Immich login page by opening a browser on any device within the same local network and navigating to
+### **（2）配置 ML 服务**：
 
-```
-http://10.126.33.241:2283/
-```
 
-![](asset/login.png)
+登录 Immich **网页端**，点击左上角**头像**，选择**Administration**，进入**设置**，选择**机器学习设置**，配置上一步获取到的 IP，并填写模型，如填为`ViT-L-14-336-CN__axera`。
+
+![image](https://cdn-uploads.huggingface.co/production/uploads/6a2ba64ddd73738eacc6ef57/77IMPafinxzYWfhYjsJkU.png)
+### **（3）上传与测试**：
 
-On first access, you will be prompted to register a new user account. Don't worry — everything runs offline on your Raspberry Pi. 
-If this is just for a demo or testing purpose, feel free to enter any username and password.
+- 在网页端上传图片
+- 创建智能搜索任务
+- 任务处理完毕后，执行智能搜索以验证 ML 服务是否正常解析图像特征。
+  
 
-### Enable the Smart Search
+![image](https://cdn-uploads.huggingface.co/production/uploads/6a2ba64ddd73738eacc6ef57/P9TVpPWFOW62O5zUrH27K.png)
 
-![](asset/settings.png)
+![image](https://cdn-uploads.huggingface.co/production/uploads/6a2ba64ddd73738eacc6ef57/HrcRSzh7o5lPnlQbtcaaa.png)
 
-![](asset/settings-machine-learning-01.png)
 
-![](asset/settings-machine-learning-02.png)
+![image](https://cdn-uploads.huggingface.co/production/uploads/6a2ba64ddd73738eacc6ef57/KwegGQkRcRYkYaBX9Vb21.png)
 
-![](asset/mission-01.png)
+### （4）APP测试
 
-![](asset/axcl-status.png)
+- 下载app，并使手机在同一网络环境下
+- 填写ip和账号密码进入
+- 进行智能搜索
 
-![](asset/deduplication.png)
+![image](https://cdn-uploads.huggingface.co/production/uploads/6a2ba64ddd73738eacc6ef57/nlsUEPdd6eSynshNTFr9V.png)
 
-![](asset/text-to-image-retrieval-01.png)
+# 六、性能评估
 
-![](asset/text-to-image-retrieval-02.png)
+在当前测试场景下，Immich 服务由 Docker 中的 `server/postgres/redis` 与宿主机 `immich_ml` 组成。由于模型懒加载、运行时缓存、数据库缓存以及AX CMM 分配策略等因素，MEM与 CMM 占用会受操作影响。
 
-## immich docs
+AX650板卡采用 `AxEngineExecutionProvider`，处理182张图片。
 
-For more usage information about Immich, please refer to the [Immich documentation](https://docs.immich.app/overview/quick-start/).
+智能搜索任务处理期间观察到的资源占用峰值约为：
 
+- CPU：整机总 CPU 约 5%～6%
+- MEM：约 1.5～1.6 GiB
+- CMM：约 600 MiB