Immich:用 AI 搜索您的照片 locale

Immich 是 Google Photos 的自托管替代方案,可以通过输入描述(“海滩上的狗”“生日蛋糕”)而不是文件名来找到照片。这种 AI 照片搜索依赖于一个在您的服务器上、在 Immich 机器学习容器中运行的 CLIP 模型。本指南将介绍它的工作原理、如何选择多语言模型以便用法语搜索、需要留意哪些错误,以及哪些数据真正会离开您的网络。文中所述步骤遵循官方文档;本指南并未在测试实例上重新操作验证。
#Immich 中的 AI 照片搜索:基本原理
该功能在 Immich 文档中称为 Smart Search(界面中称为“智能搜索”或按上下文搜索)。它不会在查询时实时读取您的照片,而是依赖两个独立的操作,两者都由 immich-machine-learning 服务负责。
- 01图像索引对于每张照片,CLIP 模型的图像编码器会计算出一个数值向量(即 embedding,嵌入向量),用来概括其视觉内容。该向量存储在 Immich 的数据库中。这就是管理界面中可见的“Smart Search”任务所做的工作;对于大型照片库,该任务可能会持续很长时间。
- 02查询编码当您输入一句话时,同一模型的文本编码器也会将其转换为向量。
- 03ComparaisonImmich 会返回向量与您所输入句子的向量最接近的照片。这里既没有文本生成,也没有聊天机器人意义上的“理解”:它只是在图像与文本共享的空间中进行相似度搜索。
直接后果是:文本和图像必须由同一个模型编码。如果更换模型,所有照片都必须重新索引,否则新旧向量将无法比较。
#CLIP 不是视觉助手
借助我们的经验和引导式路径,打造你的本地助手,在日常中使用你的 AI。
- 在线空间,终身可用
- PDF + 文件
- 30 天内退款
人们常常把 Immich 的 CLIP 搜索与通过 Ollama 运行的“视觉”模型(Qwen3-VL、Gemma 等)混为一谈。它们是两种不同的工具,满足两种不同的需求。
- CLIP 在 Immich 中的作用
- 按照与一句话的相似度对照片进行排序。结果是一个排好序的图片列表,而不是一段撰写好的回答。模型很小,索引只需进行一次,之后搜索速度很快。
- 视觉助手能做什么
- 描述图像、回答有关图像内容的问题、读取文字(OCR)、比较两张图像。它逐张图像生成文本,计算和内存开销要大得多。
- CLIP 做不到的事
- 回答“这张照片里有多少人?”、描述一个场景、可靠地读取拍摄的文档,或者计数。它只给出一个相似度分数,仅此而已。
- Immich 未原生集成的功能
- 能够撰写图片说明或与您的照片库对话的视觉 LLM。确实存在一些第三方项目,但它们不属于 Immich,本文也不涉及。
如果您的需求是找到“周二那张白板照片”,CLIP 通常就够了。如果您的需求是提取白板上的文字或对其进行总结,则需要视觉模型,例如通过 Ollama,处理您明确发送给它的图像。
#先决条件
- 一个正常运行的 Immich 实例
- 使用官方 docker-compose.yml 安装,其中包含 immich-machine-learning 服务。如果您已将其从 compose 文件中删除,智能搜索将无法使用。
- 一个管理员账户
- 模型的选择和索引任务的启动都在服务器管理界面中进行。
- 需要内存和时间
- 更大的 CLIP 模型需要更多内存,索引速度也更慢。我们不公布耗时数据:它们取决于模型、照片数量、CPU 或 GPU,而且我们没有可提供给您的有据可查的测量结果。
- 硬件加速(可选)
- Immich 的文档介绍了机器学习加速(NVIDIA 使用 CUDA,Intel 使用 OpenVINO,AMD 使用 ROCm,部分 ARM 开发板使用 ARM NN 和 RKNN)。加速并非必需:CPU 就够用,只是速度较慢。
- 一份近期备份
- 更换模型不会改动您的文件,但在家用服务器上重新运行繁重任务时,正好可以检查数据库和原始文件的备份是否为最新。
要确认机器学习服务正在运行,请在包含 docker-compose.yml 的目录中执行:
#启用 AI 照片搜索并选择多语言模型
Immich 文档中给出的默认模型是 ViT-B-32__openai,这是一个主要基于英文图片说明训练的 CLIP 模型。它可以工作,但法语查询的结果通常不如相同的英语查询相关。文档建议,如果您使用英语以外的语言搜索,请使用多语言模型。
- 01打开机器学习设置在 Immich 中,依次打开“管理”、“设置”,然后进入“机器学习”部分。确认机器学习已启用,并且服务 URL 正确指向您的容器(默认是 compose 文件中的 immich-machine-learning 服务)。
- 02选择 CLIP 模型在 Smart Search 子部分中,替换模型名称。可选模型由 Immich 团队发布在 Hugging Face 上,文档中链接了一份列表,列出了每个模型的大小、内存需求以及是否支持多语言。文档提到的多语言模型系列主要有 nllb-clip(例如 nllb-clip-base-siglip__v1、nllb-clip-large-siglip__v1)和 XLM-Roberta(例如 XLM-Roberta-Large-Vit-B-16Plus)。请从官方列表中复制准确的名称:一个拼写错误就会导致无法下载。
- 03录音下次需要时,ML 容器会从 Hugging Face 下载模型,然后将其保存在缓存中(官方 compose 中的 model-cache 卷)。因此,首次调用可能会很慢;如果服务器无法访问互联网,则可能会失败。
- 04对整个照片库重新运行索引在 Administration 中打开任务(Jobs)。在 Smart Search 这一行,对所有照片(“All”)运行处理,而不只是对缺失的照片(“Missing”)运行:用旧模型计算出的向量已不再兼容。可在同一页面和容器日志中跟踪进度。
- 05用几个已知结果的查询进行测试挑选三四张您清楚其内容的照片,用法语搜索它们,并确认它们能出现在结果中。这是您唯一真正有效的测试:相关性取决于您的照片库,我们无法远程为您保证。
该选哪个模型?文档并没有指定一个通用的“最佳”模型。这是典型的权衡:更大的模型(large 变体)有望带来更好的相关性,但占用更多内存、建立索引更慢;base 模型则更轻量。在没有 GPU 的小型服务器或 NAS 上,建议先从多语言 base 变体入手;如果相关性令您失望且机器还有余量,可以尝试更大的变体,但要知道届时需要全部重新建立索引。
#用法语搜索照片
索引完成后,即可在 Web 或移动应用的搜索栏中进行搜索。根据版本不同,界面提供多种搜索类型:上下文(即 CLIP 搜索)、文件名、描述,以及在较新版本中通过 OCR 识别的文字。若要按描述搜索,请保持在上下文模式。
- 描述画面中能看到的内容
- “靠在墙边的红色自行车”“海上日落”“吹蜡烛的孩子”。CLIP 对物体、场景、颜色和氛围有反应。
- 避免描述图像中看不到的内容
- “2019 年在 Paul 家度假”并不对应任何可见内容。日期、地点或人物请使用筛选条件。
- 与筛选条件结合使用
- 筛选面板可按人物(人脸识别,同一 ML 容器的另一项功能)、地点、设备、日期和媒体类型进行限定。简短的查询加上两个筛选条件,效果往往胜过一长句话。
- Reformulez
- 如果“猫”返回的结果太多,请描述得更具体:“睡在沙发上的黑猫”。如果什么都搜不到,就简化描述。也可以试试英语:如果英语的效果明显更好,那么您的模型很可能是单语言模型。
- 不要与文本搜索混淆
- 上下文模式不会读取照片中的文字。若要根据截图中的文字内容查找截图,请使用 OCR 搜索(如果您的版本提供),或按文件名或描述搜索。
结果按相似度排序,不存在“匹配/不匹配”的阈值:即使是荒谬的查询,搜索也总会返回一些结果。排在最前面的结果最接近;越往下,相关性越低。
#隐私:哪些数据留在您自己手中
这是自托管 AI 照片搜索的主要卖点,但需要准确地表述。本指南描述的是文档中的架构;它不构成对您安装环境的审计,也不保证没有任何数据离开您的网络。
- 计算
- 在官方配置中,照片和查询的编码由您机器上的 immich-machine-learning 容器完成。嵌入向量存储在您的 PostgreSQL 数据库中。
- 模型下载
- 模型权重会在首次使用时从 Hugging Face 下载。这部分出站流量是正常的,其中不包含您的照片。模型一旦缓存,只要保留该卷,就不会再次下载。
- 远程部署的 ML
- 机器学习服务的 URL 可以配置:您可以在另一台机器(例如一台带 GPU 的 PC)上运行 ML 容器。在这种情况下,您的照片会传输到那台机器。请将其保留在本地网络中或置于 VPN 之后,切勿直接暴露在互联网上。
- 其他功能
- 地图、版本检查或其他设置可能会连接外部服务。它们与 CLIP 搜索无关;如果您的目标是在没有出站连接的情况下运行,请检查服务器设置。
- 禁用
- 可以在设置中禁用机器学习,或仅禁用智能搜索。您的照片仍可正常访问;您只会失去按描述搜索的功能。
#常见错误与故障排除
- 搜索没有返回任何结果或报错
- ML 容器已停止、无法访问,或设置中的 URL 有误。请检查 docker compose ps 以及 immich-machine-learning 的日志。
- 模型下载失败
- 模型名称拼写错误、无法访问 Hugging Face,或磁盘已满。ML 容器的日志通常会指出是哪一种。
- ML 容器反复重启
- 通常是使用大模型时内存不足,或加速镜像(例如 -cuda)与硬件不匹配。请改回较小的模型或 CPU 镜像,以便定位问题。
- 更换模型后结果不佳
- Smart Search 任务只针对缺失的照片运行过,或者尚未完成。请对所有照片重新运行该任务。
- 法语搜索结果不佳,英语正常
- 当前启用的模型是单语言模型(例如默认的 ViT-B-32__openai)。请切换到多语言模型并重新索引。
- 找不到新照片
- 新文件的索引通过任务队列进行。如果队列已暂停或已饱和,最近的照片就还没有向量。请检查任务页面。
#局限与来源
本指南不公布任何索引耗时、实测内存占用或相关性评分:我们没有可以向您展示的、有据可查的测量数据(硬件、版本、模型、照片库规模)。您在网上找到的量级估计在很大程度上取决于这些参数;唯一可靠的参考是在您自己的服务器上,用几个您已知答案的查询进行测试。
Immich 发展很快。菜单名称、可用模型列表和搜索类型会随版本变化。以上内容基于编辑部于 2026 年 10 月 30 日查阅的官方文档“Searching”页面;发布当天并未重新核实。如有出入,以您所用版本的文档为准:docs.immich.app/features/searching/。
#深入了解
CLIP 搜索用于找到照片;若要描述照片、就照片提问或从中提取文字,则需要视觉模型。本站的这些指南对此主题做了延伸。
- 本地多模态视觉 LLM:使用 Ollama 分析图像
- 相关指南:使用本地视觉模型描述图像、进行 OCR、就照片提问。这是对 CLIP 搜索的自然补充。
- 使用 Ollama 在本地运行 Qwen3-VL
- 一个精确的视觉模型,用于详细分析通过 Immich 搜索找到的照片。
- BGE-M3:懂法语的嵌入模型
- 将同样的多语言嵌入原理应用于文本,以理解为什么单语模型会对法语查询不利。
有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。