Ente Photos 智能相册（Auto-add People）全解析：让人脸识别自动填充相册

Ente Photos 智能相册（Auto-add People）全解析：让人脸识别自动填充相册

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente

导读

本文围绕 Ente Photos 的Auto-add people（按人物自动添加照片 / 智能相册）功能展开：当你为某个相册选定了若干"人物"后，凡是后续上传且经设备端人脸识别索引出包含这些人的照片，都会自动流入该相册。文章以官方功能文档为主体，结合 Ente 开源仓库中mobile/apps/photos的 Dart 源码（SmartAlbumsService、SmartAlbumConfig、Collection.canAutoAdd等）逐层剖析其前置条件、移动端配置步骤、管理/停止方式与增量同步的底层实现，帮助读者既会操作、也懂原理。

什么是智能相册（Auto-add people）

Ente Photos 的智能相册允许你把"特定的人"绑定到任意你有编辑权限的相册上。设置完成后，只要满足以下两个条件，照片就会自动进入该相册：

1. 照片中包含你选定的人物；
2. 该照片已经过设备端的人脸识别索引。

换句话说是："为相册订阅一批人，然后让人脸识别把人脉流动起来"——上传的新照片无需手动归组，会在人脸识别索引完成后自动流入对应相册。官方文档对该功能的一句话概括是：

Automatically add photos of specific people to any album you can edit. Once set up, new matching photos you upload will flow into that album after face recognition indexes them.

需要注意的是，智能相册只作用于你自己上传的照片；其他协作者/成员上传进相册的内容不会被自动改写（详见下文ownerID过滤的源码证据）。

前置条件：先让"人"被识别出来

要使用自动添加功能，需要先满足文档列出的若干要求，它们分别对应移动端机器学习的两个前置特性：

机器学习的索引流程在 machine-learning.md 中有完整描述：应用先下载原始照片到设备，在设备本地用 ML 模型分析、建立索引，再把索引加密同步到你的其他设备。而人脸识别正是在此基础上完成"检测人脸 → 相似人脸聚类 → 命名人物 → 按名搜索"的完整闭环，详见 face-recognition.md。

[!NOTE] 与机器学习整体一样，智能相册依赖设备端能力，photos.ente.com（Web 端）不提供人脸识别，因而也无法使用自动添加功能。

权限判断的源码证据：canAutoAdd

为什么"收藏"和"未分类"不能启用自动添加？源码中给出了明确判定。在 collection.dart 中：

bool canAutoAdd(int userID) { final participantRole = getRole(userID); final canEditCollection = isOwner(userID) || participantRole == CollectionParticipantRole.collaborator || participantRole == CollectionParticipantRole.admin; final isFavoritesOrUncategorized = type == CollectionType.favorites || type == CollectionType.uncategorized; return canEditCollection && !isDeleted && !isFavoritesOrUncategorized; }

可以推断，收藏与未分类在 Ente 中属于系统内置集合而非普通可编辑相册，因此被显式排除。与此同时，相册菜单中的入口同样以该判断为前提：在 gallery_app_bar_widget.dart 中，先检查hasGrantedMLConsent（用户是否同意机器学习）再检查collection.canAutoAdd(userId)，两者同时为真才展示Auto-add people菜单项；若已配置过人，菜单文案会从autoAddPeople切换为editAutoAddPeople（见同文件 L840-L844）。

在移动端配置自动添加

官方文档给出的操作路径如下：

1. 打开你想要持续更新的相册；
2. 点击右上角溢出菜单（三个点），选择Auto-add people（若已配置过则显示Edit auto-add people）；
3. 勾选要关注的人物，点击Save；
4. 相册会先被已有的匹配照片填满，之后每当上传的新照片经人脸索引判定包含这些人，也会自动加入。

[!TIP] 对于空相册，可以直接使用空状态页上的Auto-add people快捷按钮。该入口在源码 empty_album_state.dart 中有对应实现：空相册页会同时展示"添加照片"主按钮与"Auto-add people"次级按钮，点击后直接跳转到SmartAlbumPeople选人页。

