從安裝到上手，一頁到位From install to first run

GPU 伺服器的版本檢查與更新GPU server version check & update

GPU 伺服器上跑的 remote_whisper_server.py 是一支獨立的服務，不會跟著本機升級一起更新。本機執行 ./install.sh --upgrade 更新的是本機程式，伺服器上的服務還是舊的，而有設定 GPU 伺服器時，辨識與講者辨識預設就走伺服器。The remote_whisper_server.py running on your GPU box is a separate service that does not upgrade with the client. ./install.sh --upgrade updates the local program only, and when a GPU server is configured, recognition and diarization go there by default.

v2.21.1 起，本機每次連上伺服器都會比對版本，不一致時提示並說明如何更新：Since v2.21.1 the client compares versions on every connect and tells you how to update:

  [版本不一致] GPU 伺服器 v2.20.9，本機 v2.21.1
  辨識與講者辨識仍會使用伺服器上的舊版；伺服器未開放遠端更新
  手動更新：scp remote_whisper_server.py 主機:~/jt-whisper-server/server.py 後重啟服務

版本不一致不會中斷作業：伺服器舊一點通常仍可使用，只是你會知道結果來自哪個版本。A mismatch never aborts the job: an older server usually still works; you just know which version produced the result.

自動更新（選填，預設關閉）Auto-update (optional, off by default)

兩邊都設定同一組密鑰後，本機發現伺服器版本較舊時會自動把新版推上去，由伺服器驗證通過才替換並重啟，過程中顯示狀態列。With a shared token configured on both sides, the client pushes the new version when the server is behind; the server verifies it before swapping and restarting, with a live status bar.

JT_WHISPER_UPDATE_TOKEN='夠長的隨機字串' \
  ~/jt-whisper-server/start.sh 8978

"remote_whisper": {
  "host": "192.168.1.40",
  "whisper_port": 8978,
  "update_token": "夠長的隨機字串"
}

⚠️ 這個功能本質上是「讓遠端主機執行你送過去的程式」。 區域網路不等於安全網路，所以預設關閉。不確定是否需要時，維持關閉、手動更新即可，版本提示照樣會出現。⚠️ This lets a remote host execute code you send it. A LAN is not a trusted network, so it ships disabled. If in doubt, leave it off and update manually; you still get the version warning.

任何一項不過就保留舊版、服務不受影響；舊版會備份成 server.py.bak-<時間>，只保留最近 5 份。Any failure keeps the old version and leaves the service untouched; the old file is backed up as server.py.bak-<time>, last 5 kept.

這些檢查分兩類。只有簽章在管「誰可以更新」；其餘都在管「更新的東西會不會把服務弄死」。--selftest 本身就會執行上傳的程式碼，所以它擋得住壞掉的更新、擋不住惡意的更新：密鑰是唯一的安全邊界。Two different kinds of check. Only the signature governs who may update; the rest govern whether the update breaks the service. --selftest runs the uploaded code, so it stops broken updates, not malicious ones: the key is the only security boundary.

為什麼用簽章而不是直接送密鑰：這條連線是 HTTP。直接送密鑰的話，任何能側錄區網封包的人都拿得到一組可重複使用的憑證。改用 HMAC 之後，側錄者只能重放「同一份內容」（無害），無法偽造新的 payload。
為什麼不接受降版：多個用戶端共用同一台伺服器時，若只比對「版本不同」，新舊用戶端會無限來回互相覆蓋，每次重啟都中斷別人的辨識。
為什麼要先啟動一次：服務沒有 systemd 之類的看門狗，換上去起不來就直接消失、不會自動復原。Why sign instead of sending the key: this is plain HTTP: sending the key hands a reusable credential to anyone sniffing the LAN. With HMAC a sniffer can only replay the same payload (harmless), never forge a new one.
Why downgrades are refused: with several clients sharing one server, matching on "different version" alone makes old and new clients overwrite each other forever, each restart killing someone's job.
Why it must boot once first: there is no systemd-style watchdog, so a build that won't start simply disappears.

Qwen3-ASR（實驗，v2.23.0 起）Qwen3-ASR (experimental, v2.23.0+)

離線處理錄音檔時可選用的另一個辨識模型。與現行 large-v3-turbo 同條件實測：中文真實會議 20 場字錯率 28.78% → 15.75%；中英夾雜時少數語言找回比例提高 2~3 倍（中文為主的會議，英文詞 34.7% → 74.9%）；低音量 20.67% → 14.33%；韓文長檔 13.35% → 3.54%。日文長檔較差（6.97% → 8.38%）。An alternative recognition model for offline files. Measured against large-v3-turbo under identical conditions: 20 real Chinese meetings CER 28.78% → 15.75%; 2–3× better recall of the minority language in Chinese–English code-switching (English words 34.7% → 74.9%); low volume 20.67% → 14.33%; Korean long-form 13.35% → 3.54%. Japanese long-form is worse (6.97% → 8.38%).

