Update README.md

README.md

@@ -1,3 +1,260 @@
----
-license: agpl-3.0
----
+---
+license: agpl-3.0
+language:
+- en
+- zh
+pipeline_tag: zero-shot-image-classification
+tags:
+- immich
+---
+
+
+# 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 
+
+- 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.
+
+## Reference Links  
+
+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_guide_hardware.html)
+
+## Support Models
+
+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:
+
+- [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
+
+| 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 |
+
+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.
+
+
+## How to use
+
+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.
+
+### Hardware Setup
+Ensure the following hardware is properly configured:
+
+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
+lspci | grep -i axera
+```
+
+Expected output:
+
+```text
+0001:01:00.0 Multimedia controller: Axera Semiconductor Co., Ltd Device 0650 (rev 01)
+```
+
+### Software Environment Setup
+Follow these steps to prepare the software environment on Raspberry Pi 5 (or other supported platforms):
+
+#### Install AXCL Driver (Host-side)
+Refer to the official AXCL documentation for detailed instructions:
+
+[AXCL Setup Guide - Raspberry Pi 5](https://axcl-docs.readthedocs.io/zh-cn/latest/doc_guide_setup.html#raspberry-pi-5)
+
+Key steps include:
+
+Update Raspberry Pi firmware and enable PCIe:
+```bash
+sudo rpi-eeprom-update -a
+```
+
+Modify /boot/firmware/config.txt to enable PCIe:
+
+```
+dtparam=pciex1
+[all]
+dtoverlay=pciex1-compat-pi5,no-mip
+```
+
+Reboot and verify device detection using lspci.
+Install the AXCL .deb package:
+```bash
+sudo apt install ./axcl_host_aarch64_Vxxx.deb
+```
+
+Source environment variables:
+```bash
+source /etc/profile
+```
+
+#### Install PyAXEngine (Python NPU Runtime)
+Refer to the PyAXEngine documentation:
+
+[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
+```
+
+#### Verification: Check Installation Status
+After completing the setup, run the following command to verify that the accelerator card is recognized and functioning:
+
+```bash
+axcl-smi
+```
+
+You should see output similar to:
+
+```text
+(base) axera@raspberrypi:~/samples/immich $ axcl-smi
++------------------------------------------------------------------------------------------------+
+| AXCL-SMI  V3.6.4_20250819020149                                  Driver  V3.6.4_20250819020149 |
++-----------------------------------------+--------------+---------------------------------------+
+| 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 |
++-----------------------------------------+--------------+---------------------------------------+
+
++------------------------------------------------------------------------------------------------+
+| Processes:                                                                                     |
+| 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
+
+Download
+
+```
+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
+
+```
+(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
+```
+
+#### 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
+```
+
+the following is
+
+```
+(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
+```
+
+#### Setup ml_immich
+
+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
+```
+
+the following is
+
+```
+(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']
+```
+
+### Run
+
+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
+
+```
+http://10.126.33.241:2283/
+```
+
+![](asset/login.png)
+
+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.
+
+### Enable the Smart Search
+
+![](asset/settings.png)
+
+![](asset/settings-machine-learning-01.png)
+
+![](asset/settings-machine-learning-02.png)
+
+![](asset/mission-01.png)
+
+![](asset/axcl-status.png)
+
+![](asset/text-to-image-retrieva-01.png)
+
+![](asset/text-to-image-retrieva-02.png)
+
+## immich docs
+
+For more usage information about Immich, please refer to the [Immich documentation](https://docs.immich.app/overview/quick-start/).
+