Move Immich machine learning only when it solves a real bottleneck.
Immich can run the machine learning container on another machine. That is useful when the main server is short on RAM, CPU or supported acceleration hardware, but it also creates a new network service that must be protected and updated with the rest of the stack.
What remote ML changes
Immich's architecture separates machine learning into the immich-machine-learning service. In a remote setup, the Immich server sends image previews and model requests to a machine learning container running on another host. Immich states that the remote container does not persist that image preview data or associate it with a particular user, but those previews still cross the network.
The machine learning URL is managed in Immich's Machine Learning Settings. The built-in URL is configured by default, and administrators can change it or add additional servers. Hosting the container on a host with a more powerful GPU can help when processing many photos, such as during a batch import, or when faster search processing matters.
Decision table
| Situation | Recommended path | Planning note |
|---|---|---|
| 1-4TB family library on an 8GB+ mini PC | Keep ML local first. | Reduce moving parts until the job queue shows a real bottleneck. |
| 4GB RAM host or small NAS | Consider remote ML or disable selected ML features. | Immich says 4GB systems can run with ML disabled; remote ML may preserve search and face features. |
| Large first import | Add a remote ML URL with local fallback. | Batch imports can create heavy Smart Search and Face Detection jobs. |
| Separate workstation with supported GPU | Run remote ML on the stronger host. | Check Immich's hardware acceleration backend before assuming a GPU will help. |
| Public cloud or shared computer | Avoid unless you can strictly control access. | Immich warns the ML container is an internal service with no built-in security measures. |
Implementation sequence
- Record the current settings. Save the existing Machine Learning URL, enabled model types, Docker Compose version tag and any hardware acceleration files before changing production.
- Choose fallback behavior. Adding a new URL lets Immich fall back to the local ML container if the remote host is down. Replacing the existing URL forces remote processing and means Smart Search and Face Detection jobs fail when the remote instance is unavailable.
- Deploy only on a trusted network. Immich's guide exposes the ML service on port
3003. Treat that as an internal service, not a public endpoint. - Match versions. Immich warns that version mismatches between the local instance and remote ML container can cause bugs and instability. Update the remote container whenever the main Immich stack is updated.
- Add hardware acceleration only after checking support. Immich lists hardware-accelerated ML as experimental and backend-specific. Use the matching image tag and acceleration compose file only for supported hardware.
- Run missing jobs after changes. Check Smart Search and Face Detection job status after the move. If jobs failed while remote ML was unavailable, retry the missing jobs from the Job Status page.
Security boundary
Remote ML is not the same as exposing the Immich web app. It is a backend service designed for the Immich server to call. Immich's own warning is important: image previews are sent to the remote container, and the ML container has no security measures. Use LAN-only access, firewall rules, a private tunnel or another controlled private network before considering a separate host.
Do not place the ML endpoint directly on the public internet. Do not run it on a borrowed or public computer if the photo previews are sensitive. If you use a paid cloud machine for temporary processing, assume preview data leaves the home network during that window and document that choice.
Operations checklist
- Pin the remote host name or IP so Immich does not depend on a changing desktop address.
- Keep the remote
model-cachevolume so models do not download again after every restart. - Monitor job queues during imports, especially Smart Search, Face Detection, Duplicate Detection and Facial Recognition.
- Document whether the local ML container remains as fallback or has been removed to save resources.
- Test a planned reboot of the remote host and confirm Immich either falls back locally or reports failed jobs as expected.
- Include the remote ML host in update notes, but do not include it in media backup scope unless it stores other data.
Commercial and source note
This guide does not recommend a paid GPU host, mini PC model or cloud provider. The useful decision is whether remote ML reduces a measured bottleneck enough to justify extra operations and security work.
Estimate Immich capacity and host cost before splitting services →
只有真正解决瓶颈时，才把 Immich 机器学习拆出去。
Immich 可以把机器学习容器运行在另一台机器上。当主服务器内存、CPU 或受支持的加速硬件不足时，这很有用；但它也会新增一个需要保护、监控和同步更新的网络服务。
远程 ML 改变了什么
Immich 的架构把机器学习拆成 immich-machine-learning 服务。远程部署时，Immich 服务器会把图片预览和模型请求发送到另一台主机上的机器学习容器。Immich 说明远程容器不会持久化这些图片预览，也不会把它们与具体用户关联；但这些预览仍然会经过网络传输。
机器学习 URL 在 Immich 的机器学习设置中管理。默认会配置内置 URL，管理员可以修改它，也可以添加更多服务器。把容器放到 GPU 更强的主机上，可能有助于处理大量照片，例如首次批量导入，或需要更快搜索处理的场景。
决策表
| 情况 | 建议路径 | 规划说明 |
|---|---|---|
| 1-4TB 家庭图库，8GB 以上小主机 | 先保留本地 ML。 | 等任务队列显示真实瓶颈后，再增加复杂度。 |
| 4GB 内存主机或小型 NAS | 考虑远程 ML，或关闭部分 ML 功能。 | Immich 说明 4GB 系统可在关闭 ML 后运行；远程 ML 可能保留搜索和人脸功能。 |
| 大型首次导入 | 添加远程 ML URL，并保留本地回退。 | 批量导入会产生大量智能搜索和人脸检测任务。 |
| 有受支持 GPU 的工作站 | 把远程 ML 放在更强的主机上。 | 购买或迁移前，应先核对 Immich 的硬件加速后端。 |
| 公有云或共享电脑 | 除非能严格控制访问，否则不建议。 | Immich 提醒 ML 容器是没有内置安全措施的内部服务。 |
实施顺序
- 记录当前设置。 修改生产环境前，保存现有机器学习 URL、启用的模型类型、Docker Compose 版本标签和硬件加速文件。
- 选择回退行为。 添加新 URL 可以在远程主机不可用时回退到本地 ML 容器；替换现有 URL 则会强制远程处理，远程实例不可用时智能搜索和人脸检测任务会失败。
- 只部署在可信网络内。 Immich 指南中的 ML 服务端口为
3003。它应被视为内部服务，而不是公开端点。 - 保持版本一致。 Immich 警告本地实例和远程 ML 容器版本不一致可能导致错误和不稳定；升级主 Immich 栈时，也要升级远程容器。
- 先核对支持，再启用硬件加速。 Immich 将 ML 硬件加速标为实验性，并且依赖具体后端。只有硬件受支持时，才使用对应镜像标签和加速 compose 文件。
- 变更后运行缺失任务。 迁移后检查智能搜索和人脸检测任务状态。如果远程 ML 不可用期间有任务失败，需要在任务状态页面手动重试缺失任务。
安全边界
远程 ML 不等于公开 Immich 网页。它是给 Immich 服务器调用的后端服务。Immich 的警告很关键：图片预览会被发送到远程容器，而 ML 容器本身没有安全措施。考虑独立主机前，应先使用仅限局域网的访问、防火墙规则、私有隧道或其他受控私有网络。
不要把 ML 端点直接暴露到公网。若照片预览敏感，不要在借来的电脑或公共电脑上运行它。若临时使用付费云主机处理，应该把这视为预览数据在该窗口期离开家庭网络，并记录这个选择。
运维清单
- 固定远程主机名或 IP，避免 Immich 依赖经常变化的桌面地址。
- 保留远程
model-cache卷，避免每次重启都重新下载模型。 - 导入期间监控任务队列，特别是智能搜索、人脸检测、重复检测和人脸识别。
- 记录本地 ML 容器是保留为回退，还是为了节省资源已经移除。
- 测试一次计划内远程主机重启，确认 Immich 会按预期本地回退或报告失败任务。
- 把远程 ML 主机纳入升级记录；除非它存储其他数据，否则不需要把它纳入媒体备份范围。
商业与来源说明
本指南不推荐付费 GPU 主机、小主机型号或云服务商。真正有价值的判断是：远程 ML 是否能减少可测量瓶颈，并且值得额外的运维和安全成本。