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集成指南。