前言¶
在智能體裏做「兩張圖是不是同一個人」，常見做法是手寫騰訊雲 SDK 調用、自己維護參數表和閾值說明，再把結果解釋給用戶。每一步都要查 CompareFace 文檔，本地路徑、URL、Base64 的入參也容易寫錯。
下面介紹 SkillHub 上的 TencentCloud FaceID CompareFace（@tencent-adm/tencentcloud-faceid-compareface）。它把騰訊雲人臉識別 CompareFace 封裝成標準 Agent Skill：Agent 在需要 1:1 人臉相似度時按 SKILL.md 觸發，通過腳本調用接口並返回相似度分數，便於判斷是否同一人。
這是什麼¶
TencentCloud FaceID CompareFace 是騰訊雲人臉比對（CompareFace）的接口調用技能。發佈方爲 騰訊雲慧眼人臉核身團隊，在 SkillHub 上歸類爲 ai-agent，來源標註爲 enterprise，當前版本 1.0.1。技能標籤包含 requires_api_key=true，表示需要配置騰訊雲 API 密鑰後才能調用。
它解決的核心問題：對兩張圖片中的人臉做相似度比較，返回 0~100 分的人臉相似度分數；支持 圖片 Base64 與 圖片 URL 兩種輸入（本地文件可由腳本自動轉 Base64），可用於判斷兩張人臉是否爲同一人。
SkillHub 頁面：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-faceid-compareface
官方索引：https://api.skillhub.cn/tencent-adm/tencentcloud-faceid-compareface
核心功能¶
以下能力來自技能說明與上游 SKILL.md（與騰訊雲 CompareFace 產品一致）：
- 人臉相似度比對：對 A、B 兩張圖各自檢出的人臉打分。
- 同一人判斷：結合分數與算法版本給出是否同一人等結構化結果（腳本輸出 JSON，含
Score、IsSamePerson等字段）。 - 多輸入方式：
--image-a/--image-b（本地路徑或 Base64 字符串），或--url-a/--url-b（圖片 URL；URL 優先級高於同側 image 參數）。 - 質量控制：可選
--quality-control（0~4）過濾低質量圖。 - 算法版本：
--face-model-version支持 2.0、3.0，默認 3.0。 - 旋轉檢測：可選
--need-rotate-detection（0 關閉 / 1 開啓）。
接口產品文檔：https://cloud.tencent.com/document/product/867/44987
安裝與啓用¶
從 SkillHub 安裝¶
在 SkillHub 技能頁打開 TencentCloud FaceID CompareFace，按頁面說明 將安裝提示詞發送給你使用的 AI 助手，由助手完成技能包拉取與目錄落盤。包座標：
@tencent-adm/tencentcloud-faceid-compareface
版本 1.0.1。頁面未單獨列出 Cursor、Codex CLI、Claude Code 的差異命令時，以「提示詞 + 座標」方式在各 Agent 中啓用即可；具體落盤路徑遵循你所用客戶端的 Skills 配置。
運行環境與密鑰¶
技能腳本依賴 Python 與騰訊雲 SDK，需提前準備：
pip install tencentcloud-sdk-python
環境變量（調用前寫入 shell 或 Agent 運行環境）：
TENCENTCLOUD_SECRET_ID=你的SecretId
TENCENTCLOUD_SECRET_KEY=你的SecretKey
要求：Python 3.6+。未配置密鑰時，CompareFace 請求無法通過騰訊雲鑑權。
典型用法¶
安裝完成後，在技能目錄下執行 scripts/main.py。下列示例與官方 SKILL.md 一致，可在技能根目錄復現。
兩張本地人臉圖（自動轉 Base64）：
python scripts/main.py --image-a ./face_a.jpg --image-b ./face_b.jpg
兩張圖片 URL：
python scripts/main.py --url-a "https://example.com/face_a.jpg" --url-b "https://example.com/face_b.jpg"
混合輸入並指定 3.0 算法與質量控制：
python scripts/main.py --image-a ./face_a.jpg --image-b ./face_b.jpg --face-model-version 3.0 --quality-control 2
成功時腳本返回 JSON，例如：
{
"Score": 87.5,
"ScoreDesc": "高度相似，可認定爲同一人（3.0版本）",
"IsSamePerson": true,
"FaceModelVersion": "3.0",
"RequestId": "xxx"
}
在 Agent 對話中，用戶表達「比對兩張人臉」「1:1 驗證是否同一人」等意圖時，模型應選用本技能並按上述參數調用腳本，而不是自行猜測相似度。
適用場景與注意¶
適合誰
- 已在用騰訊雲人臉識別、需要在 Coding Agent 裏做人臉 1:1 比對的開發者。
- 希望把 CompareFace 參數、閾值說明、合規提示寫進
SKILL.md，減少重複查文檔的團隊。
輸入與檢出
- 格式：PNG、JPG、JPEG、BMP；不支持 GIF。
- Base64 編碼後不超過 5MB；分辨率與人臉選取規則見技能文檔（多臉時默認取置信度最高的一張）。
閾值參考（3.0 版本，來自技能文檔）
| 分數範圍 | 建議判斷 |
|---|---|
| ≥ 40 分 | 疑似同一人 |
| ≥ 50 分 | 可認定爲同一人（推薦閾值） |
| ≥ 60 分 | 高度確信爲同一人 |
2.0 版本閾值更高（例如推薦認定閾值 ≥ 80 分），切換版本時需同步調整業務策略。
合規
技能明確要求：處理人臉等個人信息前，須取得個人信息主體合法、有效同意或其他合法性基礎；具體以騰訊雲官網服務協議爲準。
平臺側信息
SkillHub 上該技能評分 100000，下載 1428 次，安裝 38 次（以 SkillHub 頁面展示爲準，會隨時間變化）。
結尾¶
TencentCloud FaceID CompareFace 把騰訊雲 CompareFace 收斂成 Agent 可觸發的標準技能：密鑰配好、腳本參數清晰，即可在對話裏完成雙圖人臉相似度比對。需要安裝或查看說明時，請打開 SkillHub 官方頁：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-faceid-compareface
