语音识别API服务 - ChromaDB版本

基于多用户集合ChromaDB向量数据库的高性能语音识别系统，提供声纹识别、用户管理和音频处理功能。

🚀 项目特性

• 🎯 语音识别: 高精度的声纹识别和身份验证
• 👥 多用户支持: 每个用户独立集合，数据隔离
• 💾 ChromaDB存储: 基于向量数据库的高效检索
• ⏰ 临时存储: 支持临时用户注册，自动过期清理
• 🔄 自动刷新: 识别时自动刷新临时用户有效期
• 🚀 高性能: 毫秒级响应时间
• 🔧 RESTful API: 标准HTTP接口，易于集成
• 🛡️ 数据安全: 本地存储，隐私保护
• 📊 统计分析: 完整的用户和系统统计功能

📋 系统要求

• Python 3.8+
• 依赖包见 requirements.txt
• Windows/Linux/macOS

🛠️ 安装配置

1. 克隆项目

git clone <repository-url>
cd le_bot_vpr

2. 安装依赖

pip install -r requirements.txt

3. 环境变量配置 (可选)

# API配置
export API_HOST="0.0.0.0"
export API_PORT="8000"
export API_DEBUG="false"

# ChromaDB配置
export CHROMA_PERSIST_DIR="./voice_chroma_db"

# 缓存配置
export CACHE_TIMEOUT="300"
export LAZY_LOAD="true"

🚀 启动服务

开发模式启动

python run_server.py

生产模式启动

# 使用Gunicorn (推荐)
pip install gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

# 或使用uvicorn直接启动
uvicorn app.main:app --host 0.0.0.0 --port 8000

自定义配置启动

python run_server.py --host 0.0.0.0 --port 8080 --debug

服务启动后访问：

• API服务: http://localhost:8000
• API文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health

📡 API接口文档

基础信息

• 基础URL: http://localhost:8000/api/v4/vpr
• 请求格式: multipart/form-data (文件上传)
• 响应格式: application/json
• 字符编码: UTF-8

1. 注册用户音频

注册用户的语音特征到系统中。

接口: POST /api/v4/vpr/register

参数:

• file (file): 音频文件，支持格式: .wav, .mp3, .flac, .m4a, .ogg, .aac
• user_id (string): 用户唯一标识
• person_name (string): 人员姓名
• relationship (string): 与用户的关系，默认: "朋友"
• is_temporal (bool): 是否为临时存储，默认: false（临时存储固定7天后过期）

示例请求:

# 注册永久用户
curl -X POST http://localhost:8000/api/v4/vpr/register \
  -F "file=@audio.wav" \
  -F "user_id=user001" \
  -F "person_name=张三" \
  -F "relationship=本人"

# 注册临时用户（7天后自动过期）
curl -X POST http://localhost:8000/api/v4/vpr/register \
  -F "file=@audio.wav" \
  -F "user_id=user001" \
  -F "person_name=访客001" \
  -F "relationship=访客" \
  -F "is_temporal=true"

示例响应:

{
  "success": true,
  "message": "成功注册 张三 (本人) 音频特征",
  "user_id": "user001",
  "person_name": "张三",
  "voice_id": null,
  "registration_time": "2025-11-19 20:43:36"
}

2. 语音识别

识别上传的音频对应的用户身份。

接口: POST /api/v4/vpr/recognize

参数:

• file (file): 音频文件
• user_id (string, 可选): 指定在特定用户下搜索
• threshold (float): 识别阈值，范围 0.0-1.0，默认: 0.6

示例请求:

curl -X POST http://localhost:8000/api/v4/vpr/recognize \
  -F "file=@test_audio.wav" \
  -F "user_id=user001" \
  -F "threshold=0.3"

示例响应:

{
  "success": true,
  "message": "成功识别: 张三 (本人)",
  "user_id": "user001",
  "voice_id": "user001_张三_1663556282",
  "person_id": "user001_张三_1663556282",
  "person_name": "张三",
  "is_user": true,
  "confidence": 1.0,
  "similarity": 1.0,
  "processing_time_ms": 126.41,
  "match_details": {}
}

