MCP Speaker Diarization

🚀 MCP说话人识别系统

MCP说话人识别系统是一个一体化的完整解决方案，结合了GPU加速的说话人识别与转录功能，并提供了Web界面和REST API。它集成了pyannote.audio进行说话人识别，以及faster-whisper进行语音转录，适用于AI智能体集成和个人项目。

🚀 快速开始

前提条件

1. 获取HuggingFace令牌
   • 在 huggingface.co 创建账户。
   • 在 huggingface.co/settings/tokens 生成令牌。
   • 接受以下模型的使用条款：
     • pyannote/speaker-diarization-community-1
     • pyannote/embedding
2. 安装NVIDIA容器工具包（使用Docker部署时需要）

# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

选项1：使用Docker部署（推荐）

# 克隆仓库
git clone <repository-url>
cd speaker-diarization-app

# 配置环境
cp .env.example .env
# 编辑.env文件并添加你的HF_TOKEN

# 构建并运行
docker-compose up --build

# 在后台运行
docker-compose up -d

# 查看日志
docker-compose logs -f

访问应用程序：

• API文档：http://localhost:8000/docs
• API端点：http://localhost:8000/api/v1
• MCP服务器：http://localhost:8000/mcp

若要使用Web界面，请参考单独的 Next.js前端仓库。

选项2：本地开发（使用Python虚拟环境）

# 安装系统依赖
sudo apt-get update
sudo apt-get install -y ffmpeg git portaudio19-dev

# 设置Python环境
python -m venv venv
source venv/bin/activate  # 在Windows上使用：venv\Scripts\activate

# 安装Python包
pip install -r requirements.txt

# 配置环境
cp .env.example .env
# 编辑.env文件并添加你的HF_TOKEN

# 运行应用程序
./run_local.sh

# 或者手动运行：
# export HF_TOKEN="your_token_here"
# python -m app.main

首次运行：

• 模型将自动下载（约3 - 5GB）。
• 启动时加载模型可能需要2 - 3分钟。
• 会分配GPU内存（可使用nvidia-smi查看）。

✨ 主要特性