选人界面：只展示已命名人物

配置界面由 smart_album_people.dart 实现。它通过SmartAlbumPeople(collectionId: ...)接收当前相册 ID，初始化时读取已有配置并预选已绑定的人物：

• 页面标题为People，副标题是"自动添加人物"的说明文案（peopleAutoAddDesc）；
• 选人列表来自PeopleSectionAllWidget，并显式传入namedOnly: true——只有已命名的人物才出现在选人器中，这与官方文档"People must be named in Face recognition so they appear in the picker"的要求完全对应；
• 底部的 Save 按钮会与当前配置做差异比较（setEquals），只有在人物集合真正发生变化时才可点击。

保存时，代码会区分两种场景（smart_album_people.dart）：

• 首次配置（currentConfig == null）：为每个选中人物初始化updatedAt: 0, addedFiles: {}的空记录，然后写入配置；
• 编辑配置：计算被移除的人物（removedPersonIds），弹出确认对话框询问是否同时删除此前因这些人而自动加入的照片，确认后调用moveFilesFromCurrentCollection将这些文件移出当前相册。

保存后的动作

保存配置后，代码会调用smartAlbumsService.saveConfig(newConfig)落盘，并紧接着触发一次syncSmartAlbums()（见 smart_album_people.dart）——也就是说，配置一保存，相册立即开始回填已有的历史匹配照片。

管理与停止自动添加

官方文档的运维要点：

• 增删人物：重复上述配置步骤即可，选中更多人或取消勾选某人；
• 移除人物的照片：当移除某个人物时，Ente 会询问你是否同时移除之前因该人物而自动加入的照片。这一步在源码中由removeFilesDialog实现（smart_album_people.dart），对话框文案为"是否移除智能相册自动添加的照片"（shouldRemoveFilesSmartAlbumsDesc），提供 Yes / No 两个选项；确认后会按该人物addedFiles记录的文件 ID 精确清理，而不是清空整个相册；
• 完全停止：取消勾选所有人物并保存，配置中personIDs变为空集合，自动添加即停止；
• 暂停行为：如果关闭了机器学习，自动添加会暂停；重新开启机器学习后恢复更新。对应地，源码 smart_albums_service.dart 在syncSmartAlbums()开头就检查hasGrantedMLConsent，未授权时直接跳过同步并记录警告日志。

底层实现剖析：智能相册的增量同步机制

移动端的功能核心集中在 smart_albums_service.dart，配合配置模型 smart_album_config.dart 一起工作。

配置模型：SmartAlbumConfig与PersonInfo

typedef PersonInfo = ({int updatedAt, Set<int> addedFiles}); class SmartAlbumConfig { final String? id; final int collectionId; final Set<String> personIDs; final Map<String, PersonInfo> infoMap; final int updatedAt; ... }

每个智能相册配置包含：相册 ID（collectionId）、绑定的人物 ID 集合（personIDs）、以及按人物记录的增量进度（infoMap）。PersonInfo记录了两项关键数据：

• updatedAt：该人物聚类（cgroup）在本地实体库中的最后更新时间戳；
• addedFiles：已自动加入该相册的文件 ID 集合，用于去重，避免同一文件被反复加入。

配置以 JSON 序列化后通过实体服务（EntityType.smartAlbum）存储，实体 ID 采用"sa_${userId}_$collectionId"的命名规则（见 smart_albums_service.dart），保证每个用户在每张相册上的配置互不冲突，并随端到端加密的实体同步机制在多端同步。

同步流程：syncSmartAlbums()的增量逻辑

核心方法syncSmartAlbums()（smart_albums_service.dart）执行以下步骤：

1. 检查机器学习开关：未授权直接返回（对应文档"关闭 ML 自动添加暂停"）；
2. 读取全部配置：从本地实体库取回所有smartAlbum实体并解码；
3. 逐相册处理：跳过personIDs为空或当前用户无canAutoAdd权限的相册（若相册已删除则清理该配置实体）；
4. 增量比对：对每个绑定人物，通过entityService.getUpdatedAts(EntityType.cgroup, personIDs)拿到人物聚类的更新时间，与infoMap中记录的updatedAt比较——只有聚类有新变更的人物才进入本次同步；
5. 过滤候选文件（smart_albums_service.dart）：

