zimonianhua
14c2e56656
- 提取公共服务方法 _get_face_recognition、_check_result、_call_service - 添加 HTTP Session 池化与 LRU 图片缓存 - 完善 create_person 错误处理，返回统一格式 - 卸载时正确关闭 client 连接释放资源 - 传感器适配 API 返回结构变化 - 全面更新 README 文档，补充服务说明与示例
272 lines
6.9 KiB
Markdown
272 lines
6.9 KiB
Markdown
# 腾讯云人脸识别 Home Assistant 插件
|
||
|
||
基于腾讯云人脸识别 API 的 Home Assistant 自定义集成，提供完整的人脸管理能力。
|
||
|
||
## 功能特性
|
||
|
||
- **人脸搜索**：通过图片 URL、本地文件、Base64 编码或摄像头实体搜索人脸，返回匹配的人员信息
|
||
- **人脸检测**：检测图片中的人脸位置和尺寸
|
||
- **人脸属性分析**：获取人脸的性别、年龄、表情等属性
|
||
- **人员管理**：创建/删除人员，支持带图或无图创建
|
||
- **人脸管理**：为人员注册新人脸或删除已有人脸
|
||
- **传感器**：自动同步人员库状态，提供人员数量和连接状态传感器
|
||
- **多配置支持**：支持多个腾讯云账号同时接入
|
||
- **自动重试**：内置指数退避重试机制，应对网络波动和限流
|
||
- **连接复用**：HTTP Session 池化，减少重复连接开销
|
||
- **图片缓存**：URL/路径图片 LRU 缓存，避免重复下载
|
||
|
||
## 安装
|
||
|
||
### 方式一：手动安装
|
||
|
||
1. 将 `tencent_face_recognition` 目录复制到 Home Assistant 的 `custom_components` 目录下
|
||
2. 重启 Home Assistant
|
||
|
||
### 方式二：HACS 安装
|
||
|
||
在 HACS 中搜索"腾讯云人脸识别"并安装。
|
||
|
||
### 配置集成
|
||
|
||
1. 在"设置" → "设备与服务"中点击"添加集成"
|
||
2. 搜索"腾讯云人脸识别"
|
||
3. 输入腾讯云 Secret ID、Secret Key 及可选的区域和人员库 ID
|
||
|
||
## 腾讯云相关
|
||
|
||
- [腾讯云人脸识别](https://curl.qcloud.com/oqiFPa7h)
|
||
- [人脸管理控制台](https://curl.qcloud.com/RMATbuiO)
|
||
- [获取 API 密钥](https://curl.qcloud.com/cT0HlJRW)
|
||
|
||
## 配置项
|
||
|
||
| 参数 | 必需 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| Secret ID | 是 | - | 腾讯云 API 的 Secret ID |
|
||
| Secret Key | 是 | - | 腾讯云 API 的 Secret Key |
|
||
| 区域 | 否 | `ap-shanghai` | 腾讯云服务区域 |
|
||
| 人员库 ID | 否 | `Hass` | 默认使用的人员库 ID |
|
||
|
||
## 服务
|
||
|
||
所有服务均支持 `response_variable` 获取返回结果，统一返回格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"error": null,
|
||
"error_code": null,
|
||
"error_message": null
|
||
}
|
||
```
|
||
|
||
失败时：
|
||
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
**示例**：
|
||
|
||
```yaml
|
||
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`：
|
||
|
||
```yaml
|
||
- 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 | 旋转检查 |
|
||
|
||
**示例**：
|
||
|
||
```yaml
|
||
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 | 旋转检查 |
|
||
|
||
**示例**：
|
||
|
||
```yaml
|
||
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 | 旋转检查 |
|
||
|
||
**示例**：
|
||
|
||
```yaml
|
||
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 许可证
|