以下條件都符合才能用（不符合時選單與 WebUI 選不到；命令列指定會說明原因並改用推薦模型）：Available only when all of these hold (otherwise menus and the WebUI won't offer it; on the CLI the reason is shown and the recommended model is used):

• 處理錄音檔（--input 或 WebUI 選檔案）；即時字幕不提供，WebUI 標「僅限錄音檔」Processing a file (--input or a file in the WebUI); not for live captions; WebUI shows "file only"
• 所選的辨識位置跑得了：GPU 伺服器已安裝並載入完成（啟動後約 1~3 分鐘），或本機（v2.24.0 起）有 mlx-audio（Apple Silicon）／transformers 5.17 以上（Windows、Linux）；安裝程式會裝，Intel Mac 不支援The chosen location can run it: the GPU server has it installed and loaded (1–3 min after start), or locally (v2.24.0+) mlx-audio (Apple Silicon) / transformers 5.17+ (Windows, Linux) is present; the installer adds them; Intel Mac is not supported
• 中文、英文、韓文的單向模式；日文、台語、雙向不提供（台語請用 Breeze-ASR-26）Chinese / English / Korean one-way modes; not Japanese, Taiwanese Hokkien or two-way (use Breeze-ASR-26 for Hokkien)

• 本機：從舊版升級的 macOS／Windows，--upgrade 後再執行一次 ./install.sh（Windows：.\install.ps1）補裝套件（Linux 會自動補）；模型第一次選用時下載（Mac 約 2.3 GB、其他約 3.4 GB）。Mac 本機與 GPU 伺服器同一場會議字錯率相同（18.85%）。只有 CPU 時選單標「較準但很慢」，電腦記憶體不到 12 GB 不開放；GPU 伺服器失敗退回本機時不會自動在 CPU 上跑它。Windows＋NVIDIA 沒有實機驗證過Local: after --upgrade from an older version on macOS / Windows, run ./install.sh (Windows: .\install.ps1) once more to add the packages (Linux does it automatically); models download on first use (~2.3 GB on Mac, ~3.4 GB elsewhere). The Mac and the GPU server give the same CER on the same meeting (18.85%). CPU-only machines see "accurate but slow" and need 12 GB+ RAM; a GPU-server failure never silently falls back to Qwen on CPU. Windows + NVIDIA has not been tested on real hardware

cd ~/jt-whisper-server
python3 -m venv venv-qwen
venv-qwen/bin/pip install --upgrade pip
venv-qwen/bin/pip install "qwen-asr[vllm]==0.0.6"
venv-qwen/bin/pip install --force-reinstall torch==2.9.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu128
venv-qwen/bin/pip install "numpy<2.3"
systemctl restart jt-whisper-server@8978
curl -s http://localhost:8978/health   # 1~3 分鐘後 "qwen": {"ready": true, ...}

• 資源：啟動後約 7 GB 顯示記憶體、處理長錄音時約 9 GB（一次處理的片段數 JT_QWEN_BATCH 預設 16，設 32 較快但約 12 GB），磁碟約 14 GB（獨立環境 9.5 GB＋模型約 4 GB），建議 16 GB 以上的顯示卡Resources: ~7 GB VRAM after start, ~9 GB while processing long files (batch JT_QWEN_BATCH defaults to 16; 32 is faster but ~12 GB), ~14 GB disk (9.5 GB venv + ~4 GB models); 16 GB+ GPU recommended
• 為什麼要獨立環境：它需要的 PyTorch 版本與辨識服務不同，裝在一起會互相衝突；服務會自動帶起一個只聽本機的子行程，服務停止時一起結束Why a separate venv: it needs a different PyTorch version from the service; the service starts a localhost-only child process and stops it with the service
• 出錯時：處理途中失敗會自動改用 GPU 伺服器的 large-v3-turbo 重跑（本機跑的改用本機推薦的 Whisper）；伺服器上的 Qwen3-ASR 會自動重啟（一小時內最多 3 次，超過就暫停到一小時後再試）。狀態看 /health 的 qwen 欄位，記錄在 /tmp/jt-qwen-worker-<埠號>.logOn errors: a failure mid-file reruns it with the GPU server's large-v3-turbo (locally: the recommended local Whisper); Qwen3-ASR restarts itself (max 3 times per hour, then pauses and retries after the hour). Status: the qwen field of /health; log at /tmp/jt-qwen-worker-<port>.log
• 移除：刪掉 venv-qwen 後重啟服務Remove: delete venv-qwen and restart the service