• 持久的说话人识别：一次性注册说话人，在所有未来的录音和对话中都能识别他们（不仅仅是“SPEAKER_00”、“SPEAKER_01”等标签）。
• 双检测器情感系统：将通用AI（emotion2vec+）与个性化语音配置文件相结合，显著提高了9种情感（愤怒、快乐、悲伤、中性、恐惧、惊讶、厌恶、其他、未知）的检测准确率。
• 个性化学习：系统通过加权嵌入合并从修正中学习每个说话人的独特情感语音模式（无需重新注册）。
• 追溯智能：识别一个片段 → 所有具有该语音的过去片段会自动更新。
• 转录：使用faster-whisper（large-v3），提供单词级别的置信度分数，支持99种语言。
• 实时流处理：通过WebSocket流实现实时录音、VAD和即时处理。
• 支持AI的架构：内置MCP服务器，可与AI助手（Claude Desktop、Flowise、自定义智能体）无缝集成，为自然多方对话提供所需的上下文记忆。
• REST API：在/api/v1/*提供完整的编程访问（交互式文档请参阅/docs）。
• 备份/恢复：导出/导入说话人配置文件和语音设置。
• 生产就绪：能够处理数千个对话、批量处理、实时流、MP3转换，并能高效扩展。

📦 安装指南

硬件要求

• GPU：支持CUDA 12.x的NVIDIA GPU
  • 测试机型：NVIDIA RTX 3090（24GB VRAM） - 性能出色
  • VRAM要求（faster-whisper效率很高）：
    • 说话人识别 + 嵌入：约2 - 3GB基本要求
    • 情感检测：约2GB（emotion2vec_plus_large）
    • Whisper模型额外占用（根据可用VRAM选择）：
      • tiny/base：约400 - 500MB（包含情感检测时总计至少5GB）
      • small：约1GB（包含情感检测时推荐6GB）
      • medium：约2GB（包含情感检测时推荐7GB）
      • large-v3：约3 - 4GB（包含情感检测时推荐8 - 9GB，默认）
  • 适用机型：消费级GPU（GTX 1060 6GB+、1080、2060、3060、3090、4080、4090等）
• CPU备用方案：可以在CPU上运行，但速度会显著变慢（强烈推荐使用GPU）
• RAM：最低8GB，推荐16GB以上
• 存储空间：模型约需10GB，外加音频录音的存储空间

软件要求

• 操作系统：Linux（在Ubuntu上测试）、macOS（通过Docker）、Windows（通过WSL2 + Docker）
• Python：3.11或3.12
• CUDA：12.4（包含在Docker镜像中）
• cuDNN：9.x（自动安装）
• Docker（可选但推荐）：20.10以上版本，并安装NVIDIA容器工具包

系统依赖

• ffmpeg：音频处理和格式转换
• git：用于下载HuggingFace模型
• portaudio19-dev：实时麦克风录音（可选）

💻 使用示例

基础用法

# 以下是使用REST API处理音频的基础示例
import requests

# 处理音频文件
with open("meeting.wav", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/v1/process",
        files={"audio_file": f}
    )

conversation = response.json()

# 获取带有说话人标签和情感的对话片段
for segment in conversation["segments"]:
    print(f"{segment['speaker_name']}: {segment['text']}")
    print(f"  Emotion: {segment['emotion_category']} ({segment['emotion_confidence']})")

高级用法

# 以下是使用MCP服务器与AI助手集成的高级示例
# 假设已经配置好MCP客户端
import json

# AI助手接收到对话
Assistant = "I heard multiple voices. Who were you speaking with?"
User = "That was my colleague Sarah"

# AI调用MCP工具
mcp_url = "http://localhost:8000/mcp"
payload = {
    "jsonrpc": "2.0",
    "method": "identify_speaker_in_segment",
    "params": {
        "segment_id": 145,
        "speaker_name": "Sarah",
        "auto_enroll": true
    },
    "id": 1
}
headers = {'Content-Type': 'application/json'}
response = requests.post(mcp_url, data=json.dumps(payload), headers=headers)
result = response.json()

# 系统自动完成以下操作
# 1. 从片段145创建Sarah的说话人配置文件
# 2. 更新所有带有Sarah声音的过去片段
# 3. 未来的录音将自动识别Sarah

📚 详细文档

使用场景

• AI集成：使AI助手能够在对话中记住并区分多个说话人。
• 会议转录：自动标记并提供情感上下文。
• 研究与分析：对多方对话进行分析，保持身份的持久性。
• 客户支持：通过情感跟踪区分代理和客户。

技术栈

情感检测

工作原理

双检测器系统将通用AI与个性化语音配置文件相结合，显著提高了准确性。两个互补的检测器协同工作：

1. emotion2vec+检测器（1024-D情感嵌入）
   • 基于大型数据集训练的通用情感AI。
   • 适用于所有说话人（已知/未知）。
   • 9个类别：愤怒、快乐、悲伤、中性、恐惧、惊讶、厌恶、其他、未知。
2. 语音配置文件检测器（512-D说话人嵌入）
   • 学习每个说话人的独特情感语音模式。
   • 每种情感需要3个以上的语音样本才能激活。
   • 检查通用和所有特定情感的配置文件（如Andy、Andy_angry、Andy_happy等）。

最佳匹配获胜：如果Andy_angry语音配置文件的匹配度为92%，而emotion2vec的中性匹配度为78%，则语音检测器获胜。

阈值配置

环境变量：

• EMOTION_THRESHOLD=0.6 - 情感匹配灵敏度（0.3 - 0.9，值越高越严格）
• SPEAKER_THRESHOLD=0.30 - 语音匹配灵敏度（0.20 - 0.35，值越高越严格）

两个阈值都可以通过API针对每个说话人或每种情感进行自定义，以实现细粒度控制。

个性化学习

纠正任何片段的情感 → 系统自动学习：

• 存储用于emotion2vec匹配的情感嵌入（1024-D）。
• 存储用于语音配置文件匹配的语音嵌入（512-D）。
• 使用加权平均进行合并（旧样本权重更大）。
• 也更新通用说话人配置文件。
• 每种情感经过3次以上的纠正后 → 语音检测器激活。

手动纠正表示100%置信度，无需重新识别说话人。

性能

• 速度：每个片段约37ms（语音匹配额外5ms）。
• VRAM：约2GB emotion2vec + 约1GB说话人嵌入（共享）。
• 激活条件：每种情感需要3个以上的语音样本。

系统配置

所有设置都通过.env文件中的环境变量进行配置：

必需配置

# HuggingFace令牌，用于访问模型
HF_TOKEN=your_huggingface_token_here

可选配置（已优化默认值）

# 数据库位置
DATABASE_URL=sqlite:////app/volumes/speakers.db

# 说话人识别阈值（0.0 - 1.0）
# 值越低越严格，误报越少
# 推荐：正常家庭使用为0.30（在准确性和匹配度之间取得良好平衡）
# 可选：对于电影音频/背景音乐，可设置为0.20以进行更严格的匹配
SPEAKER_THRESHOLD=0.30

# 嵌入提取的上下文填充（秒）
# 在片段前后添加时间以获得更稳定的嵌入
# 最佳值：0.15s（匹配度67.4%，电影音频中仅3次误识别）
CONTEXT_PADDING=0.15

# 处理片段前的静音持续时间（秒）
# 仅适用于实时录音
# 值越低响应越快，值越高片段越完整
SILENCE_DURATION=0.5

# 过滤常见的Whisper幻觉
# 如果真实语音被过滤，请设置为false
FILTER_HALLUCINATIONS=true

# 全局情感匹配阈值（0.3 - 1.0）
# 值越高匹配越严格（需要更接近学习到的情感配置文件）
# 值越低越宽松（接受更广泛的情感表达）
# 默认值：0.6（平衡 - 适用于大多数用例）
EMOTION_THRESHOLD=0.6

# Whisper转录模型（faster-whisper with CTranslate2）
# 根据GPU能力选择：
# - tiny.en / tiny: 约400MB VRAM，最快，最低准确性
# - base.en / base: 约500MB VRAM，非常快，基本准确性
# - small.en / small: 约1GB VRAM，快速，良好的准确性
# - medium.en / medium: 约2GB VRAM，较慢，更好的准确性
# - large-v3 / large-v2: 约3 - 4GB VRAM，最慢，最佳准确性
WHISPER_MODEL=large-v3

# Whisper语言设置
# - "en" = 仅英语（默认，最快）
# - "auto" = 自动检测语言（支持99种语言）
# - 或者指定："es"、"fr"、"de"、"zh"、"ja"等
WHISPER_LANGUAGE=en

推荐设置

默认设置针对正常家庭使用进行了优化：

• SPEAKER_THRESHOLD=0.30：在家庭对话中，在准确性和匹配度之间取得良好平衡。
• CONTEXT_PADDING=0.15：对于有背景噪音/音乐的音频是最佳选择。
• SILENCE_DURATION=0.5：在响应速度和完整句子捕获之间取得平衡。
• WHISPER_MODEL=large-v3：最佳准确性，需要约3 - 4GB VRAM。对于较弱的GPU，可以使用small（约1GB）或base（约500MB）。
• WHISPER_LANGUAGE=en：仅英语（最快）。使用auto进行多语言自动检测或指定语言代码。

对于电影音频或具有挑战性的条件下进行更严格的匹配，可以将SPEAKER_THRESHOLD降低到0.20。

远程访问

如果您在远程服务器（例如，带有GPU的无头Ubuntu服务器）上运行应用程序，可以通过SSH端口转发访问Web界面。

SSH隧道（Windows）

使用PowerShell或命令提示符：

ssh -L 8000:localhost:8000 username@remote-server-ip

使用PuTTY：

1. 打开PuTTY并输入服务器主机名/IP。
2. 导航到：Connection → SSH → Tunnels。
3. 添加转发规则：
   • 源端口：8000
   • 目标：localhost:8000
   • 点击“Add”
4. 返回会话选项卡并连接

连接后：

• 在Windows机器上打开浏览器。
• 导航到：http://localhost:8000/docs（API文档）

SSH隧道（Linux/Mac）

ssh -L 8000:localhost:8000 username@remote-server-ip

然后在http://localhost:8000/docs访问API文档。

重要提示

⚠️ 重要提示

此应用程序没有内置的身份验证或加密。请勿在开放/公共网络上暴露它。仅在受信任的本地网络或通过SSH隧道使用。

💡 使用建议

• SSH连接在使用应用程序时必须保持打开状态。
• 所有音频处理都在远程服务器上进行（利用远程GPU）。
• 本地机器仅显示Web界面。
• 麦克风录音使用本地浏览器的麦克风，并上传到服务器。
• 对于网络部署，考虑使用带有nginx反向代理和身份验证的适当HTTPS。

REST API与MCP服务器

API概述

基础URL：http://localhost:8000/api/v1 交互式文档：http://localhost:8000/docs（带有测试界面的Swagger UI）

关键端点：

• 系统
  • GET /status - 健康检查、GPU状态、系统统计信息
• 设置
  • GET/POST /settings/voice - 运行时配置（阈值、填充、过滤）
  • POST /settings/voice/reset - 重置为默认值
• 说话人
  • GET /speakers - 列出所有已注册的说话人及其片段计数
  • POST /speakers/enroll - 使用音频样本注册新说话人
  • PATCH /speakers/{id}/rename - 重命名说话人（自动更新所有过去的片段）
  • DELETE /speakers/{id} - 删除说话人配置文件
  • DELETE /speakers/unknown/all - 删除所有“Unknown_*”说话人
• 情感配置文件
  • GET /speakers/{id}/emotion-profiles - 查看学习到的情感配置文件
  • DELETE /speakers/{id}/emotion-profiles - 重置情感配置文件
  • GET/PATCH /speakers/{id}/emotion-threshold - 每个说话人的情感阈值
  • PATCH /speakers/{id}/emotion-profiles/{emotion}/threshold - 每种情感的阈值
• 对话
  • GET /conversations - 列出所有对话（分页）
  • GET /conversations/{id} - 获取带有所有片段的完整转录
  • PATCH /conversations/{id} - 更新对话元数据
  • DELETE /conversations/{id} - 删除对话和音频
  • POST /conversations/{id}/reprocess - 使用当前说话人重新运行识别
  • POST /conversations/{id}/recalculate-emotions - 重新计算所有片段的情感
  • POST /process - 上传并处理音频文件
• 片段
  • POST /conversations/{id}/segments/{seg_id}/identify - 识别说话人（自动更新所有过去的片段）
  • POST /conversations/{id}/segments/{seg_id}/correct-emotion - 纠正并学习情感
  • PATCH /conversations/{id}/segments/{seg_id}/misidentified - 将说话人标记为误识别
  • PATCH /conversations/{id}/segments/{seg_id}/emotion-misidentified - 将情感标记为错误
  • GET /conversations/segments/{seg_id}/audio - 下载片段音频
• 流处理
  • WS /streaming/ws - 用于实时录音的WebSocket
• 备份/恢复
  • POST /profiles - 创建新的备份配置文件
  • GET /profiles - 列出所有备份配置文件
  • GET /profiles/{name} - 获取特定配置文件的详细信息
  • PATCH /profiles/{name} - 将当前状态保存到配置文件
  • DELETE /profiles/{name} - 删除备份配置文件
  • POST /profiles/{name}/checkpoints - 创建检查点
  • POST /profiles/restore - 从备份中恢复
  • GET /profiles/download/{name} - 下载备份JSON
  • POST /profiles/import - 导入备份JSON

📖 带有示例的完整文档：http://localhost:8000/docs

MCP服务器集成

模型上下文协议（MCP） 使AI助手能够直接与说话人识别系统进行交互。

MCP端点：http://localhost:8000/mcp 协议：基于HTTP的JSON-RPC 2.0，支持服务器发送事件 兼容对象：Claude Desktop、Flowise、自定义MCP客户端

可用的MCP工具（11个）：

1. list_conversations - 获取对话ID和元数据
2. get_conversation - 获取带有说话人标签的完整转录
3. get_latest_segments - 获取跨对话的最近片段
4. identify_speaker_in_segment - 标记未知说话人（自动更新所有过去的片段）
5. rename_speaker - 重命名现有说话人（自动更新所有过去的片段）
6. list_speakers - 获取所有已注册的说话人配置文件
7. delete_speaker - 删除说话人配置文件
8. delete_all_unknown_speakers - 清理“Unknown_*”说话人
9. update_conversation_title - 设置对话标题
10. reprocess_conversation - 使用更新后的说话人配置文件重新运行识别
11. search_conversations_by_speaker - 查找特定说话人出现的所有对话

关键特性：

• 自动追溯更新：识别/重命名说话人会自动更新所有过去的片段。
• 无需重新处理：系统在会话之间保持说话人身份。
• 自动注册：可以从任何片段创建说话人配置文件。
• 对话上下文：AI可以检索完整的“谁说了什么”历史记录。

示例MCP客户端配置（Flowise/Claude Desktop）：

{
    "mcpServers": {
        "speaker-diarization": {
            "url": "http://localhost:8000/mcp",
            "transport": "http"
        }
    }
}

使用示例：

# AI助手接收到对话
Assistant: "I heard multiple voices. Who were you speaking with?"
User: "That was my colleague Sarah"

# AI调用MCP工具
# identify_speaker_in_segment(segment_id=145, speaker_name="Sarah", auto_enroll=true)

# 系统自动完成以下操作
# 1. 从片段145创建Sarah的说话人配置文件
# 2. 更新所有带有Sarah声音的过去片段
# 3. 未来的录音将自动识别Sarah

AI助手集成示例

使用REST API或MCP服务器构建具有持久说话人记忆的对话式AI助手。

集成方法

• 选项1：REST API（完全控制）
  • 您的应用程序管理音频录制和流处理。
  • 将音频POST到/api/v1/process或使用WebSocket/streaming/ws。
  • 接收带有说话人标签和情感的片段。
  • 通过/conversations端点查询对话历史记录。
• 选项2：MCP服务器（原生支持AI）
  • 连接Claude Desktop、Flowise或自定义MCP客户端。
  • AI助手直接调用10个MCP工具进行说话人管理。
  • 识别/重命名说话人时自动进行追溯更新。
  • 零代码 - 只需配置MCP端点。

示例工作流程

场景：AI助手进行多方对话

1. 检测到未知说话人

User: "Alright mate, how are you doing?"
Unknown: "Good mate, you?"

AI: "Who are you speaking to?"
User: "That's Nick"

2. AI通过MCP识别说话人

# MCP工具调用（如果使用Claude/Flowise则自动进行）
identify_speaker_in_segment(
    segment_id=145,
    speaker_name="Nick",
    auto_enroll=true
)

3. 系统自动更新所有过去的片段
   • 从片段145创建Nick的语音配置文件。
   • 更新所有带有Nick声音的先前未知片段。
   • 未来的录音将自动识别Nick。
4. AI在未来的对话中记住Nick

Nick: "Hey, remember what we discussed yesterday?"
AI: "Yes Nick, you mentioned the project deadline..."

🔧 技术细节

架构概述

系统采用并行处理架构，将转录和说话人识别并行执行，提高处理速度约50%。主要处理步骤包括音频格式转换、并行转录和说话人识别、片段对齐、嵌入提取、说话人匹配、未知说话人处理、自动注册和情感检测等。

处理流程

1. 音频输入
   • 上传：MP3/WAV文件自动转换并保存到data/recordings/。
   • 实时：浏览器麦克风 → 流式片段保存到data/stream_segments/。
2. 并行处理（比顺序处理更快）
   • 说话人识别（pyannote）：检测说话人轮换，输出带有匿名标签（SPEAKER_00、SPEAKER_01等）的片段。
   • 转录（Whisper）：将语音转换为带有时间戳的文本。
   • 两者使用ThreadPoolExecutor同时运行。
3. 片段对齐
   • 通过时间戳重叠将转录片段与说话人标签匹配。
   • 使用片段中点进行匹配：(start + end) / 2。
   • 如果没有精确重叠，则回退到最接近的片段。
4. 嵌入提取
   • 对于每个片段，使用pyannote嵌入模型提取512维语音签名。
   • 在前后添加上下文填充（0.15s），以增强对背景噪音的鲁棒性。
   • 最小片段持续时间：0.5秒。
5. 说话人匹配
   • 将片段嵌入与已知说话人嵌入进行比较。
   • 计算余弦相似度（0.0 - 1.0）。
   • 如果相似度 > 阈值（默认0.30）：识别为已知说话人。
   • 如果相似度 ≤ 阈值：标记为“Unknown_XX”。
6. 未知说话人处理
   • 嵌入验证：检查多个未知片段是否为同一人。
   • 对相似的未知片段进行分组（相同阈值）。
   • 每个独特的语音获得唯一的“Unknown_XX”标识符。
   • 存储嵌入以供未来自动注册。
7. 自动注册（当用户识别未知说话人时）
   • 用户为任何片段提供说话人姓名。
   • 如果是新姓名：自动创建说话人配置文件。
   • 嵌入合并：对同一说话人的所有片段的嵌入进行平均。
   • 追溯更新：所有具有相同未知标签的过去片段都会更新。
   • 持续改进：每次识别都会加强说话人配置文件。

语音活动检测（VAD）

两个独立的VAD系统协同工作：

1. 实时录音VAD（基于能量）
   • 计算RMS能量：sqrt(mean(audio^2))。
   • 阈值：0.005（可配置）。
   • 实时检测语音与静音。
   • 在UI中显示实时指示：“🟢 检测到语音”或“⚪ 空闲”。
   • 在X秒静音（默认0.5秒）后，触发片段处理。
2. 转录VAD（Whisper内置）
   • 使用Silero VAD模型。
   • 在转录前过滤非语音内容。
   • 减少幻觉（“thank you.”、“thanks for watching”）。
   • 通过vad_filter=True参数启用。

误识别纠正

1. 标记为误识别：将片段排除在嵌入计算之外。
2. 重新分配给正确的说话人：更新两个说话人的嵌入。
3. 自动重新计算：从所有非误识别片段中平均嵌入。
4. 防止嵌入损坏：确保说话人配置文件保持准确。

高级特性

嵌入合并

在识别未知说话人或重新识别现有说话人时：

• 从不替换嵌入（会丢失历史数据）。
• 始终使用平均法合并：(existing_embedding + new_embedding) / 2。
• 持续改进：每次录音都会加强说话人配置文件。
• 处理变异性：对不同的音频条件、情感等进行平均。

追溯识别

重命名任何说话人 → 所有过去的片段会自动更新：

# 用户在对话5中将Unknown_01识别为“Alice”
curl -X POST "http://localhost:8000/api/v1/conversations/5/segments/123/identify?speaker_name=Alice&enroll=true"

# 系统自动完成以下操作
# 1. 创建“Alice”说话人配置文件（如果是新的）
# 2. 更新片段123
# 3. 查找所有说话人姓名为“Unknown_01”的片段
# 4. 将所有片段的说话人姓名更新为“Alice”
# 5. 合并所有片段的嵌入
# 6. 返回更新的片段数量

备份与恢复

导出和恢复说话人配置文件：

• 备份：
  • 将所有说话人及其嵌入导出到JSON。
  • 包括片段分配以实现完整状态恢复。
  • 保存到backups/backup_YYYYMMDD_HHMMSS.json。
  • 不包括音频文件（仅说话人数据）。
• 恢复：
  • 从备份中重建说话人数据库。
  • 恢复嵌入和片段分配。
  • 适用于测试不同的配置。
  • 适用于在不同部署之间迁移。

真实标签标注

测试和优化识别准确性：

1. 手动为片段标记真实的说话人身份。
2. 标签单独存储（不影响实际片段）。
3. 运行测试，比较预测结果与标签。
4. 优化阈值和填充参数。
5. 当前的最佳设置是通过此测试得出的。

数据持久化

目录结构

speaker-diarization-app/
├── data/
│   ├── recordings/              # 永久音频存储
│   │   ├── conv_7_full.mp3     # 实时录音（MP3）
│   │   ├── uploaded_1_tommy_converted.wav  # 上传文件
│   │   └── 20251109_160230_meeting.wav    # 带时间戳的上传文件
│   │
│   ├── stream_segments/         # 实时录音片段（临时）
│   │   └── conv_7/
│   │       ├── seg_0001.wav
│   │       ├── seg_0002.wav
│   │       └── ...
│   │
│   └── temp/                    # 临时片段提取
│       └── segment_123_456.wav
│
├── volumes/
│   ├── speakers.db              # SQLite数据库
│   └── huggingface_cache/       # 下载的模型
│
├── backups/                     # 备份快照（JSON）
│   └── backup_20251109_120000.json
│
├── scripts/                     # 实用脚本
│   ├── migrate_temp_audio.py   # 修复音频路径
│   ├── diagnose_speakers.py    # 调试问题
│   └── ...
│
└── tests/                       # 测试文件
    └── test_*.py

Docker卷

所有数据通过docker-compose.yml中的卷挂载进行持久化：

volumes:
    - ./volumes:/app/volumes          # 数据库 + 模型缓存
    - ./data:/app/data                # 音频文件
    - ./backups:/app/backups          # 备份快照

持久化内容：

• ✅ 说话人配置文件和嵌入
• ✅ 所有对话和片段
• ✅ 音频录音
• ✅ 下载的模型（约3 - 5GB）
• ✅ 备份快照

非持久化内容：

• ❌ 容器状态（重建安全）
• ❌ 日志（使用docker-compose logs -f进行监控）

📄 许可证

本项目采用 MIT许可证 - 详情请参阅LICENSE文件。

依赖项许可证

所有主要依赖项都使用与MIT兼容的宽松开源许可证：

• pyannote.audio（4.0.1）：MIT许可证
  • 模型需要HuggingFace令牌并接受使用条款。
  • 模型本身仍然是开源的，并遵循MIT许可证。
• faster-whisper（1.2.1）：MIT许可证（SYSTRAN）
• FastAPI（0.115.5）：MIT许可证
• Next.js（15.x）：MIT许可证
• PyTorch（2.5.1）：BSD 3 - 条款许可证
• SQLAlchemy（2.0.36）：MIT许可证
• Pydantic（2.11.0）：MIT许可证
• MCP（1.21.0）：MIT许可证

注意：虽然软件许可证是宽松的，但pyannote的预训练模型需要：

1. HuggingFace账户
2. 访问令牌
3. 接受模型使用条款

这是一个身份验证要求，而不是许可限制。模型仍然是开源的。

致谢

本项目基于以下优秀的开源项目构建：

• pyannote.audio 由Hervé Bredin开发 - 最先进的说话人识别和嵌入模型。
• faster-whisper 由SYSTRAN开发 - 使用CTranslate2优化的Whisper实现。
• OpenAI Whisper - 原始语音识别模型。
• FastAPI 由Sebastián Ramírez开发 - 现代Web框架。

感谢这些项目及其贡献者使本应用程序成为可能。

计划功能

自动对话总结和标题生成

• 录音结束时进行AI驱动的对话总结。
• 根据对话内容自动生成标题。
• 当前对话结束并开始新对话时触发。
• 用有意义的标题（如“与Nick讨论项目截止日期”）替换通用的“Conversation 15”。
• 有助于对话发现和上下文检索。

转录的向量数据库搜索

• 将转录文本存储在向量数据库中进行语义搜索。
• 按主题或内容查询对话，而不仅仅是说话人。
• 每个向量条目引用对话ID以便于检索。
• 实现长期记忆和上下文对话查找。
• 使用场景：
  • “上个月我们关于预算讨论了什么？”
  • “查找我们讨论产品功能的对话”
  • “显示所有与新项目相关的讨论”

贡献

欢迎贡献！请随时提交拉取请求。

贡献领域：

• 增加语言支持（目前仅支持英语）
• 性能优化
• UI/UX改进
• 文档改进

免责声明

本软件“按原样”提供，不提供任何形式的保证。开发者不保证说话人识别或转录的准确性。虽然我们已经实施了最佳实践并进行了广泛的测试，但说话人识别本质上是概率性的，可能会产生错误。

请谨慎使用：

• 手动验证重要的识别结果。
• 在您的环境中进行彻底测试。
• 尊重隐私并在录音前获得同意。
• 这是一个辅助工具，不能替代人类判断。

本代码库的某些部分是与Claude Code（AI配对编程助手）协作开发的。虽然经过了彻底测试，但我们建议在关键应用中部署之前审查代码。

有问题或遇到问题？ 在GitHub上打开一个问题，或查看现有问题以获取解决方案。

想将其与AI智能体一起使用？ 请参阅API参考部分以获取MCP集成指南。