3. 获取用户列表

获取所有已注册的用户及其统计信息。

接口: GET /api/v4/vpr/users

示例响应:

{
  "success": true,
  "users": [
    {
      "user_id": "user001",
      "user_name": null,
      "total_persons": 3,
      "total_audio_features": 5,
      "persons": []
    }
  ],
  "count": 1
}

4. 获取用户人员列表

获取指定用户的所有人员信息。

接口: GET /api/v4/vpr/users/{user_id}/persons

示例响应:

[
  {
    "person_id": "user001_张三_1663556282",
    "person_name": "张三",
    "audio_count": 3,
    "created_at": "2025-11-19T20:43:36.374385"
  }
]

5. 获取用户统计

获取指定用户的详细统计信息。

接口: GET /api/v4/vpr/stats/{user_id}

示例响应:

{
  "success": true,
  "stats": {
    "user_id": "user001",
    "user_audio_count": 2,
    "total_persons": 2,
    "total_audio_features": 6,
    "persons_detail": [
      {
        "person_id": "user001_张三_1663556364",
        "person_name": "张三",
        "audio_count": 2,
        "created_at": "2025-11-19T20:44:17.981238"
      }
    ],
    "last_updated": "2025-11-19T12:46:04.781949"
  },
  "message": "用户统计信息获取成功"
}

6. 获取全局统计

获取整个系统的统计信息。

接口: GET /api/v4/vpr/stats

示例响应:

{
  "success": true,
  "stats": {
    "total_users": 10,
    "total_persons": 25,
    "total_audio_features": 50,
    "last_updated": "2025-11-19T12:46:09.011458",
    "storage_info": {
      "storage_type": "single_collection_per_user",
      "total_users": 10,
      "base_directory": "./voice_chroma_db",
      "hnsw_space": "cosine",
      "collections_per_user": 1
    },
    "cache_status": {
      "cached_users": 5,
      "cache_timeout": 300
    }
  },
  "message": "全局统计信息获取成功"
}

7. 获取存储信息

获取ChromaDB存储系统信息。

接口: GET /api/v4/vpr/storage/info

示例响应:

{
  "success": true,
  "storage_info": {
    "storage_type": "single_collection_per_user",
    "total_users": 10,
    "base_directory": "./voice_chroma_db",
    "hnsw_space": "cosine",
    "collections_per_user": 1
  }
}

8. 清空缓存

清空内存缓存以释放资源。

接口: POST /api/v4/vpr/cache/clear

示例响应:

{
  "success": true,
  "message": "内存缓存已清空"
}

9. 删除用户

删除指定用户及其所有数据（谨慎操作）。

接口: DELETE /api/v4/vpr/users/{user_id}

示例响应:

{
  "success": true,
  "message": "用户 user001 及其所有数据已删除"
}

10. 清理临时向量

手动清理过期的临时向量（通常不需要手动调用，系统会每天凌晨2点自动清理）。

接口: POST /api/v4/vpr/cleanup-temporal

参数:

• user_id (query, 可选): 指定用户ID，如果不指定则清理所有用户的过期向量

示例请求:

# 清理所有用户的过期临时向量
curl -X POST http://localhost:8000/api/v4/vpr/cleanup-temporal

# 清理指定用户的过期临时向量
curl -X POST http://localhost:8000/api/v4/vpr/cleanup-temporal?user_id=user001

示例响应:

{
  "success": true,
  "message": "清理完成",
  "deleted_count": 5,
  "total_checked": 20,
  "user_id": null,
  "timestamp": "2025-12-15 15:30:00"
}

11. 删除用户人员

删除用户下的特定人员及其所有音频。

接口: DELETE /api/v4/vpr/users/{user_id}/persons/{person_id}

示例响应:

{
  "success": true,
  "message": "人员 张三 及其所有音频已删除"
}

🔧 开发和测试

运行测试

# 运行HTTP API测试
python test_chroma_windows.py

# 运行其他测试
python test_simple_chroma.py
python test_multi_collection_chroma.py

