From 8cf40d0e614fbc9e501556547db25bf9f71c95bb Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Tue, 21 Jul 2026 17:00:55 +0800
Subject: [PATCH] feat: initial speaker-id service README

- ECAPA-TDNN speaker recognition service
- endpoints: enroll, identify, verify, compare
- GPU deployment with longtasks async pattern
---
 README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 641d189..1360e02 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,61 @@
-# speaker-id
+# Speaker ID — 声纹识别服务
 
+## 概述
+
+基于 ECAPA-TDNN 的声纹识别/说话人识别服务。支持说话人注册、识别、比对。
+
+## 模型
+
+SpeechBrain ECAPA-TDNN (spkrec-ecapa-voxceleb)
+部署于 GPU 服务器，使用 longtasks 异步任务模式。
+
+## API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| /api/status | GET | 服务状态和模型信息 |
+| /api/enroll | POST | 注册说话人 (音频 → 声纹特征) |
+| /api/identify | POST | 识别说话人 (音频 → 匹配身份) |
+| /api/verify | POST | 1:1 验证 (两段音频 → 是否同一人) |
+| /api/compare | POST | 比对两个声纹向量的相似度 |
+
+## 请求示例
+
+```json
+POST /api/enroll
+{
+    "audio": "base64或文件路径",
+    "speaker_id": "speaker_001",
+    "speaker_name": "张三"
+}
+
+POST /api/identify
+{
+    "audio": "base64或文件路径",
+    "threshold": 0.7,
+    "top_k": 3
+}
+```
+
+## 响应格式
+
+```json
+{
+    "status": "SUCCEEDED",
+    "embedding": [0.123, -0.456, ...],
+    "embedding_dim": 192,
+    "elapsed": 0.523
+}
+```
+
+## 部署
+
+```bash
+cd /data/ymq/speaker-id
+bash build.sh
+sudo systemctl restart speaker-id
+```
+
+## 端口
+
+9095 (CPU + GPU)