Files

T

zimonianhua 14c2e56656 refactor: 重构服务层代码结构并优化性能

- 提取公共服务方法 _get_face_recognition、_check_result、_call_service
- 添加 HTTP Session 池化与 LRU 图片缓存
- 完善 create_person 错误处理，返回统一格式
- 卸载时正确关闭 client 连接释放资源
- 传感器适配 API 返回结构变化
- 全面更新 README 文档，补充服务说明与示例

2026-05-02 00:18:57 +08:00

6.9 KiB

Raw Blame History

腾讯云人脸识别 Home Assistant 插件

基于腾讯云人脸识别 API 的 Home Assistant 自定义集成，提供完整的人脸管理能力。

功能特性

人脸搜索：通过图片 URL、本地文件、Base64 编码或摄像头实体搜索人脸，返回匹配的人员信息
人脸检测：检测图片中的人脸位置和尺寸
人脸属性分析：获取人脸的性别、年龄、表情等属性
人员管理：创建/删除人员，支持带图或无图创建
人脸管理：为人员注册新人脸或删除已有人脸
传感器：自动同步人员库状态，提供人员数量和连接状态传感器
多配置支持：支持多个腾讯云账号同时接入
自动重试：内置指数退避重试机制，应对网络波动和限流
连接复用：HTTP Session 池化，减少重复连接开销
图片缓存：URL/路径图片 LRU 缓存，避免重复下载

安装

方式一：手动安装

将 tencent_face_recognition 目录复制到 Home Assistant 的 custom_components 目录下
重启 Home Assistant

方式二：HACS 安装

在 HACS 中搜索"腾讯云人脸识别"并安装。

配置集成

在"设置" → "设备与服务"中点击"添加集成"
搜索"腾讯云人脸识别"
输入腾讯云 Secret ID、Secret Key 及可选的区域和人员库 ID

腾讯云相关

配置项

参数	必需	默认值	说明
Secret ID	是	-	腾讯云 API 的 Secret ID
Secret Key	是	-	腾讯云 API 的 Secret Key
区域	否	`ap-shanghai`	腾讯云服务区域
人员库 ID	否	`Hass`	默认使用的人员库 ID

服务

所有服务均支持 response_variable 获取返回结果，统一返回格式：

{
  "success": true,
  "error": null,
  "error_code": null,
  "error_message": null
}

失败时：

{
  "success": false,
  "error": "错误描述",
  "error_code": "error_code",
  "error_message": "详细错误信息"
}

通用图片参数（按优先级取第一个有效的）：

参数	说明
`camera_entity_id`	摄像头实体 ID（优先）
`image_url`	图片 URL
`image_path`	本地文件路径
`image_file`	Base64 编码图片
`config_entry_id`	多配置时指定配置项 ID

人脸搜索

tencent_face_recognition.face_search

在人员库中搜索匹配的人脸。搜索成功时会触发 face_detected 事件。

独有参数：

参数	默认值	说明
`group_id` (必填)	-	要搜索的人员库 ID
`max_face_num`	1	最多处理的人脸数量
`min_face_size`	34	最小人脸尺寸（像素）
`max_user_num`	5	最多返回的匹配人员数量
`quality_control`	1	质量控制（0=关闭，1=开启）
`need_rotate_check`	1	旋转检查（0=关闭，1=开启）
`face_match_threshold`	60.0	匹配阈值（0-100）

示例：

action: tencent_face_recognition.face_search
response_variable: search_result
data:
  group_id: "Hass"
  image_path: "/config/www/camera/face.jpg"
  face_match_threshold: 70
  max_face_num: 5

触发事件 face_detected：

- trigger:
    - platform: event
      event_type: face_detected
  action:
    - service: persistent_notification.create
      data:
        message: "识别到 {{ trigger.event.data.person_name }}，置信度 {{ trigger.event.data.score }}"

人脸检测

tencent_face_recognition.detect_face

检测图片中的人脸位置和尺寸。

参数	默认值	说明
`max_face_num`	1	最多检测的人脸数量
`min_face_size`	34	最小人脸尺寸（像素）
`need_rotate_check`	1	旋转检查

示例：

action: tencent_face_recognition.detect_face
response_variable: detect_result
data:
  camera_entity_id: "camera.front_door"
  max_face_num: 10

获取人脸属性

tencent_face_recognition.get_face_attributes

获取图片中人脸的性别、年龄、表情等属性信息。

参数	默认值	说明
`max_face_num`	1	最多分析的人脸数量
`need_rotate_check`	1	旋转检查

示例：

action: tencent_face_recognition.get_face_attributes
response_variable: attr_result
data:
  image_url: "https://example.com/photo.jpg"

创建人员

tencent_face_recognition.create_person

在人员库中创建新人员，图片为可选（支持先建人后传图）。

参数	默认值	说明
`person_id` (必填)	-	人员唯一标识符
`person_name` (必填)	-	人员名称
`group_id` (必填)	-	所属人员库 ID
`gender`	-	性别（0=女，1=男）
`person_tag`	-	备注标签
`quality_control`	1	质量控制
`need_rotate_check`	1	旋转检查

示例：

action: tencent_face_recognition.create_person
response_variable: create_result
data:
  person_id: "person_001"
  person_name: "张三"
  group_id: "Hass"
  image_url: "https://example.com/face.jpg"
  gender: 1

删除人员

tencent_face_recognition.delete_person

从人员库中删除人员。

参数	说明
`person_id` (必填)	要删除的人员 ID

注册人脸

tencent_face_recognition.create_face

为已有人员添加新的人脸照片。

参数	默认值	说明
`person_id` (必填)	-	人员 ID
`quality_control`	1	质量控制
`need_rotate_check`	1	旋转检查

删除人脸

tencent_face_recognition.delete_face

删除指定人员的人脸。

参数	说明
`person_id` (必填)	人员 ID
`face_id` (必填)	要删除的人脸 ID

传感器

集成会自动创建以下传感器：

传感器	说明
状态传感器	显示连接状态（已连接/未连接/连接错误）
人员传感器	每个注册人员一个传感器，显示名称和属性

传感器每 5 分钟自动刷新。

故障排除

问题	解决方案
配置失败	检查 Secret ID/Key 是否正确，确认以 AKID 开头
图片处理失败	确保 URL 可访问或本地路径正确，图片格式为 JPG/PNG/BMP/GIF，大小不超过 10MB
人脸检测失败	确保图片中包含清晰的人脸，人脸尺寸不小于 34 像素
API 调用失败	检查账户余额和 API 调用配额
限流错误	降低调用频率，插件已内置重试机制

在"开发者工具" → "日志"中开启调试日志可获取更详细的错误信息。

许可证

MIT 许可证

6.9 KiB Raw Blame History Unescape Escape