Immich智能相册在树莓派5上的高效部署与优化

TL;DR

将海外广受欢迎的开源智能相册项目Immich部署于树莓派5上，并通过搭载基于AX650N/AX8850的M.2算力卡，显著提升了系统算力。借助该方案，我们高效部署了多模态模型CLIP，有效缓解了仅依赖树莓派5本体运行时CPU资源占用过高的瓶颈，大幅提升了“以文搜图”功能的响应速度与使用体验。

为何推荐采用M.2形态的算力卡？原因在于，目前绝大多数NAS设备均内置M.2 2280接口，主要用于安装高速SSD缓存或存储盘。利用这一通用接口扩展AI算力模块，不仅无需额外供电或外接设备，还能实现算力升级与存储扩展的兼容共存，具备极佳的硬件兼容性与部署灵活性。这种“即插即用”的升级方式，为边缘设备赋能AI能力提供了高效、低成本的解决方案。

01背景

今年下半年，随着业务推广需求增加，我们的大模型适配工作也有了新方向：不再只追求前沿模型的快速适配，而是更聚焦为销售团队提供具备实战价值的解决方案，即贴近客户刚需、可快速落地的大模型应用。

因此，接下来的技术分享会更聚焦在基于我司边缘AI芯片（如AX650/AX8850）的实际应用落地，帮助客户实现从Demo到量产的跨越。

其中一个重点场景就是：AI NAS产品应用。

自2025年下半年以来，NAS行业正加速向“AI NAS”演进，开启智能化升级的新阶段。作为产品经理，我们在调研中提炼出一系列面向家庭与个人用户的“智能内容管理”需求，涵盖图像、音频、视频等多个维度，推动NAS从传统的数据存储中心向AI内容中枢转型。

图像类功能（已整合至智能相册场景）：

自然语言检索图片（以文搜图）

智能去重与相似图识别

老照片修复与图像超分辨率

时光缩影（自动生成回忆视频）

音频类功能：

音质增强与降噪

歌词自动匹配与生成

会议录音转录与摘要

视频类功能：

视频超分与画质增强

运动插帧提升流畅度

自动生成字幕并支持多语言翻译

在构建智能相册能力的过程中，综合考虑社区活跃度、功能完整性、扩展性与部署复杂度，最终选定Immich。Immich不仅支持高质量的照片与视频备份，还内置了基于CLIP模型的语义检索能力，是实现“以文搜图”的理想基础平台。

然而，在将Immich部署于树莓派5等端侧设备时，我们发现其默认使用CPU运行CLIP模型会导致资源占用过高，响应延迟明显，严重影响用户体验。为此，我们引入基于AX650N/AX8850芯片的M.2算力卡，通过硬件卸载方式将多模态推理任务从主CPU转移至NPU，显著降低系统负载，提升检索效率。

本文将简要介绍Immich的核心功能，并重点分享如何利用M.2算力卡实现CLIP模型的高效推理部署，拓展Immich在低功耗边缘设备上的适用场景，为AI NAS的本地化智能演进提供可行路径。

02Immich

自托管的照片和视频管理解决方案。可以轻松的部署在自己的服务器（x86 mini PC或者树莓派5）上，实现备份、整理和管理自己的照片。Immich帮助便捷地浏览、搜索和管理照片与视频，由于是私有化部署，因此完全不用担心隐私风险。

官方网站：https://immich.app/

官方文档：https://docs.immich.app/overview/quick-start/

GitHub项目：https://GitHub.com/immich-app/immich

架构浅析

Immich其实是比较复杂的项目，在本文中只做最基本的探讨，主要是为了引出AI模型在什么位置，详细的架构说明请参考https://docs.immich.app/developer/architecture

Immich采用传统的客户端-服务器架构，并使用专用数据库进行数据持久化。前端客户端通过HTTP使用REST API与后端服务进行通信。以下是该架构的高层级示意图。

示意图展示了客户端通过REST与服务器的API进行通信的过程。服务器则通过仓库接口与下游系统（如Redis，Postgres，Machine Learning，file system）进行通信。图中未显示的是，服务器被拆分为两个独立的容器：immich-server和immich-microservices。微服务容器不处理API请求或安排定时任务，而主要是处理来自Redis的传入作业请求。

Immich后端被划分为多个服务，每个服务作为独立的Docker容器运行。

immich-server-负责处理和响应REST API请求，执行后台作业（如缩略图生成、元数据提取、转码等）。

immich-machine-learning-执行机器学习模型。

postgres-用于持久化数据存储。

Redis-管理后台作业的任务队列。

这些容器协同工作以提供Immich的完整功能。

Machine Learning

（适配的核心工作）

Machine Learning服务使用Python编写，并通过FastAPI进行HTTP通信。

所有与Machine Learning相关的操作均已移至该独立服务（immich-machine-learning）。Python是人工智能和机器学习领域的自然选择，但它也对硬件有较为特定的要求。将其作为独立容器运行，使得该容器可以在单独的机器上部署，或根据需要轻松地完全禁用。

对机器学习服务的每个请求都包含与模型任务、模型名称等相关元数据。这些设置与其他系统配置一同存储在Postgres数据库中。微服务容器在每次请求时会获取这些设置，并将其附加到请求中。

在服务内部，机器学习服务在处理文本或图像数据之前，会先为每个请求下载、加载并配置指定的模型。已加载的模型会被缓存，以便在后续请求中重复使用。服务使用线程池在不同线程中处理每个请求，以避免阻塞异步事件循环。