环境检查

# 检查环境和依赖
python run_server.py --check-only

调试模式

# 启用调试模式
python run_server.py --debug

📊 系统架构

语音识别API系统
├── API层 (FastAPI)
│   ├── 文件上传处理
│   ├── 参数验证
│   └── 响应格式化
├── 业务逻辑层
│   ├── 语音特征提取
│   ├── 相似度计算
│   └── 用户管理
├── 数据访问层
│   ├── ChromaDB客户端
│   ├── 缓存管理
│   └── 向量检索
└── 存储层
    ├── 向量数据库 (ChromaDB)
    ├── 文件存储
    └── 缓存存储

🎯 核心功能说明

语音识别流程

1. 音频预处理: 格式验证、降噪处理
2. 特征提取: 使用深度学习模型提取声纹特征
3. 向量存储: 将特征向量存储到ChromaDB
4. 相似度计算: 使用余弦相似度进行身份匹配
5. 结果返回: 返回识别结果和置信度

临时存储功能

1. 临时用户注册: 支持注册临时用户，自动设置7天过期时间
2. 自动过期清理: 每天凌晨2点自动清理过期的临时向量
3. 识别刷新: 识别成功时自动刷新最相似临时向量的过期时间
4. 手动清理: 提供API接口手动触发过期向量清理

使用场景:

• 访客管理：为临时访客注册语音，7天后自动清理
• 场景限制：限制数据存储时间，控制存储空间
• 测试环境：临时注册测试用户，避免手动清理

工作原理:

• 注册时：设置 is_temporal=true，系统自动计算过期日期
• 识别时：自动刷新匹配到的临时向量，延长7天有效期
• 清理时：比较当前日期与过期日期，删除过期数据

多用户架构

• 每个用户拥有独立的向量集合
• 数据完全隔离，确保隐私安全
• 支持用户级的CRUD操作
• 高效的跨用户搜索能力

性能优化

• 缓存机制: 内存缓存热点数据
• 懒加载: 按需加载用户数据
• 向量索引: HNSW索引加速检索
• 并发处理: 支持多用户并发操作

🛡️ 安全特性

• 本地存储: 所有数据存储在本地，不上传云端
• 数据隔离: 用户间数据完全隔离
• 权限控制: 基于user_id的访问控制
• 格式验证: 严格的文件格式验证

📈 性能指标

• 响应时间: 通常 < 200ms
• 识别准确率: > 95%
• 并发支持: 100+ 并发请求
• 存储效率: 每个音频约1KB向量数据

🔧 故障排除

常见问题

1. 服务启动失败

   # 检查端口占用
   netstat -ano | findstr :8000
   
   # 检查依赖安装
   pip install -r requirements.txt

2. 音频识别失败

   # 检查音频格式是否支持
   # 确保音频文件不为空
   # 检查采样率是否为16kHz

3. 数据库连接问题

   # 检查ChromaDB权限
   # 确认存储目录存在且可写
   # 检查磁盘空间

日志查看

# 查看API日志
tail -f api.log

# 查看错误日志
tail -f error.log

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

• 项目主页: [GitHub Repository]
• 问题反馈: [GitHub Issues]
• 技术文档: [Wiki]

🔄 版本历史

• v5.1.0 - 临时存储功能版本

  • 临时用户注册（7天自动过期）
  • 识别时自动刷新临时用户有效期
  • 每天凌晨2点自动清理过期数据
  • 手动清理过期向量API

• v5.0.0 - ChromaDB多用户集合版本

  • 完整的多用户支持
  • HTTP API接口
  • 高性能向量检索

• v4.0.0 - ChromaDB基础版本

  • ChromaDB集成
  • 基础识别功能

• v3.0.0 - MongoDB优化版本

  • 性能优化
  • 缓存机制

• v2.0.0 - MongoDB版本

  • 数据库支持
  • 用户管理

• v1.0.0 - 初始版本

  • 基础识别功能

---

注意: 本系统仅用于学习和研究目的，请确保在合规的环境中使用。