Immich

High performance self-hosted photo and video management solution

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

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)
- M.2 Accelerator card

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:

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:

lspci | grep -i axera

Expected output:

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

Key steps include:

Update Raspberry Pi firmware and enable PCIe:

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:

sudo apt install ./axcl_host_aarch64_Vxxx.deb

Source environment variables:

source /etc/profile

Install PyAXEngine (Python NPU Runtime)

Refer to the PyAXEngine documentation:

PyAXEngine GitHub

Install the Python wheel package for NPU inference:

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:

axcl-smi

You should see output similar to:

(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/

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

immich docs

For more usage information about Immich, please refer to the Immich documentation.

Downloads last month: 7