README.md

---
license: agpl-3.0
language:
- en
- zh
pipeline_tag: zero-shot-image-classification
tags:
- immich
---


# Immich


<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">

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_introduction.html#id4)

## 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

![](asset/rpi5-with-m.2-card.png)

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/deduplication.png)

![](asset/text-to-image-retrieval-01.png)

![](asset/text-to-image-retrieval-02.png)

## immich docs

For more usage information about Immich, please refer to the [Immich documentation](https://docs.immich.app/overview/quick-start/).