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

- 提取公共服务方法 _get_face_recognition、_check_result、_call_service - 添加 HTTP Session 池化与 LRU 图片缓存 - 完善 create_person 错误处理，返回统一格式 - 卸载时正确关闭 client 连接释放资源 - 传感器适配 API 返回结构变化 - 全面更新 README 文档，补充服务说明与示例
2026-05-02 00:18:57 +08:00
parent d081a51aa0
commit 14c2e56656
6 changed files with 654 additions and 564 deletions
@@ -1,100 +1,271 @@
-# 腾讯云人脸识别Home Assistant插件
+# 腾讯云人脸识别 Home Assistant 插件

-这是一个基于腾讯云人脸识别API的Home Assistant插件，提供了人脸搜索功能。
+基于腾讯云人脸识别 API 的 Home Assistant 自定义集成，提供完整的人脸管理能力。

 ## 功能特性

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

 ## 安装

-1. 将`custom_components/tencent_face_recognition`目录复制到Home Assistant的`custom_components`目录下
-2. 重启Home Assistant
-3. 在"配置" -> "集成"中点击"+"添加集成
-4. 搜索"腾讯云人脸识别"并点击
-5. 输入您的腾讯云凭据和配置信息
+### 方式一：手动安装

-## 腾讯云相关页面入口
+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)
+- [获取 API 密钥](https://curl.qcloud.com/cT0HlJRW)

-## 配置
+## 配置项

-### 必需配置
-
- **Secret ID**：腾讯云API的Secret ID
- **Secret Key**：腾讯云API的Secret Key
-
-### 可选配置
-
- **人员库ID**：默认使用的人员库ID（默认值：Hass）
- **区域**：腾讯云服务区域（默认值：ap-shanghai）
- **名称**：集成名称（默认值：腾讯云人脸识别）
+| 参数 | 必需 | 默认值 | 说明 |
+|------|------|--------|------|
+| 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`
+`tencent_face_recognition.face_search`

-**描述**：在人员库中搜索人脸
+在人员库中搜索匹配的人脸。搜索成功时会触发 `face_detected` 事件。

-**参数**：
+**独有参数**：

- `image_url`（可选）：要搜索的图片URL
- `image_path`（可选）：要搜索的本地图片路径
- `person_group_id`（可选）：要搜索的人员库ID，留空使用默认人员库
- `max_face_num`（可选，默认1）：最多处理的人脸数量
- `min_face_size`（可选，默认34）：最小人脸尺寸（像素）
- `max_user_num`（可选，默认5）：最多返回的匹配人员数量
- `quality_control`（可选，默认1）：是否进行质量控制（0：不控制，1：低质量控制，2：高质量控制）
- `need_rotate_check`（可选，默认1）：是否进行旋转检查（0：不检查，1：检查）
- `face_match_threshold`（可选，默认60.0）：人脸匹配阈值（0-100）
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `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
+```yaml
 action: tencent_face_recognition.face_search
-response_variable: face_recognition_result_raw
+response_variable: search_result
 data:
-  group_id: Hass
-  face_match_threshold: 60
-  min_face_size: 34
-  max_face_num: 10
-  max_user_num: 10
-  image_path: /config/www/camera/face.jpg
+  group_id: "Hass"
+  image_path: "/config/www/camera/face.jpg"
+  face_match_threshold: 70
+  max_face_num: 5
 ```

-
+**触发事件** `face_detected`：

 ```yaml
-service: tencent_face_recognition.face_search
-data:
-  image_url: "https://example.com/face.jpg"
-  group_id: "Hass"
+- 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 调用配额 |
+| 限流错误 | 降低调用频率，插件已内置重试机制 |

-1. **配置失败**：请检查腾讯云凭据是否正确，以及是否有足够的权限
-2. **图片处理失败**：请确保图片URL可访问或本地文件路径正确
-3. **人脸检测失败**：请确保图片中包含清晰的人脸，且人脸尺寸足够大
-4. **API调用失败**：请检查腾讯云账户余额是否充足，以及API调用配额是否足够
-
-### 日志查看
-
-在Home Assistant的"开发者工具" -> "日志"中查看插件日志，可以获取更多错误信息。
-
-## 贡献
-
-欢迎提交Issue和Pull Request来改进这个插件。
+在"开发者工具" → "日志"中开启调试日志可获取更详细的错误信息。

 ## 许可证

-MIT许可证
+MIT 许可证