Immich官方仓库中，所有模型均采用ONNX格式。该格式在业界得到广泛支持，意味着大多数其他模型格式均可导出为ONNX，且许多硬件API也支持该格式。但是对于以文搜图这样的算法应用，Immich采用的是主流的CLIP模型，即使使用性能较强的消费级x86 CPU，运行较大的CLIP模型效率也较低。

因此，我们引入基于AX650N/AX8850的M.2算力卡，作为提升边缘推理性能的硬件加速方案。将“以文搜图”这类模型体积大、内存与算力需求高的任务，其运行负载卸载到M.2算力卡上。这样即使在性能较低的NAS主控产品上也能启用机器学习的服务，提升用户体验。我们始终在探索改进方法，以专门优化该容器在内存使用和性能方面的表现。

03示例展示

硬件方案

本方案选用在开发者社区中用户基础广泛、生态成熟的Raspberry Pi 5作为主控平台，部署开源智能相册系统Immich。树莓派5凭借其较强的计算性能、良好的Linux兼容性以及丰富的外设支持，为轻量级AI NAS应用提供了理想的边缘计算载体。

为进一步提升端侧AI推理能力，解决多模态模型（如CLIP）在CPU上运行时资源占用高、响应延迟大的问题，系统额外搭载了一块M.2 2242规格的AI算力卡（基于AX650N/AX8850等NPU芯片），用于卸载图像语义分析等高算力需求任务。该算力卡通过PCIe接口直连主控，具备低功耗、高能效比的特点，可在不增加系统复杂性的前提下显著提升本地推理性能。

采用M.2 2242形态而非更常见的2280，旨在适配更多紧凑型设备与HAT扩展板的空间限制，尤其适合树莓派生态中的小型化AI边缘部署场景。该设计也为未来在其他NAS平台实现“存储+算力”一体化扩展提供了参考路径。

https://docs.m5stack.com/zh_CN/ai_hardware/LLM-8850_Card

软件方案

为充分发挥M.2算力卡的AI加速能力，我们对immich-machine-learning服务进行了深度定制与扩展，核心在于集成对AXCL（Axera Compute Library）驱动的原生支持。通过引入Axera提供的NPU Python API，系统可在运行时直接调用部署于AX650N/AX8850芯片上的axmodel模型，实现高效、低延迟的本地化推理。

所有axmodel模型均通过Axera官方Pulsar2 NPU工具链，由标准ONNX模型转换而来，确保模型精度与推理性能的最优平衡。我们特别选用了更大规模的CLIP-L/14-336视觉-语言预训练模型，其参数量显著优于Immich默认的ViT-B/16等轻量模型。该模型基于Transformer架构，能够更精准地提取图像与文本的高层语义特征，在“以文搜图”任务中实现更高的召回率与语义匹配准确度。

为降低用户部署门槛，我们已将定制后的Immich服务打包为预编译的Docker镜像，并连同转换好的axmodel模型文件一并开源至Hugging Face。树莓派用户可直接拉取镜像并启动服务，无需手动编译或模型转换，即可在边缘设备上体验高性能的本地化AI图像检索能力。

该软件方案不仅验证了Immich在异构计算环境下的可扩展性，也为未来在更多NPU平台上实现开源AI NAS功能提供了可复用的技术路径。

https://huggingface.co/AXERA-TECH/immich

运行

在完成树莓派5的软硬件环境配置，并参考Hugging Face项目页面部署预编译的Docker镜像后，系统将自动启动Immich相关服务。

假设您的树莓派5分配到的局域网IP地址为10.126.33.241，您可通过任意设备上的浏览器访问以下地址：

http://10.126.33.241:2283/

首次访问时，系统会提示您注册一个新用户账户。请放心，所有数据都仅在您的树莓派上离线运行。如果仅用于演示或测试目的，您可以随意输入任意用户名和密码。

启用以文搜图功能。

这里需要显式地指定immich-machine-learning服务的IP地址和端口号，同时需要指明使用哪种CLIP模型。

同时也支持照片去重功能：通过对比图片的特征相似度差异来实现去重功能。

完成设置后记得保存。然后在任务状态栏就能发现后台已经在高效率地提取照片库中每一张图片的特征信息了。

图片去重也支持上了。

在执行任务过程中，我们可以通过树莓派5上的终端来查询算力卡的使用情况，图片中可以看出NPU使用率已经拉满了。由于M.2算力卡计算CLIP模型效率高，即使是本示例中使用的CLIP-L/14-336的模型，也能做到10+张/秒的高效率。所以很快就完成了所有的照片特征建档。

接下来就可以使用“以文搜图”的功能了。

输入“stop”：

输入“吃披萨的照片，拿着手机拍照”：

04总结

Immich是一个极具影响力的开源智能相册项目，其官方最新版本已推出适用于Android和iOS的移动客户端，用户可通过手机或平板便捷地连接并管理私有部署的Immich服务器，真正实现随时随地访问个人影像库。

同时我们会持续努力，将其更多的智能算法、视频编解码的功能迁移到M.2算力上，让Immich在树莓派等边缘设备上的运行更加流畅、高效，惠及更广泛的个人用户与开发者群体。

关于AI NAS的一些信息同步

最近2个月，我们针对AI NAS的智能化升级主动适配了以下功能，同时支持AX650N/AX8850主控与AXCL算力卡产品形态。

针对AI NAS产品，大家还想实现什么功能欢迎留言，我们尽可能实现。