本文档介绍了 Immich 的人脸识别系统，该系统自动识别照片中的人脸并将其分组为“人物”实体。它解释了系统如何检测人脸、跨多张照片识别个体，并提供了用户管理和组织其照片集中人物的界面。
有关相册管理和共享的信息，请参阅相册与共享。有关包括基于人物的搜索在内的搜索功能，请参阅搜索与发现。
Immich 的人脸识别系统自动检测上传照片中的人脸，生成人脸嵌入（人脸的数学表示），并将相似的人脸分组。这使用户能够按人物浏览照片、为人脸命名，并根据图像中出现的人物来组织其收藏。
该系统由以下几个组件组成
以下是人脸识别系统如何融入 Immich 架构的高级概览图
来源：web/src/routes/(user)/people/+page.svelte、machine-learning/Dockerfile
来源：machine-learning/Dockerfile、docs/docs/install/environment-variables.md
人脸识别系统采用两步法
机器学习服务支持多种硬件加速选项，以提高性能，包括
这些可以通过环境变量进行配置，以根据您的硬件优化性能。
来源：machine-learning/Dockerfile:15-117、docs/docs/install/environment-variables.md:152-174
网页界面提供了所有已检测到人物的全面视图以及管理它们的工具。
主人员页面（/people）显示了照片中检测到的人物网格。每个人物都由一张卡片表示，显示
用户可以
来源：web/src/routes/(user)/people/+page.svelte、web/src/lib/components/faces-page/people-card.svelte、web/src/lib/components/faces-page/people-infinite-scroll.svelte
每个人物都显示为一张带有其个人资料图片的卡片。该卡片包含通过上下文菜单管理人物的选项
来源：web/src/lib/components/faces-page/people-card.svelte:15-85
当系统检测到同一人物有多个条目，或者用户希望合并单独的人物条目时，他们可以使用合并功能
当尝试将人物重命名为已存在的名称时，系统还会提供合并建议，有助于维护一个清晰的人物数据库。
来源：web/src/lib/components/faces-page/merge-face-selector.svelte、web/src/lib/components/faces-page/merge-suggestion-modal.svelte
用户可以使用可见性管理功能控制界面中哪些人物可见
这对于管理包含许多不重要或未识别人脸的大型收藏尤其有用。
来源：web/src/lib/components/faces-page/manage-people-visibility.svelte:10-164
数据模型展示了系统中人物、人脸和资产之间的关系。每个人物可以有多张人脸，每个资产（照片）可以包含多张人脸。
来源：web/src/routes/(user)/people/+page.svelte:45-273
人脸识别系统可以通过多个环境变量进行配置
| 可变 | 描述 | 默认 |
|---|---|---|
MACHINE_LEARNING_MODEL_TTL | 模型卸载前的非活动时间 | 300 秒 |
MACHINE_LEARNING_CACHE_FOLDER | 下载模型的目录 | /cache |
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__RECOGNITION | 要预加载的识别模型 | - |
MACHINE_LEARNING_PRELOAD__FACIAL_RECOGNITION__DETECTION | 要预加载的检测模型 | - |
MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION | 一次处理的最大人脸数量 | 可变 |
MACHINE_LEARNING_ANN | 启用 ARM-NN 硬件加速 | True |
MACHINE_LEARNING_RKNN | 启用 RKNN 硬件加速 | True |
MACHINE_LEARNING_DEVICE_IDS | 多 GPU 环境的设备 ID | 0 |
来源：docs/docs/install/environment-variables.md:150-174
机器学习服务支持多种硬件加速选项，以提高人脸检测和识别性能
每个选项都需要特定的配置，并且可能具有不同的性能特征。应根据您的硬件环境选择合适的选项。
来源：machine-learning/Dockerfile:1-18、docs/docs/install/environment-variables.md:166-174
人脸识别模型可能很大且内存密集。系统包含多种机制来管理内存使用
对于内存有限的系统，请考虑
人脸识别可以批量进行以提高吞吐量。MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION 环境变量控制同时处理的最大人脸数量。
来源：docs/docs/install/environment-variables.md:170-171
遗漏的人脸：有些面部可能无法被检测到，如果它们是
分组错误：系统有时可能会将不同的人分组在一起，或者将同一个人拆分为多个条目。这可以使用合并功能进行纠正。
性能问题：人脸识别是计算密集型任务。如果性能缓慢