final fileIds = (await SearchService.instance.getFilesForPersonID(personId, sortOnTime: false)) ..removeWhere( (e) => e.uploadedFileID == null || config.infoMap[personId]!.addedFiles.contains(e.uploadedFileID) || e.ownerID != userId, );

这里做了三重过滤：剔除无上传 ID 的文件、剔除已在addedFiles中记录过的文件（去重）、剔除ownerID != userId的文件——这正是文档"Only photos you upload are auto-added; items uploaded by other contributors stay unchanged"的源码级印证； 6.写入相册：将候选文件通过addOrCopyToCollection(collectionId, files, toCopy: false)加入相册（非复制，即建立集合关联而不产生额外存储占用）； 7.更新进度：用config.addFiles(updatedAtMap, pendingSyncFiles)合并新增文件到infoMap并保存配置，从而记录本轮的updatedAt与addedFiles，为下一轮增量同步打点； 8.事件通知：整个过程中通过Bus广播SmartAlbumSyncingEvent，UI 据此展示同步中状态。

也就是说，同步是事件驱动的增量拉取：每次人物聚类数据更新后，服务会针对性地把该人物的新文件补进相册，而不是全量扫描重算，这也解释了为什么新上传的照片"在人脸识别索引之后"才流入相册——getFilesForPersonID依赖的是人脸索引的结果。

配置的保存与加密同步

saveConfig→_addOrUpdateEntity(EntityType.smartAlbum, ...)将配置写入本地实体库。从 machine-learning.md 可知，机器学习索引数据（包括人脸聚类、搜索索引）都会加密后同步到其他设备；智能相册配置作为其中的一部分，同样遵循端到端加密，Ente 服务器无法读取你的选人与文件关联信息。

平台差异与已知限制

依据官方文档与源码，各端能力对比如下：

值得注意的细节：虽然配置只能在移动端完成，但自动添加的执行（syncSmartAlbums）以及相册的查看并不局限于配置端——只要该客户端具备机器学习能力与canAutoAdd权限，索引数据同步到哪个设备，哪个设备就能继续维持相册更新（参见 machine-learning.md 中"索引跨设备同步"一节）。桌面端索引更快，适合大图库先行索引，索引结果会加密同步给移动端。

常见问题与使用建议

• 选人器中看不到某个人？先到搜索页的 People 区确认该人物已命名。配置界面使用namedOnly: true过滤，未命名聚类不会出现在候选列表。
• 关闭机器学习后相册不更新？这是预期行为：syncSmartAlbums()在未授权 ML 时直接跳过。重新在Settings > Machine learning开启后恢复。
• 移除人物时误删了照片？删除动作仅针对该人物addedFiles记录中"自动加入"的照片，手动放入的照片不受影响；若选择不删除，则仅解除人物绑定。
• 协作者上传的照片没有自动进入相册？属于设计约束：增量同步对候选文件强制ownerID == userId，只处理你自己上传的内容。
• 建议的启用顺序：若图库很大，先在桌面端开启机器学习完成首次索引（更快），索引加密同步到移动端后再配置智能相册，可显著缩短"配置后回填"的等待时间。

更完整的人脸识别操作（合并/拆分人物、封面、忽略人物等）可参考 face-recognition.md；机器学习索引与隐私说明见 machine-learning.md。相册的通用操作（排序、置顶、描述、地图视图等）参见 albums.md。

结语

智能相册是 Ente Photos "本地机器学习 + 端到端加密"理念的典型应用：人脸识别全部在设备端完成，人物与相册的关联配置同样加密存储与同步，服务器始终接触不到未加密的照片、人脸数据与关联关系。从本文的源码分析可以看到，其增量同步机制（updatedAt比对 +addedFiles去重 +ownerID过滤）兼顾了效率、幂等与权限边界，让"指定人物自动归类"这一体验既智能又可控。

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente