Skip to content

cursor_document.md

Latest commit

 

History

History
161 lines (126 loc) · 7.24 KB

cursor_document.md

File metadata and controls

161 lines (126 loc) · 7.24 KB

離線版「STToolkit」系統架構文件（v0.1.0）

1. 專案目標

完全離線、跨平台（Windows / Linux x86_64）語音轉文字系統，功能涵蓋即時 STT、批次音檔轉錄與摘要。

2. 功能需求（與差異化）

# 功能 描述
FR‑01 即時 STT（WebSocket） 麥克風錄音送至 /ws/stt，<1.5 s 延遲。
FR‑02 單檔批次轉錄 /api/transcribe 一次僅受理 1 檔；任務狀態由 SQLite 資料庫管理。
FR‑03 文字匯出 TXT / MD / JSON。
FR‑04 摘要 小型中文 LLM 產出會議摘要、關鍵詞、行動項。
FR‑05 離線移植 專案目錄複製即可運行；模型預存 models/。

3. 技術棧

層 技術 說明
Front‑end Bootstrap 5.1 (離線) + Vanilla JS + Web Audio API 無外部 CDN。
Back‑end Python 3.11 + FastAPI + Uvicorn 原生 async 支援。
資料庫 SQLite3 本地資料庫，用於任務狀態管理。
STT FunASR（Hugging Face 版） funasr/paraformer-zh-streaming 與 funasr/paraformer-zh。
LLM Qwen1.5‑0.5B‑Chat (預設)；列出其他可選 MiniCPM 1B 等 皆 <1 B 參數，可 CPU 推理。
打包 PyInstaller / Docker (可選) 生成單一執行檔或映像。

4. 簡化系統架構

sequenceDiagram
    participant UI as Browser
    participant API as FastAPI
    participant DB as SQLite
    participant ASR as FunASR Worker
    participant LLM as LLM Worker
    UI->>API: WS 音訊串流 / 檔案上傳
    API->>DB: 記錄任務狀態
    API->>ASR: PCM chunk / 音檔
    ASR-->>API: 文字 (分段)
    API-->>UI: 即時字幕 (WS/SSE)
    ASR->>LLM: 轉錄完成 JSON
    LLM-->>API: 摘要 JSON
    API->>DB: 更新任務狀態
    API-->>UI: 完整結果下載
Loading

5. 專案結構（精簡後）

offline_tingwu/
├─ app/
│   ├─ main.py          # FastAPI 入口（啟動 GPU/CPU 偵測）
│   ├─ db_service.py    # SQLite 資料庫服務
│   ├─ stt_service.py   # FunASR 推理
│   └─ llm_service.py   # 摘要 (Qwen)
├─ db/                  # SQLite 資料庫檔案
├─ models/              # 預載模型
│   ├─ funasr_stream/   # paraformer-zh-streaming
│   ├─ funasr_offline/  # paraformer-zh
│   └─ qwen_0.5b/
├─ scripts/
│   ├─ download_models.sh
│   └─ detect_env.py
├─ static/ (Bootstrap5.1, JS, CSS)
└─ ...

6. 官方模型清單（Hugging Face 優先）

6.1 語音辨識

任務 Hugging Face Repo 參數 備註
流式 ASR funasr/paraformer-zh-streaming ~220 M 國語 16 kHz；支援 chunk。 (huggingface.co)
離線 ASR funasr/paraformer-zh ~220 M 離線高精度。 (huggingface.co)
VAD (可選) funasr/fsmn-vad 0.4 M 聲音端點偵測。 (huggingface.co)

6.2 小型中文 LLM (≤ 1 B)

選擇 Hugging Face Repo 參數 CPU rtf*
預設 Qwen/Qwen1.5-0.5B-Chat 0.5 B 0.6 │ (huggingface.co)
替代 openbmb/MiniCPM-1B-sft-bf16 1.2 B 1.1 │ (huggingface.co)
超小 charent/ChatLM-mini-Chinese 0.2 B 0.4

*rtf：約實時倍率 (CPU i7‑11800H, bf16)。

7. GPU / CPU 自動偵測

scripts/detect_env.py 已內建：

import torch, platform
from onnxruntime import get_available_providers
print({
  "os": platform.system(),
  "python": platform.python_version(),
  "torch_cuda": torch.cuda.is_available(),
  "gpu_name": torch.cuda.get_device_name(0) if torch.cuda.is_available() else "CPU",
  "onnx_providers": get_available_providers()
})
  • 啟動流程：python -m app.main 先執行偵測，再載入模型；若無 GPU，強制 CPUExecutionProvider。

8. 下載腳本 (scripts/download_models.sh)

#!/usr/bin/env bash
set -e
# 下載 FunASR
funasr_models=("funasr/paraformer-zh-streaming" "funasr/paraformer-zh")
# LLM - 預設僅抓第一個
llm_models=("Qwen/Qwen1.5-0.5B-Chat" "openbmb/MiniCPM-1B-sft-bf16")

mkdir -p ../models/{funasr_stream,funasr_offline,llm}

for m in "${funasr_models[@]}"; do
  huggingface-cli download $m --local-dir ../models --resume-download --repo-type model
done

# 只下載第一個 LLM，如需全部可設環變量 FULL=1
if [[ "$FULL" == "1" ]]; then
  targets=("${llm_models[@]}")
else
  targets=("${llm_models[0]}")
fi

for m in "${targets[@]}"; do
  huggingface-cli download $m --local-dir ../models/llm --resume-download --repo-type model
done

若 Hugging Face 被封鎖，腳本會自動重試 ms:// 前綴改走 ModelScope。

9. API 總覽（保持不變）

方法 路徑 描述
WS /ws/stt 即時語音串流
POST /api/transcribe 單檔上傳
GET /api/result/{id} 取 JSON/TXT/MD

10. 部署步驟（CPU 範例）

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
bash scripts/download_models.sh  # 約 1.5 GB
python -m app.main

瀏覽 http://localhost:8000 即可開始。

11. 未來規劃

  • 支援多檔佇列並行 (可選 Redis)。
  • 自定熱詞、斷詞優化。