企业官网建设流程全解析

Immich 机器学习模型损坏或下载失败怎么处理

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich

Immich 的机器学习服务（immich-machine-learning）负责智能搜索、人脸识别等任务，它需要先从官方模型源下载模型文件。在标准 Docker Compose 部署中，如果日志或任务报错提示模型损坏（corrupt）或模型下载失败，官方给出的处理路径是：先定位模型缓存卷，删除该卷让服务在干净环境中重新下载；如果下载源本身不可达，则手动下载模型放入缓存目录。

模型缓存在哪里：先定位 model-cache 卷

机器学习服务下载的模型存放在专用 Docker 卷中。默认 compose 文件 docker/docker-compose.yml 里，immich-machine-learning服务将model-cache卷挂载到容器内的/cache：

immich-machine-learning: ... volumes: - model-cache:/cache ... volumes: model-cache:

环境变量MACHINE_LEARNING_CACHE_FOLDER的含义是 "Directory where models are downloaded"，默认值/cache（见 docs/docs/install/environment-variables.md）。由于默认 compose 文件的项目名（name:字段）是immich，这个卷在 Docker 中的实际名称是immich_model-cache——官方 FAQ 的命令示例使用的就是这个名字。

可以启动一个临时 alpine 容器挂载该卷，查看已下载的模型目录：

docker run -it --rm -v immich_model-cache:/mnt-models alpine sh cd /mnt-models ls clip/ facial-recognition/

这会列出clip/、facial-recognition/等按模型类型划分的子目录及其下的具体模型，方便你确认哪些模型已经就位、哪些缺失或损坏。

模型损坏：删除缓存卷让服务重新下载

FAQ 对 "getting errors about models being corrupt or failing to download" 给出的处理方式是：删除模型缓存卷，让服务获得一个干净环境重新下载模型（"This will give the service a clean environment to download the model again"）。对应的 Docker 命令是：

docker volume rm immich_model-cache

执行前注意副作用：

• 该操作只删除缓存的模型文件，不会触碰数据库和已上传的媒体（数据库在DB_DATA_LOCATION目录，媒体在UPLOAD_LOCATION目录）；
• 删除后，服务在运行机器学习任务时会按需重新下载模型，下载需要能访问互联网；
• 如果你改过 compose 项目名，命令中的immich_model-cache要替换为你的实际卷名（即docker-compose.yml中声明为model-cache的那个卷）。

如果只是某一个模型损坏，或者想顺带清理不再使用的旧模型，也可以只删具体的模型目录而不是整个卷：先进入上面命令给出的交互环境，再执行删除。FAQ 给出的示例形式如下，其中ABC、DEF替换为你ls看到的实际模型目录名：

# rm -r clip/ABC facial-recognition/DEF # delete unused models

下载完全失败：手动放置模型文件

FAQ 同时给出了一条兜底路径：如果模型完全无法自动下载（"failing to download entirely"），可以从 Immich 官方的 Hugging Face 模型页面手动下载（页面链接在 FAQ 文档末尾的引用中），再放入缓存目录。放入时按上面ls看到的目录结构组织，模型存放在按模型类型和模型名划分的子文件夹中。

两条文档依据的边界需要留意：

• 官方 Hugging Face 页面上列出的模型才受支持，FAQ 明确回答自定义 CLIP 模型 "No, this is not supported"；
• TrueNAS 安装文档中提到 Hugging Face Endpoint 设置项，说明其用途是 "download ML models from a different source"，默认建议留空。如果你的环境无法访问默认下载源，这个设置项是文档中提到的切换下载来源的位置。

验证与判断

删除或修复缓存后，重新执行上面的检查命令，确认缺失的模型目录会重新出现。机器学习服务在处理每次任务前会检查对应模型是否已下载，没有则下载（人脸识别原理一节的描述），架构文档也说明服务会按需下载并加载模型、加载后缓存复用。因此当智能搜索、人脸识别等机器学习任务再次运行时，缓存中重新出现模型文件，说明下载链路已恢复。

排查时如果日志显示的是进程类错误而非模型错误，参考 FAQ 对 worker crashing 的判断：错误提到SIGKILL或错误码 137，多半是服务内存不足；提到SIGILL（没有 K）或错误码 132，多半是服务器 CPU 与 Immich 不兼容。这两种情况不属于模型缓存问题，FAQ 建议增加内存、换用内存更大的服务器或确认 CPU 兼容性。

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich