功能特色¶

TranscriptFlow 旨在展示產品級 AI 管道設計，而非單一提示詞封裝。以下重點著重批次韌性、資料完整性與操作可視性。

工程亮點¶

亮點	為何重要
可復原的多階段處理	明確檔案狀態，長任務可暫停、恢復與檢查
區塊層級重試	模型中途失敗時保留已成功的工作
模型層級診斷	吞吐量、延遲、失敗與錯誤分布皆可見
原子化檢查點寫入	摘要進度在當機與重啟後仍安全
失敗關閉驗證	部分摘要、部分嵌入、不相容的 DB 記錄會停止管道
冪等 LanceDB 寫入	穩定的 `file_id`／`chunk_id` 鍵與合併插入，避免重跑重複列
自適應嵌入批次	兼顧吞吐量，並有斷路器保護
稽核工具	完整性檢查、陳舊任務、跨檔案一致性
OpenAI 相容 HTTP API	支援 OpenAI、LiteLLM Proxy、OpenRouter、vLLM 等

近期強化亦包含 DNS 感知的 URL 清理、延遲模組初始化（環境未設定時匯入不會崩潰）、共享嵌入用戶端單例、Pydantic 設定驗證，以及縮減的子程序環境——細節見文件變更紀錄（英文）或儲存庫完整 CHANGELOG.md。

Smart Merge 3.0 語意區塊切割¶

長篇逐字稿以嵌入輔助的 Smart Merge 策略切割，而非固定長度切段或 LLM 臆造時間戳：

重疊字幕視窗
視窗間嵌入餘弦相似度
以百分位數決定強／弱斷點
接受邊界前的最小跨度驗證
過濾短而低價值的雜訊段落
可選的 min_chunks／max_chunks 上下限

區塊參數可調，使同一管道能適應訪談、講座、播客、座談、課程或混合長篇媒體。設定細節見設定。

四階段管道¶

每個檔案依序經過四個明確階段：

區塊切割（chunking） — 解析 SRT → 語意區塊
摘要（summarizing） — LLM 摘要、標籤、講者提示
嵌入（embedding） — 經驗證的批次向量
資料庫寫入（db_inserting） — 定稿寫入 LanceDB

可由看門狗自動推進，或用直接 --phase 指令除錯與即時驗證。完整流程見架構。

區塊層級重試¶

失敗的摘要或嵌入工作以區塊粒度重試。成功區塊會保留，因此偶發模型失敗不需整檔重做。每模型診斷會追蹤吞吐量、延遲、失敗與錯誤分布。

檢查點安全恢復¶

長時間摘要任務會寫入原子化檢查點。已完成的摘要僅在來源區塊文字雜湊仍相符時才重用——恢復時不會把舊元資料靜默掛到已變更的區塊上。

失敗關閉驗證¶

部分或不一致的產物會停止管道，而非寫入損壞的 RAG 資料：

部分摘要結果
部分嵌入回應
無效或維度錯誤的向量
不相容的 LanceDB 架構／記錄

寧可可見失敗，也不要靜默丟資料。

冪等 LanceDB 寫入¶

向量寫入使用穩定的 file_id 與 chunk_id，並採合併插入語意。重跑某一階段或整檔，不應為同一區塊產生重複列。

看門狗自動化¶

auto_watchdog.py 會掃描批次狀態檔並：

推進可執行的階段工作
遵守各階段並發限制（phase_concurrency.*）
重設超過 watchdog.max_working_time_sec 的任務
將反覆失敗升級為永久失敗狀態

OpenAI 相容 API¶

聊天與嵌入呼叫使用 OpenAI 相容的 HTTP 介面。文件化目標包含 OpenAI、LiteLLM Proxy、OpenRouter、vLLM 等閘道。將 OPENAI_BASE_URL（與金鑰）指向你的端點；模型名稱主要放在 config.json 的 summarization.models 與 embedding.model。

操作友善的內部設計¶

能力	說明
明確檔案狀態	可看到每個檔案在管道中的位置
共享嵌入用戶端	避免同一端點出現重複斷路器
統一 LLM 用戶端	共享重試、模型備援、逾時、JSON 解析（`llm_client.py`）
延遲模組初始化	環境未設定時匯入管道模組不會崩潰
Pydantic 設定 schema	結構化驗證，取代臨時檢查
狀態檔鎖定	並發更新批次狀態時使用 sidecar 鎖定